Lines Matching +full:event +full:-
2 * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu>
3 * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
19 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
35 Libevent is an event notification library for developing scalable network
37 function when a specific event occurs on a file descriptor or after a
41 Libevent is meant to replace the event loop found in event driven network
43 remove events dynamically without having to change the event loop.
47 epoll(4), and evports. The internal event mechanism is completely
48 independent of the exposed event API, and a simple update of Libevent can
51 the most scalable event notification mechanism available on an operating
57 Every program that uses Libevent must include the <event2/event.h>
58 header, and pass the -levent flag to the linker. (You can instead link
59 -levent_core if you only want the main event and buffered IO-based code,
66 multithreaded application, you need to initialize thread support --
75 @section base Creating an event base
81 Every event is associated with a single event_base.
83 @section event Event notification
86 event structure with event_new(). (You may also declare an event
89 of monitored events by calling event_add(). The event structure must
96 You can also use event_base_loop() for more fine-grained control.
105 Libevent provides a buffered I/O abstraction on top of the regular event
108 automatically. The user of a buffered event no longer deals directly
128 an event struct to use as a timer. To activate the timer, call
139 @section evhttp Event-driven HTTP servers
141 Libevent provides a very simple event-driven HTTP server that can be
157 event2/event.h
173 An embedded libevent-based HTTP server
180 /** @file event2/event.h
182 Core functions for waiting for and receiving events, and using event bases.
191 #include <event2/event-config.h>
224 * @struct event
226 * Structure to represent a single event.
228 * An event can have some underlying condition it represents: a socket
230 * (An event that represents no underlying condition is still useful: you
236 * longer want the event, free it with event_free().
240 * An event may be "pending" (one whose condition we are watching),
245 * To make an event pending, pass it to event_add(). When doing so, you
246 * can also set a timeout for the event.
250 * also activate an event manually using event_active(). The even_base
254 * You can make an event non-pending by passing it to event_del(). This
255 * also makes the event non-active.
257 * Events can be "persistent" or "non-persistent". A non-persistent event
258 * becomes non-pending as soon as it is triggered: thus, it only runs at
259 * most once per call to event_add(). A persistent event remains pending
261 * order to make it non-pending. When a persistent event with a timeout
276 struct event struct
287 * complex many-argument constructor, we provide an abstract data type
309 * An event is re-assigned while it is added
310 * Any function is called on a non-assigned event
312 * Note that debugging mode uses memory to track every event that has been
317 * are no longer considered set-up.
325 * When debugging mode is enabled, informs Libevent that an event should no
329 * This function must only be called on a non-added event.
334 void event_debug_unassign(struct event *);
347 Reinitialize the event base after a fork
349 Some event mechanisms do not survive across fork. The event base needs
352 @param base the event base that needs to be re-initialized
353 @return 0 if successful, or -1 if some events could not be re-added.
360 Event dispatching loop
362 This loop will run the event base until either there are no more pending or
368 @return 0 if successful, -1 if an error occurred, or 1 if we exited because
376 Get the kernel event notification mechanism used by Libevent.
379 @return a string identifying the kernel event mechanism (kqueue, epoll, etc.)
385 Gets all event notification mechanisms supported by Libevent.
387 This functions returns the event mechanism in order preferred by
389 Libevent has compiled-in support for, and will not necessarily check
406 @name event type flag
415 * condition, other than a pending event, that keeps the loop from exiting. */
417 /** count the number of events which have been added to event base, including
425 Since event base has some internal events added to make some of its
430 active event will be counted twice. However, this might not be the case in
457 Allocates a new event configuration object.
459 The event configuration object can be used to change the behavior of
460 an event base.
470 Deallocates all memory associated with an event configuration object
472 @param cfg the event configuration object to be freed.
478 Enters an event method that should be avoided into the configuration.
480 This can be used to avoid event mechanisms that do not support certain
481 file descriptor types, or for debugging to avoid certain event
482 mechanisms. An application can make use of multiple event bases to
485 @param cfg the event configuration object
486 @param method the name of the event method to avoid
487 @return 0 on success, -1 on failure.
502 /** Require an event method that allows edge-triggered events with EV_ET. */
504 /** Require an event method where having one event triggered among
509 /** Require an event method that allows file descriptors as well as
512 /** Require an event method that allows you to use EV_CLOSED to detect
530 /** Do not allocate a lock for the event base, even if we have
543 evconn_listener_new() will use IOCP-backed implementations
544 instead of the usual select-based one on Windows.
547 /** Instead of checking the current time every time the event loop is
553 safe to use Libevent's internal change-list code to batch up
558 will produce strange and hard-to-diagnose bugs.
577 Return a bitmask of the features implemented by an event base. This
587 Enters a required event method feature that the application demands.
596 // We can't get edge-triggered behavior here.
602 @param cfg the event configuration object
605 @return 0 on success, -1 on failure.
625 * @param cfg the event configuration object
627 * @return 0 on success, -1 on failure.
633 * Record an interval and/or a number of callbacks after which the event base
634 * should check for new events. By default, the event base will run as many
642 * This option can decrease the latency of high-priority events, and
643 * avoid priority inversions where multiple low-priority events keep us from
644 * polling for high-priority events, but at the expense of slightly decreasing
652 * stop running callbacks and check for more events, or -1 if there
658 * @return 0 on success, -1 on failure.
666 Initialize the event API.
668 Use event_base_new_with_config() to initialize a new event base, taking
670 can currently be used to avoid certain event notification mechanisms.
672 @param cfg the event configuration object
674 or NULL if no event base can be created with the requested event_config.
710 * They violate the reserved-identifier namespace. */
743 Override Libevent's behavior in the event of a fatal internal error.
764 before any calls that create an event-base. You must call it before any
778 Associate a different event base with an event.
780 The event to be associated must not be currently active or pending.
782 @param eb the event base
783 @param ev the event
784 @return 0 on success, -1 on failure.
787 int event_base_set(struct event_base *, struct event *);
794 /** Block until we have an active event, then exit once all active events
798 * of the highest-priority ones, then exit. */
812 By default, this loop will run the event base until either there are no more
820 @return 0 if successful, -1 if an error occurred, or 1 if we exited because
829 Exit the event loop after the specified time
840 @return 0 if successful, or -1 if an error occurred
849 event_base_loop() will abort the loop after the next event is completed;
850 event_base_loopbreak() is typically invoked from this event's callback.
856 @return 0 if successful, or -1 if an error occurred
867 event callback finishes. If the event loop is not running, this
870 event_base_loopbreak() is typically invoked from this event's callback.
873 Subsequent invocations of event loop will proceed normally.
876 @return 0 if successful, or -1 if an error occurred
883 Checks if the event loop was told to exit by event_base_loopexit().
886 event_loopexit() is called, until the event loop is next entered.
889 @return true if event_base_loopexit() was called on this event base,
898 Checks if the event loop was told to abort immediately by event_base_loopbreak().
901 event_base_loopbreak() is called, until the event loop is next entered.
904 @return true if event_base_loopbreak() was called on this event base,
913 * @name event flags
929 * Persistent event: won't get removed automatically when activated.
931 * When a persistent event with a timeout becomes activated, its timeout
935 /** Select edge-triggered behavior, if supported by the backend. */
939 * while waiting for the event callback to complete in another thread.
942 * event_free_finalize() in order to safely tear down an event in a
960 Aliases for working with one-shot timer events
965 event_assign((ev), (b), -1, 0, (cb), (arg))
966 #define evtimer_new(b, cb, arg) event_new((b), -1, 0, (cb), (arg))
992 Aliases for working with user-triggered events
993 If you need EV_PERSIST event use event_*() functions.
996 #define evuser_new(b, cb, arg) event_new((b), -1, 0, (cb), (arg))
1004 A callback function for an event.
1010 @param arg A user-supplied argument.
1017 Return a value used to specify that the event itself must be used as the callback argument.
1020 to the event's callback function. To specify that the argument to be
1021 passed to the callback function is the event that event_new() returns,
1027 struct event *ev = event_new(base, sock, events, callback, %event_self_cbarg());
1032 achieves the same result as passing the event in directly.
1042 Allocate and assign a new event structure, ready to be added.
1044 The function event_new() returns a new event that can be used in
1046 arguments determine which conditions will trigger the event; the
1048 event becomes active.
1055 event can be triggered only by a timeout or by manual activation with
1056 event_active(): In this case, fd must be -1.
1062 only by certain backends. It tells Libevent to use edge-triggered
1068 they must either all be edge-triggered, or all not be edge triggered.
1070 When the event becomes active, the event loop will run the provided
1074 that a timeout occurred, and EV_ET indicates that an edge-triggered
1075 event occurred. The third event will be the callback_arg pointer that
1078 @param base the event base to which the event should be attached.
1079 @param fd the file descriptor or signal to be monitored, or -1.
1082 @param callback callback function to be invoked when the event occurs
1085 @return a newly allocated struct event that must later be freed with
1090 struct event *event_new(struct event_base *, evutil_socket_t, short, event_callback_fn, void *);
1094 Prepare a new, already-allocated event structure to be added.
1096 The function event_assign() prepares the event structure ev to be used
1099 allocated a struct event, probably on the heap. Doing this will
1100 typically make your code depend on the size of the event structure, and
1106 A slightly harder way to future-proof your code is to use
1107 event_get_struct_event_size() to determine the required size of an event
1110 Note that it is NOT safe to call this function on an event that is
1112 Libevent, and lead to strange, hard-to-diagnose bugs. You _can_ use
1113 event_assign to change an existing event, but only if it is not active
1119 @param ev an event struct to be modified
1120 @param base the event base to which ev should be attached.
1123 @param callback callback function to be invoked when the event occurs
1126 @return 0 if success, or -1 on invalid arguments.
1132 int event_assign(struct event *, struct event_base *, evutil_socket_t, short, event_callback_fn, vo…
1135 Deallocate a struct event * returned by event_new().
1137 If the event is pending or active, this function makes it non-pending
1138 and non-active first.
1141 void event_free(struct event *);
1146 typedef void (*event_finalize_callback_fn)(struct event *, void *);
1150 These functions are used to safely tear down an event in a multithreaded
1152 deadlocks, you will need a way to remove an event in the certainty that
1157 0 for its first argument, the event to tear down as its second argument,
1159 invoked as part of the event loop, with the event's priority.
1162 no longer work on the event, and event_del() will produce a no-op. You
1163 must not try to change the event's fields with event_assign() or
1165 callback has been invoked, you should treat the event structure as
1168 The event_free_finalize() function frees the event after it's finalized;
1172 add events, activate events, or attempt to "resuscitate" the event being
1175 @return 0 on success, -1 on failure.
1179 int event_finalize(unsigned, struct event *, event_finalize_callback_fn);
1181 int event_free_finalize(unsigned, struct event *, event_finalize_callback_fn);
1185 Schedule a one-time event
1189 caller to prepare an event structure.
1191 Note that in Libevent 2.0 and earlier, if the event is never triggered, the
1193 the internal memory will get freed by event_base_free() if the event
1195 case--you'll need to free that on your own if you want it to go away.
1198 @param fd a file descriptor to monitor, or -1 for no fd.
1199 @param events event(s) to monitor; can be any of EV_READ |
1201 @param callback callback function to be invoked when the event occurs
1203 @param timeout the maximum amount of time to wait for the event. NULL
1204 makes an EV_READ/EV_WRITE event make forever; NULL makes an
1205 EV_TIMEOUT event success immediately.
1206 @return 0 if successful, or -1 if an error occurred
1212 Add an event to the set of pending events.
1214 The function event_add() schedules the execution of the event 'ev' when the
1218 called if a matching event occurs. The event in the
1223 If the event in the ev argument already has a scheduled timeout, calling
1224 event_add() replaces the old timeout with the new one if tv is non-NULL.
1226 @param ev an event struct initialized via event_assign() or event_new()
1227 @param timeout the maximum amount of time to wait for the event, or NULL
1229 @return 0 if successful, or -1 if an error occurred
1233 int event_add(struct event *ev, const struct timeval *timeout);
1236 Remove a timer from a pending event without removing the event itself.
1238 If the event has a scheduled timeout, this function unschedules it but
1239 leaves the event otherwise pending.
1241 @param ev an event struct initialized via event_assign() or event_new()
1242 @return 0 on success, or -1 if an error occurred.
1245 int event_remove_timer(struct event *ev);
1248 Remove an event from the set of monitored events.
1250 The function event_del() will cancel the event in the argument ev. If the
1251 event has already executed or has never been added the call will have no
1254 @param ev an event struct to be removed from the working set
1255 @return 0 if successful, or -1 if an error occurred
1259 int event_del(struct event *);
1262 As event_del(), but never blocks while the event's callback is running
1263 in another thread, even if the event was constructed without the
1267 int event_del_noblock(struct event *ev);
1269 As event_del(), but always blocks while the event's callback is running
1270 in another thread, even if the event was constructed with the
1274 int event_del_block(struct event *ev);
1277 Make an event active.
1279 You can use this function on a pending or a non-pending event to make it
1286 @param ev an event to make active.
1287 @param res a set of flags to pass to the event's callback.
1291 void event_active(struct event *ev, int res, short ncalls);
1294 Checks if a specific event is pending or scheduled.
1296 @param ev an event struct previously passed to event_add()
1297 @param events the requested event type; any of EV_TIMEOUT|EV_READ|
1299 @param tv if this field is not NULL, and the event has a timeout,
1303 @return true if the event is pending on any of the events in 'what', (that
1304 is to say, it has been added), or 0 if the event is not added.
1307 int event_pending(const struct event *ev, short events, struct timeval *tv);
1310 If called from within the callback for an event, returns that event.
1313 callback function for an event.
1316 struct event *event_base_get_running_event(struct event_base *base);
1319 Test if an event structure might be initialized.
1321 The event_initialized() function can be used to check if an event has been
1324 Warning: This function is only useful for distinguishing a zeroed-out
1325 piece of memory from an initialized event, it can easily be confused by
1327 initialized event from zero.
1329 @param ev an event structure to be tested
1334 int event_initialized(const struct event *ev);
1337 Get the signal number assigned to a signal event
1342 Get the socket or signal assigned to an event, or -1 if the event has
1346 evutil_socket_t event_get_fd(const struct event *ev);
1349 Get the event_base associated with an event.
1352 struct event_base *event_get_base(const struct event *ev);
1355 Return the events (EV_READ, EV_WRITE, etc) assigned to an event.
1358 short event_get_events(const struct event *ev);
1361 Return the callback assigned to an event.
1364 event_callback_fn event_get_callback(const struct event *ev);
1367 Return the callback argument assigned to an event.
1370 void *event_get_callback_arg(const struct event *ev);
1373 Return the priority of an event.
1377 int event_get_priority(const struct event *ev);
1380 Extract _all_ of arguments given to construct a given event. The
1387 void event_get_assignment(const struct event *event,
1392 Return the size of struct event that the Libevent library was compiled
1395 This will be NO GREATER than sizeof(struct event) if you're running with
1399 Note that it might be SMALLER than sizeof(struct event) if some future
1400 version of Libevent adds extra padding to the end of struct event.
1401 We might do this to help ensure ABI-compatibility between different
1427 the version number. The low-order byte is unused. For example, version
1428 2.0.1-alpha has a numeric representation of 0x02000100
1442 Set the number of different event priorities
1454 event. By default, Libevent assigns the middle priority to all events
1457 Note that urgent-priority events can starve less-urgent events: after
1458 running all urgent-priority callbacks, Libevent checks for more urgent
1459 events again, before running less-urgent events. Less-urgent events
1465 @return 0 if successful, or -1 if an error occurred
1472 Get the number of different event priorities.
1475 @return Number of different event priorities
1482 Assign a priority to an event.
1484 @param ev an event struct
1486 @return 0 if successful, or -1 if an error occurred
1490 int event_priority_set(struct event *, int);
1500 connections that all have a 10-second timeout), then you can improve
1506 schedule the event more efficiently.
1549 Writes a human-readable description of all inserted and/or active
1563 Activates all pending events for the given fd and event mask.
1588 * Callback for iterating events in an event base via event_base_foreach_event
1590 typedef int (*event_base_foreach_event_cb)(const struct event_base *, const struct event *, void *);
1593 Iterate over all added or active events events in an event loop, and invoke
1596 The callback must not call any function that modifies the event base, that
1597 modifies any event in the event base, or that adds or removes any event to
1598 the event base. Doing so is unsupported and will lead to undefined
1599 behavior -- likely, to crashes.
1614 @return 0 if we iterated over every event, or the value returned by the
1627 processing event callbacks, and may be very inaccurate if your
1643 * event loop, or if timeval caching is disabled via
1646 * @return 0 on success, -1 on failure
1651 /** Release up all globally-allocated resources allocated by Libevent.
1653 This function does not free developer-controlled resources like
1659 so that resource-leak debugging tools don't see Libevent as holding
1663 be invoked -- e.g., when cleanly exiting a program.