OLD | NEW |
| (Empty) |
1 /* | |
2 * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> | |
3 * All rights reserved. | |
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 _EVENT_H_ | |
28 #define _EVENT_H_ | |
29 | |
30 /** @mainpage | |
31 | |
32 @section intro Introduction | |
33 | |
34 libevent is an event notification library for developing scalable network | |
35 servers. The libevent API provides a mechanism to execute a callback | |
36 function when a specific event occurs on a file descriptor or after a | |
37 timeout has been reached. Furthermore, libevent also support callbacks due | |
38 to signals or regular timeouts. | |
39 | |
40 libevent is meant to replace the event loop found in event driven network | |
41 servers. An application just needs to call event_dispatch() and then add or | |
42 remove events dynamically without having to change the event loop. | |
43 | |
44 Currently, libevent supports /dev/poll, kqueue(2), select(2), poll(2) and | |
45 epoll(4). It also has experimental support for real-time signals. The | |
46 internal event mechanism is completely independent of the exposed event API, | |
47 and a simple update of libevent can provide new functionality without having | |
48 to redesign the applications. As a result, Libevent allows for portable | |
49 application development and provides the most scalable event notification | |
50 mechanism available on an operating system. Libevent can also be used for | |
51 multi-threaded aplications; see Steven Grimm's explanation. Libevent should | |
52 compile on Linux, *BSD, Mac OS X, Solaris and Windows. | |
53 | |
54 @section usage Standard usage | |
55 | |
56 Every program that uses libevent must include the <event.h> header, and pass | |
57 the -levent flag to the linker. Before using any of the functions in the | |
58 library, you must call event_init() or event_base_new() to perform one-time | |
59 initialization of the libevent library. | |
60 | |
61 @section event Event notification | |
62 | |
63 For each file descriptor that you wish to monitor, you must declare an event | |
64 structure and call event_set() to initialize the members of the structure. | |
65 To enable notification, you add the structure to the list of monitored | |
66 events by calling event_add(). The event structure must remain allocated as | |
67 long as it is active, so it should be allocated on the heap. Finally, you | |
68 call event_dispatch() to loop and dispatch events. | |
69 | |
70 @section bufferevent I/O Buffers | |
71 | |
72 libevent provides an abstraction on top of the regular event callbacks. This | |
73 abstraction is called a buffered event. A buffered event provides input and | |
74 output buffers that get filled and drained automatically. The user of a | |
75 buffered event no longer deals directly with the I/O, but instead is reading | |
76 from input and writing to output buffers. | |
77 | |
78 Once initialized via bufferevent_new(), the bufferevent structure can be | |
79 used repeatedly with bufferevent_enable() and bufferevent_disable(). | |
80 Instead of reading and writing directly to a socket, you would call | |
81 bufferevent_read() and bufferevent_write(). | |
82 | |
83 When read enabled the bufferevent will try to read from the file descriptor | |
84 and call the read callback. The write callback is executed whenever the | |
85 output buffer is drained below the write low watermark, which is 0 by | |
86 default. | |
87 | |
88 @section timers Timers | |
89 | |
90 libevent can also be used to create timers that invoke a callback after a | |
91 certain amount of time has expired. The evtimer_set() function prepares an | |
92 event struct to be used as a timer. To activate the timer, call | |
93 evtimer_add(). Timers can be deactivated by calling evtimer_del(). | |
94 | |
95 @section timeouts Timeouts | |
96 | |
97 In addition to simple timers, libevent can assign timeout events to file | |
98 descriptors that are triggered whenever a certain amount of time has passed | |
99 with no activity on a file descriptor. The timeout_set() function | |
100 initializes an event struct for use as a timeout. Once initialized, the | |
101 event must be activated by using timeout_add(). To cancel the timeout, call | |
102 timeout_del(). | |
103 | |
104 @section evdns Asynchronous DNS resolution | |
105 | |
106 libevent provides an asynchronous DNS resolver that should be used instead | |
107 of the standard DNS resolver functions. These functions can be imported by | |
108 including the <evdns.h> header in your program. Before using any of the | |
109 resolver functions, you must call evdns_init() to initialize the library. To | |
110 convert a hostname to an IP address, you call the evdns_resolve_ipv4() | |
111 function. To perform a reverse lookup, you would call the | |
112 evdns_resolve_reverse() function. All of these functions use callbacks to | |
113 avoid blocking while the lookup is performed. | |
114 | |
115 @section evhttp Event-driven HTTP servers | |
116 | |
117 libevent provides a very simple event-driven HTTP server that can be | |
118 embedded in your program and used to service HTTP requests. | |
119 | |
120 To use this capability, you need to include the <evhttp.h> header in your | |
121 program. You create the server by calling evhttp_new(). Add addresses and | |
122 ports to listen on with evhttp_bind_socket(). You then register one or more | |
123 callbacks to handle incoming requests. Each URI can be assigned a callback | |
124 via the evhttp_set_cb() function. A generic callback function can also be | |
125 registered via evhttp_set_gencb(); this callback will be invoked if no other | |
126 callbacks have been registered for a given URI. | |
127 | |
128 @section evrpc A framework for RPC servers and clients | |
129 | |
130 libevents provides a framework for creating RPC servers and clients. It | |
131 takes care of marshaling and unmarshaling all data structures. | |
132 | |
133 @section api API Reference | |
134 | |
135 To browse the complete documentation of the libevent API, click on any of | |
136 the following links. | |
137 | |
138 event.h | |
139 The primary libevent header | |
140 | |
141 evdns.h | |
142 Asynchronous DNS resolution | |
143 | |
144 evhttp.h | |
145 An embedded libevent-based HTTP server | |
146 | |
147 evrpc.h | |
148 A framework for creating RPC servers and clients | |
149 | |
150 */ | |
151 | |
152 /** @file event.h | |
153 | |
154 A library for writing event-driven network servers | |
155 | |
156 */ | |
157 | |
158 #ifdef __cplusplus | |
159 extern "C" { | |
160 #endif | |
161 | |
162 #include "event-config.h" | |
163 #ifdef _EVENT_HAVE_SYS_TYPES_H | |
164 #include <sys/types.h> | |
165 #endif | |
166 #ifdef _EVENT_HAVE_SYS_TIME_H | |
167 #include <sys/time.h> | |
168 #endif | |
169 #ifdef _EVENT_HAVE_STDINT_H | |
170 #include <stdint.h> | |
171 #endif | |
172 #include <stdarg.h> | |
173 | |
174 /* For int types. */ | |
175 #include "evutil.h" | |
176 | |
177 #ifdef WIN32 | |
178 #define WIN32_LEAN_AND_MEAN | |
179 #include <windows.h> | |
180 #undef WIN32_LEAN_AND_MEAN | |
181 typedef unsigned char u_char; | |
182 typedef unsigned short u_short; | |
183 #endif | |
184 | |
185 #define EVLIST_TIMEOUT 0x01 | |
186 #define EVLIST_INSERTED 0x02 | |
187 #define EVLIST_SIGNAL 0x04 | |
188 #define EVLIST_ACTIVE 0x08 | |
189 #define EVLIST_INTERNAL 0x10 | |
190 #define EVLIST_INIT 0x80 | |
191 | |
192 /* EVLIST_X_ Private space: 0x1000-0xf000 */ | |
193 #define EVLIST_ALL (0xf000 | 0x9f) | |
194 | |
195 #define EV_TIMEOUT 0x01 | |
196 #define EV_READ 0x02 | |
197 #define EV_WRITE 0x04 | |
198 #define EV_SIGNAL 0x08 | |
199 #define EV_PERSIST 0x10 /* Persistant event */ | |
200 | |
201 /* Fix so that ppl dont have to run with <sys/queue.h> */ | |
202 #ifndef TAILQ_ENTRY | |
203 #define _EVENT_DEFINED_TQENTRY | |
204 #define TAILQ_ENTRY(type) \ | |
205 struct { \ | |
206 struct type *tqe_next; /* next element */ \ | |
207 struct type **tqe_prev; /* address of previous next element */ \ | |
208 } | |
209 #endif /* !TAILQ_ENTRY */ | |
210 | |
211 struct event_base; | |
212 #ifndef EVENT_NO_STRUCT | |
213 struct event { | |
214 TAILQ_ENTRY (event) ev_next; | |
215 TAILQ_ENTRY (event) ev_active_next; | |
216 TAILQ_ENTRY (event) ev_signal_next; | |
217 unsigned int min_heap_idx; /* for managing timeouts */ | |
218 | |
219 struct event_base *ev_base; | |
220 | |
221 int ev_fd; | |
222 short ev_events; | |
223 short ev_ncalls; | |
224 short *ev_pncalls; /* Allows deletes in callback */ | |
225 | |
226 struct timeval ev_timeout; | |
227 | |
228 int ev_pri; /* smaller numbers are higher priority */ | |
229 | |
230 void (*ev_callback)(int, short, void *arg); | |
231 void *ev_arg; | |
232 | |
233 int ev_res; /* result passed to event callback */ | |
234 int ev_flags; | |
235 }; | |
236 #else | |
237 struct event; | |
238 #endif | |
239 | |
240 #define EVENT_SIGNAL(ev) (int)(ev)->ev_fd | |
241 #define EVENT_FD(ev) (int)(ev)->ev_fd | |
242 | |
243 /* | |
244 * Key-Value pairs. Can be used for HTTP headers but also for | |
245 * query argument parsing. | |
246 */ | |
247 struct evkeyval { | |
248 TAILQ_ENTRY(evkeyval) next; | |
249 | |
250 char *key; | |
251 char *value; | |
252 }; | |
253 | |
254 #ifdef _EVENT_DEFINED_TQENTRY | |
255 #undef TAILQ_ENTRY | |
256 struct event_list; | |
257 struct evkeyvalq; | |
258 #undef _EVENT_DEFINED_TQENTRY | |
259 #else | |
260 TAILQ_HEAD (event_list, event); | |
261 TAILQ_HEAD (evkeyvalq, evkeyval); | |
262 #endif /* _EVENT_DEFINED_TQENTRY */ | |
263 | |
264 /** | |
265 Initialize the event API. | |
266 | |
267 Use event_base_new() to initialize a new event base, but does not set | |
268 the current_base global. If using only event_base_new(), each event | |
269 added must have an event base set with event_base_set() | |
270 | |
271 @see event_base_set(), event_base_free(), event_init() | |
272 */ | |
273 struct event_base *event_base_new(void); | |
274 | |
275 /** | |
276 Initialize the event API. | |
277 | |
278 The event API needs to be initialized with event_init() before it can be | |
279 used. Sets the current_base global representing the default base for | |
280 events that have no base associated with them. | |
281 | |
282 @see event_base_set(), event_base_new() | |
283 */ | |
284 struct event_base *event_init(void); | |
285 | |
286 /** | |
287 Reinitialized the event base after a fork | |
288 | |
289 Some event mechanisms do not survive across fork. The event base needs | |
290 to be reinitialized with the event_reinit() function. | |
291 | |
292 @param base the event base that needs to be re-initialized | |
293 @return 0 if successful, or -1 if some events could not be re-added. | |
294 @see event_base_new(), event_init() | |
295 */ | |
296 int event_reinit(struct event_base *base); | |
297 | |
298 /** | |
299 Loop to process events. | |
300 | |
301 In order to process events, an application needs to call | |
302 event_dispatch(). This function only returns on error, and should | |
303 replace the event core of the application program. | |
304 | |
305 @see event_base_dispatch() | |
306 */ | |
307 int event_dispatch(void); | |
308 | |
309 | |
310 /** | |
311 Threadsafe event dispatching loop. | |
312 | |
313 @param eb the event_base structure returned by event_init() | |
314 @see event_init(), event_dispatch() | |
315 */ | |
316 int event_base_dispatch(struct event_base *); | |
317 | |
318 | |
319 /** | |
320 Get the kernel event notification mechanism used by libevent. | |
321 | |
322 @param eb the event_base structure returned by event_base_new() | |
323 @return a string identifying the kernel event mechanism (kqueue, epoll, etc.) | |
324 */ | |
325 const char *event_base_get_method(struct event_base *); | |
326 | |
327 | |
328 /** | |
329 Deallocate all memory associated with an event_base, and free the base. | |
330 | |
331 Note that this function will not close any fds or free any memory passed | |
332 to event_set as the argument to callback. | |
333 | |
334 @param eb an event_base to be freed | |
335 */ | |
336 void event_base_free(struct event_base *); | |
337 | |
338 | |
339 #define _EVENT_LOG_DEBUG 0 | |
340 #define _EVENT_LOG_MSG 1 | |
341 #define _EVENT_LOG_WARN 2 | |
342 #define _EVENT_LOG_ERR 3 | |
343 typedef void (*event_log_cb)(int severity, const char *msg); | |
344 /** | |
345 Redirect libevent's log messages. | |
346 | |
347 @param cb a function taking two arguments: an integer severity between | |
348 _EVENT_LOG_DEBUG and _EVENT_LOG_ERR, and a string. If cb is NULL, | |
349 then the default log is used. | |
350 */ | |
351 void event_set_log_callback(event_log_cb cb); | |
352 | |
353 /** | |
354 Associate a different event base with an event. | |
355 | |
356 @param eb the event base | |
357 @param ev the event | |
358 */ | |
359 int event_base_set(struct event_base *, struct event *); | |
360 | |
361 /** | |
362 event_loop() flags | |
363 */ | |
364 /*@{*/ | |
365 #define EVLOOP_ONCE 0x01 /**< Block at most once. */ | |
366 #define EVLOOP_NONBLOCK 0x02 /**< Do not block. */ | |
367 /*@}*/ | |
368 | |
369 /** | |
370 Handle events. | |
371 | |
372 This is a more flexible version of event_dispatch(). | |
373 | |
374 @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK | |
375 @return 0 if successful, -1 if an error occurred, or 1 if no events were | |
376 registered. | |
377 @see event_loopexit(), event_base_loop() | |
378 */ | |
379 int event_loop(int); | |
380 | |
381 /** | |
382 Handle events (threadsafe version). | |
383 | |
384 This is a more flexible version of event_base_dispatch(). | |
385 | |
386 @param eb the event_base structure returned by event_init() | |
387 @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK | |
388 @return 0 if successful, -1 if an error occurred, or 1 if no events were | |
389 registered. | |
390 @see event_loopexit(), event_base_loop() | |
391 */ | |
392 int event_base_loop(struct event_base *, int); | |
393 | |
394 /** | |
395 Exit the event loop after the specified time. | |
396 | |
397 The next event_loop() iteration after the given timer expires will | |
398 complete normally (handling all queued events) then exit without | |
399 blocking for events again. | |
400 | |
401 Subsequent invocations of event_loop() will proceed normally. | |
402 | |
403 @param tv the amount of time after which the loop should terminate. | |
404 @return 0 if successful, or -1 if an error occurred | |
405 @see event_loop(), event_base_loop(), event_base_loopexit() | |
406 */ | |
407 int event_loopexit(const struct timeval *); | |
408 | |
409 | |
410 /** | |
411 Exit the event loop after the specified time (threadsafe variant). | |
412 | |
413 The next event_base_loop() iteration after the given timer expires will | |
414 complete normally (handling all queued events) then exit without | |
415 blocking for events again. | |
416 | |
417 Subsequent invocations of event_base_loop() will proceed normally. | |
418 | |
419 @param eb the event_base structure returned by event_init() | |
420 @param tv the amount of time after which the loop should terminate. | |
421 @return 0 if successful, or -1 if an error occurred | |
422 @see event_loopexit() | |
423 */ | |
424 int event_base_loopexit(struct event_base *, const struct timeval *); | |
425 | |
426 /** | |
427 Abort the active event_loop() immediately. | |
428 | |
429 event_loop() will abort the loop after the next event is completed; | |
430 event_loopbreak() is typically invoked from this event's callback. | |
431 This behavior is analogous to the "break;" statement. | |
432 | |
433 Subsequent invocations of event_loop() will proceed normally. | |
434 | |
435 @return 0 if successful, or -1 if an error occurred | |
436 @see event_base_loopbreak(), event_loopexit() | |
437 */ | |
438 int event_loopbreak(void); | |
439 | |
440 /** | |
441 Abort the active event_base_loop() immediately. | |
442 | |
443 event_base_loop() will abort the loop after the next event is completed; | |
444 event_base_loopbreak() is typically invoked from this event's callback. | |
445 This behavior is analogous to the "break;" statement. | |
446 | |
447 Subsequent invocations of event_loop() will proceed normally. | |
448 | |
449 @param eb the event_base structure returned by event_init() | |
450 @return 0 if successful, or -1 if an error occurred | |
451 @see event_base_loopexit | |
452 */ | |
453 int event_base_loopbreak(struct event_base *); | |
454 | |
455 | |
456 /** | |
457 Add a timer event. | |
458 | |
459 @param ev the event struct | |
460 @param tv timeval struct | |
461 */ | |
462 #define evtimer_add(ev, tv) event_add(ev, tv) | |
463 | |
464 | |
465 /** | |
466 Define a timer event. | |
467 | |
468 @param ev event struct to be modified | |
469 @param cb callback function | |
470 @param arg argument that will be passed to the callback function | |
471 */ | |
472 #define evtimer_set(ev, cb, arg) event_set(ev, -1, 0, cb, arg) | |
473 | |
474 | |
475 /** | |
476 * Delete a timer event. | |
477 * | |
478 * @param ev the event struct to be disabled | |
479 */ | |
480 #define evtimer_del(ev) event_del(ev) | |
481 #define evtimer_pending(ev, tv) event_pending(ev, EV_TIMEOUT, tv) | |
482 #define evtimer_initialized(ev) ((ev)->ev_flags & EVLIST_INIT) | |
483 | |
484 /** | |
485 * Add a timeout event. | |
486 * | |
487 * @param ev the event struct to be disabled | |
488 * @param tv the timeout value, in seconds | |
489 */ | |
490 #define timeout_add(ev, tv) event_add(ev, tv) | |
491 | |
492 | |
493 /** | |
494 * Define a timeout event. | |
495 * | |
496 * @param ev the event struct to be defined | |
497 * @param cb the callback to be invoked when the timeout expires | |
498 * @param arg the argument to be passed to the callback | |
499 */ | |
500 #define timeout_set(ev, cb, arg) event_set(ev, -1, 0, cb, arg) | |
501 | |
502 | |
503 /** | |
504 * Disable a timeout event. | |
505 * | |
506 * @param ev the timeout event to be disabled | |
507 */ | |
508 #define timeout_del(ev) event_del(ev) | |
509 | |
510 #define timeout_pending(ev, tv) event_pending(ev, EV_TIMEOUT, tv) | |
511 #define timeout_initialized(ev) ((ev)->ev_flags & EVLIST_INIT) | |
512 | |
513 #define signal_add(ev, tv) event_add(ev, tv) | |
514 #define signal_set(ev, x, cb, arg) \ | |
515 event_set(ev, x, EV_SIGNAL|EV_PERSIST, cb, arg) | |
516 #define signal_del(ev) event_del(ev) | |
517 #define signal_pending(ev, tv) event_pending(ev, EV_SIGNAL, tv) | |
518 #define signal_initialized(ev) ((ev)->ev_flags & EVLIST_INIT) | |
519 | |
520 /** | |
521 Prepare an event structure to be added. | |
522 | |
523 The function event_set() prepares the event structure ev to be used in | |
524 future calls to event_add() and event_del(). The event will be prepared to | |
525 call the function specified by the fn argument with an int argument | |
526 indicating the file descriptor, a short argument indicating the type of | |
527 event, and a void * argument given in the arg argument. The fd indicates | |
528 the file descriptor that should be monitored for events. The events can be | |
529 either EV_READ, EV_WRITE, or both. Indicating that an application can read | |
530 or write from the file descriptor respectively without blocking. | |
531 | |
532 The function fn will be called with the file descriptor that triggered the | |
533 event and the type of event which will be either EV_TIMEOUT, EV_SIGNAL, | |
534 EV_READ, or EV_WRITE. The additional flag EV_PERSIST makes an event_add() | |
535 persistent until event_del() has been called. | |
536 | |
537 @param ev an event struct to be modified | |
538 @param fd the file descriptor to be monitored | |
539 @param event desired events to monitor; can be EV_READ and/or EV_WRITE | |
540 @param fn callback function to be invoked when the event occurs | |
541 @param arg an argument to be passed to the callback function | |
542 | |
543 @see event_add(), event_del(), event_once() | |
544 | |
545 */ | |
546 void event_set(struct event *, int, short, void (*)(int, short, void *), void *)
; | |
547 | |
548 /** | |
549 Schedule a one-time event to occur. | |
550 | |
551 The function event_once() is similar to event_set(). However, it schedules | |
552 a callback to be called exactly once and does not require the caller to | |
553 prepare an event structure. | |
554 | |
555 @param fd a file descriptor to monitor | |
556 @param events event(s) to monitor; can be any of EV_TIMEOUT | EV_READ | | |
557 EV_WRITE | |
558 @param callback callback function to be invoked when the event occurs | |
559 @param arg an argument to be passed to the callback function | |
560 @param timeout the maximum amount of time to wait for the event, or NULL | |
561 to wait forever | |
562 @return 0 if successful, or -1 if an error occurred | |
563 @see event_set() | |
564 | |
565 */ | |
566 int event_once(int, short, void (*)(int, short, void *), void *, | |
567 const struct timeval *); | |
568 | |
569 | |
570 /** | |
571 Schedule a one-time event (threadsafe variant) | |
572 | |
573 The function event_base_once() is similar to event_set(). However, it | |
574 schedules a callback to be called exactly once and does not require the | |
575 caller to prepare an event structure. | |
576 | |
577 @param base an event_base returned by event_init() | |
578 @param fd a file descriptor to monitor | |
579 @param events event(s) to monitor; can be any of EV_TIMEOUT | EV_READ | | |
580 EV_WRITE | |
581 @param callback callback function to be invoked when the event occurs | |
582 @param arg an argument to be passed to the callback function | |
583 @param timeout the maximum amount of time to wait for the event, or NULL | |
584 to wait forever | |
585 @return 0 if successful, or -1 if an error occurred | |
586 @see event_once() | |
587 */ | |
588 int event_base_once(struct event_base *base, int fd, short events, | |
589 void (*callback)(int, short, void *), void *arg, | |
590 const struct timeval *timeout); | |
591 | |
592 | |
593 /** | |
594 Add an event to the set of monitored events. | |
595 | |
596 The function event_add() schedules the execution of the ev event when the | |
597 event specified in event_set() occurs or in at least the time specified in | |
598 the tv. If tv is NULL, no timeout occurs and the function will only be | |
599 called if a matching event occurs on the file descriptor. The event in the | |
600 ev argument must be already initialized by event_set() and may not be used | |
601 in calls to event_set() until it has timed out or been removed with | |
602 event_del(). If the event in the ev argument already has a scheduled | |
603 timeout, the old timeout will be replaced by the new one. | |
604 | |
605 @param ev an event struct initialized via event_set() | |
606 @param timeout the maximum amount of time to wait for the event, or NULL | |
607 to wait forever | |
608 @return 0 if successful, or -1 if an error occurred | |
609 @see event_del(), event_set() | |
610 */ | |
611 int event_add(struct event *ev, const struct timeval *timeout); | |
612 | |
613 | |
614 /** | |
615 Remove an event from the set of monitored events. | |
616 | |
617 The function event_del() will cancel the event in the argument ev. If the | |
618 event has already executed or has never been added the call will have no | |
619 effect. | |
620 | |
621 @param ev an event struct to be removed from the working set | |
622 @return 0 if successful, or -1 if an error occurred | |
623 @see event_add() | |
624 */ | |
625 int event_del(struct event *); | |
626 | |
627 void event_active(struct event *, int, short); | |
628 | |
629 | |
630 /** | |
631 Checks if a specific event is pending or scheduled. | |
632 | |
633 @param ev an event struct previously passed to event_add() | |
634 @param event the requested event type; any of EV_TIMEOUT|EV_READ| | |
635 EV_WRITE|EV_SIGNAL | |
636 @param tv an alternate timeout (FIXME - is this true?) | |
637 | |
638 @return 1 if the event is pending, or 0 if the event has not occurred | |
639 | |
640 */ | |
641 int event_pending(struct event *ev, short event, struct timeval *tv); | |
642 | |
643 | |
644 /** | |
645 Test if an event structure has been initialized. | |
646 | |
647 The event_initialized() macro can be used to check if an event has been | |
648 initialized. | |
649 | |
650 @param ev an event structure to be tested | |
651 @return 1 if the structure has been initialized, or 0 if it has not been | |
652 initialized | |
653 */ | |
654 #ifdef WIN32 | |
655 #define event_initialized(ev) ((ev)->ev_flags & EVLIST_INIT && (ev)->e
v_fd != (int)INVALID_HANDLE_VALUE) | |
656 #else | |
657 #define event_initialized(ev) ((ev)->ev_flags & EVLIST_INIT) | |
658 #endif | |
659 | |
660 | |
661 /** | |
662 Get the libevent version number. | |
663 | |
664 @return a string containing the version number of libevent | |
665 */ | |
666 const char *event_get_version(void); | |
667 | |
668 | |
669 /** | |
670 Get the kernel event notification mechanism used by libevent. | |
671 | |
672 @return a string identifying the kernel event mechanism (kqueue, epoll, etc.) | |
673 */ | |
674 const char *event_get_method(void); | |
675 | |
676 | |
677 /** | |
678 Set the number of different event priorities. | |
679 | |
680 By default libevent schedules all active events with the same priority. | |
681 However, some time it is desirable to process some events with a higher | |
682 priority than others. For that reason, libevent supports strict priority | |
683 queues. Active events with a lower priority are always processed before | |
684 events with a higher priority. | |
685 | |
686 The number of different priorities can be set initially with the | |
687 event_priority_init() function. This function should be called before the | |
688 first call to event_dispatch(). The event_priority_set() function can be | |
689 used to assign a priority to an event. By default, libevent assigns the | |
690 middle priority to all events unless their priority is explicitly set. | |
691 | |
692 @param npriorities the maximum number of priorities | |
693 @return 0 if successful, or -1 if an error occurred | |
694 @see event_base_priority_init(), event_priority_set() | |
695 | |
696 */ | |
697 int event_priority_init(int); | |
698 | |
699 | |
700 /** | |
701 Set the number of different event priorities (threadsafe variant). | |
702 | |
703 See the description of event_priority_init() for more information. | |
704 | |
705 @param eb the event_base structure returned by event_init() | |
706 @param npriorities the maximum number of priorities | |
707 @return 0 if successful, or -1 if an error occurred | |
708 @see event_priority_init(), event_priority_set() | |
709 */ | |
710 int event_base_priority_init(struct event_base *, int); | |
711 | |
712 | |
713 /** | |
714 Assign a priority to an event. | |
715 | |
716 @param ev an event struct | |
717 @param priority the new priority to be assigned | |
718 @return 0 if successful, or -1 if an error occurred | |
719 @see event_priority_init() | |
720 */ | |
721 int event_priority_set(struct event *, int); | |
722 | |
723 | |
724 /* These functions deal with buffering input and output */ | |
725 | |
726 struct evbuffer { | |
727 u_char *buffer; | |
728 u_char *orig_buffer; | |
729 | |
730 size_t misalign; | |
731 size_t totallen; | |
732 size_t off; | |
733 | |
734 void (*cb)(struct evbuffer *, size_t, size_t, void *); | |
735 void *cbarg; | |
736 }; | |
737 | |
738 /* Just for error reporting - use other constants otherwise */ | |
739 #define EVBUFFER_READ 0x01 | |
740 #define EVBUFFER_WRITE 0x02 | |
741 #define EVBUFFER_EOF 0x10 | |
742 #define EVBUFFER_ERROR 0x20 | |
743 #define EVBUFFER_TIMEOUT 0x40 | |
744 | |
745 struct bufferevent; | |
746 typedef void (*evbuffercb)(struct bufferevent *, void *); | |
747 typedef void (*everrorcb)(struct bufferevent *, short what, void *); | |
748 | |
749 struct event_watermark { | |
750 size_t low; | |
751 size_t high; | |
752 }; | |
753 | |
754 #ifndef EVENT_NO_STRUCT | |
755 struct bufferevent { | |
756 struct event_base *ev_base; | |
757 | |
758 struct event ev_read; | |
759 struct event ev_write; | |
760 | |
761 struct evbuffer *input; | |
762 struct evbuffer *output; | |
763 | |
764 struct event_watermark wm_read; | |
765 struct event_watermark wm_write; | |
766 | |
767 evbuffercb readcb; | |
768 evbuffercb writecb; | |
769 everrorcb errorcb; | |
770 void *cbarg; | |
771 | |
772 int timeout_read; /* in seconds */ | |
773 int timeout_write; /* in seconds */ | |
774 | |
775 short enabled; /* events that are currently enabled */ | |
776 }; | |
777 #endif | |
778 | |
779 /** | |
780 Create a new bufferevent. | |
781 | |
782 libevent provides an abstraction on top of the regular event callbacks. | |
783 This abstraction is called a buffered event. A buffered event provides | |
784 input and output buffers that get filled and drained automatically. The | |
785 user of a buffered event no longer deals directly with the I/O, but | |
786 instead is reading from input and writing to output buffers. | |
787 | |
788 Once initialized, the bufferevent structure can be used repeatedly with | |
789 bufferevent_enable() and bufferevent_disable(). | |
790 | |
791 When read enabled the bufferevent will try to read from the file descriptor | |
792 and call the read callback. The write callback is executed whenever the | |
793 output buffer is drained below the write low watermark, which is 0 by | |
794 default. | |
795 | |
796 If multiple bases are in use, bufferevent_base_set() must be called before | |
797 enabling the bufferevent for the first time. | |
798 | |
799 @param fd the file descriptor from which data is read and written to. | |
800 This file descriptor is not allowed to be a pipe(2). | |
801 @param readcb callback to invoke when there is data to be read, or NULL if | |
802 no callback is desired | |
803 @param writecb callback to invoke when the file descriptor is ready for | |
804 writing, or NULL if no callback is desired | |
805 @param errorcb callback to invoke when there is an error on the file | |
806 descriptor | |
807 @param cbarg an argument that will be supplied to each of the callbacks | |
808 (readcb, writecb, and errorcb) | |
809 @return a pointer to a newly allocated bufferevent struct, or NULL if an | |
810 error occurred | |
811 @see bufferevent_base_set(), bufferevent_free() | |
812 */ | |
813 struct bufferevent *bufferevent_new(int fd, | |
814 evbuffercb readcb, evbuffercb writecb, everrorcb errorcb, void *cbarg); | |
815 | |
816 | |
817 /** | |
818 Assign a bufferevent to a specific event_base. | |
819 | |
820 @param base an event_base returned by event_init() | |
821 @param bufev a bufferevent struct returned by bufferevent_new() | |
822 @return 0 if successful, or -1 if an error occurred | |
823 @see bufferevent_new() | |
824 */ | |
825 int bufferevent_base_set(struct event_base *base, struct bufferevent *bufev); | |
826 | |
827 | |
828 /** | |
829 Assign a priority to a bufferevent. | |
830 | |
831 @param bufev a bufferevent struct | |
832 @param pri the priority to be assigned | |
833 @return 0 if successful, or -1 if an error occurred | |
834 */ | |
835 int bufferevent_priority_set(struct bufferevent *bufev, int pri); | |
836 | |
837 | |
838 /** | |
839 Deallocate the storage associated with a bufferevent structure. | |
840 | |
841 @param bufev the bufferevent structure to be freed. | |
842 */ | |
843 void bufferevent_free(struct bufferevent *bufev); | |
844 | |
845 | |
846 /** | |
847 Changes the callbacks for a bufferevent. | |
848 | |
849 @param bufev the bufferevent object for which to change callbacks | |
850 @param readcb callback to invoke when there is data to be read, or NULL if | |
851 no callback is desired | |
852 @param writecb callback to invoke when the file descriptor is ready for | |
853 writing, or NULL if no callback is desired | |
854 @param errorcb callback to invoke when there is an error on the file | |
855 descriptor | |
856 @param cbarg an argument that will be supplied to each of the callbacks | |
857 (readcb, writecb, and errorcb) | |
858 @see bufferevent_new() | |
859 */ | |
860 void bufferevent_setcb(struct bufferevent *bufev, | |
861 evbuffercb readcb, evbuffercb writecb, everrorcb errorcb, void *cbarg); | |
862 | |
863 /** | |
864 Changes the file descriptor on which the bufferevent operates. | |
865 | |
866 @param bufev the bufferevent object for which to change the file descriptor | |
867 @param fd the file descriptor to operate on | |
868 */ | |
869 void bufferevent_setfd(struct bufferevent *bufev, int fd); | |
870 | |
871 /** | |
872 Write data to a bufferevent buffer. | |
873 | |
874 The bufferevent_write() function can be used to write data to the file | |
875 descriptor. The data is appended to the output buffer and written to the | |
876 descriptor automatically as it becomes available for writing. | |
877 | |
878 @param bufev the bufferevent to be written to | |
879 @param data a pointer to the data to be written | |
880 @param size the length of the data, in bytes | |
881 @return 0 if successful, or -1 if an error occurred | |
882 @see bufferevent_write_buffer() | |
883 */ | |
884 int bufferevent_write(struct bufferevent *bufev, | |
885 const void *data, size_t size); | |
886 | |
887 | |
888 /** | |
889 Write data from an evbuffer to a bufferevent buffer. The evbuffer is | |
890 being drained as a result. | |
891 | |
892 @param bufev the bufferevent to be written to | |
893 @param buf the evbuffer to be written | |
894 @return 0 if successful, or -1 if an error occurred | |
895 @see bufferevent_write() | |
896 */ | |
897 int bufferevent_write_buffer(struct bufferevent *bufev, struct evbuffer *buf); | |
898 | |
899 | |
900 /** | |
901 Read data from a bufferevent buffer. | |
902 | |
903 The bufferevent_read() function is used to read data from the input buffer. | |
904 | |
905 @param bufev the bufferevent to be read from | |
906 @param data pointer to a buffer that will store the data | |
907 @param size the size of the data buffer, in bytes | |
908 @return the amount of data read, in bytes. | |
909 */ | |
910 size_t bufferevent_read(struct bufferevent *bufev, void *data, size_t size); | |
911 | |
912 /** | |
913 Enable a bufferevent. | |
914 | |
915 @param bufev the bufferevent to be enabled | |
916 @param event any combination of EV_READ | EV_WRITE. | |
917 @return 0 if successful, or -1 if an error occurred | |
918 @see bufferevent_disable() | |
919 */ | |
920 int bufferevent_enable(struct bufferevent *bufev, short event); | |
921 | |
922 | |
923 /** | |
924 Disable a bufferevent. | |
925 | |
926 @param bufev the bufferevent to be disabled | |
927 @param event any combination of EV_READ | EV_WRITE. | |
928 @return 0 if successful, or -1 if an error occurred | |
929 @see bufferevent_enable() | |
930 */ | |
931 int bufferevent_disable(struct bufferevent *bufev, short event); | |
932 | |
933 | |
934 /** | |
935 Set the read and write timeout for a buffered event. | |
936 | |
937 @param bufev the bufferevent to be modified | |
938 @param timeout_read the read timeout | |
939 @param timeout_write the write timeout | |
940 */ | |
941 void bufferevent_settimeout(struct bufferevent *bufev, | |
942 int timeout_read, int timeout_write); | |
943 | |
944 | |
945 /** | |
946 Sets the watermarks for read and write events. | |
947 | |
948 On input, a bufferevent does not invoke the user read callback unless | |
949 there is at least low watermark data in the buffer. If the read buffer | |
950 is beyond the high watermark, the buffevent stops reading from the network. | |
951 | |
952 On output, the user write callback is invoked whenever the buffered data | |
953 falls below the low watermark. | |
954 | |
955 @param bufev the bufferevent to be modified | |
956 @param events EV_READ, EV_WRITE or both | |
957 @param lowmark the lower watermark to set | |
958 @param highmark the high watermark to set | |
959 */ | |
960 | |
961 void bufferevent_setwatermark(struct bufferevent *bufev, short events, | |
962 size_t lowmark, size_t highmark); | |
963 | |
964 #define EVBUFFER_LENGTH(x) (x)->off | |
965 #define EVBUFFER_DATA(x) (x)->buffer | |
966 #define EVBUFFER_INPUT(x) (x)->input | |
967 #define EVBUFFER_OUTPUT(x) (x)->output | |
968 | |
969 | |
970 /** | |
971 Allocate storage for a new evbuffer. | |
972 | |
973 @return a pointer to a newly allocated evbuffer struct, or NULL if an error | |
974 occurred | |
975 */ | |
976 struct evbuffer *evbuffer_new(void); | |
977 | |
978 | |
979 /** | |
980 Deallocate storage for an evbuffer. | |
981 | |
982 @param pointer to the evbuffer to be freed | |
983 */ | |
984 void evbuffer_free(struct evbuffer *); | |
985 | |
986 | |
987 /** | |
988 Expands the available space in an event buffer. | |
989 | |
990 Expands the available space in the event buffer to at least datlen | |
991 | |
992 @param buf the event buffer to be expanded | |
993 @param datlen the new minimum length requirement | |
994 @return 0 if successful, or -1 if an error occurred | |
995 */ | |
996 int evbuffer_expand(struct evbuffer *, size_t); | |
997 | |
998 | |
999 /** | |
1000 Append data to the end of an evbuffer. | |
1001 | |
1002 @param buf the event buffer to be appended to | |
1003 @param data pointer to the beginning of the data buffer | |
1004 @param datlen the number of bytes to be copied from the data buffer | |
1005 */ | |
1006 int evbuffer_add(struct evbuffer *, const void *, size_t); | |
1007 | |
1008 | |
1009 | |
1010 /** | |
1011 Read data from an event buffer and drain the bytes read. | |
1012 | |
1013 @param buf the event buffer to be read from | |
1014 @param data the destination buffer to store the result | |
1015 @param datlen the maximum size of the destination buffer | |
1016 @return the number of bytes read | |
1017 */ | |
1018 int evbuffer_remove(struct evbuffer *, void *, size_t); | |
1019 | |
1020 | |
1021 /** | |
1022 * Read a single line from an event buffer. | |
1023 * | |
1024 * Reads a line terminated by either '\r\n', '\n\r' or '\r' or '\n'. | |
1025 * The returned buffer needs to be freed by the caller. | |
1026 * | |
1027 * @param buffer the evbuffer to read from | |
1028 * @return pointer to a single line, or NULL if an error occurred | |
1029 */ | |
1030 char *evbuffer_readline(struct evbuffer *); | |
1031 | |
1032 | |
1033 /** Used to tell evbuffer_readln what kind of line-ending to look for. | |
1034 */ | |
1035 enum evbuffer_eol_style { | |
1036 /** Any sequence of CR and LF characters is acceptable as an EOL. */ | |
1037 EVBUFFER_EOL_ANY, | |
1038 /** An EOL is an LF, optionally preceded by a CR. This style is | |
1039 * most useful for implementing text-based internet protocols. */ | |
1040 EVBUFFER_EOL_CRLF, | |
1041 /** An EOL is a CR followed by an LF. */ | |
1042 EVBUFFER_EOL_CRLF_STRICT, | |
1043 /** An EOL is a LF. */ | |
1044 EVBUFFER_EOL_LF | |
1045 }; | |
1046 | |
1047 /** | |
1048 * Read a single line from an event buffer. | |
1049 * | |
1050 * Reads a line terminated by an EOL as determined by the evbuffer_eol_style | |
1051 * argument. Returns a newly allocated nul-terminated string; the caller must | |
1052 * free the returned value. The EOL is not included in the returned string. | |
1053 * | |
1054 * @param buffer the evbuffer to read from | |
1055 * @param n_read_out if non-NULL, points to a size_t that is set to the | |
1056 * number of characters in the returned string. This is useful for | |
1057 * strings that can contain NUL characters. | |
1058 * @param eol_style the style of line-ending to use. | |
1059 * @return pointer to a single line, or NULL if an error occurred | |
1060 */ | |
1061 char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out, | |
1062 enum evbuffer_eol_style eol_style); | |
1063 | |
1064 | |
1065 /** | |
1066 Move data from one evbuffer into another evbuffer. | |
1067 | |
1068 This is a destructive add. The data from one buffer moves into | |
1069 the other buffer. The destination buffer is expanded as needed. | |
1070 | |
1071 @param outbuf the output buffer | |
1072 @param inbuf the input buffer | |
1073 @return 0 if successful, or -1 if an error occurred | |
1074 */ | |
1075 int evbuffer_add_buffer(struct evbuffer *, struct evbuffer *); | |
1076 | |
1077 | |
1078 /** | |
1079 Append a formatted string to the end of an evbuffer. | |
1080 | |
1081 @param buf the evbuffer that will be appended to | |
1082 @param fmt a format string | |
1083 @param ... arguments that will be passed to printf(3) | |
1084 @return The number of bytes added if successful, or -1 if an error occurred. | |
1085 */ | |
1086 int evbuffer_add_printf(struct evbuffer *, const char *fmt, ...) | |
1087 #ifdef __GNUC__ | |
1088 __attribute__((format(printf, 2, 3))) | |
1089 #endif | |
1090 ; | |
1091 | |
1092 | |
1093 /** | |
1094 Append a va_list formatted string to the end of an evbuffer. | |
1095 | |
1096 @param buf the evbuffer that will be appended to | |
1097 @param fmt a format string | |
1098 @param ap a varargs va_list argument array that will be passed to vprintf(3) | |
1099 @return The number of bytes added if successful, or -1 if an error occurred. | |
1100 */ | |
1101 int evbuffer_add_vprintf(struct evbuffer *, const char *fmt, va_list ap); | |
1102 | |
1103 | |
1104 /** | |
1105 Remove a specified number of bytes data from the beginning of an evbuffer. | |
1106 | |
1107 @param buf the evbuffer to be drained | |
1108 @param len the number of bytes to drain from the beginning of the buffer | |
1109 */ | |
1110 void evbuffer_drain(struct evbuffer *, size_t); | |
1111 | |
1112 | |
1113 /** | |
1114 Write the contents of an evbuffer to a file descriptor. | |
1115 | |
1116 The evbuffer will be drained after the bytes have been successfully written. | |
1117 | |
1118 @param buffer the evbuffer to be written and drained | |
1119 @param fd the file descriptor to be written to | |
1120 @return the number of bytes written, or -1 if an error occurred | |
1121 @see evbuffer_read() | |
1122 */ | |
1123 int evbuffer_write(struct evbuffer *, int); | |
1124 | |
1125 | |
1126 /** | |
1127 Read from a file descriptor and store the result in an evbuffer. | |
1128 | |
1129 @param buf the evbuffer to store the result | |
1130 @param fd the file descriptor to read from | |
1131 @param howmuch the number of bytes to be read | |
1132 @return the number of bytes read, or -1 if an error occurred | |
1133 @see evbuffer_write() | |
1134 */ | |
1135 int evbuffer_read(struct evbuffer *, int, int); | |
1136 | |
1137 | |
1138 /** | |
1139 Find a string within an evbuffer. | |
1140 | |
1141 @param buffer the evbuffer to be searched | |
1142 @param what the string to be searched for | |
1143 @param len the length of the search string | |
1144 @return a pointer to the beginning of the search string, or NULL if the search
failed. | |
1145 */ | |
1146 u_char *evbuffer_find(struct evbuffer *, const u_char *, size_t); | |
1147 | |
1148 /** | |
1149 Set a callback to invoke when the evbuffer is modified. | |
1150 | |
1151 @param buffer the evbuffer to be monitored | |
1152 @param cb the callback function to invoke when the evbuffer is modified | |
1153 @param cbarg an argument to be provided to the callback function | |
1154 */ | |
1155 void evbuffer_setcb(struct evbuffer *, void (*)(struct evbuffer *, size_t, size_
t, void *), void *); | |
1156 | |
1157 /* | |
1158 * Marshaling tagged data - We assume that all tags are inserted in their | |
1159 * numeric order - so that unknown tags will always be higher than the | |
1160 * known ones - and we can just ignore the end of an event buffer. | |
1161 */ | |
1162 | |
1163 void evtag_init(void); | |
1164 | |
1165 void evtag_marshal(struct evbuffer *evbuf, ev_uint32_t tag, const void *data, | |
1166 ev_uint32_t len); | |
1167 | |
1168 /** | |
1169 Encode an integer and store it in an evbuffer. | |
1170 | |
1171 We encode integer's by nibbles; the first nibble contains the number | |
1172 of significant nibbles - 1; this allows us to encode up to 64-bit | |
1173 integers. This function is byte-order independent. | |
1174 | |
1175 @param evbuf evbuffer to store the encoded number | |
1176 @param number a 32-bit integer | |
1177 */ | |
1178 void encode_int(struct evbuffer *evbuf, ev_uint32_t number); | |
1179 | |
1180 void evtag_marshal_int(struct evbuffer *evbuf, ev_uint32_t tag, | |
1181 ev_uint32_t integer); | |
1182 | |
1183 void evtag_marshal_string(struct evbuffer *buf, ev_uint32_t tag, | |
1184 const char *string); | |
1185 | |
1186 void evtag_marshal_timeval(struct evbuffer *evbuf, ev_uint32_t tag, | |
1187 struct timeval *tv); | |
1188 | |
1189 int evtag_unmarshal(struct evbuffer *src, ev_uint32_t *ptag, | |
1190 struct evbuffer *dst); | |
1191 int evtag_peek(struct evbuffer *evbuf, ev_uint32_t *ptag); | |
1192 int evtag_peek_length(struct evbuffer *evbuf, ev_uint32_t *plength); | |
1193 int evtag_payload_length(struct evbuffer *evbuf, ev_uint32_t *plength); | |
1194 int evtag_consume(struct evbuffer *evbuf); | |
1195 | |
1196 int evtag_unmarshal_int(struct evbuffer *evbuf, ev_uint32_t need_tag, | |
1197 ev_uint32_t *pinteger); | |
1198 | |
1199 int evtag_unmarshal_fixed(struct evbuffer *src, ev_uint32_t need_tag, | |
1200 void *data, size_t len); | |
1201 | |
1202 int evtag_unmarshal_string(struct evbuffer *evbuf, ev_uint32_t need_tag, | |
1203 char **pstring); | |
1204 | |
1205 int evtag_unmarshal_timeval(struct evbuffer *evbuf, ev_uint32_t need_tag, | |
1206 struct timeval *ptv); | |
1207 | |
1208 #ifdef __cplusplus | |
1209 } | |
1210 #endif | |
1211 | |
1212 #endif /* _EVENT_H_ */ | |
OLD | NEW |