1 | /* |
2 | * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> |
3 | * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson |
4 | * |
5 | * Redistribution and use in source and binary forms, with or without |
6 | * modification, are permitted provided that the following conditions |
7 | * are met: |
8 | * 1. Redistributions of source code must retain the above copyright |
9 | * notice, this list of conditions and the following disclaimer. |
10 | * 2. Redistributions in binary form must reproduce the above copyright |
11 | * notice, this list of conditions and the following disclaimer in the |
12 | * documentation and/or other materials provided with the distribution. |
13 | * 3. The name of the author may not be used to endorse or promote products |
14 | * derived from this software without specific prior written permission. |
15 | * |
16 | * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
17 | * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
18 | * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
19 | * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, |
20 | * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
21 | * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
22 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
23 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
24 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
25 | * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
26 | */ |
27 | #ifndef EVENT2_EVENT_H_INCLUDED_ |
28 | #define EVENT2_EVENT_H_INCLUDED_ |
29 | |
30 | /** |
31 | @mainpage |
32 | |
33 | @section intro Introduction |
34 | |
35 | Libevent is an event notification library for developing scalable network |
36 | servers. The Libevent API provides a mechanism to execute a callback |
37 | function when a specific event occurs on a file descriptor or after a |
38 | timeout has been reached. Furthermore, Libevent also support callbacks due |
39 | to signals or regular timeouts. |
40 | |
41 | Libevent is meant to replace the event loop found in event driven network |
42 | servers. An application just needs to call event_base_dispatch() and then add or |
43 | remove events dynamically without having to change the event loop. |
44 | |
45 | |
46 | Currently, Libevent supports /dev/poll, kqueue(2), select(2), poll(2), |
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 |
49 | provide new functionality without having to redesign the applications. As a |
50 | result, Libevent allows for portable application development and provides |
51 | the most scalable event notification mechanism available on an operating |
52 | system. Libevent can also be used for multithreaded programs. Libevent |
53 | should compile on Linux, *BSD, Mac OS X, Solaris and, Windows. |
54 | |
55 | @section usage Standard usage |
56 | |
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, |
60 | and don't want to link any protocol code.) |
61 | |
62 | @section setup Library setup |
63 | |
64 | Before you call any other Libevent functions, you need to set up the |
65 | library. If you're going to use Libevent from multiple threads in a |
66 | multithreaded application, you need to initialize thread support -- |
67 | typically by using evthread_use_pthreads() or |
68 | evthread_use_windows_threads(). See <event2/thread.h> for more |
69 | information. |
70 | |
71 | This is also the point where you can replace Libevent's memory |
72 | management functions with event_set_mem_functions, and enable debug mode |
73 | with event_enable_debug_mode(). |
74 | |
75 | @section base Creating an event base |
76 | |
77 | Next, you need to create an event_base structure, using event_base_new() |
78 | or event_base_new_with_config(). The event_base is responsible for |
79 | keeping track of which events are "pending" (that is to say, being |
80 | watched to see if they become active) and which events are "active". |
81 | Every event is associated with a single event_base. |
82 | |
83 | @section event Event notification |
84 | |
85 | For each file descriptor that you wish to monitor, you must create an |
86 | event structure with event_new(). (You may also declare an event |
87 | structure and call event_assign() to initialize the members of the |
88 | structure.) To enable notification, you add the structure to the list |
89 | of monitored events by calling event_add(). The event structure must |
90 | remain allocated as long as it is active, so it should generally be |
91 | allocated on the heap. |
92 | |
93 | @section loop Dispatching events. |
94 | |
95 | Finally, you call event_base_dispatch() to loop and dispatch events. |
96 | You can also use event_base_loop() for more fine-grained control. |
97 | |
98 | Currently, only one thread can be dispatching a given event_base at a |
99 | time. If you want to run events in multiple threads at once, you can |
100 | either have a single event_base whose events add work to a work queue, |
101 | or you can create multiple event_base objects. |
102 | |
103 | @section bufferevent I/O Buffers |
104 | |
105 | Libevent provides a buffered I/O abstraction on top of the regular event |
106 | callbacks. This abstraction is called a bufferevent. A bufferevent |
107 | provides input and output buffers that get filled and drained |
108 | automatically. The user of a buffered event no longer deals directly |
109 | with the I/O, but instead is reading from input and writing to output |
110 | buffers. |
111 | |
112 | Once initialized via bufferevent_socket_new(), the bufferevent structure |
113 | can be used repeatedly with bufferevent_enable() and |
114 | bufferevent_disable(). Instead of reading and writing directly to a |
115 | socket, you would call bufferevent_read() and bufferevent_write(). |
116 | |
117 | When read enabled the bufferevent will try to read from the file descriptor |
118 | and call the read callback. The write callback is executed whenever the |
119 | output buffer is drained below the write low watermark, which is 0 by |
120 | default. |
121 | |
122 | See <event2/bufferevent*.h> for more information. |
123 | |
124 | @section timers Timers |
125 | |
126 | Libevent can also be used to create timers that invoke a callback after a |
127 | certain amount of time has expired. The evtimer_new() macro returns |
128 | an event struct to use as a timer. To activate the timer, call |
129 | evtimer_add(). Timers can be deactivated by calling evtimer_del(). |
130 | (These macros are thin wrappers around event_new(), event_add(), |
131 | and event_del(); you can also use those instead.) |
132 | |
133 | @section evdns Asynchronous DNS resolution |
134 | |
135 | Libevent provides an asynchronous DNS resolver that should be used instead |
136 | of the standard DNS resolver functions. See the <event2/dns.h> |
137 | functions for more detail. |
138 | |
139 | @section evhttp Event-driven HTTP servers |
140 | |
141 | Libevent provides a very simple event-driven HTTP server that can be |
142 | embedded in your program and used to service HTTP requests. |
143 | |
144 | To use this capability, you need to include the <event2/http.h> header in your |
145 | program. See that header for more information. |
146 | |
147 | @section evrpc A framework for RPC servers and clients |
148 | |
149 | Libevent provides a framework for creating RPC servers and clients. It |
150 | takes care of marshaling and unmarshaling all data structures. |
151 | |
152 | @section api API Reference |
153 | |
154 | To browse the complete documentation of the libevent API, click on any of |
155 | the following links. |
156 | |
157 | event2/event.h |
158 | The primary libevent header |
159 | |
160 | event2/thread.h |
161 | Functions for use by multithreaded programs |
162 | |
163 | event2/buffer.h and event2/bufferevent.h |
164 | Buffer management for network reading and writing |
165 | |
166 | event2/util.h |
167 | Utility functions for portable nonblocking network code |
168 | |
169 | event2/dns.h |
170 | Asynchronous DNS resolution |
171 | |
172 | event2/http.h |
173 | An embedded libevent-based HTTP server |
174 | |
175 | event2/rpc.h |
176 | A framework for creating RPC servers and clients |
177 | |
178 | */ |
179 | |
180 | /** @file event2/event.h |
181 | |
182 | Core functions for waiting for and receiving events, and using event bases. |
183 | */ |
184 | |
185 | #include <event2/visibility.h> |
186 | |
187 | #ifdef __cplusplus |
188 | extern "C" { |
189 | #endif |
190 | |
191 | #include <event2/event-config.h> |
192 | #ifdef EVENT__HAVE_SYS_TYPES_H |
193 | #include <sys/types.h> |
194 | #endif |
195 | #ifdef EVENT__HAVE_SYS_TIME_H |
196 | #include <sys/time.h> |
197 | #endif |
198 | |
199 | #include <stdio.h> |
200 | |
201 | /* For int types. */ |
202 | #include <event2/util.h> |
203 | |
204 | /** |
205 | * Structure to hold information and state for a Libevent dispatch loop. |
206 | * |
207 | * The event_base lies at the center of Libevent; every application will |
208 | * have one. It keeps track of all pending and active events, and |
209 | * notifies your application of the active ones. |
210 | * |
211 | * This is an opaque structure; you can allocate one using |
212 | * event_base_new() or event_base_new_with_config(). |
213 | * |
214 | * @see event_base_new(), event_base_free(), event_base_loop(), |
215 | * event_base_new_with_config() |
216 | */ |
217 | struct event_base |
218 | #ifdef EVENT_IN_DOXYGEN_ |
219 | {/*Empty body so that doxygen will generate documentation here.*/} |
220 | #endif |
221 | ; |
222 | |
223 | /** |
224 | * @struct event |
225 | * |
226 | * Structure to represent a single event. |
227 | * |
228 | * An event can have some underlying condition it represents: a socket |
229 | * becoming readable or writeable (or both), or a signal becoming raised. |
230 | * (An event that represents no underlying condition is still useful: you |
231 | * can use one to implement a timer, or to communicate between threads.) |
232 | * |
233 | * Generally, you can create events with event_new(), then make them |
234 | * pending with event_add(). As your event_base runs, it will run the |
235 | * callbacks of an events whose conditions are triggered. When you no |
236 | * longer want the event, free it with event_free(). |
237 | * |
238 | * In more depth: |
239 | * |
240 | * An event may be "pending" (one whose condition we are watching), |
241 | * "active" (one whose condition has triggered and whose callback is about |
242 | * to run), neither, or both. Events come into existence via |
243 | * event_assign() or event_new(), and are then neither active nor pending. |
244 | * |
245 | * To make an event pending, pass it to event_add(). When doing so, you |
246 | * can also set a timeout for the event. |
247 | * |
248 | * Events become active during an event_base_loop() call when either their |
249 | * condition has triggered, or when their timeout has elapsed. You can |
250 | * also activate an event manually using event_active(). The even_base |
251 | * loop will run the callbacks of active events; after it has done so, it |
252 | * marks them as no longer active. |
253 | * |
254 | * You can make an event non-pending by passing it to event_del(). This |
255 | * also makes the event non-active. |
256 | * |
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 |
260 | * even when it becomes active: you'll need to event_del() it manually in |
261 | * order to make it non-pending. When a persistent event with a timeout |
262 | * becomes active, its timeout is reset: this means you can use persistent |
263 | * events to implement periodic timeouts. |
264 | * |
265 | * This should be treated as an opaque structure; you should never read or |
266 | * write any of its fields directly. For backward compatibility with old |
267 | * code, it is defined in the event2/event_struct.h header; including this |
268 | * header may make your code incompatible with other versions of Libevent. |
269 | * |
270 | * @see event_new(), event_free(), event_assign(), event_get_assignment(), |
271 | * event_add(), event_del(), event_active(), event_pending(), |
272 | * event_get_fd(), event_get_base(), event_get_events(), |
273 | * event_get_callback(), event_get_callback_arg(), |
274 | * event_priority_set() |
275 | */ |
276 | struct event |
277 | #ifdef EVENT_IN_DOXYGEN_ |
278 | {/*Empty body so that doxygen will generate documentation here.*/} |
279 | #endif |
280 | ; |
281 | |
282 | /** |
283 | * Configuration for an event_base. |
284 | * |
285 | * There are many options that can be used to alter the behavior and |
286 | * implementation of an event_base. To avoid having to pass them all in a |
287 | * complex many-argument constructor, we provide an abstract data type |
288 | * where you set up configuration information before passing it to |
289 | * event_base_new_with_config(). |
290 | * |
291 | * @see event_config_new(), event_config_free(), event_base_new_with_config(), |
292 | * event_config_avoid_method(), event_config_require_features(), |
293 | * event_config_set_flag(), event_config_set_num_cpus_hint() |
294 | */ |
295 | struct event_config |
296 | #ifdef EVENT_IN_DOXYGEN_ |
297 | {/*Empty body so that doxygen will generate documentation here.*/} |
298 | #endif |
299 | ; |
300 | |
301 | /** |
302 | * Enable some relatively expensive debugging checks in Libevent that |
303 | * would normally be turned off. Generally, these checks cause code that |
304 | * would otherwise crash mysteriously to fail earlier with an assertion |
305 | * failure. Note that this method MUST be called before any events or |
306 | * event_bases have been created. |
307 | * |
308 | * Debug mode can currently catch the following errors: |
309 | * An event is re-assigned while it is added |
310 | * Any function is called on a non-assigned event |
311 | * |
312 | * Note that debugging mode uses memory to track every event that has been |
313 | * initialized (via event_assign, event_set, or event_new) but not yet |
314 | * released (via event_free or event_debug_unassign). If you want to use |
315 | * debug mode, and you find yourself running out of memory, you will need |
316 | * to use event_debug_unassign to explicitly stop tracking events that |
317 | * are no longer considered set-up. |
318 | * |
319 | * @see event_debug_unassign() |
320 | */ |
321 | EVENT2_EXPORT_SYMBOL |
322 | void event_enable_debug_mode(void); |
323 | |
324 | /** |
325 | * When debugging mode is enabled, informs Libevent that an event should no |
326 | * longer be considered as assigned. When debugging mode is not enabled, does |
327 | * nothing. |
328 | * |
329 | * This function must only be called on a non-added event. |
330 | * |
331 | * @see event_enable_debug_mode() |
332 | */ |
333 | EVENT2_EXPORT_SYMBOL |
334 | void event_debug_unassign(struct event *); |
335 | |
336 | /** |
337 | * Create and return a new event_base to use with the rest of Libevent. |
338 | * |
339 | * @return a new event_base on success, or NULL on failure. |
340 | * |
341 | * @see event_base_free(), event_base_new_with_config() |
342 | */ |
343 | EVENT2_EXPORT_SYMBOL |
344 | struct event_base *event_base_new(void); |
345 | |
346 | /** |
347 | Reinitialize the event base after a fork |
348 | |
349 | Some event mechanisms do not survive across fork. The event base needs |
350 | to be reinitialized with the event_reinit() function. |
351 | |
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. |
354 | @see event_base_new() |
355 | */ |
356 | EVENT2_EXPORT_SYMBOL |
357 | int event_reinit(struct event_base *base); |
358 | |
359 | /** |
360 | Event dispatching loop |
361 | |
362 | This loop will run the event base until either there are no more pending or |
363 | active, or until something calls event_base_loopbreak() or |
364 | event_base_loopexit(). |
365 | |
366 | @param base the event_base structure returned by event_base_new() or |
367 | event_base_new_with_config() |
368 | @return 0 if successful, -1 if an error occurred, or 1 if we exited because |
369 | no events were pending or active. |
370 | @see event_base_loop() |
371 | */ |
372 | EVENT2_EXPORT_SYMBOL |
373 | int event_base_dispatch(struct event_base *); |
374 | |
375 | /** |
376 | Get the kernel event notification mechanism used by Libevent. |
377 | |
378 | @param eb the event_base structure returned by event_base_new() |
379 | @return a string identifying the kernel event mechanism (kqueue, epoll, etc.) |
380 | */ |
381 | EVENT2_EXPORT_SYMBOL |
382 | const char *event_base_get_method(const struct event_base *); |
383 | |
384 | /** |
385 | Gets all event notification mechanisms supported by Libevent. |
386 | |
387 | This functions returns the event mechanism in order preferred by |
388 | Libevent. Note that this list will include all backends that |
389 | Libevent has compiled-in support for, and will not necessarily check |
390 | your OS to see whether it has the required resources. |
391 | |
392 | @return an array with pointers to the names of support methods. |
393 | The end of the array is indicated by a NULL pointer. If an |
394 | error is encountered NULL is returned. |
395 | */ |
396 | EVENT2_EXPORT_SYMBOL |
397 | const char **event_get_supported_methods(void); |
398 | |
399 | /** Query the current monotonic time from a the timer for a struct |
400 | * event_base. |
401 | */ |
402 | EVENT2_EXPORT_SYMBOL |
403 | int event_gettime_monotonic(struct event_base *base, struct timeval *tp); |
404 | |
405 | /** |
406 | @name event type flag |
407 | |
408 | Flags to pass to event_base_get_num_events() to specify the kinds of events |
409 | we want to aggregate counts for |
410 | */ |
411 | /**@{*/ |
412 | /** count the number of active events, which have been triggered.*/ |
413 | #define EVENT_BASE_COUNT_ACTIVE 1U |
414 | /** count the number of virtual events, which is used to represent an internal |
415 | * condition, other than a pending event, that keeps the loop from exiting. */ |
416 | #define EVENT_BASE_COUNT_VIRTUAL 2U |
417 | /** count the number of events which have been added to event base, including |
418 | * internal events. */ |
419 | #define EVENT_BASE_COUNT_ADDED 4U |
420 | /**@}*/ |
421 | |
422 | /** |
423 | Gets the number of events in event_base, as specified in the flags. |
424 | |
425 | Since event base has some internal events added to make some of its |
426 | functionalities work, EVENT_BASE_COUNT_ADDED may return more than the |
427 | number of events you added using event_add(). |
428 | |
429 | If you pass EVENT_BASE_COUNT_ACTIVE and EVENT_BASE_COUNT_ADDED together, an |
430 | active event will be counted twice. However, this might not be the case in |
431 | future libevent versions. The return value is an indication of the work |
432 | load, but the user shouldn't rely on the exact value as this may change in |
433 | the future. |
434 | |
435 | @param eb the event_base structure returned by event_base_new() |
436 | @param flags a bitwise combination of the kinds of events to aggregate |
437 | counts for |
438 | @return the number of events specified in the flags |
439 | */ |
440 | EVENT2_EXPORT_SYMBOL |
441 | int event_base_get_num_events(struct event_base *, unsigned int); |
442 | |
443 | /** |
444 | Get the maximum number of events in a given event_base as specified in the |
445 | flags. |
446 | |
447 | @param eb the event_base structure returned by event_base_new() |
448 | @param flags a bitwise combination of the kinds of events to aggregate |
449 | counts for |
450 | @param clear option used to reset the maximum count. |
451 | @return the number of events specified in the flags |
452 | */ |
453 | EVENT2_EXPORT_SYMBOL |
454 | int event_base_get_max_events(struct event_base *, unsigned int, int); |
455 | |
456 | /** |
457 | Allocates a new event configuration object. |
458 | |
459 | The event configuration object can be used to change the behavior of |
460 | an event base. |
461 | |
462 | @return an event_config object that can be used to store configuration, or |
463 | NULL if an error is encountered. |
464 | @see event_base_new_with_config(), event_config_free(), event_config |
465 | */ |
466 | EVENT2_EXPORT_SYMBOL |
467 | struct event_config *event_config_new(void); |
468 | |
469 | /** |
470 | Deallocates all memory associated with an event configuration object |
471 | |
472 | @param cfg the event configuration object to be freed. |
473 | */ |
474 | EVENT2_EXPORT_SYMBOL |
475 | void event_config_free(struct event_config *cfg); |
476 | |
477 | /** |
478 | Enters an event method that should be avoided into the configuration. |
479 | |
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 |
483 | accommodate incompatible file descriptor types. |
484 | |
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. |
488 | */ |
489 | EVENT2_EXPORT_SYMBOL |
490 | int event_config_avoid_method(struct event_config *cfg, const char *method); |
491 | |
492 | /** |
493 | A flag used to describe which features an event_base (must) provide. |
494 | |
495 | Because of OS limitations, not every Libevent backend supports every |
496 | possible feature. You can use this type with |
497 | event_config_require_features() to tell Libevent to only proceed if your |
498 | event_base implements a given feature, and you can receive this type from |
499 | event_base_get_features() to see which features are available. |
500 | */ |
501 | enum event_method_feature { |
502 | /** Require an event method that allows edge-triggered events with EV_ET. */ |
503 | EV_FEATURE_ET = 0x01, |
504 | /** Require an event method where having one event triggered among |
505 | * many is [approximately] an O(1) operation. This excludes (for |
506 | * example) select and poll, which are approximately O(N) for N |
507 | * equal to the total number of possible events. */ |
508 | EV_FEATURE_O1 = 0x02, |
509 | /** Require an event method that allows file descriptors as well as |
510 | * sockets. */ |
511 | EV_FEATURE_FDS = 0x04, |
512 | /** Require an event method that allows you to use EV_CLOSED to detect |
513 | * connection close without the necessity of reading all the pending data. |
514 | * |
515 | * Methods that do support EV_CLOSED may not be able to provide support on |
516 | * all kernel versions. |
517 | **/ |
518 | EV_FEATURE_EARLY_CLOSE = 0x08 |
519 | }; |
520 | |
521 | /** |
522 | A flag passed to event_config_set_flag(). |
523 | |
524 | These flags change the behavior of an allocated event_base. |
525 | |
526 | @see event_config_set_flag(), event_base_new_with_config(), |
527 | event_method_feature |
528 | */ |
529 | enum event_base_config_flag { |
530 | /** Do not allocate a lock for the event base, even if we have |
531 | locking set up. |
532 | |
533 | Setting this option will make it unsafe and nonfunctional to call |
534 | functions on the base concurrently from multiple threads. |
535 | */ |
536 | EVENT_BASE_FLAG_NOLOCK = 0x01, |
537 | /** Do not check the EVENT_* environment variables when configuring |
538 | an event_base */ |
539 | EVENT_BASE_FLAG_IGNORE_ENV = 0x02, |
540 | /** Windows only: enable the IOCP dispatcher at startup |
541 | |
542 | If this flag is set then bufferevent_socket_new() and |
543 | evconn_listener_new() will use IOCP-backed implementations |
544 | instead of the usual select-based one on Windows. |
545 | */ |
546 | EVENT_BASE_FLAG_STARTUP_IOCP = 0x04, |
547 | /** Instead of checking the current time every time the event loop is |
548 | ready to run timeout callbacks, check after each timeout callback. |
549 | */ |
550 | EVENT_BASE_FLAG_NO_CACHE_TIME = 0x08, |
551 | |
552 | /** If we are using the epoll backend, this flag says that it is |
553 | safe to use Libevent's internal change-list code to batch up |
554 | adds and deletes in order to try to do as few syscalls as |
555 | possible. Setting this flag can make your code run faster, but |
556 | it may trigger a Linux bug: it is not safe to use this flag |
557 | if you have any fds cloned by dup() or its variants. Doing so |
558 | will produce strange and hard-to-diagnose bugs. |
559 | |
560 | This flag can also be activated by setting the |
561 | EVENT_EPOLL_USE_CHANGELIST environment variable. |
562 | |
563 | This flag has no effect if you wind up using a backend other than |
564 | epoll. |
565 | */ |
566 | EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST = 0x10, |
567 | |
568 | /** Ordinarily, Libevent implements its time and timeout code using |
569 | the fastest monotonic timer that we have. If this flag is set, |
570 | however, we use less efficient more precise timer, assuming one is |
571 | present. |
572 | */ |
573 | EVENT_BASE_FLAG_PRECISE_TIMER = 0x20 |
574 | }; |
575 | |
576 | /** |
577 | Return a bitmask of the features implemented by an event base. This |
578 | will be a bitwise OR of one or more of the values of |
579 | event_method_feature |
580 | |
581 | @see event_method_feature |
582 | */ |
583 | EVENT2_EXPORT_SYMBOL |
584 | int event_base_get_features(const struct event_base *base); |
585 | |
586 | /** |
587 | Enters a required event method feature that the application demands. |
588 | |
589 | Note that not every feature or combination of features is supported |
590 | on every platform. Code that requests features should be prepared |
591 | to handle the case where event_base_new_with_config() returns NULL, as in: |
592 | <pre> |
593 | event_config_require_features(cfg, EV_FEATURE_ET); |
594 | base = event_base_new_with_config(cfg); |
595 | if (base == NULL) { |
596 | // We can't get edge-triggered behavior here. |
597 | event_config_require_features(cfg, 0); |
598 | base = event_base_new_with_config(cfg); |
599 | } |
600 | </pre> |
601 | |
602 | @param cfg the event configuration object |
603 | @param feature a bitfield of one or more event_method_feature values. |
604 | Replaces values from previous calls to this function. |
605 | @return 0 on success, -1 on failure. |
606 | @see event_method_feature, event_base_new_with_config() |
607 | */ |
608 | EVENT2_EXPORT_SYMBOL |
609 | int event_config_require_features(struct event_config *cfg, int feature); |
610 | |
611 | /** |
612 | * Sets one or more flags to configure what parts of the eventual event_base |
613 | * will be initialized, and how they'll work. |
614 | * |
615 | * @see event_base_config_flags, event_base_new_with_config() |
616 | **/ |
617 | EVENT2_EXPORT_SYMBOL |
618 | int event_config_set_flag(struct event_config *cfg, int flag); |
619 | |
620 | /** |
621 | * Records a hint for the number of CPUs in the system. This is used for |
622 | * tuning thread pools, etc, for optimal performance. In Libevent 2.0, |
623 | * it is only on Windows, and only when IOCP is in use. |
624 | * |
625 | * @param cfg the event configuration object |
626 | * @param cpus the number of cpus |
627 | * @return 0 on success, -1 on failure. |
628 | */ |
629 | EVENT2_EXPORT_SYMBOL |
630 | int event_config_set_num_cpus_hint(struct event_config *cfg, int cpus); |
631 | |
632 | /** |
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 |
635 | * events are as activated at the highest activated priority before checking |
636 | * for new events. If you configure it by setting max_interval, it will check |
637 | * the time after each callback, and not allow more than max_interval to |
638 | * elapse before checking for new events. If you configure it by setting |
639 | * max_callbacks to a value >= 0, it will run no more than max_callbacks |
640 | * callbacks before checking for new events. |
641 | * |
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 |
645 | * the throughput. Use it with caution! |
646 | * |
647 | * @param cfg The event_base configuration object. |
648 | * @param max_interval An interval after which Libevent should stop running |
649 | * callbacks and check for more events, or NULL if there should be |
650 | * no such interval. |
651 | * @param max_callbacks A number of callbacks after which Libevent should |
652 | * stop running callbacks and check for more events, or -1 if there |
653 | * should be no such limit. |
654 | * @param min_priority A priority below which max_interval and max_callbacks |
655 | * should not be enforced. If this is set to 0, they are enforced |
656 | * for events of every priority; if it's set to 1, they're enforced |
657 | * for events of priority 1 and above, and so on. |
658 | * @return 0 on success, -1 on failure. |
659 | **/ |
660 | EVENT2_EXPORT_SYMBOL |
661 | int event_config_set_max_dispatch_interval(struct event_config *cfg, |
662 | const struct timeval *max_interval, int max_callbacks, |
663 | int min_priority); |
664 | |
665 | /** |
666 | Initialize the event API. |
667 | |
668 | Use event_base_new_with_config() to initialize a new event base, taking |
669 | the specified configuration under consideration. The configuration object |
670 | can currently be used to avoid certain event notification mechanisms. |
671 | |
672 | @param cfg the event configuration object |
673 | @return an initialized event_base that can be used to registering events, |
674 | or NULL if no event base can be created with the requested event_config. |
675 | @see event_base_new(), event_base_free(), event_init(), event_assign() |
676 | */ |
677 | EVENT2_EXPORT_SYMBOL |
678 | struct event_base *event_base_new_with_config(const struct event_config *); |
679 | |
680 | /** |
681 | Deallocate all memory associated with an event_base, and free the base. |
682 | |
683 | Note that this function will not close any fds or free any memory passed |
684 | to event_new as the argument to callback. |
685 | |
686 | If there are any pending finalizer callbacks, this function will invoke |
687 | them. |
688 | |
689 | @param eb an event_base to be freed |
690 | */ |
691 | EVENT2_EXPORT_SYMBOL |
692 | void event_base_free(struct event_base *); |
693 | |
694 | /** |
695 | As event_base_free, but do not run finalizers. |
696 | */ |
697 | EVENT2_EXPORT_SYMBOL |
698 | void event_base_free_nofinalize(struct event_base *); |
699 | |
700 | /** @name Log severities |
701 | */ |
702 | /**@{*/ |
703 | #define EVENT_LOG_DEBUG 0 |
704 | #define EVENT_LOG_MSG 1 |
705 | #define EVENT_LOG_WARN 2 |
706 | #define EVENT_LOG_ERR 3 |
707 | /**@}*/ |
708 | |
709 | /* Obsolete names: these are deprecated, but older programs might use them. |
710 | * They violate the reserved-identifier namespace. */ |
711 | #define _EVENT_LOG_DEBUG EVENT_LOG_DEBUG |
712 | #define _EVENT_LOG_MSG EVENT_LOG_MSG |
713 | #define _EVENT_LOG_WARN EVENT_LOG_WARN |
714 | #define _EVENT_LOG_ERR EVENT_LOG_ERR |
715 | |
716 | /** |
717 | A callback function used to intercept Libevent's log messages. |
718 | |
719 | @see event_set_log_callback |
720 | */ |
721 | typedef void (*event_log_cb)(int severity, const char *msg); |
722 | /** |
723 | Redirect Libevent's log messages. |
724 | |
725 | @param cb a function taking two arguments: an integer severity between |
726 | EVENT_LOG_DEBUG and EVENT_LOG_ERR, and a string. If cb is NULL, |
727 | then the default log is used. |
728 | |
729 | NOTE: The function you provide *must not* call any other libevent |
730 | functionality. Doing so can produce undefined behavior. |
731 | */ |
732 | EVENT2_EXPORT_SYMBOL |
733 | void event_set_log_callback(event_log_cb cb); |
734 | |
735 | /** |
736 | A function to be called if Libevent encounters a fatal internal error. |
737 | |
738 | @see event_set_fatal_callback |
739 | */ |
740 | typedef void (*event_fatal_cb)(int err); |
741 | |
742 | /** |
743 | Override Libevent's behavior in the event of a fatal internal error. |
744 | |
745 | By default, Libevent will call exit(1) if a programming error makes it |
746 | impossible to continue correct operation. This function allows you to supply |
747 | another callback instead. Note that if the function is ever invoked, |
748 | something is wrong with your program, or with Libevent: any subsequent calls |
749 | to Libevent may result in undefined behavior. |
750 | |
751 | Libevent will (almost) always log an EVENT_LOG_ERR message before calling |
752 | this function; look at the last log message to see why Libevent has died. |
753 | */ |
754 | EVENT2_EXPORT_SYMBOL |
755 | void event_set_fatal_callback(event_fatal_cb cb); |
756 | |
757 | #define EVENT_DBG_ALL 0xffffffffu |
758 | #define EVENT_DBG_NONE 0 |
759 | |
760 | /** |
761 | Turn on debugging logs and have them sent to the default log handler. |
762 | |
763 | This is a global setting; if you are going to call it, you must call this |
764 | before any calls that create an event-base. You must call it before any |
765 | multithreaded use of Libevent. |
766 | |
767 | Debug logs are verbose. |
768 | |
769 | @param which Controls which debug messages are turned on. This option is |
770 | unused for now; for forward compatibility, you must pass in the constant |
771 | "EVENT_DBG_ALL" to turn debugging logs on, or "EVENT_DBG_NONE" to turn |
772 | debugging logs off. |
773 | */ |
774 | EVENT2_EXPORT_SYMBOL |
775 | void event_enable_debug_logging(ev_uint32_t which); |
776 | |
777 | /** |
778 | Associate a different event base with an event. |
779 | |
780 | The event to be associated must not be currently active or pending. |
781 | |
782 | @param eb the event base |
783 | @param ev the event |
784 | @return 0 on success, -1 on failure. |
785 | */ |
786 | EVENT2_EXPORT_SYMBOL |
787 | int event_base_set(struct event_base *, struct event *); |
788 | |
789 | /** @name Loop flags |
790 | |
791 | These flags control the behavior of event_base_loop(). |
792 | */ |
793 | /**@{*/ |
794 | /** Block until we have an active event, then exit once all active events |
795 | * have had their callbacks run. */ |
796 | #define EVLOOP_ONCE 0x01 |
797 | /** Do not block: see which events are ready now, run the callbacks |
798 | * of the highest-priority ones, then exit. */ |
799 | #define EVLOOP_NONBLOCK 0x02 |
800 | /** Do not exit the loop because we have no pending events. Instead, keep |
801 | * running until event_base_loopexit() or event_base_loopbreak() makes us |
802 | * stop. |
803 | */ |
804 | #define EVLOOP_NO_EXIT_ON_EMPTY 0x04 |
805 | /**@}*/ |
806 | |
807 | /** |
808 | Wait for events to become active, and run their callbacks. |
809 | |
810 | This is a more flexible version of event_base_dispatch(). |
811 | |
812 | By default, this loop will run the event base until either there are no more |
813 | pending or active events, or until something calls event_base_loopbreak() or |
814 | event_base_loopexit(). You can override this behavior with the 'flags' |
815 | argument. |
816 | |
817 | @param eb the event_base structure returned by event_base_new() or |
818 | event_base_new_with_config() |
819 | @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK |
820 | @return 0 if successful, -1 if an error occurred, or 1 if we exited because |
821 | no events were pending or active. |
822 | @see event_base_loopexit(), event_base_dispatch(), EVLOOP_ONCE, |
823 | EVLOOP_NONBLOCK |
824 | */ |
825 | EVENT2_EXPORT_SYMBOL |
826 | int event_base_loop(struct event_base *, int); |
827 | |
828 | /** |
829 | Exit the event loop after the specified time |
830 | |
831 | The next event_base_loop() iteration after the given timer expires will |
832 | complete normally (handling all queued events) then exit without |
833 | blocking for events again. |
834 | |
835 | Subsequent invocations of event_base_loop() will proceed normally. |
836 | |
837 | @param eb the event_base structure returned by event_init() |
838 | @param tv the amount of time after which the loop should terminate, |
839 | or NULL to exit after running all currently active events. |
840 | @return 0 if successful, or -1 if an error occurred |
841 | @see event_base_loopbreak() |
842 | */ |
843 | EVENT2_EXPORT_SYMBOL |
844 | int event_base_loopexit(struct event_base *, const struct timeval *); |
845 | |
846 | /** |
847 | Abort the active event_base_loop() immediately. |
848 | |
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. |
851 | This behavior is analogous to the "break;" statement. |
852 | |
853 | Subsequent invocations of event_base_loop() will proceed normally. |
854 | |
855 | @param eb the event_base structure returned by event_init() |
856 | @return 0 if successful, or -1 if an error occurred |
857 | @see event_base_loopexit() |
858 | */ |
859 | EVENT2_EXPORT_SYMBOL |
860 | int event_base_loopbreak(struct event_base *); |
861 | |
862 | /** |
863 | Tell the active event_base_loop() to scan for new events immediately. |
864 | |
865 | Calling this function makes the currently active event_base_loop() |
866 | start the loop over again (scanning for new events) after the current |
867 | event callback finishes. If the event loop is not running, this |
868 | function has no effect. |
869 | |
870 | event_base_loopbreak() is typically invoked from this event's callback. |
871 | This behavior is analogous to the "continue;" statement. |
872 | |
873 | Subsequent invocations of event loop will proceed normally. |
874 | |
875 | @param eb the event_base structure returned by event_init() |
876 | @return 0 if successful, or -1 if an error occurred |
877 | @see event_base_loopbreak() |
878 | */ |
879 | EVENT2_EXPORT_SYMBOL |
880 | int event_base_loopcontinue(struct event_base *); |
881 | |
882 | /** |
883 | Checks if the event loop was told to exit by event_base_loopexit(). |
884 | |
885 | This function will return true for an event_base at every point after |
886 | event_loopexit() is called, until the event loop is next entered. |
887 | |
888 | @param eb the event_base structure returned by event_init() |
889 | @return true if event_base_loopexit() was called on this event base, |
890 | or 0 otherwise |
891 | @see event_base_loopexit() |
892 | @see event_base_got_break() |
893 | */ |
894 | EVENT2_EXPORT_SYMBOL |
895 | int event_base_got_exit(struct event_base *); |
896 | |
897 | /** |
898 | Checks if the event loop was told to abort immediately by event_base_loopbreak(). |
899 | |
900 | This function will return true for an event_base at every point after |
901 | event_base_loopbreak() is called, until the event loop is next entered. |
902 | |
903 | @param eb the event_base structure returned by event_init() |
904 | @return true if event_base_loopbreak() was called on this event base, |
905 | or 0 otherwise |
906 | @see event_base_loopbreak() |
907 | @see event_base_got_exit() |
908 | */ |
909 | EVENT2_EXPORT_SYMBOL |
910 | int event_base_got_break(struct event_base *); |
911 | |
912 | /** |
913 | * @name event flags |
914 | * |
915 | * Flags to pass to event_new(), event_assign(), event_pending(), and |
916 | * anything else with an argument of the form "short events" |
917 | */ |
918 | /**@{*/ |
919 | /** Indicates that a timeout has occurred. It's not necessary to pass |
920 | * this flag to event_for new()/event_assign() to get a timeout. */ |
921 | #define EV_TIMEOUT 0x01 |
922 | /** Wait for a socket or FD to become readable */ |
923 | #define EV_READ 0x02 |
924 | /** Wait for a socket or FD to become writeable */ |
925 | #define EV_WRITE 0x04 |
926 | /** Wait for a POSIX signal to be raised*/ |
927 | #define EV_SIGNAL 0x08 |
928 | /** |
929 | * Persistent event: won't get removed automatically when activated. |
930 | * |
931 | * When a persistent event with a timeout becomes activated, its timeout |
932 | * is reset to 0. |
933 | */ |
934 | #define EV_PERSIST 0x10 |
935 | /** Select edge-triggered behavior, if supported by the backend. */ |
936 | #define EV_ET 0x20 |
937 | /** |
938 | * If this option is provided, then event_del() will not block in one thread |
939 | * while waiting for the event callback to complete in another thread. |
940 | * |
941 | * To use this option safely, you may need to use event_finalize() or |
942 | * event_free_finalize() in order to safely tear down an event in a |
943 | * multithreaded application. See those functions for more information. |
944 | **/ |
945 | #define EV_FINALIZE 0x40 |
946 | /** |
947 | * Detects connection close events. You can use this to detect when a |
948 | * connection has been closed, without having to read all the pending data |
949 | * from a connection. |
950 | * |
951 | * Not all backends support EV_CLOSED. To detect or require it, use the |
952 | * feature flag EV_FEATURE_EARLY_CLOSE. |
953 | **/ |
954 | #define EV_CLOSED 0x80 |
955 | /**@}*/ |
956 | |
957 | /** |
958 | @name evtimer_* macros |
959 | |
960 | Aliases for working with one-shot timer events |
961 | If you need EV_PERSIST timer use event_*() functions. |
962 | */ |
963 | /**@{*/ |
964 | #define evtimer_assign(ev, b, cb, arg) \ |
965 | event_assign((ev), (b), -1, 0, (cb), (arg)) |
966 | #define evtimer_new(b, cb, arg) event_new((b), -1, 0, (cb), (arg)) |
967 | #define evtimer_add(ev, tv) event_add((ev), (tv)) |
968 | #define evtimer_del(ev) event_del(ev) |
969 | #define evtimer_pending(ev, tv) event_pending((ev), EV_TIMEOUT, (tv)) |
970 | #define evtimer_initialized(ev) event_initialized(ev) |
971 | /**@}*/ |
972 | |
973 | /** |
974 | @name evsignal_* macros |
975 | |
976 | Aliases for working with signal events |
977 | */ |
978 | /**@{*/ |
979 | #define evsignal_add(ev, tv) event_add((ev), (tv)) |
980 | #define evsignal_assign(ev, b, x, cb, arg) \ |
981 | event_assign((ev), (b), (x), EV_SIGNAL|EV_PERSIST, cb, (arg)) |
982 | #define evsignal_new(b, x, cb, arg) \ |
983 | event_new((b), (x), EV_SIGNAL|EV_PERSIST, (cb), (arg)) |
984 | #define evsignal_del(ev) event_del(ev) |
985 | #define evsignal_pending(ev, tv) event_pending((ev), EV_SIGNAL, (tv)) |
986 | #define evsignal_initialized(ev) event_initialized(ev) |
987 | /**@}*/ |
988 | |
989 | /** |
990 | @name evuser_* macros |
991 | |
992 | Aliases for working with user-triggered events |
993 | If you need EV_PERSIST event use event_*() functions. |
994 | */ |
995 | /**@{*/ |
996 | #define evuser_new(b, cb, arg) event_new((b), -1, 0, (cb), (arg)) |
997 | #define evuser_del(ev) event_del(ev) |
998 | #define evuser_pending(ev, tv) event_pending((ev), 0, (tv)) |
999 | #define evuser_initialized(ev) event_initialized(ev) |
1000 | #define evuser_trigger(ev) event_active((ev), 0, 0) |
1001 | /**@}*/ |
1002 | |
1003 | /** |
1004 | A callback function for an event. |
1005 | |
1006 | It receives three arguments: |
1007 | |
1008 | @param fd An fd or signal |
1009 | @param events One or more EV_* flags |
1010 | @param arg A user-supplied argument. |
1011 | |
1012 | @see event_new() |
1013 | */ |
1014 | typedef void (*event_callback_fn)(evutil_socket_t, short, void *); |
1015 | |
1016 | /** |
1017 | Return a value used to specify that the event itself must be used as the callback argument. |
1018 | |
1019 | The function event_new() takes a callback argument which is passed |
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, |
1022 | pass in the return value of event_self_cbarg() as the callback argument |
1023 | for event_new(). |
1024 | |
1025 | For example: |
1026 | <pre> |
1027 | struct event *ev = event_new(base, sock, events, callback, %event_self_cbarg()); |
1028 | </pre> |
1029 | |
1030 | For consistency with event_new(), it is possible to pass the return value |
1031 | of this function as the callback argument for event_assign() – this |
1032 | achieves the same result as passing the event in directly. |
1033 | |
1034 | @return a value to be passed as the callback argument to event_new() or |
1035 | event_assign(). |
1036 | @see event_new(), event_assign() |
1037 | */ |
1038 | EVENT2_EXPORT_SYMBOL |
1039 | void *event_self_cbarg(void); |
1040 | |
1041 | /** |
1042 | Allocate and assign a new event structure, ready to be added. |
1043 | |
1044 | The function event_new() returns a new event that can be used in |
1045 | future calls to event_add() and event_del(). The fd and events |
1046 | arguments determine which conditions will trigger the event; the |
1047 | callback and callback_arg arguments tell Libevent what to do when the |
1048 | event becomes active. |
1049 | |
1050 | If events contains one of EV_READ, EV_WRITE, or EV_READ|EV_WRITE, then |
1051 | fd is a file descriptor or socket that should get monitored for |
1052 | readiness to read, readiness to write, or readiness for either operation |
1053 | (respectively). If events contains EV_SIGNAL, then fd is a signal |
1054 | number to wait for. If events contains none of those flags, then the |
1055 | event can be triggered only by a timeout or by manual activation with |
1056 | event_active(): In this case, fd must be -1. |
1057 | |
1058 | The EV_PERSIST flag can also be passed in the events argument: it makes |
1059 | event_add() persistent until event_del() is called. |
1060 | |
1061 | The EV_ET flag is compatible with EV_READ and EV_WRITE, and supported |
1062 | only by certain backends. It tells Libevent to use edge-triggered |
1063 | events. |
1064 | |
1065 | The EV_TIMEOUT flag has no effect here. |
1066 | |
1067 | It is okay to have multiple events all listening on the same fds; but |
1068 | they must either all be edge-triggered, or all not be edge triggered. |
1069 | |
1070 | When the event becomes active, the event loop will run the provided |
1071 | callback function, with three arguments. The first will be the provided |
1072 | fd value. The second will be a bitfield of the events that triggered: |
1073 | EV_READ, EV_WRITE, or EV_SIGNAL. Here the EV_TIMEOUT flag indicates |
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 |
1076 | you provide. |
1077 | |
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. |
1080 | @param events desired events to monitor: bitfield of EV_READ, EV_WRITE, |
1081 | EV_SIGNAL, EV_PERSIST, EV_ET. |
1082 | @param callback callback function to be invoked when the event occurs |
1083 | @param callback_arg an argument to be passed to the callback function |
1084 | |
1085 | @return a newly allocated struct event that must later be freed with |
1086 | event_free() or NULL if an error occurred. |
1087 | @see event_free(), event_add(), event_del(), event_assign() |
1088 | */ |
1089 | EVENT2_EXPORT_SYMBOL |
1090 | struct event *event_new(struct event_base *, evutil_socket_t, short, event_callback_fn, void *); |
1091 | |
1092 | |
1093 | /** |
1094 | Prepare a new, already-allocated event structure to be added. |
1095 | |
1096 | The function event_assign() prepares the event structure ev to be used |
1097 | in future calls to event_add() and event_del(). Unlike event_new(), it |
1098 | doesn't allocate memory itself: it requires that you have already |
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 |
1101 | thereby create incompatibility with future versions of Libevent. |
1102 | |
1103 | The easiest way to avoid this problem is just to use event_new() and |
1104 | event_free() instead. |
1105 | |
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 |
1108 | at runtime. |
1109 | |
1110 | Note that it is NOT safe to call this function on an event that is |
1111 | active or pending. Doing so WILL corrupt internal data structures in |
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 |
1114 | or pending! |
1115 | |
1116 | The arguments for this function, and the behavior of the events that it |
1117 | makes, are as for event_new(). |
1118 | |
1119 | @param ev an event struct to be modified |
1120 | @param base the event base to which ev should be attached. |
1121 | @param fd the file descriptor to be monitored |
1122 | @param events desired events to monitor; can be EV_READ and/or EV_WRITE |
1123 | @param callback callback function to be invoked when the event occurs |
1124 | @param callback_arg an argument to be passed to the callback function |
1125 | |
1126 | @return 0 if success, or -1 on invalid arguments. |
1127 | |
1128 | @see event_new(), event_add(), event_del(), event_base_once(), |
1129 | event_get_struct_event_size() |
1130 | */ |
1131 | EVENT2_EXPORT_SYMBOL |
1132 | int event_assign(struct event *, struct event_base *, evutil_socket_t, short, event_callback_fn, void *); |
1133 | |
1134 | /** |
1135 | Deallocate a struct event * returned by event_new(). |
1136 | |
1137 | If the event is pending or active, this function makes it non-pending |
1138 | and non-active first. |
1139 | */ |
1140 | EVENT2_EXPORT_SYMBOL |
1141 | void event_free(struct event *); |
1142 | |
1143 | /** |
1144 | * Callback type for event_finalize and event_free_finalize(). |
1145 | **/ |
1146 | typedef void (*event_finalize_callback_fn)(struct event *, void *); |
1147 | /** |
1148 | @name Finalization functions |
1149 | |
1150 | These functions are used to safely tear down an event in a multithreaded |
1151 | application. If you construct your events with EV_FINALIZE to avoid |
1152 | deadlocks, you will need a way to remove an event in the certainty that |
1153 | it will definitely not be running its callback when you deallocate it |
1154 | and its callback argument. |
1155 | |
1156 | To do this, call one of event_finalize() or event_free_finalize with |
1157 | 0 for its first argument, the event to tear down as its second argument, |
1158 | and a callback function as its third argument. The callback will be |
1159 | invoked as part of the event loop, with the event's priority. |
1160 | |
1161 | After you call a finalizer function, event_add() and event_active() will |
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 |
1164 | event_set() while the finalize callback is in progress. Once the |
1165 | callback has been invoked, you should treat the event structure as |
1166 | containing uninitialized memory. |
1167 | |
1168 | The event_free_finalize() function frees the event after it's finalized; |
1169 | event_finalize() does not. |
1170 | |
1171 | A finalizer callback must not make events pending or active. It must not |
1172 | add events, activate events, or attempt to "resuscitate" the event being |
1173 | finalized in any way. |
1174 | |
1175 | @return 0 on success, -1 on failure. |
1176 | */ |
1177 | /**@{*/ |
1178 | EVENT2_EXPORT_SYMBOL |
1179 | int event_finalize(unsigned, struct event *, event_finalize_callback_fn); |
1180 | EVENT2_EXPORT_SYMBOL |
1181 | int event_free_finalize(unsigned, struct event *, event_finalize_callback_fn); |
1182 | /**@}*/ |
1183 | |
1184 | /** |
1185 | Schedule a one-time event |
1186 | |
1187 | The function event_base_once() is similar to event_new(). However, it |
1188 | schedules a callback to be called exactly once, and does not require the |
1189 | caller to prepare an event structure. |
1190 | |
1191 | Note that in Libevent 2.0 and earlier, if the event is never triggered, the |
1192 | internal memory used to hold it will never be freed. In Libevent 2.1, |
1193 | the internal memory will get freed by event_base_free() if the event |
1194 | is never triggered. The 'arg' value, however, will not get freed in either |
1195 | case--you'll need to free that on your own if you want it to go away. |
1196 | |
1197 | @param base an event_base |
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 | |
1200 | EV_WRITE, or EV_TIMEOUT |
1201 | @param callback callback function to be invoked when the event occurs |
1202 | @param arg an argument to be passed to the callback function |
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 |
1207 | */ |
1208 | EVENT2_EXPORT_SYMBOL |
1209 | int event_base_once(struct event_base *, evutil_socket_t, short, event_callback_fn, void *, const struct timeval *); |
1210 | |
1211 | /** |
1212 | Add an event to the set of pending events. |
1213 | |
1214 | The function event_add() schedules the execution of the event 'ev' when the |
1215 | condition specified by event_assign() or event_new() occurs, or when the time |
1216 | specified in timeout has elapsed. If a timeout is NULL, no timeout |
1217 | occurs and the function will only be |
1218 | called if a matching event occurs. The event in the |
1219 | ev argument must be already initialized by event_assign() or event_new() |
1220 | and may not be used |
1221 | in calls to event_assign() until it is no longer pending. |
1222 | |
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. |
1225 | |
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 |
1228 | to wait forever |
1229 | @return 0 if successful, or -1 if an error occurred |
1230 | @see event_del(), event_assign(), event_new() |
1231 | */ |
1232 | EVENT2_EXPORT_SYMBOL |
1233 | int event_add(struct event *ev, const struct timeval *timeout); |
1234 | |
1235 | /** |
1236 | Remove a timer from a pending event without removing the event itself. |
1237 | |
1238 | If the event has a scheduled timeout, this function unschedules it but |
1239 | leaves the event otherwise pending. |
1240 | |
1241 | @param ev an event struct initialized via event_assign() or event_new() |
1242 | @return 0 on success, or -1 if an error occurred. |
1243 | */ |
1244 | EVENT2_EXPORT_SYMBOL |
1245 | int event_remove_timer(struct event *ev); |
1246 | |
1247 | /** |
1248 | Remove an event from the set of monitored events. |
1249 | |
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 |
1252 | effect. |
1253 | |
1254 | @param ev an event struct to be removed from the working set |
1255 | @return 0 if successful, or -1 if an error occurred |
1256 | @see event_add() |
1257 | */ |
1258 | EVENT2_EXPORT_SYMBOL |
1259 | int event_del(struct event *); |
1260 | |
1261 | /** |
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 |
1264 | EV_FINALIZE flag. |
1265 | */ |
1266 | EVENT2_EXPORT_SYMBOL |
1267 | int event_del_noblock(struct event *ev); |
1268 | /** |
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 |
1271 | EV_FINALIZE flag. |
1272 | */ |
1273 | EVENT2_EXPORT_SYMBOL |
1274 | int event_del_block(struct event *ev); |
1275 | |
1276 | /** |
1277 | Make an event active. |
1278 | |
1279 | You can use this function on a pending or a non-pending event to make it |
1280 | active, so that its callback will be run by event_base_dispatch() or |
1281 | event_base_loop(). |
1282 | |
1283 | One common use in multithreaded programs is to wake the thread running |
1284 | event_base_loop() from another thread. |
1285 | |
1286 | @param ev an event to make active. |
1287 | @param res a set of flags to pass to the event's callback. |
1288 | @param ncalls an obsolete argument: this is ignored. |
1289 | **/ |
1290 | EVENT2_EXPORT_SYMBOL |
1291 | void event_active(struct event *ev, int res, short ncalls); |
1292 | |
1293 | /** |
1294 | Checks if a specific event is pending or scheduled. |
1295 | |
1296 | @param ev an event struct previously passed to event_add() |
1297 | @param events the requested event type; any of EV_TIMEOUT|EV_READ| |
1298 | EV_WRITE|EV_SIGNAL |
1299 | @param tv if this field is not NULL, and the event has a timeout, |
1300 | this field is set to hold the time at which the timeout will |
1301 | expire. |
1302 | |
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. |
1305 | */ |
1306 | EVENT2_EXPORT_SYMBOL |
1307 | int event_pending(const struct event *ev, short events, struct timeval *tv); |
1308 | |
1309 | /** |
1310 | If called from within the callback for an event, returns that event. |
1311 | |
1312 | The behavior of this function is not defined when called from outside the |
1313 | callback function for an event. |
1314 | */ |
1315 | EVENT2_EXPORT_SYMBOL |
1316 | struct event *event_base_get_running_event(struct event_base *base); |
1317 | |
1318 | /** |
1319 | Test if an event structure might be initialized. |
1320 | |
1321 | The event_initialized() function can be used to check if an event has been |
1322 | initialized. |
1323 | |
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 |
1326 | uninitialized memory. Thus, it should ONLY be used to distinguish an |
1327 | initialized event from zero. |
1328 | |
1329 | @param ev an event structure to be tested |
1330 | @return 1 if the structure might be initialized, or 0 if it has not been |
1331 | initialized |
1332 | */ |
1333 | EVENT2_EXPORT_SYMBOL |
1334 | int event_initialized(const struct event *ev); |
1335 | |
1336 | /** |
1337 | Get the signal number assigned to a signal event |
1338 | */ |
1339 | #define event_get_signal(ev) ((int)event_get_fd(ev)) |
1340 | |
1341 | /** |
1342 | Get the socket or signal assigned to an event, or -1 if the event has |
1343 | no socket. |
1344 | */ |
1345 | EVENT2_EXPORT_SYMBOL |
1346 | evutil_socket_t event_get_fd(const struct event *ev); |
1347 | |
1348 | /** |
1349 | Get the event_base associated with an event. |
1350 | */ |
1351 | EVENT2_EXPORT_SYMBOL |
1352 | struct event_base *event_get_base(const struct event *ev); |
1353 | |
1354 | /** |
1355 | Return the events (EV_READ, EV_WRITE, etc) assigned to an event. |
1356 | */ |
1357 | EVENT2_EXPORT_SYMBOL |
1358 | short event_get_events(const struct event *ev); |
1359 | |
1360 | /** |
1361 | Return the callback assigned to an event. |
1362 | */ |
1363 | EVENT2_EXPORT_SYMBOL |
1364 | event_callback_fn event_get_callback(const struct event *ev); |
1365 | |
1366 | /** |
1367 | Return the callback argument assigned to an event. |
1368 | */ |
1369 | EVENT2_EXPORT_SYMBOL |
1370 | void *event_get_callback_arg(const struct event *ev); |
1371 | |
1372 | /** |
1373 | Return the priority of an event. |
1374 | @see event_priority_init(), event_get_priority() |
1375 | */ |
1376 | EVENT2_EXPORT_SYMBOL |
1377 | int event_get_priority(const struct event *ev); |
1378 | |
1379 | /** |
1380 | Extract _all_ of arguments given to construct a given event. The |
1381 | event_base is copied into *base_out, the fd is copied into *fd_out, and so |
1382 | on. |
1383 | |
1384 | If any of the "_out" arguments is NULL, it will be ignored. |
1385 | */ |
1386 | EVENT2_EXPORT_SYMBOL |
1387 | void event_get_assignment(const struct event *event, |
1388 | struct event_base **base_out, evutil_socket_t *fd_out, short *events_out, |
1389 | event_callback_fn *callback_out, void **arg_out); |
1390 | |
1391 | /** |
1392 | Return the size of struct event that the Libevent library was compiled |
1393 | with. |
1394 | |
1395 | This will be NO GREATER than sizeof(struct event) if you're running with |
1396 | the same version of Libevent that your application was built with, but |
1397 | otherwise might not. |
1398 | |
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 |
1402 | versions of Libevent. |
1403 | */ |
1404 | EVENT2_EXPORT_SYMBOL |
1405 | size_t event_get_struct_event_size(void); |
1406 | |
1407 | /** |
1408 | Get the Libevent version. |
1409 | |
1410 | Note that this will give you the version of the library that you're |
1411 | currently linked against, not the version of the headers that you've |
1412 | compiled against. |
1413 | |
1414 | @return a string containing the version number of Libevent |
1415 | */ |
1416 | EVENT2_EXPORT_SYMBOL |
1417 | const char *event_get_version(void); |
1418 | |
1419 | /** |
1420 | Return a numeric representation of Libevent's version. |
1421 | |
1422 | Note that this will give you the version of the library that you're |
1423 | currently linked against, not the version of the headers you've used to |
1424 | compile. |
1425 | |
1426 | The format uses one byte each for the major, minor, and patchlevel parts of |
1427 | the version number. The low-order byte is unused. For example, version |
1428 | 2.0.1-alpha has a numeric representation of 0x02000100 |
1429 | */ |
1430 | EVENT2_EXPORT_SYMBOL |
1431 | ev_uint32_t event_get_version_number(void); |
1432 | |
1433 | /** As event_get_version, but gives the version of Libevent's headers. */ |
1434 | #define LIBEVENT_VERSION EVENT__VERSION |
1435 | /** As event_get_version_number, but gives the version number of Libevent's |
1436 | * headers. */ |
1437 | #define LIBEVENT_VERSION_NUMBER EVENT__NUMERIC_VERSION |
1438 | |
1439 | /** Largest number of priorities that Libevent can support. */ |
1440 | #define EVENT_MAX_PRIORITIES 256 |
1441 | /** |
1442 | Set the number of different event priorities |
1443 | |
1444 | By default Libevent schedules all active events with the same priority. |
1445 | However, some time it is desirable to process some events with a higher |
1446 | priority than others. For that reason, Libevent supports strict priority |
1447 | queues. Active events with a lower priority are always processed before |
1448 | events with a higher priority. |
1449 | |
1450 | The number of different priorities can be set initially with the |
1451 | event_base_priority_init() function. This function should be called |
1452 | before the first call to event_base_dispatch(). The |
1453 | event_priority_set() function can be used to assign a priority to an |
1454 | event. By default, Libevent assigns the middle priority to all events |
1455 | unless their priority is explicitly set. |
1456 | |
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 |
1460 | will not have their callbacks run until there are no events more urgent |
1461 | than them that want to be active. |
1462 | |
1463 | @param eb the event_base structure returned by event_base_new() |
1464 | @param npriorities the maximum number of priorities |
1465 | @return 0 if successful, or -1 if an error occurred |
1466 | @see event_priority_set() |
1467 | */ |
1468 | EVENT2_EXPORT_SYMBOL |
1469 | int event_base_priority_init(struct event_base *, int); |
1470 | |
1471 | /** |
1472 | Get the number of different event priorities. |
1473 | |
1474 | @param eb the event_base structure returned by event_base_new() |
1475 | @return Number of different event priorities |
1476 | @see event_base_priority_init() |
1477 | */ |
1478 | EVENT2_EXPORT_SYMBOL |
1479 | int event_base_get_npriorities(struct event_base *eb); |
1480 | |
1481 | /** |
1482 | Assign a priority to an event. |
1483 | |
1484 | @param ev an event struct |
1485 | @param priority the new priority to be assigned |
1486 | @return 0 if successful, or -1 if an error occurred |
1487 | @see event_priority_init(), event_get_priority() |
1488 | */ |
1489 | EVENT2_EXPORT_SYMBOL |
1490 | int event_priority_set(struct event *, int); |
1491 | |
1492 | /** |
1493 | Prepare an event_base to use a large number of timeouts with the same |
1494 | duration. |
1495 | |
1496 | Libevent's default scheduling algorithm is optimized for having a large |
1497 | number of timeouts with their durations more or less randomly |
1498 | distributed. But if you have a large number of timeouts that all have |
1499 | the same duration (for example, if you have a large number of |
1500 | connections that all have a 10-second timeout), then you can improve |
1501 | Libevent's performance by telling Libevent about it. |
1502 | |
1503 | To do this, call this function with the common duration. It will return a |
1504 | pointer to a different, opaque timeout value. (Don't depend on its actual |
1505 | contents!) When you use this timeout value in event_add(), Libevent will |
1506 | schedule the event more efficiently. |
1507 | |
1508 | (This optimization probably will not be worthwhile until you have thousands |
1509 | or tens of thousands of events with the same timeout.) |
1510 | */ |
1511 | EVENT2_EXPORT_SYMBOL |
1512 | const struct timeval *event_base_init_common_timeout(struct event_base *base, |
1513 | const struct timeval *duration); |
1514 | |
1515 | #if !defined(EVENT__DISABLE_MM_REPLACEMENT) || defined(EVENT_IN_DOXYGEN_) |
1516 | /** |
1517 | Override the functions that Libevent uses for memory management. |
1518 | |
1519 | Usually, Libevent uses the standard libc functions malloc, realloc, and |
1520 | free to allocate memory. Passing replacements for those functions to |
1521 | event_set_mem_functions() overrides this behavior. |
1522 | |
1523 | Note that all memory returned from Libevent will be allocated by the |
1524 | replacement functions rather than by malloc() and realloc(). Thus, if you |
1525 | have replaced those functions, it will not be appropriate to free() memory |
1526 | that you get from Libevent. Instead, you must use the free_fn replacement |
1527 | that you provided. |
1528 | |
1529 | Note also that if you are going to call this function, you should do so |
1530 | before any call to any Libevent function that does allocation. |
1531 | Otherwise, those functions will allocate their memory using malloc(), but |
1532 | then later free it using your provided free_fn. |
1533 | |
1534 | @param malloc_fn A replacement for malloc. |
1535 | @param realloc_fn A replacement for realloc |
1536 | @param free_fn A replacement for free. |
1537 | **/ |
1538 | EVENT2_EXPORT_SYMBOL |
1539 | void event_set_mem_functions( |
1540 | void *(*malloc_fn)(size_t sz), |
1541 | void *(*realloc_fn)(void *ptr, size_t sz), |
1542 | void (*free_fn)(void *ptr)); |
1543 | /** This definition is present if Libevent was built with support for |
1544 | event_set_mem_functions() */ |
1545 | #define EVENT_SET_MEM_FUNCTIONS_IMPLEMENTED |
1546 | #endif |
1547 | |
1548 | /** |
1549 | Writes a human-readable description of all inserted and/or active |
1550 | events to a provided stdio stream. |
1551 | |
1552 | This is intended for debugging; its format is not guaranteed to be the same |
1553 | between libevent versions. |
1554 | |
1555 | @param base An event_base on which to scan the events. |
1556 | @param output A stdio file to write on. |
1557 | */ |
1558 | EVENT2_EXPORT_SYMBOL |
1559 | void event_base_dump_events(struct event_base *, FILE *); |
1560 | |
1561 | |
1562 | /** |
1563 | Activates all pending events for the given fd and event mask. |
1564 | |
1565 | This function activates pending events only. Events which have not been |
1566 | added will not become active. |
1567 | |
1568 | @param base the event_base on which to activate the events. |
1569 | @param fd An fd to active events on. |
1570 | @param events One or more of EV_{READ,WRITE,TIMEOUT}. |
1571 | */ |
1572 | EVENT2_EXPORT_SYMBOL |
1573 | void event_base_active_by_fd(struct event_base *base, evutil_socket_t fd, short events); |
1574 | |
1575 | /** |
1576 | Activates all pending signals with a given signal number |
1577 | |
1578 | This function activates pending events only. Events which have not been |
1579 | added will not become active. |
1580 | |
1581 | @param base the event_base on which to activate the events. |
1582 | @param fd The signal to active events on. |
1583 | */ |
1584 | EVENT2_EXPORT_SYMBOL |
1585 | void event_base_active_by_signal(struct event_base *base, int sig); |
1586 | |
1587 | /** |
1588 | * Callback for iterating events in an event base via event_base_foreach_event |
1589 | */ |
1590 | typedef int (*event_base_foreach_event_cb)(const struct event_base *, const struct event *, void *); |
1591 | |
1592 | /** |
1593 | Iterate over all added or active events events in an event loop, and invoke |
1594 | a given callback on each one. |
1595 | |
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. |
1600 | |
1601 | event_base_foreach_event() holds a lock on the event_base() for the whole |
1602 | time it's running: slow callbacks are not advisable. |
1603 | |
1604 | Note that Libevent adds some events of its own to make pieces of its |
1605 | functionality work. You must not assume that the only events you'll |
1606 | encounter will be the ones you added yourself. |
1607 | |
1608 | The callback function must return 0 to continue iteration, or some other |
1609 | integer to stop iterating. |
1610 | |
1611 | @param base An event_base on which to scan the events. |
1612 | @param fn A callback function to receive the events. |
1613 | @param arg An argument passed to the callback function. |
1614 | @return 0 if we iterated over every event, or the value returned by the |
1615 | callback function if the loop exited early. |
1616 | */ |
1617 | EVENT2_EXPORT_SYMBOL |
1618 | int event_base_foreach_event(struct event_base *base, event_base_foreach_event_cb fn, void *arg); |
1619 | |
1620 | |
1621 | /** Sets 'tv' to the current time (as returned by gettimeofday()), |
1622 | looking at the cached value in 'base' if possible, and calling |
1623 | gettimeofday() or clock_gettime() as appropriate if there is no |
1624 | cached time. |
1625 | |
1626 | Generally, this value will only be cached while actually |
1627 | processing event callbacks, and may be very inaccurate if your |
1628 | callbacks take a long time to execute. |
1629 | |
1630 | Returns 0 on success, negative on failure. |
1631 | */ |
1632 | EVENT2_EXPORT_SYMBOL |
1633 | int event_base_gettimeofday_cached(struct event_base *base, |
1634 | struct timeval *tv); |
1635 | |
1636 | /** Update cached_tv in the 'base' to the current time |
1637 | * |
1638 | * You can use this function is useful for selectively increasing |
1639 | * the accuracy of the cached time value in 'base' during callbacks |
1640 | * that take a long time to execute. |
1641 | * |
1642 | * This function has no effect if the base is currently not in its |
1643 | * event loop, or if timeval caching is disabled via |
1644 | * EVENT_BASE_FLAG_NO_CACHE_TIME. |
1645 | * |
1646 | * @return 0 on success, -1 on failure |
1647 | */ |
1648 | EVENT2_EXPORT_SYMBOL |
1649 | int event_base_update_cache_time(struct event_base *base); |
1650 | |
1651 | /** Release up all globally-allocated resources allocated by Libevent. |
1652 | |
1653 | This function does not free developer-controlled resources like |
1654 | event_bases, events, bufferevents, listeners, and so on. It only releases |
1655 | resources like global locks that there is no other way to free. |
1656 | |
1657 | It is not actually necessary to call this function before exit: every |
1658 | resource that it frees would be released anyway on exit. It mainly exists |
1659 | so that resource-leak debugging tools don't see Libevent as holding |
1660 | resources at exit. |
1661 | |
1662 | You should only call this function when no other Libevent functions will |
1663 | be invoked -- e.g., when cleanly exiting a program. |
1664 | */ |
1665 | EVENT2_EXPORT_SYMBOL |
1666 | void libevent_global_shutdown(void); |
1667 | |
1668 | #ifdef __cplusplus |
1669 | } |
1670 | #endif |
1671 | |
1672 | #endif /* EVENT2_EVENT_H_INCLUDED_ */ |
1673 | |