Annotation of embedaddon/libevent/event.h, revision 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