1 /* 2 * Copyright (c) 2000-2007 Niels Provos <provos (at) 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
