1 /* $NetBSD: event.h,v 1.1.1.2 2015/01/29 06:38:26 spz Exp $ */ 2 /* $NetBSD: event.h,v 1.1.1.2 2015/01/29 06:38:26 spz Exp $ */ 3 /* 4 * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> 5 * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 1. Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 2. Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 3. The name of the author may not be used to endorse or promote products 16 * derived from this software without specific prior written permission. 17 * 18 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 19 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 22 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 */ 29 #ifndef _EVENT2_EVENT_H_ 30 #define _EVENT2_EVENT_H_ 31 32 /** 33 @mainpage 34 35 @section intro Introduction 36 37 Libevent is an event notification library for developing scalable network 38 servers. The Libevent API provides a mechanism to execute a callback 39 function when a specific event occurs on a file descriptor or after a 40 timeout has been reached. Furthermore, Libevent also support callbacks due 41 to signals or regular timeouts. 42 43 Libevent is meant to replace the event loop found in event driven network 44 servers. An application just needs to call event_dispatch() and then add or 45 remove events dynamically without having to change the event loop. 46 47 48 Currently, Libevent supports /dev/poll, kqueue(2), select(2), poll(2), 49 epoll(4), and evports. The internal event mechanism is completely 50 independent of the exposed event API, and a simple update of Libevent can 51 provide new functionality without having to redesign the applications. As a 52 result, Libevent allows for portable application development and provides 53 the most scalable event notification mechanism available on an operating 54 system. Libevent can also be used for multithreaded programs. Libevent 55 should compile on Linux, *BSD, Mac OS X, Solaris and, Windows. 56 57 @section usage Standard usage 58 59 Every program that uses Libevent must inclurde the <event2/event.h> 60 header, and pass the -levent flag to the linker. (You can instead link 61 -levent_core if you only want the main event and buffered IO-based code, 62 and don't want to link any protocol code.) 63 64 @section setup Library setup 65 66 Before you call any other Libevent functions, you need to set up the 67 library. If you're going to use Libevent from multiple threads in a 68 multithreaded application, you need to initialize thread support -- 69 typically by using evthread_use_pthreads() or 70 evthread_use_windows_threads(). See <event2/thread.h> for more 71 information. 72 73 This is also the point where you can replace Libevent's memory 74 management functions with event_set_mem_functions, and enable debug mode 75 with event_enable_debug_mode(). 76 77 @section base Creating an event base 78 79 Next, you need to create an event_base structure, using event_base_new() 80 or event_base_new_with_config(). The event_base is responsible for 81 keeping track of which events are "pending" (that is to say, being 82 watched to see if they become active) and which events are "active". 83 Every event is associated with a single event_base. 84 85 @section event Event notification 86 87 For each file descriptor that you wish to monitor, you must create an 88 event structure with event_new(). (You may also declare an event 89 structure and call event_assign() to initialize the members of the 90 structure.) To enable notification, you add the structure to the list 91 of monitored events by calling event_add(). The event structure must 92 remain allocated as long as it is active, so it should generally be 93 allocated on the heap. 94 95 @section loop Dispaching evets. 96 97 Finally, you call event_base_dispatch() to loop and dispatch events. 98 You can also use event_base_loop() for more fine-grained control. 99 100 Currently, only one thread can be dispatching a given event_base at a 101 time. If you want to run events in multiple threads at once, you can 102 either have a single event_base whose events add work to a work queue, 103 or you can create multiple event_base objects. 104 105 @section bufferevent I/O Buffers 106 107 Libevent provides a buffered I/O abstraction on top of the regular event 108 callbacks. This abstraction is called a bufferevent. A bufferevent 109 provides input and output buffers that get filled and drained 110 automatically. The user of a buffered event no longer deals directly 111 with the I/O, but instead is reading from input and writing to output 112 buffers. 113 114 Once initialized via bufferevent_socket_new(), the bufferevent structure 115 can be used repeatedly with bufferevent_enable() and 116 bufferevent_disable(). Instead of reading and writing directly to a 117 socket, you would call bufferevent_read() and bufferevent_write(). 118 119 When read enabled the bufferevent will try to read from the file descriptor 120 and call the read callback. The write callback is executed whenever the 121 output buffer is drained below the write low watermark, which is 0 by 122 default. 123 124 See <event2/bufferevent*.h> for more information. 125 126 @section timers Timers 127 128 Libevent can also be used to create timers that invoke a callback after a 129 certain amount of time has expired. The evtimer_new() function returns 130 an event struct to use as a timer. To activate the timer, call 131 evtimer_add(). Timers can be deactivated by calling evtimer_del(). 132 133 @section evdns Asynchronous DNS resolution 134 135 Libevent provides an asynchronous DNS resolver that should be used instead 136 of the standard DNS resolver functions. See the <event2/dns.h> 137 functions for more detail. 138 139 @section evhttp Event-driven HTTP servers 140 141 Libevent provides a very simple event-driven HTTP server that can be 142 embedded in your program and used to service HTTP requests. 143 144 To use this capability, you need to include the <event2/http.h> header in your 145 program. See that header for more information. 146 147 @section evrpc A framework for RPC servers and clients 148 149 Libevent provides a framework for creating RPC servers and clients. It 150 takes care of marshaling and unmarshaling all data structures. 151 152 @section api API Reference 153 154 To browse the complete documentation of the libevent API, click on any of 155 the following links. 156 157 event2/event.h 158 The primary libevent header 159 160 event2/thread.h 161 Functions for use by multithreaded programs 162 163 event2/buffer.h and event2/bufferevent.h 164 Buffer management for network reading and writing 165 166 event2/util.h 167 Utility functions for portable nonblocking network code 168 169 event2/dns.h 170 Asynchronous DNS resolution 171 172 event2/http.h 173 An embedded libevent-based HTTP server 174 175 event2/rpc.h 176 A framework for creating RPC servers and clients 177 178 */ 179 180 /** @file event2/event.h 181 182 Core functions for waiting for and receiving events, and using event bases. 183 */ 184 185 #ifdef __cplusplus 186 extern "C" { 187 #endif 188 189 #include <event2/event-config.h> 190 #ifdef _EVENT_HAVE_SYS_TYPES_H 191 #include <sys/types.h> 192 #endif 193 #ifdef _EVENT_HAVE_SYS_TIME_H 194 #include <sys/time.h> 195 #endif 196 197 #include <stdio.h> 198 199 /* For int types. */ 200 #include <event2/util.h> 201 202 /** 203 * Structure to hold information and state for a Libevent dispatch loop. 204 * 205 * The event_base lies at the center of Libevent; every application will 206 * have one. It keeps track of all pending and active events, and 207 * notifies your application of the active ones. 208 * 209 * This is an opaque structure; you can allocate one using 210 * event_base_new() or event_base_new_with_config(). 211 * 212 * @see event_base_new(), event_base_free(), event_base_loop(), 213 * event_base_new_with_config() 214 */ 215 struct event_base 216 #ifdef _EVENT_IN_DOXYGEN 217 {/*Empty body so that doxygen will generate documentation here.*/} 218 #endif 219 ; 220 221 /** 222 * @struct event 223 * 224 * Structure to represent a single event. 225 * 226 * An event can have some underlying condition it represents: a socket 227 * becoming readable or writeable (or both), or a signal becoming raised. 228 * (An event that represents no underlying condition is still useful: you 229 * can use one to implement a timer, or to communicate between threads.) 230 * 231 * Generally, you can create events with event_new(), then make them 232 * pending with event_add(). As your event_base runs, it will run the 233 * callbacks of an events whose conditions are triggered. When you 234 * longer want the event, free it with event_free(). 235 * 236 * In more depth: 237 * 238 * An event may be "pending" (one whose condition we are watching), 239 * "active" (one whose condition has triggered and whose callback is about 240 * to run), neither, or both. Events come into existence via 241 * event_assign() or event_new(), and are then neither active nor pending. 242 * 243 * To make an event pending, pass it to event_add(). When doing so, you 244 * can also set a timeout for the event. 245 * 246 * Events become active during an event_base_loop() call when either their 247 * condition has triggered, or when their timeout has elapsed. You can 248 * also activate an event manually using event_active(). The even_base 249 * loop will run the callbacks of active events; after it has done so, it 250 * marks them as no longer active. 251 * 252 * You can make an event non-pending by passing it to event_del(). This 253 * also makes the event non-active. 254 * 255 * Events can be "persistent" or "non-persistent". A non-persistent event 256 * becomes non-pending as soon as it is triggered: thus, it only runs at 257 * most once per call to event_add(). A persistent event remains pending 258 * even when it becomes active: you'll need to event_del() it manually in 259 * order to make it non-pending. When a persistent event with a timeout 260 * becomes active, its timeout is reset: this means you can use persistent 261 * events to implement periodic timeouts. 262 * 263 * This should be treated as an opaque structure; you should never read or 264 * write any of its fields directly. For backward compatibility with old 265 * code, it is defined in the event2/event_struct.h header; including this 266 * header may make your code incompatible with other versions of Libevent. 267 * 268 * @see event_new(), event_free(), event_assign(), event_get_assignment(), 269 * event_add(), event_del(), event_active(), event_pending(), 270 * event_get_fd(), event_get_base(), event_get_events(), 271 * event_get_callback(), event_get_callback_arg(), 272 * event_priority_set() 273 */ 274 struct event 275 #ifdef _EVENT_IN_DOXYGEN 276 {/*Empty body so that doxygen will generate documentation here.*/} 277 #endif 278 ; 279 280 /** 281 * Configuration for an event_base. 282 * 283 * There are many options that can be used to alter the behavior and 284 * implementation of an event_base. To avoid having to pass them all in a 285 * complex many-argument constructor, we provide an abstract data type 286 * wrhere you set up configation information before passing it to 287 * event_base_new_with_config(). 288 * 289 * @see event_config_new(), event_config_free(), event_base_new_with_config(), 290 * event_config_avoid_method(), event_config_require_features(), 291 * event_config_set_flag(), event_config_set_num_cpus_hint() 292 */ 293 struct event_config 294 #ifdef _EVENT_IN_DOXYGEN 295 {/*Empty body so that doxygen will generate documentation here.*/} 296 #endif 297 ; 298 299 /** 300 * Enable some relatively expensive debugging checks in Libevent that 301 * would normally be turned off. Generally, these checks cause code that 302 * would otherwise crash mysteriously to fail earlier with an assertion 303 * failure. Note that this method MUST be called before any events or 304 * event_bases have been created. 305 * 306 * Debug mode can currently catch the following errors: 307 * An event is re-assigned while it is added 308 * Any function is called on a non-assigned event 309 * 310 * Note that debugging mode uses memory to track every event that has been 311 * initialized (via event_assign, event_set, or event_new) but not yet 312 * released (via event_free or event_debug_unassign). If you want to use 313 * debug mode, and you find yourself running out of memory, you will need 314 * to use event_debug_unassign to explicitly stop tracking events that 315 * are no longer considered set-up. 316 * 317 * @see event_debug_unassign() 318 */ 319 void event_enable_debug_mode(void); 320 321 /** 322 * When debugging mode is enabled, informs Libevent that an event should no 323 * longer be considered as assigned. When debugging mode is not enabled, does 324 * nothing. 325 * 326 * This function must only be called on a non-added event. 327 * 328 * @see event_enable_debug_mode() 329 */ 330 void event_debug_unassign(struct event *); 331 332 /** 333 * Create and return a new event_base to use with the rest of Libevent. 334 * 335 * @return a new event_base on success, or NULL on failure. 336 * 337 * @see event_base_free(), event_base_new_with_config() 338 */ 339 struct event_base *event_base_new(void); 340 341 /** 342 Reinitialize the event base after a fork 343 344 Some event mechanisms do not survive across fork. The event base needs 345 to be reinitialized with the event_reinit() function. 346 347 @param base the event base that needs to be re-initialized 348 @return 0 if successful, or -1 if some events could not be re-added. 349 @see event_base_new() 350 */ 351 int event_reinit(struct event_base *base); 352 353 /** 354 Event dispatching loop 355 356 This loop will run the event base until either there are no more pending or 357 active, or until something calls event_base_loopbreak() or 358 event_base_loopexit(). 359 360 @param base the event_base structure returned by event_base_new() or 361 event_base_new_with_config() 362 @return 0 if successful, -1 if an error occurred, or 1 if we exited because 363 no events were pending or active. 364 @see event_base_loop() 365 */ 366 int event_base_dispatch(struct event_base *); 367 368 /** 369 Get the kernel event notification mechanism used by Libevent. 370 371 @param eb the event_base structure returned by event_base_new() 372 @return a string identifying the kernel event mechanism (kqueue, epoll, etc.) 373 */ 374 const char *event_base_get_method(const struct event_base *); 375 376 /** 377 Gets all event notification mechanisms supported by Libevent. 378 379 This functions returns the event mechanism in order preferred by 380 Libevent. Note that this list will include all backends that 381 Libevent has compiled-in support for, and will not necessarily check 382 your OS to see whether it has the required resources. 383 384 @return an array with pointers to the names of support methods. 385 The end of the array is indicated by a NULL pointer. If an 386 error is encountered NULL is returned. 387 */ 388 const char **event_get_supported_methods(void); 389 390 /** 391 Allocates a new event configuration object. 392 393 The event configuration object can be used to change the behavior of 394 an event base. 395 396 @return an event_config object that can be used to store configuration, or 397 NULL if an error is encountered. 398 @see event_base_new_with_config(), event_config_free(), event_config 399 */ 400 struct event_config *event_config_new(void); 401 402 /** 403 Deallocates all memory associated with an event configuration object 404 405 @param cfg the event configuration object to be freed. 406 */ 407 void event_config_free(struct event_config *cfg); 408 409 /** 410 Enters an event method that should be avoided into the configuration. 411 412 This can be used to avoid event mechanisms that do not support certain 413 file descriptor types, or for debugging to avoid certain event 414 mechanisms. An application can make use of multiple event bases to 415 accommodate incompatible file descriptor types. 416 417 @param cfg the event configuration object 418 @param method the name of the event method to avoid 419 @return 0 on success, -1 on failure. 420 */ 421 int event_config_avoid_method(struct event_config *cfg, const char *method); 422 423 /** 424 A flag used to describe which features an event_base (must) provide. 425 426 Because of OS limitations, not every Libevent backend supports every 427 possible feature. You can use this type with 428 event_config_require_features() to tell Libevent to only proceed if your 429 event_base implements a given feature, and you can receive this type from 430 event_base_get_features() to see which features are available. 431 */ 432 enum event_method_feature { 433 /** Require an event method that allows edge-triggered events with EV_ET. */ 434 EV_FEATURE_ET = 0x01, 435 /** Require an event method where having one event triggered among 436 * many is [approximately] an O(1) operation. This excludes (for 437 * example) select and poll, which are approximately O(N) for N 438 * equal to the total number of possible events. */ 439 EV_FEATURE_O1 = 0x02, 440 /** Require an event method that allows file descriptors as well as 441 * sockets. */ 442 EV_FEATURE_FDS = 0x04 443 }; 444 445 /** 446 A flag passed to event_config_set_flag(). 447 448 These flags change the behavior of an allocated event_base. 449 450 @see event_config_set_flag(), event_base_new_with_config(), 451 event_method_feature 452 */ 453 enum event_base_config_flag { 454 /** Do not allocate a lock for the event base, even if we have 455 locking set up. */ 456 EVENT_BASE_FLAG_NOLOCK = 0x01, 457 /** Do not check the EVENT_* environment variables when configuring 458 an event_base */ 459 EVENT_BASE_FLAG_IGNORE_ENV = 0x02, 460 /** Windows only: enable the IOCP dispatcher at startup 461 462 If this flag is set then bufferevent_socket_new() and 463 evconn_listener_new() will use IOCP-backed implementations 464 instead of the usual select-based one on Windows. 465 */ 466 EVENT_BASE_FLAG_STARTUP_IOCP = 0x04, 467 /** Instead of checking the current time every time the event loop is 468 ready to run timeout callbacks, check after each timeout callback. 469 */ 470 EVENT_BASE_FLAG_NO_CACHE_TIME = 0x08, 471 472 /** If we are using the epoll backend, this flag says that it is 473 safe to use Libevent's internal change-list code to batch up 474 adds and deletes in order to try to do as few syscalls as 475 possible. Setting this flag can make your code run faster, but 476 it may trigger a Linux bug: it is not safe to use this flag 477 if you have any fds cloned by dup() or its variants. Doing so 478 will produce strange and hard-to-diagnose bugs. 479 480 This flag can also be activated by settnig the 481 EVENT_EPOLL_USE_CHANGELIST environment variable. 482 483 This flag has no effect if you wind up using a backend other than 484 epoll. 485 */ 486 EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST = 0x10 487 }; 488 489 /** 490 Return a bitmask of the features implemented by an event base. This 491 will be a bitwise OR of one or more of the values of 492 event_method_feature 493 494 @see event_method_feature 495 */ 496 int event_base_get_features(const struct event_base *base); 497 498 /** 499 Enters a required event method feature that the application demands. 500 501 Note that not every feature or combination of features is supported 502 on every platform. Code that requests features should be prepared 503 to handle the case where event_base_new_with_config() returns NULL, as in: 504 <pre> 505 event_config_require_features(cfg, EV_FEATURE_ET); 506 base = event_base_new_with_config(cfg); 507 if (base == NULL) { 508 // We can't get edge-triggered behavior here. 509 event_config_require_features(cfg, 0); 510 base = event_base_new_with_config(cfg); 511 } 512 </pre> 513 514 @param cfg the event configuration object 515 @param feature a bitfield of one or more event_method_feature values. 516 Replaces values from previous calls to this function. 517 @return 0 on success, -1 on failure. 518 @see event_method_feature, event_base_new_with_config() 519 */ 520 int event_config_require_features(struct event_config *cfg, int feature); 521 522 /** 523 * Sets one or more flags to configure what parts of the eventual event_base 524 * will be initialized, and how they'll work. 525 * 526 * @see event_base_config_flags, event_base_new_with_config() 527 **/ 528 int event_config_set_flag(struct event_config *cfg, int flag); 529 530 /** 531 * Records a hint for the number of CPUs in the system. This is used for 532 * tuning thread pools, etc, for optimal performance. In Libevent 2.0, 533 * it is only on Windows, and only when IOCP is in use. 534 * 535 * @param cfg the event configuration object 536 * @param cpus the number of cpus 537 * @return 0 on success, -1 on failure. 538 */ 539 int event_config_set_num_cpus_hint(struct event_config *cfg, int cpus); 540 541 /** 542 Initialize the event API. 543 544 Use event_base_new_with_config() to initialize a new event base, taking 545 the specified configuration under consideration. The configuration object 546 can currently be used to avoid certain event notification mechanisms. 547 548 @param cfg the event configuration object 549 @return an initialized event_base that can be used to registering events, 550 or NULL if no event base can be created with the requested event_config. 551 @see event_base_new(), event_base_free(), event_init(), event_assign() 552 */ 553 struct event_base *event_base_new_with_config(const struct event_config *); 554 555 /** 556 Deallocate all memory associated with an event_base, and free the base. 557 558 Note that this function will not close any fds or free any memory passed 559 to event_new as the argument to callback. 560 561 @param eb an event_base to be freed 562 */ 563 void event_base_free(struct event_base *); 564 565 /** @name Log severities 566 */ 567 /**@{*/ 568 #define EVENT_LOG_DEBUG 0 569 #define EVENT_LOG_MSG 1 570 #define EVENT_LOG_WARN 2 571 #define EVENT_LOG_ERR 3 572 /**@}*/ 573 574 /* Obsolete names: these are deprecated, but older programs might use them. 575 * They violate the reserved-identifier namespace. */ 576 #define _EVENT_LOG_DEBUG EVENT_LOG_DEBUG 577 #define _EVENT_LOG_MSG EVENT_LOG_MSG 578 #define _EVENT_LOG_WARN EVENT_LOG_WARN 579 #define _EVENT_LOG_ERR EVENT_LOG_ERR 580 581 /** 582 A callback function used to intercept Libevent's log messages. 583 584 @see event_set_log_callback 585 */ 586 typedef void (*event_log_cb)(int severity, const char *msg); 587 /** 588 Redirect Libevent's log messages. 589 590 @param cb a function taking two arguments: an integer severity between 591 _EVENT_LOG_DEBUG and _EVENT_LOG_ERR, and a string. If cb is NULL, 592 then the default log is used. 593 594 NOTE: The function you provide *must not* call any other libevent 595 functionality. Doing so can produce undefined behavior. 596 */ 597 void event_set_log_callback(event_log_cb cb); 598 599 /** 600 A function to be called if Libevent encounters a fatal internal error. 601 602 @see event_set_fatal_callback 603 */ 604 typedef void (*event_fatal_cb)(int err); 605 606 /** 607 Override Libevent's behavior in the event of a fatal internal error. 608 609 By default, Libevent will call exit(1) if a programming error makes it 610 impossible to continue correct operation. This function allows you to supply 611 another callback instead. Note that if the function is ever invoked, 612 something is wrong with your program, or with Libevent: any subsequent calls 613 to Libevent may result in undefined behavior. 614 615 Libevent will (almost) always log an _EVENT_LOG_ERR message before calling 616 this function; look at the last log message to see why Libevent has died. 617 */ 618 void event_set_fatal_callback(event_fatal_cb cb); 619 620 /** 621 Associate a different event base with an event. 622 623 The event to be associated must not be currently active or pending. 624 625 @param eb the event base 626 @param ev the event 627 @return 0 on success, -1 on failure. 628 */ 629 int event_base_set(struct event_base *, struct event *); 630 631 /** @name Loop flags 632 633 These flags control the behavior of event_base_loop(). 634 */ 635 /**@{*/ 636 /** Block until we have an active event, then exit once all active events 637 * have had their callbacks run. */ 638 #define EVLOOP_ONCE 0x01 639 /** Do not block: see which events are ready now, run the callbacks 640 * of the highest-priority ones, then exit. */ 641 #define EVLOOP_NONBLOCK 0x02 642 /**@}*/ 643 644 /** 645 Wait for events to become active, and run their callbacks. 646 647 This is a more flexible version of event_base_dispatch(). 648 649 By default, this loop will run the event base until either there are no more 650 pending or active events, or until something calls event_base_loopbreak() or 651 event_base_loopexit(). You can override this behavior with the 'flags' 652 argument. 653 654 @param eb the event_base structure returned by event_base_new() or 655 event_base_new_with_config() 656 @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK 657 @return 0 if successful, -1 if an error occurred, or 1 if we exited because 658 no events were pending or active. 659 @see event_base_loopexit(), event_base_dispatch(), EVLOOP_ONCE, 660 EVLOOP_NONBLOCK 661 */ 662 int event_base_loop(struct event_base *, int); 663 664 /** 665 Exit the event loop after the specified time 666 667 The next event_base_loop() iteration after the given timer expires will 668 complete normally (handling all queued events) then exit without 669 blocking for events again. 670 671 Subsequent invocations of event_base_loop() will proceed normally. 672 673 @param eb the event_base structure returned by event_init() 674 @param tv the amount of time after which the loop should terminate, 675 or NULL to exit after running all currently active events. 676 @return 0 if successful, or -1 if an error occurred 677 @see event_base_loopbreak() 678 */ 679 int event_base_loopexit(struct event_base *, const struct timeval *); 680 681 /** 682 Abort the active event_base_loop() immediately. 683 684 event_base_loop() will abort the loop after the next event is completed; 685 event_base_loopbreak() is typically invoked from this event's callback. 686 This behavior is analogous to the "break;" statement. 687 688 Subsequent invocations of event_loop() will proceed normally. 689 690 @param eb the event_base structure returned by event_init() 691 @return 0 if successful, or -1 if an error occurred 692 @see event_base_loopexit() 693 */ 694 int event_base_loopbreak(struct event_base *); 695 696 /** 697 Checks if the event loop was told to exit by event_loopexit(). 698 699 This function will return true for an event_base at every point after 700 event_loopexit() is called, until the event loop is next entered. 701 702 @param eb the event_base structure returned by event_init() 703 @return true if event_base_loopexit() was called on this event base, 704 or 0 otherwise 705 @see event_base_loopexit() 706 @see event_base_got_break() 707 */ 708 int event_base_got_exit(struct event_base *); 709 710 /** 711 Checks if the event loop was told to abort immediately by event_loopbreak(). 712 713 This function will return true for an event_base at every point after 714 event_loopbreak() is called, until the event loop is next entered. 715 716 @param eb the event_base structure returned by event_init() 717 @return true if event_base_loopbreak() was called on this event base, 718 or 0 otherwise 719 @see event_base_loopbreak() 720 @see event_base_got_exit() 721 */ 722 int event_base_got_break(struct event_base *); 723 724 /** 725 * @name event flags 726 * 727 * Flags to pass to event_new(), event_assign(), event_pending(), and 728 * anything else with an argument of the form "short events" 729 */ 730 /**@{*/ 731 /** Indicates that a timeout has occurred. It's not necessary to pass 732 * this flag to event_for new()/event_assign() to get a timeout. */ 733 #define EV_TIMEOUT 0x01 734 /** Wait for a socket or FD to become readable */ 735 #define EV_READ 0x02 736 /** Wait for a socket or FD to become writeable */ 737 #define EV_WRITE 0x04 738 /** Wait for a POSIX signal to be raised*/ 739 #define EV_SIGNAL 0x08 740 /** 741 * Persistent event: won't get removed automatically when activated. 742 * 743 * When a persistent event with a timeout becomes activated, its timeout 744 * is reset to 0. 745 */ 746 #define EV_PERSIST 0x10 747 /** Select edge-triggered behavior, if supported by the backend. */ 748 #define EV_ET 0x20 749 /**@}*/ 750 751 /** 752 @name evtimer_* macros 753 754 Aliases for working with one-shot timer events */ 755 /**@{*/ 756 #define evtimer_assign(ev, b, cb, arg) \ 757 event_assign((ev), (b), -1, 0, (cb), (arg)) 758 #define evtimer_new(b, cb, arg) event_new((b), -1, 0, (cb), (arg)) 759 #define evtimer_add(ev, tv) event_add((ev), (tv)) 760 #define evtimer_del(ev) event_del(ev) 761 #define evtimer_pending(ev, tv) event_pending((ev), EV_TIMEOUT, (tv)) 762 #define evtimer_initialized(ev) event_initialized(ev) 763 /**@}*/ 764 765 /** 766 @name evsignal_* macros 767 768 Aliases for working with signal events 769 */ 770 /**@{*/ 771 #define evsignal_add(ev, tv) event_add((ev), (tv)) 772 #define evsignal_assign(ev, b, x, cb, arg) \ 773 event_assign((ev), (b), (x), EV_SIGNAL|EV_PERSIST, cb, (arg)) 774 #define evsignal_new(b, x, cb, arg) \ 775 event_new((b), (x), EV_SIGNAL|EV_PERSIST, (cb), (arg)) 776 #define evsignal_del(ev) event_del(ev) 777 #define evsignal_pending(ev, tv) event_pending((ev), EV_SIGNAL, (tv)) 778 #define evsignal_initialized(ev) event_initialized(ev) 779 /**@}*/ 780 781 /** 782 A callback function for an event. 783 784 It receives three arguments: 785 786 @param fd An fd or signal 787 @param events One or more EV_* flags 788 @param arg A user-supplied argument. 789 790 @see event_new() 791 */ 792 typedef void (*event_callback_fn)(evutil_socket_t, short, void *); 793 794 /** 795 Allocate and asssign a new event structure, ready to be added. 796 797 The function event_new() returns a new event that can be used in 798 future calls to event_add() and event_del(). The fd and events 799 arguments determine which conditions will trigger the event; the 800 callback and callback_arg arguments tell Libevent what to do when the 801 event becomes active. 802 803 If events contains one of EV_READ, EV_WRITE, or EV_READ|EV_WRITE, then 804 fd is a file descriptor or socket that should get monitored for 805 readiness to read, readiness to write, or readiness for either operation 806 (respectively). If events contains EV_SIGNAL, then fd is a signal 807 number to wait for. If events contains none of those flags, then the 808 event can be triggered only by a timeout or by manual activation with 809 event_active(): In this case, fd must be -1. 810 811 The EV_PERSIST flag can also be passed in the events argument: it makes 812 event_add() persistent until event_del() is called. 813 814 The EV_ET flag is compatible with EV_READ and EV_WRITE, and supported 815 only by certain backends. It tells Libevent to use edge-triggered 816 events. 817 818 The EV_TIMEOUT flag has no effect here. 819 820 It is okay to have multiple events all listening on the same fds; but 821 they must either all be edge-triggered, or all not be edge triggerd. 822 823 When the event becomes active, the event loop will run the provided 824 callbuck function, with three arguments. The first will be the provided 825 fd value. The second will be a bitfield of the events that triggered: 826 EV_READ, EV_WRITE, or EV_SIGNAL. Here the EV_TIMEOUT flag indicates 827 that a timeout occurred, and EV_ET indicates that an edge-triggered 828 event occurred. The third event will be the callback_arg pointer that 829 you provide. 830 831 @param base the event base to which the event should be attached. 832 @param fd the file descriptor or signal to be monitored, or -1. 833 @param events desired events to monitor: bitfield of EV_READ, EV_WRITE, 834 EV_SIGNAL, EV_PERSIST, EV_ET. 835 @param callback callback function to be invoked when the event occurs 836 @param callback_arg an argument to be passed to the callback function 837 838 @return a newly allocated struct event that must later be freed with 839 event_free(). 840 @see event_free(), event_add(), event_del(), event_assign() 841 */ 842 struct event *event_new(struct event_base *, evutil_socket_t, short, event_callback_fn, void *); 843 844 845 /** 846 Prepare a new, already-allocated event structure to be added. 847 848 The function event_assign() prepares the event structure ev to be used 849 in future calls to event_add() and event_del(). Unlike event_new(), it 850 doesn't allocate memory itself: it requires that you have already 851 allocated a struct event, probably on the heap. Doing this will 852 typically make your code depend on the size of the event structure, and 853 thereby create incompatibility with future versions of Libevent. 854 855 The easiest way to avoid this problem is just to use event_new() and 856 event_free() instead. 857 858 A slightly harder way to future-proof your code is to use 859 event_get_struct_event_size() to determine the required size of an event 860 at runtime. 861 862 Note that it is NOT safe to call this function on an event that is 863 active or pending. Doing so WILL corrupt internal data structures in 864 Libevent, and lead to strange, hard-to-diagnose bugs. You _can_ use 865 event_assign to change an existing event, but only if it is not active 866 or pending! 867 868 The arguments for this function, and the behavior of the events that it 869 makes, are as for event_new(). 870 871 @param ev an event struct to be modified 872 @param base the event base to which ev should be attached. 873 @param fd the file descriptor to be monitored 874 @param events desired events to monitor; can be EV_READ and/or EV_WRITE 875 @param callback callback function to be invoked when the event occurs 876 @param callback_arg an argument to be passed to the callback function 877 878 @return 0 if success, or -1 on invalid arguments. 879 880 @see event_new(), event_add(), event_del(), event_base_once(), 881 event_get_struct_event_size() 882 */ 883 int event_assign(struct event *, struct event_base *, evutil_socket_t, short, event_callback_fn, void *); 884 885 /** 886 Deallocate a struct event * returned by event_new(). 887 888 If the event is pending or active, first make it non-pending and 889 non-active. 890 */ 891 void event_free(struct event *); 892 893 /** 894 Schedule a one-time event 895 896 The function event_base_once() is similar to event_set(). However, it 897 schedules a callback to be called exactly once, and does not require the 898 caller to prepare an event structure. 899 900 Note that in Libevent 2.0 and earlier, if the event is never triggered, 901 the internal memory used to hold it will never be freed. This may be 902 fixed in a later version of Libevent. 903 904 @param base an event_base 905 @param fd a file descriptor to monitor, or -1 for no fd. 906 @param events event(s) to monitor; can be any of EV_READ | 907 EV_WRITE, or EV_TIMEOUT 908 @param callback callback function to be invoked when the event occurs 909 @param arg an argument to be passed to the callback function 910 @param timeout the maximum amount of time to wait for the event. NULL 911 makes an EV_READ/EV_WRITE event make forever; NULL makes an 912 EV_TIMEOUT event succees immediately. 913 @return 0 if successful, or -1 if an error occurred 914 */ 915 int event_base_once(struct event_base *, evutil_socket_t, short, event_callback_fn, void *, const struct timeval *); 916 917 /** 918 Add an event to the set of pending events. 919 920 The function event_add() schedules the execution of the ev event when the 921 event specified in event_assign()/event_new() occurs, or when the time 922 specified in timeout has elapesed. If atimeout is NULL, no timeout 923 occurs and the function will only be 924 called if a matching event occurs. The event in the 925 ev argument must be already initialized by event_assign() or event_new() 926 and may not be used 927 in calls to event_assign() until it is no longer pending. 928 929 If the event in the ev argument already has a scheduled timeout, calling 930 event_add() replaces the old timeout with the new one, or clears the old 931 timeout if the timeout argument is NULL. 932 933 @param ev an event struct initialized via event_set() 934 @param timeout the maximum amount of time to wait for the event, or NULL 935 to wait forever 936 @return 0 if successful, or -1 if an error occurred 937 @see event_del(), event_assign(), event_new() 938 */ 939 int event_add(struct event *ev, const struct timeval *timeout); 940 941 /** 942 Remove an event from the set of monitored events. 943 944 The function event_del() will cancel the event in the argument ev. If the 945 event has already executed or has never been added the call will have no 946 effect. 947 948 @param ev an event struct to be removed from the working set 949 @return 0 if successful, or -1 if an error occurred 950 @see event_add() 951 */ 952 int event_del(struct event *); 953 954 955 /** 956 Make an event active. 957 958 You can use this function on a pending or a non-pending event to make it 959 active, so that its callback will be run by event_base_dispatch() or 960 event_base_loop(). 961 962 One common use in multithreaded programs is to wake the thread running 963 event_base_loop() from another thread. 964 965 @param ev an event to make active. 966 @param res a set of flags to pass to the event's callback. 967 @param ncalls an obsolete argument: this is ignored. 968 **/ 969 void event_active(struct event *ev, int res, short ncalls); 970 971 /** 972 Checks if a specific event is pending or scheduled. 973 974 @param ev an event struct previously passed to event_add() 975 @param events the requested event type; any of EV_TIMEOUT|EV_READ| 976 EV_WRITE|EV_SIGNAL 977 @param tv if this field is not NULL, and the event has a timeout, 978 this field is set to hold the time at which the timeout will 979 expire. 980 981 @return true if the event is pending on any of the events in 'what', (that 982 is to say, it has been added), or 0 if the event is not added. 983 */ 984 int event_pending(const struct event *ev, short events, struct timeval *tv); 985 986 987 /** 988 Test if an event structure might be initialized. 989 990 The event_initialized() function can be used to check if an event has been 991 initialized. 992 993 Warning: This function is only useful for distinguishing a a zeroed-out 994 piece of memory from an initialized event, it can easily be confused by 995 uninitialized memory. Thus, it should ONLY be used to distinguish an 996 initialized event from zero. 997 998 @param ev an event structure to be tested 999 @return 1 if the structure might be initialized, or 0 if it has not been 1000 initialized 1001 */ 1002 int event_initialized(const struct event *ev); 1003 1004 /** 1005 Get the signal number assigned to a signal event 1006 */ 1007 #define event_get_signal(ev) ((int)event_get_fd(ev)) 1008 1009 /** 1010 Get the socket or signal assigned to an event, or -1 if the event has 1011 no socket. 1012 */ 1013 evutil_socket_t event_get_fd(const struct event *ev); 1014 1015 /** 1016 Get the event_base associated with an event. 1017 */ 1018 struct event_base *event_get_base(const struct event *ev); 1019 1020 /** 1021 Return the events (EV_READ, EV_WRITE, etc) assigned to an event. 1022 */ 1023 short event_get_events(const struct event *ev); 1024 1025 /** 1026 Return the callback assigned to an event. 1027 */ 1028 event_callback_fn event_get_callback(const struct event *ev); 1029 1030 /** 1031 Return the callback argument assigned to an event. 1032 */ 1033 void *event_get_callback_arg(const struct event *ev); 1034 1035 /** 1036 Extract _all_ of arguments given to construct a given event. The 1037 event_base is copied into *base_out, the fd is copied into *fd_out, and so 1038 on. 1039 1040 If any of the "_out" arguments is NULL, it will be ignored. 1041 */ 1042 void event_get_assignment(const struct event *event, 1043 struct event_base **base_out, evutil_socket_t *fd_out, short *events_out, 1044 event_callback_fn *callback_out, void **arg_out); 1045 1046 /** 1047 Return the size of struct event that the Libevent library was compiled 1048 with. 1049 1050 This will be NO GREATER than sizeof(struct event) if you're running with 1051 the same version of Libevent that your application was built with, but 1052 otherwise might not. 1053 1054 Note that it might be SMALLER than sizeof(struct event) if some future 1055 version of Libevent adds extra padding to the end of struct event. 1056 We might do this to help ensure ABI-compatibility between different 1057 versions of Libevent. 1058 */ 1059 size_t event_get_struct_event_size(void); 1060 1061 /** 1062 Get the Libevent version. 1063 1064 Note that this will give you the version of the library that you're 1065 currently linked against, not the version of the headers that you've 1066 compiled against. 1067 1068 @return a string containing the version number of Libevent 1069 */ 1070 const char *event_get_version(void); 1071 1072 /** 1073 Return a numeric representation of Libevent's version. 1074 1075 Note that this will give you the version of the library that you're 1076 currently linked against, not the version of the headers you've used to 1077 compile. 1078 1079 The format uses one byte each for the major, minor, and patchlevel parts of 1080 the version number. The low-order byte is unused. For example, version 1081 2.0.1-alpha has a numeric representation of 0x02000100 1082 */ 1083 ev_uint32_t event_get_version_number(void); 1084 1085 /** As event_get_version, but gives the version of Libevent's headers. */ 1086 #define LIBEVENT_VERSION _EVENT_VERSION 1087 /** As event_get_version_number, but gives the version number of Libevent's 1088 * headers. */ 1089 #define LIBEVENT_VERSION_NUMBER _EVENT_NUMERIC_VERSION 1090 1091 /** Largest number of priorities that Libevent can support. */ 1092 #define EVENT_MAX_PRIORITIES 256 1093 /** 1094 Set the number of different event priorities 1095 1096 By default Libevent schedules all active events with the same priority. 1097 However, some time it is desirable to process some events with a higher 1098 priority than others. For that reason, Libevent supports strict priority 1099 queues. Active events with a lower priority are always processed before 1100 events with a higher priority. 1101 1102 The number of different priorities can be set initially with the 1103 event_base_priority_init() function. This function should be called 1104 before the first call to event_base_dispatch(). The 1105 event_priority_set() function can be used to assign a priority to an 1106 event. By default, Libevent assigns the middle priority to all events 1107 unless their priority is explicitly set. 1108 1109 Note that urgent-priority events can starve less-urgent events: after 1110 running all urgent-priority callbacks, Libevent checks for more urgent 1111 events again, before running less-urgent events. Less-urgent events 1112 will not have their callbacks run until there are no events more urgent 1113 than them that want to be active. 1114 1115 @param eb the event_base structure returned by event_base_new() 1116 @param npriorities the maximum number of priorities 1117 @return 0 if successful, or -1 if an error occurred 1118 @see event_priority_set() 1119 */ 1120 int event_base_priority_init(struct event_base *, int); 1121 1122 /** 1123 Assign a priority to an event. 1124 1125 @param ev an event struct 1126 @param priority the new priority to be assigned 1127 @return 0 if successful, or -1 if an error occurred 1128 @see event_priority_init() 1129 */ 1130 int event_priority_set(struct event *, int); 1131 1132 /** 1133 Prepare an event_base to use a large number of timeouts with the same 1134 duration. 1135 1136 Libevent's default scheduling algorithm is optimized for having a large 1137 number of timeouts with their durations more or less randomly 1138 distributed. But if you have a large number of timeouts that all have 1139 the same duration (for example, if you have a large number of 1140 connections that all have a 10-second timeout), then you can improve 1141 Libevent's performance by telling Libevent about it. 1142 1143 To do this, call this function with the common duration. It will return a 1144 pointer to a different, opaque timeout value. (Don't depend on its actual 1145 contents!) When you use this timeout value in event_add(), Libevent will 1146 schedule the event more efficiently. 1147 1148 (This optimization probably will not be worthwhile until you have thousands 1149 or tens of thousands of events with the same timeout.) 1150 */ 1151 const struct timeval *event_base_init_common_timeout(struct event_base *base, 1152 const struct timeval *duration); 1153 1154 #if !defined(_EVENT_DISABLE_MM_REPLACEMENT) || defined(_EVENT_IN_DOXYGEN) 1155 /** 1156 Override the functions that Libevent uses for memory management. 1157 1158 Usually, Libevent uses the standard libc functions malloc, realloc, and 1159 free to allocate memory. Passing replacements for those functions to 1160 event_set_mem_functions() overrides this behavior. 1161 1162 Note that all memory returned from Libevent will be allocated by the 1163 replacement functions rather than by malloc() and realloc(). Thus, if you 1164 have replaced those functions, it will not be appropriate to free() memory 1165 that you get from Libevent. Instead, you must use the free_fn replacement 1166 that you provided. 1167 1168 Note also that if you are going to call this function, you should do so 1169 before any call to any Libevent function that does allocation. 1170 Otherwise, those funtions will allocate their memory using malloc(), but 1171 then later free it using your provided free_fn. 1172 1173 @param malloc_fn A replacement for malloc. 1174 @param realloc_fn A replacement for realloc 1175 @param free_fn A replacement for free. 1176 **/ 1177 void event_set_mem_functions( 1178 void *(*malloc_fn)(size_t sz), 1179 void *(*realloc_fn)(void *ptr, size_t sz), 1180 void (*free_fn)(void *ptr)); 1181 /** This definition is present if Libevent was built with support for 1182 event_set_mem_functions() */ 1183 #define EVENT_SET_MEM_FUNCTIONS_IMPLEMENTED 1184 #endif 1185 1186 void event_base_dump_events(struct event_base *, FILE *); 1187 1188 /** Sets 'tv' to the current time (as returned by gettimeofday()), 1189 looking at the cached value in 'base' if possible, and calling 1190 gettimeofday() or clock_gettime() as appropriate if there is no 1191 cached time. 1192 1193 Generally, this value will only be cached while actually 1194 processing event callbacks, and may be very inaccuate if your 1195 callbacks take a long time to execute. 1196 1197 Returns 0 on success, negative on failure. 1198 */ 1199 int event_base_gettimeofday_cached(struct event_base *base, 1200 struct timeval *tv); 1201 1202 #ifdef __cplusplus 1203 } 1204 #endif 1205 1206 #endif /* _EVENT2_EVENT_H_ */ 1207