• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 /**
1034   Move data from one evbuffer into another evbuffer.
1035 
1036   This is a destructive add.  The data from one buffer moves into
1037   the other buffer. The destination buffer is expanded as needed.
1038 
1039   @param outbuf the output buffer
1040   @param inbuf the input buffer
1041   @return 0 if successful, or -1 if an error occurred
1042  */
1043 int evbuffer_add_buffer(struct evbuffer *, struct evbuffer *);
1044 
1045 
1046 /**
1047   Append a formatted string to the end of an evbuffer.
1048 
1049   @param buf the evbuffer that will be appended to
1050   @param fmt a format string
1051   @param ... arguments that will be passed to printf(3)
1052   @return The number of bytes added if successful, or -1 if an error occurred.
1053  */
1054 int evbuffer_add_printf(struct evbuffer *, const char *fmt, ...)
1055 #ifdef __GNUC__
1056   __attribute__((format(printf, 2, 3)))
1057 #endif
1058 ;
1059 
1060 
1061 /**
1062   Append a va_list formatted string to the end of an evbuffer.
1063 
1064   @param buf the evbuffer that will be appended to
1065   @param fmt a format string
1066   @param ap a varargs va_list argument array that will be passed to vprintf(3)
1067   @return The number of bytes added if successful, or -1 if an error occurred.
1068  */
1069 int evbuffer_add_vprintf(struct evbuffer *, const char *fmt, va_list ap);
1070 
1071 
1072 /**
1073   Remove a specified number of bytes data from the beginning of an evbuffer.
1074 
1075   @param buf the evbuffer to be drained
1076   @param len the number of bytes to drain from the beginning of the buffer
1077  */
1078 void evbuffer_drain(struct evbuffer *, size_t);
1079 
1080 
1081 /**
1082   Write the contents of an evbuffer to a file descriptor.
1083 
1084   The evbuffer will be drained after the bytes have been successfully written.
1085 
1086   @param buffer the evbuffer to be written and drained
1087   @param fd the file descriptor to be written to
1088   @return the number of bytes written, or -1 if an error occurred
1089   @see evbuffer_read()
1090  */
1091 int evbuffer_write(struct evbuffer *, int);
1092 
1093 
1094 /**
1095   Read from a file descriptor and store the result in an evbuffer.
1096 
1097   @param buf the evbuffer to store the result
1098   @param fd the file descriptor to read from
1099   @param howmuch the number of bytes to be read
1100   @return the number of bytes read, or -1 if an error occurred
1101   @see evbuffer_write()
1102  */
1103 int evbuffer_read(struct evbuffer *, int, int);
1104 
1105 
1106 /**
1107   Find a string within an evbuffer.
1108 
1109   @param buffer the evbuffer to be searched
1110   @param what the string to be searched for
1111   @param len the length of the search string
1112   @return a pointer to the beginning of the search string, or NULL if the search failed.
1113  */
1114 u_char *evbuffer_find(struct evbuffer *, const u_char *, size_t);
1115 
1116 /**
1117   Set a callback to invoke when the evbuffer is modified.
1118 
1119   @param buffer the evbuffer to be monitored
1120   @param cb the callback function to invoke when the evbuffer is modified
1121   @param cbarg an argument to be provided to the callback function
1122  */
1123 void evbuffer_setcb(struct evbuffer *, void (*)(struct evbuffer *, size_t, size_t, void *), void *);
1124 
1125 /*
1126  * Marshaling tagged data - We assume that all tags are inserted in their
1127  * numeric order - so that unknown tags will always be higher than the
1128  * known ones - and we can just ignore the end of an event buffer.
1129  */
1130 
1131 void evtag_init(void);
1132 
1133 void evtag_marshal(struct evbuffer *evbuf, ev_uint32_t tag, const void *data,
1134     ev_uint32_t len);
1135 
1136 /**
1137   Encode an integer and store it in an evbuffer.
1138 
1139   We encode integer's by nibbles; the first nibble contains the number
1140   of significant nibbles - 1;  this allows us to encode up to 64-bit
1141   integers.  This function is byte-order independent.
1142 
1143   @param evbuf evbuffer to store the encoded number
1144   @param number a 32-bit integer
1145  */
1146 void encode_int(struct evbuffer *evbuf, ev_uint32_t number);
1147 
1148 void evtag_marshal_int(struct evbuffer *evbuf, ev_uint32_t tag,
1149     ev_uint32_t integer);
1150 
1151 void evtag_marshal_string(struct evbuffer *buf, ev_uint32_t tag,
1152     const char *string);
1153 
1154 void evtag_marshal_timeval(struct evbuffer *evbuf, ev_uint32_t tag,
1155     struct timeval *tv);
1156 
1157 int evtag_unmarshal(struct evbuffer *src, ev_uint32_t *ptag,
1158     struct evbuffer *dst);
1159 int evtag_peek(struct evbuffer *evbuf, ev_uint32_t *ptag);
1160 int evtag_peek_length(struct evbuffer *evbuf, ev_uint32_t *plength);
1161 int evtag_payload_length(struct evbuffer *evbuf, ev_uint32_t *plength);
1162 int evtag_consume(struct evbuffer *evbuf);
1163 
1164 int evtag_unmarshal_int(struct evbuffer *evbuf, ev_uint32_t need_tag,
1165     ev_uint32_t *pinteger);
1166 
1167 int evtag_unmarshal_fixed(struct evbuffer *src, ev_uint32_t need_tag,
1168     void *data, size_t len);
1169 
1170 int evtag_unmarshal_string(struct evbuffer *evbuf, ev_uint32_t need_tag,
1171     char **pstring);
1172 
1173 int evtag_unmarshal_timeval(struct evbuffer *evbuf, ev_uint32_t need_tag,
1174     struct timeval *ptv);
1175 
1176 #ifdef __cplusplus
1177 }
1178 #endif
1179 
1180 #endif /* _EVENT_H_ */
1181