Annotation of embedaddon/libevent/event.h, revision 1.1.1.1
1.1 misho 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)->ev_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_ */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to event.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libevent