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 #define EVLOOP_PRECISE 0x08 /**< Try to implement more precise timeouts. */ 368 /*@}*/ 369 370 /** 371 Handle events. 372 373 This is a more flexible version of event_dispatch(). 374 375 @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK 376 @return 0 if successful, -1 if an error occurred, or 1 if no events were 377 registered. 378 @see event_loopexit(), event_base_loop() 379 */ 380 int event_loop(int); 381 382 /** 383 Handle events (threadsafe version). 384 385 This is a more flexible version of event_base_dispatch(). 386 387 @param eb the event_base structure returned by event_init() 388 @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK 389 @return 0 if successful, -1 if an error occurred, or 1 if no events were 390 registered. 391 @see event_loopexit(), event_base_loop() 392 */ 393 int event_base_loop(struct event_base *, int); 394 395 /** 396 Exit the event loop after the specified time. 397 398 The next event_loop() iteration after the given timer expires will 399 complete normally (handling all queued events) then exit without 400 blocking for events again. 401 402 Subsequent invocations of event_loop() will proceed normally. 403 404 @param tv the amount of time after which the loop should terminate. 405 @return 0 if successful, or -1 if an error occurred 406 @see event_loop(), event_base_loop(), event_base_loopexit() 407 */ 408 int event_loopexit(const struct timeval *); 409 410 411 /** 412 Exit the event loop after the specified time (threadsafe variant). 413 414 The next event_base_loop() iteration after the given timer expires will 415 complete normally (handling all queued events) then exit without 416 blocking for events again. 417 418 Subsequent invocations of event_base_loop() will proceed normally. 419 420 @param eb the event_base structure returned by event_init() 421 @param tv the amount of time after which the loop should terminate. 422 @return 0 if successful, or -1 if an error occurred 423 @see event_loopexit() 424 */ 425 int event_base_loopexit(struct event_base *, const struct timeval *); 426 427 /** 428 Abort the active event_loop() immediately. 429 430 event_loop() will abort the loop after the next event is completed; 431 event_loopbreak() is typically invoked from this event's callback. 432 This behavior is analogous to the "break;" statement. 433 434 Subsequent invocations of event_loop() will proceed normally. 435 436 @return 0 if successful, or -1 if an error occurred 437 @see event_base_loopbreak(), event_loopexit() 438 */ 439 int event_loopbreak(void); 440 441 /** 442 Abort the active event_base_loop() immediately. 443 444 event_base_loop() will abort the loop after the next event is completed; 445 event_base_loopbreak() is typically invoked from this event's callback. 446 This behavior is analogous to the "break;" statement. 447 448 Subsequent invocations of event_loop() will proceed normally. 449 450 @param eb the event_base structure returned by event_init() 451 @return 0 if successful, or -1 if an error occurred 452 @see event_base_loopexit 453 */ 454 int event_base_loopbreak(struct event_base *); 455 456 457 /** 458 Add a timer event. 459 460 @param ev the event struct 461 @param tv timeval struct 462 */ 463 #define evtimer_add(ev, tv) event_add(ev, tv) 464 465 466 /** 467 Define a timer event. 468 469 @param ev event struct to be modified 470 @param cb callback function 471 @param arg argument that will be passed to the callback function 472 */ 473 #define evtimer_set(ev, cb, arg) event_set(ev, -1, 0, cb, arg) 474 475 476 /** 477 * Delete a timer event. 478 * 479 * @param ev the event struct to be disabled 480 */ 481 #define evtimer_del(ev) event_del(ev) 482 #define evtimer_pending(ev, tv) event_pending(ev, EV_TIMEOUT, tv) 483 #define evtimer_initialized(ev) ((ev)->ev_flags & EVLIST_INIT) 484 485 /** 486 * Add a timeout event. 487 * 488 * @param ev the event struct to be disabled 489 * @param tv the timeout value, in seconds 490 */ 491 #define timeout_add(ev, tv) event_add(ev, tv) 492 493 494 /** 495 * Define a timeout event. 496 * 497 * @param ev the event struct to be defined 498 * @param cb the callback to be invoked when the timeout expires 499 * @param arg the argument to be passed to the callback 500 */ 501 #define timeout_set(ev, cb, arg) event_set(ev, -1, 0, cb, arg) 502 503 504 /** 505 * Disable a timeout event. 506 * 507 * @param ev the timeout event to be disabled 508 */ 509 #define timeout_del(ev) event_del(ev) 510 511 #define timeout_pending(ev, tv) event_pending(ev, EV_TIMEOUT, tv) 512 #define timeout_initialized(ev) ((ev)->ev_flags & EVLIST_INIT) 513 514 #define signal_add(ev, tv) event_add(ev, tv) 515 #define signal_set(ev, x, cb, arg) \ 516 event_set(ev, x, EV_SIGNAL|EV_PERSIST, cb, arg) 517 #define signal_del(ev) event_del(ev) 518 #define signal_pending(ev, tv) event_pending(ev, EV_SIGNAL, tv) 519 #define signal_initialized(ev) ((ev)->ev_flags & EVLIST_INIT) 520 521 /** 522 Prepare an event structure to be added. 523 524 The function event_set() prepares the event structure ev to be used in 525 future calls to event_add() and event_del(). The event will be prepared to 526 call the function specified by the fn argument with an int argument 527 indicating the file descriptor, a short argument indicating the type of 528 event, and a void * argument given in the arg argument. The fd indicates 529 the file descriptor that should be monitored for events. The events can be 530 either EV_READ, EV_WRITE, or both. Indicating that an application can read 531 or write from the file descriptor respectively without blocking. 532 533 The function fn will be called with the file descriptor that triggered the 534 event and the type of event which will be either EV_TIMEOUT, EV_SIGNAL, 535 EV_READ, or EV_WRITE. The additional flag EV_PERSIST makes an event_add() 536 persistent until event_del() has been called. 537 538 @param ev an event struct to be modified 539 @param fd the file descriptor to be monitored 540 @param event desired events to monitor; can be EV_READ and/or EV_WRITE 541 @param fn callback function to be invoked when the event occurs 542 @param arg an argument to be passed to the callback function 543 544 @see event_add(), event_del(), event_once() 545 546 */ 547 void event_set(struct event *, int, short, void (*)(int, short, void *), void *); 548 549 /** 550 Schedule a one-time event to occur. 551 552 The function event_once() is similar to event_set(). However, it schedules 553 a callback to be called exactly once and does not require the caller to 554 prepare an event structure. 555 556 @param fd a file descriptor to monitor 557 @param events event(s) to monitor; can be any of EV_TIMEOUT | EV_READ | 558 EV_WRITE 559 @param callback callback function to be invoked when the event occurs 560 @param arg an argument to be passed to the callback function 561 @param timeout the maximum amount of time to wait for the event, or NULL 562 to wait forever 563 @return 0 if successful, or -1 if an error occurred 564 @see event_set() 565 566 */ 567 int event_once(int, short, void (*)(int, short, void *), void *, 568 const struct timeval *); 569 570 571 /** 572 Schedule a one-time event (threadsafe variant) 573 574 The function event_base_once() is similar to event_set(). However, it 575 schedules a callback to be called exactly once and does not require the 576 caller to prepare an event structure. 577 578 @param base an event_base returned by event_init() 579 @param fd a file descriptor to monitor 580 @param events event(s) to monitor; can be any of EV_TIMEOUT | EV_READ | 581 EV_WRITE 582 @param callback callback function to be invoked when the event occurs 583 @param arg an argument to be passed to the callback function 584 @param timeout the maximum amount of time to wait for the event, or NULL 585 to wait forever 586 @return 0 if successful, or -1 if an error occurred 587 @see event_once() 588 */ 589 int event_base_once(struct event_base *base, int fd, short events, 590 void (*callback)(int, short, void *), void *arg, 591 const struct timeval *timeout); 592 593 594 /** 595 Add an event to the set of monitored events. 596 597 The function event_add() schedules the execution of the ev event when the 598 event specified in event_set() occurs or in at least the time specified in 599 the tv. If tv is NULL, no timeout occurs and the function will only be 600 called if a matching event occurs on the file descriptor. The event in the 601 ev argument must be already initialized by event_set() and may not be used 602 in calls to event_set() until it has timed out or been removed with 603 event_del(). If the event in the ev argument already has a scheduled 604 timeout, the old timeout will be replaced by the new one. 605 606 @param ev an event struct initialized via event_set() 607 @param timeout the maximum amount of time to wait for the event, or NULL 608 to wait forever 609 @return 0 if successful, or -1 if an error occurred 610 @see event_del(), event_set() 611 */ 612 int event_add(struct event *ev, const struct timeval *timeout); 613 614 615 /** 616 Remove an event from the set of monitored events. 617 618 The function event_del() will cancel the event in the argument ev. If the 619 event has already executed or has never been added the call will have no 620 effect. 621 622 @param ev an event struct to be removed from the working set 623 @return 0 if successful, or -1 if an error occurred 624 @see event_add() 625 */ 626 int event_del(struct event *); 627 628 void event_active(struct event *, int, short); 629 630 631 /** 632 Checks if a specific event is pending or scheduled. 633 634 @param ev an event struct previously passed to event_add() 635 @param event the requested event type; any of EV_TIMEOUT|EV_READ| 636 EV_WRITE|EV_SIGNAL 637 @param tv an alternate timeout (FIXME - is this true?) 638 639 @return 1 if the event is pending, or 0 if the event has not occurred 640 641 */ 642 int event_pending(struct event *ev, short event, struct timeval *tv); 643 644 645 /** 646 Test if an event structure has been initialized. 647 648 The event_initialized() macro can be used to check if an event has been 649 initialized. 650 651 @param ev an event structure to be tested 652 @return 1 if the structure has been initialized, or 0 if it has not been 653 initialized 654 */ 655 #ifdef WIN32 656 #define event_initialized(ev) ((ev)->ev_flags & EVLIST_INIT && (ev)->ev_fd != (int)INVALID_HANDLE_VALUE) 657 #else 658 #define event_initialized(ev) ((ev)->ev_flags & EVLIST_INIT) 659 #endif 660 661 662 /** 663 Get the libevent version number. 664 665 @return a string containing the version number of libevent 666 */ 667 const char *event_get_version(void); 668 669 670 /** 671 Get the kernel event notification mechanism used by libevent. 672 673 @return a string identifying the kernel event mechanism (kqueue, epoll, etc.) 674 */ 675 const char *event_get_method(void); 676 677 678 /** 679 Set the number of different event priorities. 680 681 By default libevent schedules all active events with the same priority. 682 However, some time it is desirable to process some events with a higher 683 priority than others. For that reason, libevent supports strict priority 684 queues. Active events with a lower priority are always processed before 685 events with a higher priority. 686 687 The number of different priorities can be set initially with the 688 event_priority_init() function. This function should be called before the 689 first call to event_dispatch(). The event_priority_set() function can be 690 used to assign a priority to an event. By default, libevent assigns the 691 middle priority to all events unless their priority is explicitly set. 692 693 @param npriorities the maximum number of priorities 694 @return 0 if successful, or -1 if an error occurred 695 @see event_base_priority_init(), event_priority_set() 696 697 */ 698 int event_priority_init(int); 699 700 701 /** 702 Set the number of different event priorities (threadsafe variant). 703 704 See the description of event_priority_init() for more information. 705 706 @param eb the event_base structure returned by event_init() 707 @param npriorities the maximum number of priorities 708 @return 0 if successful, or -1 if an error occurred 709 @see event_priority_init(), event_priority_set() 710 */ 711 int event_base_priority_init(struct event_base *, int); 712 713 714 /** 715 Assign a priority to an event. 716 717 @param ev an event struct 718 @param priority the new priority to be assigned 719 @return 0 if successful, or -1 if an error occurred 720 @see event_priority_init() 721 */ 722 int event_priority_set(struct event *, int); 723 724 725 /* These functions deal with buffering input and output */ 726 727 struct evbuffer { 728 u_char *buffer; 729 u_char *orig_buffer; 730 731 size_t misalign; 732 size_t totallen; 733 size_t off; 734 735 void (*cb)(struct evbuffer *, size_t, size_t, void *); 736 void *cbarg; 737 }; 738 739 /* Just for error reporting - use other constants otherwise */ 740 #define EVBUFFER_READ 0x01 741 #define EVBUFFER_WRITE 0x02 742 #define EVBUFFER_EOF 0x10 743 #define EVBUFFER_ERROR 0x20 744 #define EVBUFFER_TIMEOUT 0x40 745 746 struct bufferevent; 747 typedef void (*evbuffercb)(struct bufferevent *, void *); 748 typedef void (*everrorcb)(struct bufferevent *, short what, void *); 749 750 struct event_watermark { 751 size_t low; 752 size_t high; 753 }; 754 755 #ifndef EVENT_NO_STRUCT 756 struct bufferevent { 757 struct event_base *ev_base; 758 759 struct event ev_read; 760 struct event ev_write; 761 762 struct evbuffer *input; 763 struct evbuffer *output; 764 765 struct event_watermark wm_read; 766 struct event_watermark wm_write; 767 768 evbuffercb readcb; 769 evbuffercb writecb; 770 everrorcb errorcb; 771 void *cbarg; 772 773 int timeout_read; /* in seconds */ 774 int timeout_write; /* in seconds */ 775 776 short enabled; /* events that are currently enabled */ 777 }; 778 #endif 779 780 /** 781 Create a new bufferevent. 782 783 libevent provides an abstraction on top of the regular event callbacks. 784 This abstraction is called a buffered event. A buffered event provides 785 input and output buffers that get filled and drained automatically. The 786 user of a buffered event no longer deals directly with the I/O, but 787 instead is reading from input and writing to output buffers. 788 789 Once initialized, the bufferevent structure can be used repeatedly with 790 bufferevent_enable() and bufferevent_disable(). 791 792 When read enabled the bufferevent will try to read from the file descriptor 793 and call the read callback. The write callback is executed whenever the 794 output buffer is drained below the write low watermark, which is 0 by 795 default. 796 797 If multiple bases are in use, bufferevent_base_set() must be called before 798 enabling the bufferevent for the first time. 799 800 @param fd the file descriptor from which data is read and written to. 801 This file descriptor is not allowed to be a pipe(2). 802 @param readcb callback to invoke when there is data to be read, or NULL if 803 no callback is desired 804 @param writecb callback to invoke when the file descriptor is ready for 805 writing, or NULL if no callback is desired 806 @param errorcb callback to invoke when there is an error on the file 807 descriptor 808 @param cbarg an argument that will be supplied to each of the callbacks 809 (readcb, writecb, and errorcb) 810 @return a pointer to a newly allocated bufferevent struct, or NULL if an 811 error occurred 812 @see bufferevent_base_set(), bufferevent_free() 813 */ 814 struct bufferevent *bufferevent_new(int fd, 815 evbuffercb readcb, evbuffercb writecb, everrorcb errorcb, void *cbarg); 816 817 818 /** 819 Assign a bufferevent to a specific event_base. 820 821 @param base an event_base returned by event_init() 822 @param bufev a bufferevent struct returned by bufferevent_new() 823 @return 0 if successful, or -1 if an error occurred 824 @see bufferevent_new() 825 */ 826 int bufferevent_base_set(struct event_base *base, struct bufferevent *bufev); 827 828 829 /** 830 Assign a priority to a bufferevent. 831 832 @param bufev a bufferevent struct 833 @param pri the priority to be assigned 834 @return 0 if successful, or -1 if an error occurred 835 */ 836 int bufferevent_priority_set(struct bufferevent *bufev, int pri); 837 838 839 /** 840 Deallocate the storage associated with a bufferevent structure. 841 842 @param bufev the bufferevent structure to be freed. 843 */ 844 void bufferevent_free(struct bufferevent *bufev); 845 846 847 /** 848 Changes the callbacks for a bufferevent. 849 850 @param bufev the bufferevent object for which to change callbacks 851 @param readcb callback to invoke when there is data to be read, or NULL if 852 no callback is desired 853 @param writecb callback to invoke when the file descriptor is ready for 854 writing, or NULL if no callback is desired 855 @param errorcb callback to invoke when there is an error on the file 856 descriptor 857 @param cbarg an argument that will be supplied to each of the callbacks 858 (readcb, writecb, and errorcb) 859 @see bufferevent_new() 860 */ 861 void bufferevent_setcb(struct bufferevent *bufev, 862 evbuffercb readcb, evbuffercb writecb, everrorcb errorcb, void *cbarg); 863 864 /** 865 Changes the file descriptor on which the bufferevent operates. 866 867 @param bufev the bufferevent object for which to change the file descriptor 868 @param fd the file descriptor to operate on 869 */ 870 void bufferevent_setfd(struct bufferevent *bufev, int fd); 871 872 /** 873 Write data to a bufferevent buffer. 874 875 The bufferevent_write() function can be used to write data to the file 876 descriptor. The data is appended to the output buffer and written to the 877 descriptor automatically as it becomes available for writing. 878 879 @param bufev the bufferevent to be written to 880 @param data a pointer to the data to be written 881 @param size the length of the data, in bytes 882 @return 0 if successful, or -1 if an error occurred 883 @see bufferevent_write_buffer() 884 */ 885 int bufferevent_write(struct bufferevent *bufev, 886 const void *data, size_t size); 887 888 889 /** 890 Write data from an evbuffer to a bufferevent buffer. The evbuffer is 891 being drained as a result. 892 893 @param bufev the bufferevent to be written to 894 @param buf the evbuffer to be written 895 @return 0 if successful, or -1 if an error occurred 896 @see bufferevent_write() 897 */ 898 int bufferevent_write_buffer(struct bufferevent *bufev, struct evbuffer *buf); 899 900 901 /** 902 Read data from a bufferevent buffer. 903 904 The bufferevent_read() function is used to read data from the input buffer. 905 906 @param bufev the bufferevent to be read from 907 @param data pointer to a buffer that will store the data 908 @param size the size of the data buffer, in bytes 909 @return the amount of data read, in bytes. 910 */ 911 size_t bufferevent_read(struct bufferevent *bufev, void *data, size_t size); 912 913 /** 914 Enable a bufferevent. 915 916 @param bufev the bufferevent to be enabled 917 @param event any combination of EV_READ | EV_WRITE. 918 @return 0 if successful, or -1 if an error occurred 919 @see bufferevent_disable() 920 */ 921 int bufferevent_enable(struct bufferevent *bufev, short event); 922 923 924 /** 925 Disable a bufferevent. 926 927 @param bufev the bufferevent to be disabled 928 @param event any combination of EV_READ | EV_WRITE. 929 @return 0 if successful, or -1 if an error occurred 930 @see bufferevent_enable() 931 */ 932 int bufferevent_disable(struct bufferevent *bufev, short event); 933 934 935 /** 936 Set the read and write timeout for a buffered event. 937 938 @param bufev the bufferevent to be modified 939 @param timeout_read the read timeout 940 @param timeout_write the write timeout 941 */ 942 void bufferevent_settimeout(struct bufferevent *bufev, 943 int timeout_read, int timeout_write); 944 945 946 /** 947 Sets the watermarks for read and write events. 948 949 On input, a bufferevent does not invoke the user read callback unless 950 there is at least low watermark data in the buffer. If the read buffer 951 is beyond the high watermark, the buffevent stops reading from the network. 952 953 On output, the user write callback is invoked whenever the buffered data 954 falls below the low watermark. 955 956 @param bufev the bufferevent to be modified 957 @param events EV_READ, EV_WRITE or both 958 @param lowmark the lower watermark to set 959 @param highmark the high watermark to set 960 */ 961 962 void bufferevent_setwatermark(struct bufferevent *bufev, short events, 963 size_t lowmark, size_t highmark); 964 965 #define EVBUFFER_LENGTH(x) (x)->off 966 #define EVBUFFER_DATA(x) (x)->buffer 967 #define EVBUFFER_INPUT(x) (x)->input 968 #define EVBUFFER_OUTPUT(x) (x)->output 969 970 971 /** 972 Allocate storage for a new evbuffer. 973 974 @return a pointer to a newly allocated evbuffer struct, or NULL if an error 975 occurred 976 */ 977 struct evbuffer *evbuffer_new(void); 978 979 980 /** 981 Deallocate storage for an evbuffer. 982 983 @param pointer to the evbuffer to be freed 984 */ 985 void evbuffer_free(struct evbuffer *); 986 987 988 /** 989 Expands the available space in an event buffer. 990 991 Expands the available space in the event buffer to at least datlen 992 993 @param buf the event buffer to be expanded 994 @param datlen the new minimum length requirement 995 @return 0 if successful, or -1 if an error occurred 996 */ 997 int evbuffer_expand(struct evbuffer *, size_t); 998 999 1000 /** 1001 Append data to the end of an evbuffer. 1002 1003 @param buf the event buffer to be appended to 1004 @param data pointer to the beginning of the data buffer 1005 @param datlen the number of bytes to be copied from the data buffer 1006 */ 1007 int evbuffer_add(struct evbuffer *, const void *, size_t); 1008 1009 1010 1011 /** 1012 Read data from an event buffer and drain the bytes read. 1013 1014 @param buf the event buffer to be read from 1015 @param data the destination buffer to store the result 1016 @param datlen the maximum size of the destination buffer 1017 @return the number of bytes read 1018 */ 1019 int evbuffer_remove(struct evbuffer *, void *, size_t); 1020 1021 1022 /** 1023 * Read a single line from an event buffer. 1024 * 1025 * Reads a line terminated by either '\r\n', '\n\r' or '\r' or '\n'. 1026 * The returned buffer needs to be freed by the caller. 1027 * 1028 * @param buffer the evbuffer to read from 1029 * @return pointer to a single line, or NULL if an error occurred 1030 */ 1031 char *evbuffer_readline(struct evbuffer *); 1032 1033 1034 /** Used to tell evbuffer_readln what kind of line-ending to look for. 1035 */ 1036 enum evbuffer_eol_style { 1037 /** Any sequence of CR and LF characters is acceptable as an EOL. */ 1038 EVBUFFER_EOL_ANY, 1039 /** An EOL is an LF, optionally preceded by a CR. This style is 1040 * most useful for implementing text-based internet protocols. */ 1041 EVBUFFER_EOL_CRLF, 1042 /** An EOL is a CR followed by an LF. */ 1043 EVBUFFER_EOL_CRLF_STRICT, 1044 /** An EOL is a LF. */ 1045 EVBUFFER_EOL_LF 1046 }; 1047 1048 /** 1049 * Read a single line from an event buffer. 1050 * 1051 * Reads a line terminated by an EOL as determined by the evbuffer_eol_style 1052 * argument. Returns a newly allocated nul-terminated string; the caller must 1053 * free the returned value. The EOL is not included in the returned string. 1054 * 1055 * @param buffer the evbuffer to read from 1056 * @param n_read_out if non-NULL, points to a size_t that is set to the 1057 * number of characters in the returned string. This is useful for 1058 * strings that can contain NUL characters. 1059 * @param eol_style the style of line-ending to use. 1060 * @return pointer to a single line, or NULL if an error occurred 1061 */ 1062 char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out, 1063 enum evbuffer_eol_style eol_style); 1064 1065 1066 /** 1067 Move data from one evbuffer into another evbuffer. 1068 1069 This is a destructive add. The data from one buffer moves into 1070 the other buffer. The destination buffer is expanded as needed. 1071 1072 @param outbuf the output buffer 1073 @param inbuf the input buffer 1074 @return 0 if successful, or -1 if an error occurred 1075 */ 1076 int evbuffer_add_buffer(struct evbuffer *, struct evbuffer *); 1077 1078 1079 /** 1080 Append a formatted string to the end of an evbuffer. 1081 1082 @param buf the evbuffer that will be appended to 1083 @param fmt a format string 1084 @param ... arguments that will be passed to printf(3) 1085 @return The number of bytes added if successful, or -1 if an error occurred. 1086 */ 1087 int evbuffer_add_printf(struct evbuffer *, const char *fmt, ...) 1088 #ifdef __GNUC__ 1089 __attribute__((format(printf, 2, 3))) 1090 #endif 1091 ; 1092 1093 1094 /** 1095 Append a va_list formatted string to the end of an evbuffer. 1096 1097 @param buf the evbuffer that will be appended to 1098 @param fmt a format string 1099 @param ap a varargs va_list argument array that will be passed to vprintf(3) 1100 @return The number of bytes added if successful, or -1 if an error occurred. 1101 */ 1102 int evbuffer_add_vprintf(struct evbuffer *, const char *fmt, va_list ap); 1103 1104 1105 /** 1106 Remove a specified number of bytes data from the beginning of an evbuffer. 1107 1108 @param buf the evbuffer to be drained 1109 @param len the number of bytes to drain from the beginning of the buffer 1110 */ 1111 void evbuffer_drain(struct evbuffer *, size_t); 1112 1113 1114 /** 1115 Write the contents of an evbuffer to a file descriptor. 1116 1117 The evbuffer will be drained after the bytes have been successfully written. 1118 1119 @param buffer the evbuffer to be written and drained 1120 @param fd the file descriptor to be written to 1121 @return the number of bytes written, or -1 if an error occurred 1122 @see evbuffer_read() 1123 */ 1124 int evbuffer_write(struct evbuffer *, int); 1125 1126 1127 /** 1128 Read from a file descriptor and store the result in an evbuffer. 1129 1130 @param buf the evbuffer to store the result 1131 @param fd the file descriptor to read from 1132 @param howmuch the number of bytes to be read 1133 @return the number of bytes read, or -1 if an error occurred 1134 @see evbuffer_write() 1135 */ 1136 int evbuffer_read(struct evbuffer *, int, int); 1137 1138 1139 /** 1140 Find a string within an evbuffer. 1141 1142 @param buffer the evbuffer to be searched 1143 @param what the string to be searched for 1144 @param len the length of the search string 1145 @return a pointer to the beginning of the search string, or NULL if the search failed. 1146 */ 1147 u_char *evbuffer_find(struct evbuffer *, const u_char *, size_t); 1148 1149 /** 1150 Set a callback to invoke when the evbuffer is modified. 1151 1152 @param buffer the evbuffer to be monitored 1153 @param cb the callback function to invoke when the evbuffer is modified 1154 @param cbarg an argument to be provided to the callback function 1155 */ 1156 void evbuffer_setcb(struct evbuffer *, void (*)(struct evbuffer *, size_t, size_t, void *), void *); 1157 1158 /* 1159 * Marshaling tagged data - We assume that all tags are inserted in their 1160 * numeric order - so that unknown tags will always be higher than the 1161 * known ones - and we can just ignore the end of an event buffer. 1162 */ 1163 1164 void evtag_init(void); 1165 1166 void evtag_marshal(struct evbuffer *evbuf, ev_uint32_t tag, const void *data, 1167 ev_uint32_t len); 1168 1169 /** 1170 Encode an integer and store it in an evbuffer. 1171 1172 We encode integer's by nibbles; the first nibble contains the number 1173 of significant nibbles - 1; this allows us to encode up to 64-bit 1174 integers. This function is byte-order independent. 1175 1176 @param evbuf evbuffer to store the encoded number 1177 @param number a 32-bit integer 1178 */ 1179 void encode_int(struct evbuffer *evbuf, ev_uint32_t number); 1180 1181 void evtag_marshal_int(struct evbuffer *evbuf, ev_uint32_t tag, 1182 ev_uint32_t integer); 1183 1184 void evtag_marshal_string(struct evbuffer *buf, ev_uint32_t tag, 1185 const char *string); 1186 1187 void evtag_marshal_timeval(struct evbuffer *evbuf, ev_uint32_t tag, 1188 struct timeval *tv); 1189 1190 int evtag_unmarshal(struct evbuffer *src, ev_uint32_t *ptag, 1191 struct evbuffer *dst); 1192 int evtag_peek(struct evbuffer *evbuf, ev_uint32_t *ptag); 1193 int evtag_peek_length(struct evbuffer *evbuf, ev_uint32_t *plength); 1194 int evtag_payload_length(struct evbuffer *evbuf, ev_uint32_t *plength); 1195 int evtag_consume(struct evbuffer *evbuf); 1196 1197 int evtag_unmarshal_int(struct evbuffer *evbuf, ev_uint32_t need_tag, 1198 ev_uint32_t *pinteger); 1199 1200 int evtag_unmarshal_fixed(struct evbuffer *src, ev_uint32_t need_tag, 1201 void *data, size_t len); 1202 1203 int evtag_unmarshal_string(struct evbuffer *evbuf, ev_uint32_t need_tag, 1204 char **pstring); 1205 1206 int evtag_unmarshal_timeval(struct evbuffer *evbuf, ev_uint32_t need_tag, 1207 struct timeval *ptv); 1208 1209 #ifdef __cplusplus 1210 } 1211 #endif 1212 1213 #endif /* _EVENT_H_ */ 1214