1*9034ec65Schristos /* $NetBSD: event.h,v 1.6 2020/05/25 20:47:34 christos Exp $ */ 22b3787f6Schristos 32b3787f6Schristos /* 42b3787f6Schristos * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> 52b3787f6Schristos * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 62b3787f6Schristos * 72b3787f6Schristos * Redistribution and use in source and binary forms, with or without 82b3787f6Schristos * modification, are permitted provided that the following conditions 92b3787f6Schristos * are met: 102b3787f6Schristos * 1. Redistributions of source code must retain the above copyright 112b3787f6Schristos * notice, this list of conditions and the following disclaimer. 122b3787f6Schristos * 2. Redistributions in binary form must reproduce the above copyright 132b3787f6Schristos * notice, this list of conditions and the following disclaimer in the 142b3787f6Schristos * documentation and/or other materials provided with the distribution. 152b3787f6Schristos * 3. The name of the author may not be used to endorse or promote products 162b3787f6Schristos * derived from this software without specific prior written permission. 172b3787f6Schristos * 182b3787f6Schristos * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 192b3787f6Schristos * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 202b3787f6Schristos * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 212b3787f6Schristos * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 222b3787f6Schristos * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 232b3787f6Schristos * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 242b3787f6Schristos * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 252b3787f6Schristos * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 262b3787f6Schristos * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 272b3787f6Schristos * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 282b3787f6Schristos */ 292b3787f6Schristos #ifndef EVENT2_EVENT_H_INCLUDED_ 302b3787f6Schristos #define EVENT2_EVENT_H_INCLUDED_ 312b3787f6Schristos 322b3787f6Schristos /** 332b3787f6Schristos @mainpage 342b3787f6Schristos 352b3787f6Schristos @section intro Introduction 362b3787f6Schristos 372b3787f6Schristos Libevent is an event notification library for developing scalable network 382b3787f6Schristos servers. The Libevent API provides a mechanism to execute a callback 392b3787f6Schristos function when a specific event occurs on a file descriptor or after a 402b3787f6Schristos timeout has been reached. Furthermore, Libevent also support callbacks due 412b3787f6Schristos to signals or regular timeouts. 422b3787f6Schristos 432b3787f6Schristos Libevent is meant to replace the event loop found in event driven network 442b3787f6Schristos servers. An application just needs to call event_base_dispatch() and then add or 452b3787f6Schristos remove events dynamically without having to change the event loop. 462b3787f6Schristos 472b3787f6Schristos 482b3787f6Schristos Currently, Libevent supports /dev/poll, kqueue(2), select(2), poll(2), 492b3787f6Schristos epoll(4), and evports. The internal event mechanism is completely 502b3787f6Schristos independent of the exposed event API, and a simple update of Libevent can 512b3787f6Schristos provide new functionality without having to redesign the applications. As a 522b3787f6Schristos result, Libevent allows for portable application development and provides 532b3787f6Schristos the most scalable event notification mechanism available on an operating 542b3787f6Schristos system. Libevent can also be used for multithreaded programs. Libevent 552b3787f6Schristos should compile on Linux, *BSD, Mac OS X, Solaris and, Windows. 562b3787f6Schristos 572b3787f6Schristos @section usage Standard usage 582b3787f6Schristos 591b6f2cd4Schristos Every program that uses Libevent must include the <event2/event.h> 602b3787f6Schristos header, and pass the -levent flag to the linker. (You can instead link 612b3787f6Schristos -levent_core if you only want the main event and buffered IO-based code, 622b3787f6Schristos and don't want to link any protocol code.) 632b3787f6Schristos 642b3787f6Schristos @section setup Library setup 652b3787f6Schristos 662b3787f6Schristos Before you call any other Libevent functions, you need to set up the 672b3787f6Schristos library. If you're going to use Libevent from multiple threads in a 682b3787f6Schristos multithreaded application, you need to initialize thread support -- 692b3787f6Schristos typically by using evthread_use_pthreads() or 702b3787f6Schristos evthread_use_windows_threads(). See <event2/thread.h> for more 712b3787f6Schristos information. 722b3787f6Schristos 732b3787f6Schristos This is also the point where you can replace Libevent's memory 742b3787f6Schristos management functions with event_set_mem_functions, and enable debug mode 752b3787f6Schristos with event_enable_debug_mode(). 762b3787f6Schristos 772b3787f6Schristos @section base Creating an event base 782b3787f6Schristos 792b3787f6Schristos Next, you need to create an event_base structure, using event_base_new() 802b3787f6Schristos or event_base_new_with_config(). The event_base is responsible for 812b3787f6Schristos keeping track of which events are "pending" (that is to say, being 822b3787f6Schristos watched to see if they become active) and which events are "active". 832b3787f6Schristos Every event is associated with a single event_base. 842b3787f6Schristos 852b3787f6Schristos @section event Event notification 862b3787f6Schristos 872b3787f6Schristos For each file descriptor that you wish to monitor, you must create an 882b3787f6Schristos event structure with event_new(). (You may also declare an event 892b3787f6Schristos structure and call event_assign() to initialize the members of the 902b3787f6Schristos structure.) To enable notification, you add the structure to the list 912b3787f6Schristos of monitored events by calling event_add(). The event structure must 922b3787f6Schristos remain allocated as long as it is active, so it should generally be 932b3787f6Schristos allocated on the heap. 942b3787f6Schristos 952b3787f6Schristos @section loop Dispatching events. 962b3787f6Schristos 972b3787f6Schristos Finally, you call event_base_dispatch() to loop and dispatch events. 982b3787f6Schristos You can also use event_base_loop() for more fine-grained control. 992b3787f6Schristos 1002b3787f6Schristos Currently, only one thread can be dispatching a given event_base at a 1012b3787f6Schristos time. If you want to run events in multiple threads at once, you can 1022b3787f6Schristos either have a single event_base whose events add work to a work queue, 1032b3787f6Schristos or you can create multiple event_base objects. 1042b3787f6Schristos 1052b3787f6Schristos @section bufferevent I/O Buffers 1062b3787f6Schristos 1072b3787f6Schristos Libevent provides a buffered I/O abstraction on top of the regular event 1082b3787f6Schristos callbacks. This abstraction is called a bufferevent. A bufferevent 1092b3787f6Schristos provides input and output buffers that get filled and drained 1102b3787f6Schristos automatically. The user of a buffered event no longer deals directly 1112b3787f6Schristos with the I/O, but instead is reading from input and writing to output 1122b3787f6Schristos buffers. 1132b3787f6Schristos 1142b3787f6Schristos Once initialized via bufferevent_socket_new(), the bufferevent structure 1152b3787f6Schristos can be used repeatedly with bufferevent_enable() and 1162b3787f6Schristos bufferevent_disable(). Instead of reading and writing directly to a 1172b3787f6Schristos socket, you would call bufferevent_read() and bufferevent_write(). 1182b3787f6Schristos 1192b3787f6Schristos When read enabled the bufferevent will try to read from the file descriptor 1202b3787f6Schristos and call the read callback. The write callback is executed whenever the 1212b3787f6Schristos output buffer is drained below the write low watermark, which is 0 by 1222b3787f6Schristos default. 1232b3787f6Schristos 1242b3787f6Schristos See <event2/bufferevent*.h> for more information. 1252b3787f6Schristos 1262b3787f6Schristos @section timers Timers 1272b3787f6Schristos 1282b3787f6Schristos Libevent can also be used to create timers that invoke a callback after a 1291b6f2cd4Schristos certain amount of time has expired. The evtimer_new() macro returns 1302b3787f6Schristos an event struct to use as a timer. To activate the timer, call 1312b3787f6Schristos evtimer_add(). Timers can be deactivated by calling evtimer_del(). 1321b6f2cd4Schristos (These macros are thin wrappers around event_new(), event_add(), 1331b6f2cd4Schristos and event_del(); you can also use those instead.) 1342b3787f6Schristos 1352b3787f6Schristos @section evdns Asynchronous DNS resolution 1362b3787f6Schristos 1372b3787f6Schristos Libevent provides an asynchronous DNS resolver that should be used instead 1382b3787f6Schristos of the standard DNS resolver functions. See the <event2/dns.h> 1392b3787f6Schristos functions for more detail. 1402b3787f6Schristos 1412b3787f6Schristos @section evhttp Event-driven HTTP servers 1422b3787f6Schristos 1432b3787f6Schristos Libevent provides a very simple event-driven HTTP server that can be 1442b3787f6Schristos embedded in your program and used to service HTTP requests. 1452b3787f6Schristos 1462b3787f6Schristos To use this capability, you need to include the <event2/http.h> header in your 1472b3787f6Schristos program. See that header for more information. 1482b3787f6Schristos 1492b3787f6Schristos @section evrpc A framework for RPC servers and clients 1502b3787f6Schristos 1512b3787f6Schristos Libevent provides a framework for creating RPC servers and clients. It 1522b3787f6Schristos takes care of marshaling and unmarshaling all data structures. 1532b3787f6Schristos 1542b3787f6Schristos @section api API Reference 1552b3787f6Schristos 1562b3787f6Schristos To browse the complete documentation of the libevent API, click on any of 1572b3787f6Schristos the following links. 1582b3787f6Schristos 1592b3787f6Schristos event2/event.h 1602b3787f6Schristos The primary libevent header 1612b3787f6Schristos 1622b3787f6Schristos event2/thread.h 1632b3787f6Schristos Functions for use by multithreaded programs 1642b3787f6Schristos 1652b3787f6Schristos event2/buffer.h and event2/bufferevent.h 1662b3787f6Schristos Buffer management for network reading and writing 1672b3787f6Schristos 1682b3787f6Schristos event2/util.h 1692b3787f6Schristos Utility functions for portable nonblocking network code 1702b3787f6Schristos 1712b3787f6Schristos event2/dns.h 1722b3787f6Schristos Asynchronous DNS resolution 1732b3787f6Schristos 1742b3787f6Schristos event2/http.h 1752b3787f6Schristos An embedded libevent-based HTTP server 1762b3787f6Schristos 1772b3787f6Schristos event2/rpc.h 1782b3787f6Schristos A framework for creating RPC servers and clients 1792b3787f6Schristos 1802b3787f6Schristos */ 1812b3787f6Schristos 1822b3787f6Schristos /** @file event2/event.h 1832b3787f6Schristos 1842b3787f6Schristos Core functions for waiting for and receiving events, and using event bases. 1852b3787f6Schristos */ 1862b3787f6Schristos 1871b6f2cd4Schristos #include <event2/visibility.h> 1881b6f2cd4Schristos 1892b3787f6Schristos #ifdef __cplusplus 1902b3787f6Schristos extern "C" { 1912b3787f6Schristos #endif 1922b3787f6Schristos 1932b3787f6Schristos #include <event2/event-config.h> 1942b3787f6Schristos #ifdef EVENT__HAVE_SYS_TYPES_H 1952b3787f6Schristos #include <sys/types.h> 1962b3787f6Schristos #endif 1972b3787f6Schristos #ifdef EVENT__HAVE_SYS_TIME_H 1982b3787f6Schristos #include <sys/time.h> 1992b3787f6Schristos #endif 2002b3787f6Schristos 2012b3787f6Schristos #include <stdio.h> 2022b3787f6Schristos 2032b3787f6Schristos /* For int types. */ 2042b3787f6Schristos #include <event2/util.h> 2052b3787f6Schristos 2062b3787f6Schristos /** 2072b3787f6Schristos * Structure to hold information and state for a Libevent dispatch loop. 2082b3787f6Schristos * 2092b3787f6Schristos * The event_base lies at the center of Libevent; every application will 2102b3787f6Schristos * have one. It keeps track of all pending and active events, and 2112b3787f6Schristos * notifies your application of the active ones. 2122b3787f6Schristos * 2132b3787f6Schristos * This is an opaque structure; you can allocate one using 2142b3787f6Schristos * event_base_new() or event_base_new_with_config(). 2152b3787f6Schristos * 2162b3787f6Schristos * @see event_base_new(), event_base_free(), event_base_loop(), 2172b3787f6Schristos * event_base_new_with_config() 2182b3787f6Schristos */ 2192b3787f6Schristos struct event_base 2202b3787f6Schristos #ifdef EVENT_IN_DOXYGEN_ 2212b3787f6Schristos {/*Empty body so that doxygen will generate documentation here.*/} 2222b3787f6Schristos #endif 2232b3787f6Schristos ; 2242b3787f6Schristos 2252b3787f6Schristos /** 2262b3787f6Schristos * @struct event 2272b3787f6Schristos * 2282b3787f6Schristos * Structure to represent a single event. 2292b3787f6Schristos * 2302b3787f6Schristos * An event can have some underlying condition it represents: a socket 2312b3787f6Schristos * becoming readable or writeable (or both), or a signal becoming raised. 2322b3787f6Schristos * (An event that represents no underlying condition is still useful: you 2332b3787f6Schristos * can use one to implement a timer, or to communicate between threads.) 2342b3787f6Schristos * 2352b3787f6Schristos * Generally, you can create events with event_new(), then make them 2362b3787f6Schristos * pending with event_add(). As your event_base runs, it will run the 2372b3787f6Schristos * callbacks of an events whose conditions are triggered. When you 2382b3787f6Schristos * longer want the event, free it with event_free(). 2392b3787f6Schristos * 2402b3787f6Schristos * In more depth: 2412b3787f6Schristos * 2422b3787f6Schristos * An event may be "pending" (one whose condition we are watching), 2432b3787f6Schristos * "active" (one whose condition has triggered and whose callback is about 2442b3787f6Schristos * to run), neither, or both. Events come into existence via 2452b3787f6Schristos * event_assign() or event_new(), and are then neither active nor pending. 2462b3787f6Schristos * 2472b3787f6Schristos * To make an event pending, pass it to event_add(). When doing so, you 2482b3787f6Schristos * can also set a timeout for the event. 2492b3787f6Schristos * 2502b3787f6Schristos * Events become active during an event_base_loop() call when either their 2512b3787f6Schristos * condition has triggered, or when their timeout has elapsed. You can 2522b3787f6Schristos * also activate an event manually using event_active(). The even_base 2532b3787f6Schristos * loop will run the callbacks of active events; after it has done so, it 2542b3787f6Schristos * marks them as no longer active. 2552b3787f6Schristos * 2562b3787f6Schristos * You can make an event non-pending by passing it to event_del(). This 2572b3787f6Schristos * also makes the event non-active. 2582b3787f6Schristos * 2592b3787f6Schristos * Events can be "persistent" or "non-persistent". A non-persistent event 2602b3787f6Schristos * becomes non-pending as soon as it is triggered: thus, it only runs at 2612b3787f6Schristos * most once per call to event_add(). A persistent event remains pending 2622b3787f6Schristos * even when it becomes active: you'll need to event_del() it manually in 2632b3787f6Schristos * order to make it non-pending. When a persistent event with a timeout 2642b3787f6Schristos * becomes active, its timeout is reset: this means you can use persistent 2652b3787f6Schristos * events to implement periodic timeouts. 2662b3787f6Schristos * 2672b3787f6Schristos * This should be treated as an opaque structure; you should never read or 2682b3787f6Schristos * write any of its fields directly. For backward compatibility with old 2692b3787f6Schristos * code, it is defined in the event2/event_struct.h header; including this 2702b3787f6Schristos * header may make your code incompatible with other versions of Libevent. 2712b3787f6Schristos * 2722b3787f6Schristos * @see event_new(), event_free(), event_assign(), event_get_assignment(), 2732b3787f6Schristos * event_add(), event_del(), event_active(), event_pending(), 2742b3787f6Schristos * event_get_fd(), event_get_base(), event_get_events(), 2752b3787f6Schristos * event_get_callback(), event_get_callback_arg(), 2762b3787f6Schristos * event_priority_set() 2772b3787f6Schristos */ 2782b3787f6Schristos struct event 2792b3787f6Schristos #ifdef EVENT_IN_DOXYGEN_ 2802b3787f6Schristos {/*Empty body so that doxygen will generate documentation here.*/} 2812b3787f6Schristos #endif 2822b3787f6Schristos ; 2832b3787f6Schristos 2842b3787f6Schristos /** 2852b3787f6Schristos * Configuration for an event_base. 2862b3787f6Schristos * 2872b3787f6Schristos * There are many options that can be used to alter the behavior and 2882b3787f6Schristos * implementation of an event_base. To avoid having to pass them all in a 2892b3787f6Schristos * complex many-argument constructor, we provide an abstract data type 2902b3787f6Schristos * wrhere you set up configation information before passing it to 2912b3787f6Schristos * event_base_new_with_config(). 2922b3787f6Schristos * 2932b3787f6Schristos * @see event_config_new(), event_config_free(), event_base_new_with_config(), 2942b3787f6Schristos * event_config_avoid_method(), event_config_require_features(), 2952b3787f6Schristos * event_config_set_flag(), event_config_set_num_cpus_hint() 2962b3787f6Schristos */ 2972b3787f6Schristos struct event_config 2982b3787f6Schristos #ifdef EVENT_IN_DOXYGEN_ 2992b3787f6Schristos {/*Empty body so that doxygen will generate documentation here.*/} 3002b3787f6Schristos #endif 3012b3787f6Schristos ; 3022b3787f6Schristos 3032b3787f6Schristos /** 3042b3787f6Schristos * Enable some relatively expensive debugging checks in Libevent that 3052b3787f6Schristos * would normally be turned off. Generally, these checks cause code that 3062b3787f6Schristos * would otherwise crash mysteriously to fail earlier with an assertion 3072b3787f6Schristos * failure. Note that this method MUST be called before any events or 3082b3787f6Schristos * event_bases have been created. 3092b3787f6Schristos * 3102b3787f6Schristos * Debug mode can currently catch the following errors: 3112b3787f6Schristos * An event is re-assigned while it is added 3122b3787f6Schristos * Any function is called on a non-assigned event 3132b3787f6Schristos * 3142b3787f6Schristos * Note that debugging mode uses memory to track every event that has been 3152b3787f6Schristos * initialized (via event_assign, event_set, or event_new) but not yet 3162b3787f6Schristos * released (via event_free or event_debug_unassign). If you want to use 3172b3787f6Schristos * debug mode, and you find yourself running out of memory, you will need 3182b3787f6Schristos * to use event_debug_unassign to explicitly stop tracking events that 3192b3787f6Schristos * are no longer considered set-up. 3202b3787f6Schristos * 3212b3787f6Schristos * @see event_debug_unassign() 3222b3787f6Schristos */ 3231b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 3242b3787f6Schristos void event_enable_debug_mode(void); 3252b3787f6Schristos 3262b3787f6Schristos /** 3272b3787f6Schristos * When debugging mode is enabled, informs Libevent that an event should no 3282b3787f6Schristos * longer be considered as assigned. When debugging mode is not enabled, does 3292b3787f6Schristos * nothing. 3302b3787f6Schristos * 3312b3787f6Schristos * This function must only be called on a non-added event. 3322b3787f6Schristos * 3332b3787f6Schristos * @see event_enable_debug_mode() 3342b3787f6Schristos */ 3351b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 3362b3787f6Schristos void event_debug_unassign(struct event *); 3372b3787f6Schristos 3382b3787f6Schristos /** 3392b3787f6Schristos * Create and return a new event_base to use with the rest of Libevent. 3402b3787f6Schristos * 3412b3787f6Schristos * @return a new event_base on success, or NULL on failure. 3422b3787f6Schristos * 3432b3787f6Schristos * @see event_base_free(), event_base_new_with_config() 3442b3787f6Schristos */ 3451b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 3462b3787f6Schristos struct event_base *event_base_new(void); 3472b3787f6Schristos 3482b3787f6Schristos /** 3492b3787f6Schristos Reinitialize the event base after a fork 3502b3787f6Schristos 3512b3787f6Schristos Some event mechanisms do not survive across fork. The event base needs 3522b3787f6Schristos to be reinitialized with the event_reinit() function. 3532b3787f6Schristos 3542b3787f6Schristos @param base the event base that needs to be re-initialized 3552b3787f6Schristos @return 0 if successful, or -1 if some events could not be re-added. 3562b3787f6Schristos @see event_base_new() 3572b3787f6Schristos */ 3581b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 3592b3787f6Schristos int event_reinit(struct event_base *base); 3602b3787f6Schristos 3612b3787f6Schristos /** 3622b3787f6Schristos Event dispatching loop 3632b3787f6Schristos 3641b6f2cd4Schristos This loop will run the event base until either there are no more pending or 3651b6f2cd4Schristos active, or until something calls event_base_loopbreak() or 3662b3787f6Schristos event_base_loopexit(). 3672b3787f6Schristos 3682b3787f6Schristos @param base the event_base structure returned by event_base_new() or 3692b3787f6Schristos event_base_new_with_config() 3701b6f2cd4Schristos @return 0 if successful, -1 if an error occurred, or 1 if we exited because 3711b6f2cd4Schristos no events were pending or active. 3722b3787f6Schristos @see event_base_loop() 3732b3787f6Schristos */ 3741b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 3752b3787f6Schristos int event_base_dispatch(struct event_base *); 3762b3787f6Schristos 3772b3787f6Schristos /** 3782b3787f6Schristos Get the kernel event notification mechanism used by Libevent. 3792b3787f6Schristos 3802b3787f6Schristos @param eb the event_base structure returned by event_base_new() 3812b3787f6Schristos @return a string identifying the kernel event mechanism (kqueue, epoll, etc.) 3822b3787f6Schristos */ 3831b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 3842b3787f6Schristos const char *event_base_get_method(const struct event_base *); 3852b3787f6Schristos 3862b3787f6Schristos /** 3872b3787f6Schristos Gets all event notification mechanisms supported by Libevent. 3882b3787f6Schristos 3892b3787f6Schristos This functions returns the event mechanism in order preferred by 3902b3787f6Schristos Libevent. Note that this list will include all backends that 3912b3787f6Schristos Libevent has compiled-in support for, and will not necessarily check 3922b3787f6Schristos your OS to see whether it has the required resources. 3932b3787f6Schristos 3942b3787f6Schristos @return an array with pointers to the names of support methods. 3952b3787f6Schristos The end of the array is indicated by a NULL pointer. If an 3962b3787f6Schristos error is encountered NULL is returned. 3972b3787f6Schristos */ 3981b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 3992b3787f6Schristos const char **event_get_supported_methods(void); 4002b3787f6Schristos 40150cc4415Schristos /** Query the current monotonic time from a the timer for a struct 40250cc4415Schristos * event_base. 40350cc4415Schristos */ 40450cc4415Schristos EVENT2_EXPORT_SYMBOL 40550cc4415Schristos int event_gettime_monotonic(struct event_base *base, struct timeval *tp); 40650cc4415Schristos 4072b3787f6Schristos /** 4081b6f2cd4Schristos @name event type flag 4091b6f2cd4Schristos 4101b6f2cd4Schristos Flags to pass to event_base_get_num_events() to specify the kinds of events 4111b6f2cd4Schristos we want to aggregate counts for 4121b6f2cd4Schristos */ 4131b6f2cd4Schristos /**@{*/ 4141b6f2cd4Schristos /** count the number of active events, which have been triggered.*/ 4151b6f2cd4Schristos #define EVENT_BASE_COUNT_ACTIVE 1U 4161b6f2cd4Schristos /** count the number of virtual events, which is used to represent an internal 4171b6f2cd4Schristos * condition, other than a pending event, that keeps the loop from exiting. */ 4181b6f2cd4Schristos #define EVENT_BASE_COUNT_VIRTUAL 2U 4191b6f2cd4Schristos /** count the number of events which have been added to event base, including 4201b6f2cd4Schristos * internal events. */ 4211b6f2cd4Schristos #define EVENT_BASE_COUNT_ADDED 4U 4221b6f2cd4Schristos /**@}*/ 4231b6f2cd4Schristos 4241b6f2cd4Schristos /** 4251b6f2cd4Schristos Gets the number of events in event_base, as specified in the flags. 4261b6f2cd4Schristos 4271b6f2cd4Schristos Since event base has some internal events added to make some of its 4281b6f2cd4Schristos functionalities work, EVENT_BASE_COUNT_ADDED may return more than the 4291b6f2cd4Schristos number of events you added using event_add(). 4301b6f2cd4Schristos 4311b6f2cd4Schristos If you pass EVENT_BASE_COUNT_ACTIVE and EVENT_BASE_COUNT_ADDED together, an 4321b6f2cd4Schristos active event will be counted twice. However, this might not be the case in 4331b6f2cd4Schristos future libevent versions. The return value is an indication of the work 4341b6f2cd4Schristos load, but the user shouldn't rely on the exact value as this may change in 4351b6f2cd4Schristos the future. 4361b6f2cd4Schristos 4371b6f2cd4Schristos @param eb the event_base structure returned by event_base_new() 4381b6f2cd4Schristos @param flags a bitwise combination of the kinds of events to aggregate 4391b6f2cd4Schristos counts for 4401b6f2cd4Schristos @return the number of events specified in the flags 4411b6f2cd4Schristos */ 4421b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 4431b6f2cd4Schristos int event_base_get_num_events(struct event_base *, unsigned int); 4441b6f2cd4Schristos 4451b6f2cd4Schristos /** 4461b6f2cd4Schristos Get the maximum number of events in a given event_base as specified in the 4471b6f2cd4Schristos flags. 4481b6f2cd4Schristos 4491b6f2cd4Schristos @param eb the event_base structure returned by event_base_new() 4501b6f2cd4Schristos @param flags a bitwise combination of the kinds of events to aggregate 4511b6f2cd4Schristos counts for 4521b6f2cd4Schristos @param clear option used to reset the maximum count. 4531b6f2cd4Schristos @return the number of events specified in the flags 4541b6f2cd4Schristos */ 4551b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 4561b6f2cd4Schristos int event_base_get_max_events(struct event_base *, unsigned int, int); 4571b6f2cd4Schristos 4581b6f2cd4Schristos /** 4592b3787f6Schristos Allocates a new event configuration object. 4602b3787f6Schristos 4612b3787f6Schristos The event configuration object can be used to change the behavior of 4622b3787f6Schristos an event base. 4632b3787f6Schristos 4642b3787f6Schristos @return an event_config object that can be used to store configuration, or 4652b3787f6Schristos NULL if an error is encountered. 4662b3787f6Schristos @see event_base_new_with_config(), event_config_free(), event_config 4672b3787f6Schristos */ 4681b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 4692b3787f6Schristos struct event_config *event_config_new(void); 4702b3787f6Schristos 4712b3787f6Schristos /** 4722b3787f6Schristos Deallocates all memory associated with an event configuration object 4732b3787f6Schristos 4742b3787f6Schristos @param cfg the event configuration object to be freed. 4752b3787f6Schristos */ 4761b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 4772b3787f6Schristos void event_config_free(struct event_config *cfg); 4782b3787f6Schristos 4792b3787f6Schristos /** 4802b3787f6Schristos Enters an event method that should be avoided into the configuration. 4812b3787f6Schristos 4822b3787f6Schristos This can be used to avoid event mechanisms that do not support certain 4832b3787f6Schristos file descriptor types, or for debugging to avoid certain event 4842b3787f6Schristos mechanisms. An application can make use of multiple event bases to 4852b3787f6Schristos accommodate incompatible file descriptor types. 4862b3787f6Schristos 4872b3787f6Schristos @param cfg the event configuration object 4882b3787f6Schristos @param method the name of the event method to avoid 4892b3787f6Schristos @return 0 on success, -1 on failure. 4902b3787f6Schristos */ 4911b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 4922b3787f6Schristos int event_config_avoid_method(struct event_config *cfg, const char *method); 4932b3787f6Schristos 4942b3787f6Schristos /** 4952b3787f6Schristos A flag used to describe which features an event_base (must) provide. 4962b3787f6Schristos 4972b3787f6Schristos Because of OS limitations, not every Libevent backend supports every 4982b3787f6Schristos possible feature. You can use this type with 4992b3787f6Schristos event_config_require_features() to tell Libevent to only proceed if your 5002b3787f6Schristos event_base implements a given feature, and you can receive this type from 5012b3787f6Schristos event_base_get_features() to see which features are available. 5022b3787f6Schristos */ 5032b3787f6Schristos enum event_method_feature { 5042b3787f6Schristos /** Require an event method that allows edge-triggered events with EV_ET. */ 5052b3787f6Schristos EV_FEATURE_ET = 0x01, 5062b3787f6Schristos /** Require an event method where having one event triggered among 5072b3787f6Schristos * many is [approximately] an O(1) operation. This excludes (for 5082b3787f6Schristos * example) select and poll, which are approximately O(N) for N 5092b3787f6Schristos * equal to the total number of possible events. */ 5102b3787f6Schristos EV_FEATURE_O1 = 0x02, 5112b3787f6Schristos /** Require an event method that allows file descriptors as well as 5122b3787f6Schristos * sockets. */ 5131b6f2cd4Schristos EV_FEATURE_FDS = 0x04, 5141b6f2cd4Schristos /** Require an event method that allows you to use EV_CLOSED to detect 5151b6f2cd4Schristos * connection close without the necessity of reading all the pending data. 5161b6f2cd4Schristos * 5171b6f2cd4Schristos * Methods that do support EV_CLOSED may not be able to provide support on 5181b6f2cd4Schristos * all kernel versions. 5191b6f2cd4Schristos **/ 5201b6f2cd4Schristos EV_FEATURE_EARLY_CLOSE = 0x08 5212b3787f6Schristos }; 5222b3787f6Schristos 5232b3787f6Schristos /** 5242b3787f6Schristos A flag passed to event_config_set_flag(). 5252b3787f6Schristos 5262b3787f6Schristos These flags change the behavior of an allocated event_base. 5272b3787f6Schristos 5282b3787f6Schristos @see event_config_set_flag(), event_base_new_with_config(), 5292b3787f6Schristos event_method_feature 5302b3787f6Schristos */ 5312b3787f6Schristos enum event_base_config_flag { 5322b3787f6Schristos /** Do not allocate a lock for the event base, even if we have 5332b3787f6Schristos locking set up. 5342b3787f6Schristos 5352b3787f6Schristos Setting this option will make it unsafe and nonfunctional to call 5362b3787f6Schristos functions on the base concurrently from multiple threads. 5372b3787f6Schristos */ 5382b3787f6Schristos EVENT_BASE_FLAG_NOLOCK = 0x01, 5392b3787f6Schristos /** Do not check the EVENT_* environment variables when configuring 5402b3787f6Schristos an event_base */ 5412b3787f6Schristos EVENT_BASE_FLAG_IGNORE_ENV = 0x02, 5422b3787f6Schristos /** Windows only: enable the IOCP dispatcher at startup 5432b3787f6Schristos 5442b3787f6Schristos If this flag is set then bufferevent_socket_new() and 5452b3787f6Schristos evconn_listener_new() will use IOCP-backed implementations 5462b3787f6Schristos instead of the usual select-based one on Windows. 5472b3787f6Schristos */ 5482b3787f6Schristos EVENT_BASE_FLAG_STARTUP_IOCP = 0x04, 5492b3787f6Schristos /** Instead of checking the current time every time the event loop is 5502b3787f6Schristos ready to run timeout callbacks, check after each timeout callback. 5512b3787f6Schristos */ 5522b3787f6Schristos EVENT_BASE_FLAG_NO_CACHE_TIME = 0x08, 5532b3787f6Schristos 5542b3787f6Schristos /** If we are using the epoll backend, this flag says that it is 5552b3787f6Schristos safe to use Libevent's internal change-list code to batch up 5562b3787f6Schristos adds and deletes in order to try to do as few syscalls as 5572b3787f6Schristos possible. Setting this flag can make your code run faster, but 5582b3787f6Schristos it may trigger a Linux bug: it is not safe to use this flag 5592b3787f6Schristos if you have any fds cloned by dup() or its variants. Doing so 5602b3787f6Schristos will produce strange and hard-to-diagnose bugs. 5612b3787f6Schristos 5621b6f2cd4Schristos This flag can also be activated by setting the 5632b3787f6Schristos EVENT_EPOLL_USE_CHANGELIST environment variable. 5642b3787f6Schristos 5652b3787f6Schristos This flag has no effect if you wind up using a backend other than 5662b3787f6Schristos epoll. 5672b3787f6Schristos */ 5682b3787f6Schristos EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST = 0x10, 5692b3787f6Schristos 5702b3787f6Schristos /** Ordinarily, Libevent implements its time and timeout code using 5712b3787f6Schristos the fastest monotonic timer that we have. If this flag is set, 5722b3787f6Schristos however, we use less efficient more precise timer, assuming one is 5732b3787f6Schristos present. 5742b3787f6Schristos */ 5752b3787f6Schristos EVENT_BASE_FLAG_PRECISE_TIMER = 0x20 5762b3787f6Schristos }; 5772b3787f6Schristos 5782b3787f6Schristos /** 5792b3787f6Schristos Return a bitmask of the features implemented by an event base. This 5802b3787f6Schristos will be a bitwise OR of one or more of the values of 5812b3787f6Schristos event_method_feature 5822b3787f6Schristos 5832b3787f6Schristos @see event_method_feature 5842b3787f6Schristos */ 5851b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 5862b3787f6Schristos int event_base_get_features(const struct event_base *base); 5872b3787f6Schristos 5882b3787f6Schristos /** 5892b3787f6Schristos Enters a required event method feature that the application demands. 5902b3787f6Schristos 5912b3787f6Schristos Note that not every feature or combination of features is supported 5922b3787f6Schristos on every platform. Code that requests features should be prepared 5932b3787f6Schristos to handle the case where event_base_new_with_config() returns NULL, as in: 5942b3787f6Schristos <pre> 5952b3787f6Schristos event_config_require_features(cfg, EV_FEATURE_ET); 5962b3787f6Schristos base = event_base_new_with_config(cfg); 5972b3787f6Schristos if (base == NULL) { 5982b3787f6Schristos // We can't get edge-triggered behavior here. 5992b3787f6Schristos event_config_require_features(cfg, 0); 6002b3787f6Schristos base = event_base_new_with_config(cfg); 6012b3787f6Schristos } 6022b3787f6Schristos </pre> 6032b3787f6Schristos 6042b3787f6Schristos @param cfg the event configuration object 6052b3787f6Schristos @param feature a bitfield of one or more event_method_feature values. 6062b3787f6Schristos Replaces values from previous calls to this function. 6072b3787f6Schristos @return 0 on success, -1 on failure. 6082b3787f6Schristos @see event_method_feature, event_base_new_with_config() 6092b3787f6Schristos */ 6101b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 6112b3787f6Schristos int event_config_require_features(struct event_config *cfg, int feature); 6122b3787f6Schristos 6132b3787f6Schristos /** 6142b3787f6Schristos * Sets one or more flags to configure what parts of the eventual event_base 6152b3787f6Schristos * will be initialized, and how they'll work. 6162b3787f6Schristos * 6172b3787f6Schristos * @see event_base_config_flags, event_base_new_with_config() 6182b3787f6Schristos **/ 6191b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 6202b3787f6Schristos int event_config_set_flag(struct event_config *cfg, int flag); 6212b3787f6Schristos 6222b3787f6Schristos /** 6232b3787f6Schristos * Records a hint for the number of CPUs in the system. This is used for 6242b3787f6Schristos * tuning thread pools, etc, for optimal performance. In Libevent 2.0, 6252b3787f6Schristos * it is only on Windows, and only when IOCP is in use. 6262b3787f6Schristos * 6272b3787f6Schristos * @param cfg the event configuration object 6282b3787f6Schristos * @param cpus the number of cpus 6292b3787f6Schristos * @return 0 on success, -1 on failure. 6302b3787f6Schristos */ 6311b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 6322b3787f6Schristos int event_config_set_num_cpus_hint(struct event_config *cfg, int cpus); 6332b3787f6Schristos 6342b3787f6Schristos /** 6352b3787f6Schristos * Record an interval and/or a number of callbacks after which the event base 6362b3787f6Schristos * should check for new events. By default, the event base will run as many 6372b3787f6Schristos * events are as activated at the higest activated priority before checking 6382b3787f6Schristos * for new events. If you configure it by setting max_interval, it will check 6392b3787f6Schristos * the time after each callback, and not allow more than max_interval to 6402b3787f6Schristos * elapse before checking for new events. If you configure it by setting 6412b3787f6Schristos * max_callbacks to a value >= 0, it will run no more than max_callbacks 6422b3787f6Schristos * callbacks before checking for new events. 6432b3787f6Schristos * 6442b3787f6Schristos * This option can decrease the latency of high-priority events, and 6452b3787f6Schristos * avoid priority inversions where multiple low-priority events keep us from 6462b3787f6Schristos * polling for high-priority events, but at the expense of slightly decreasing 6472b3787f6Schristos * the throughput. Use it with caution! 6482b3787f6Schristos * 6492b3787f6Schristos * @param cfg The event_base configuration object. 6502b3787f6Schristos * @param max_interval An interval after which Libevent should stop running 6512b3787f6Schristos * callbacks and check for more events, or NULL if there should be 6522b3787f6Schristos * no such interval. 6532b3787f6Schristos * @param max_callbacks A number of callbacks after which Libevent should 6542b3787f6Schristos * stop running callbacks and check for more events, or -1 if there 6552b3787f6Schristos * should be no such limit. 6562b3787f6Schristos * @param min_priority A priority below which max_interval and max_callbacks 6572b3787f6Schristos * should not be enforced. If this is set to 0, they are enforced 6582b3787f6Schristos * for events of every priority; if it's set to 1, they're enforced 6592b3787f6Schristos * for events of priority 1 and above, and so on. 6602b3787f6Schristos * @return 0 on success, -1 on failure. 6612b3787f6Schristos **/ 6621b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 6632b3787f6Schristos int event_config_set_max_dispatch_interval(struct event_config *cfg, 6642b3787f6Schristos const struct timeval *max_interval, int max_callbacks, 6652b3787f6Schristos int min_priority); 6662b3787f6Schristos 6672b3787f6Schristos /** 6682b3787f6Schristos Initialize the event API. 6692b3787f6Schristos 6702b3787f6Schristos Use event_base_new_with_config() to initialize a new event base, taking 6712b3787f6Schristos the specified configuration under consideration. The configuration object 6722b3787f6Schristos can currently be used to avoid certain event notification mechanisms. 6732b3787f6Schristos 6742b3787f6Schristos @param cfg the event configuration object 6752b3787f6Schristos @return an initialized event_base that can be used to registering events, 6762b3787f6Schristos or NULL if no event base can be created with the requested event_config. 6772b3787f6Schristos @see event_base_new(), event_base_free(), event_init(), event_assign() 6782b3787f6Schristos */ 6791b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 6802b3787f6Schristos struct event_base *event_base_new_with_config(const struct event_config *); 6812b3787f6Schristos 6822b3787f6Schristos /** 6832b3787f6Schristos Deallocate all memory associated with an event_base, and free the base. 6842b3787f6Schristos 6852b3787f6Schristos Note that this function will not close any fds or free any memory passed 6862b3787f6Schristos to event_new as the argument to callback. 6872b3787f6Schristos 6881b6f2cd4Schristos If there are any pending finalizer callbacks, this function will invoke 6891b6f2cd4Schristos them. 6901b6f2cd4Schristos 6912b3787f6Schristos @param eb an event_base to be freed 6922b3787f6Schristos */ 6931b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 6942b3787f6Schristos void event_base_free(struct event_base *); 6952b3787f6Schristos 6961b6f2cd4Schristos /** 6971b6f2cd4Schristos As event_free, but do not run finalizers. 6981b6f2cd4Schristos 6991b6f2cd4Schristos THIS IS AN EXPERIMENTAL API. IT MIGHT CHANGE BEFORE THE LIBEVENT 2.1 SERIES 7001b6f2cd4Schristos BECOMES STABLE. 7011b6f2cd4Schristos */ 7021b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 7031b6f2cd4Schristos void event_base_free_nofinalize(struct event_base *); 7041b6f2cd4Schristos 7052b3787f6Schristos /** @name Log severities 7062b3787f6Schristos */ 7072b3787f6Schristos /**@{*/ 7082b3787f6Schristos #define EVENT_LOG_DEBUG 0 7092b3787f6Schristos #define EVENT_LOG_MSG 1 7102b3787f6Schristos #define EVENT_LOG_WARN 2 7112b3787f6Schristos #define EVENT_LOG_ERR 3 7122b3787f6Schristos /**@}*/ 7132b3787f6Schristos 7142b3787f6Schristos /* Obsolete names: these are deprecated, but older programs might use them. 7152b3787f6Schristos * They violate the reserved-identifier namespace. */ 7162b3787f6Schristos #define _EVENT_LOG_DEBUG EVENT_LOG_DEBUG 7172b3787f6Schristos #define _EVENT_LOG_MSG EVENT_LOG_MSG 7182b3787f6Schristos #define _EVENT_LOG_WARN EVENT_LOG_WARN 7192b3787f6Schristos #define _EVENT_LOG_ERR EVENT_LOG_ERR 7202b3787f6Schristos 7212b3787f6Schristos /** 7222b3787f6Schristos A callback function used to intercept Libevent's log messages. 7232b3787f6Schristos 7242b3787f6Schristos @see event_set_log_callback 7252b3787f6Schristos */ 7262b3787f6Schristos typedef void (*event_log_cb)(int severity, const char *msg); 7272b3787f6Schristos /** 7282b3787f6Schristos Redirect Libevent's log messages. 7292b3787f6Schristos 7302b3787f6Schristos @param cb a function taking two arguments: an integer severity between 7312b3787f6Schristos EVENT_LOG_DEBUG and EVENT_LOG_ERR, and a string. If cb is NULL, 7322b3787f6Schristos then the default log is used. 7332b3787f6Schristos 7342b3787f6Schristos NOTE: The function you provide *must not* call any other libevent 7352b3787f6Schristos functionality. Doing so can produce undefined behavior. 7362b3787f6Schristos */ 7371b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 7382b3787f6Schristos void event_set_log_callback(event_log_cb cb); 7392b3787f6Schristos 7402b3787f6Schristos /** 7412b3787f6Schristos A function to be called if Libevent encounters a fatal internal error. 7422b3787f6Schristos 7432b3787f6Schristos @see event_set_fatal_callback 7442b3787f6Schristos */ 7452b3787f6Schristos typedef void (*event_fatal_cb)(int err); 7462b3787f6Schristos 7472b3787f6Schristos /** 7482b3787f6Schristos Override Libevent's behavior in the event of a fatal internal error. 7492b3787f6Schristos 7502b3787f6Schristos By default, Libevent will call exit(1) if a programming error makes it 7512b3787f6Schristos impossible to continue correct operation. This function allows you to supply 7522b3787f6Schristos another callback instead. Note that if the function is ever invoked, 7532b3787f6Schristos something is wrong with your program, or with Libevent: any subsequent calls 7542b3787f6Schristos to Libevent may result in undefined behavior. 7552b3787f6Schristos 7562b3787f6Schristos Libevent will (almost) always log an EVENT_LOG_ERR message before calling 7572b3787f6Schristos this function; look at the last log message to see why Libevent has died. 7582b3787f6Schristos */ 7591b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 7602b3787f6Schristos void event_set_fatal_callback(event_fatal_cb cb); 7612b3787f6Schristos 7622b3787f6Schristos #define EVENT_DBG_ALL 0xffffffffu 7632b3787f6Schristos #define EVENT_DBG_NONE 0 7642b3787f6Schristos 7652b3787f6Schristos /** 7662b3787f6Schristos Turn on debugging logs and have them sent to the default log handler. 7672b3787f6Schristos 7682b3787f6Schristos This is a global setting; if you are going to call it, you must call this 7692b3787f6Schristos before any calls that create an event-base. You must call it before any 7702b3787f6Schristos multithreaded use of Libevent. 7712b3787f6Schristos 7722b3787f6Schristos Debug logs are verbose. 7732b3787f6Schristos 7742b3787f6Schristos @param which Controls which debug messages are turned on. This option is 7752b3787f6Schristos unused for now; for forward compatibility, you must pass in the constant 7762b3787f6Schristos "EVENT_DBG_ALL" to turn debugging logs on, or "EVENT_DBG_NONE" to turn 7772b3787f6Schristos debugging logs off. 7782b3787f6Schristos */ 7791b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 7802b3787f6Schristos void event_enable_debug_logging(ev_uint32_t which); 7812b3787f6Schristos 78250cc4415Schristos EVENT2_EXPORT_SYMBOL 78350cc4415Schristos void 78450cc4415Schristos event_disable_debug_mode(void); 78550cc4415Schristos 7862b3787f6Schristos /** 7872b3787f6Schristos Associate a different event base with an event. 7882b3787f6Schristos 7892b3787f6Schristos The event to be associated must not be currently active or pending. 7902b3787f6Schristos 7912b3787f6Schristos @param eb the event base 7922b3787f6Schristos @param ev the event 7932b3787f6Schristos @return 0 on success, -1 on failure. 7942b3787f6Schristos */ 7951b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 7962b3787f6Schristos int event_base_set(struct event_base *, struct event *); 7972b3787f6Schristos 7982b3787f6Schristos /** @name Loop flags 7992b3787f6Schristos 8002b3787f6Schristos These flags control the behavior of event_base_loop(). 8012b3787f6Schristos */ 8022b3787f6Schristos /**@{*/ 8032b3787f6Schristos /** Block until we have an active event, then exit once all active events 8042b3787f6Schristos * have had their callbacks run. */ 8052b3787f6Schristos #define EVLOOP_ONCE 0x01 8062b3787f6Schristos /** Do not block: see which events are ready now, run the callbacks 8072b3787f6Schristos * of the highest-priority ones, then exit. */ 8082b3787f6Schristos #define EVLOOP_NONBLOCK 0x02 8092b3787f6Schristos /** Do not exit the loop because we have no pending events. Instead, keep 8102b3787f6Schristos * running until event_base_loopexit() or event_base_loopbreak() makes us 8112b3787f6Schristos * stop. 8122b3787f6Schristos */ 8132b3787f6Schristos #define EVLOOP_NO_EXIT_ON_EMPTY 0x04 8142b3787f6Schristos /**@}*/ 8152b3787f6Schristos 8162b3787f6Schristos /** 8172b3787f6Schristos Wait for events to become active, and run their callbacks. 8182b3787f6Schristos 8192b3787f6Schristos This is a more flexible version of event_base_dispatch(). 8202b3787f6Schristos 8212b3787f6Schristos By default, this loop will run the event base until either there are no more 8221b6f2cd4Schristos pending or active events, or until something calls event_base_loopbreak() or 8231b6f2cd4Schristos event_base_loopexit(). You can override this behavior with the 'flags' 8242b3787f6Schristos argument. 8252b3787f6Schristos 8262b3787f6Schristos @param eb the event_base structure returned by event_base_new() or 8272b3787f6Schristos event_base_new_with_config() 8282b3787f6Schristos @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK 8291b6f2cd4Schristos @return 0 if successful, -1 if an error occurred, or 1 if we exited because 8301b6f2cd4Schristos no events were pending or active. 8312b3787f6Schristos @see event_base_loopexit(), event_base_dispatch(), EVLOOP_ONCE, 8322b3787f6Schristos EVLOOP_NONBLOCK 8332b3787f6Schristos */ 8341b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 8352b3787f6Schristos int event_base_loop(struct event_base *, int); 8362b3787f6Schristos 8372b3787f6Schristos /** 8382b3787f6Schristos Exit the event loop after the specified time 8392b3787f6Schristos 8402b3787f6Schristos The next event_base_loop() iteration after the given timer expires will 8412b3787f6Schristos complete normally (handling all queued events) then exit without 8422b3787f6Schristos blocking for events again. 8432b3787f6Schristos 8442b3787f6Schristos Subsequent invocations of event_base_loop() will proceed normally. 8452b3787f6Schristos 8462b3787f6Schristos @param eb the event_base structure returned by event_init() 8472b3787f6Schristos @param tv the amount of time after which the loop should terminate, 8482b3787f6Schristos or NULL to exit after running all currently active events. 8492b3787f6Schristos @return 0 if successful, or -1 if an error occurred 8502b3787f6Schristos @see event_base_loopbreak() 8512b3787f6Schristos */ 8521b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 8532b3787f6Schristos int event_base_loopexit(struct event_base *, const struct timeval *); 8542b3787f6Schristos 8552b3787f6Schristos /** 8562b3787f6Schristos Abort the active event_base_loop() immediately. 8572b3787f6Schristos 8582b3787f6Schristos event_base_loop() will abort the loop after the next event is completed; 8592b3787f6Schristos event_base_loopbreak() is typically invoked from this event's callback. 8602b3787f6Schristos This behavior is analogous to the "break;" statement. 8612b3787f6Schristos 8622b3787f6Schristos Subsequent invocations of event_base_loop() will proceed normally. 8632b3787f6Schristos 8642b3787f6Schristos @param eb the event_base structure returned by event_init() 8652b3787f6Schristos @return 0 if successful, or -1 if an error occurred 8662b3787f6Schristos @see event_base_loopexit() 8672b3787f6Schristos */ 8681b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 8692b3787f6Schristos int event_base_loopbreak(struct event_base *); 8702b3787f6Schristos 8712b3787f6Schristos /** 8722b3787f6Schristos Tell the active event_base_loop() to scan for new events immediately. 8732b3787f6Schristos 8742b3787f6Schristos Calling this function makes the currently active event_base_loop() 8752b3787f6Schristos start the loop over again (scanning for new events) after the current 8762b3787f6Schristos event callback finishes. If the event loop is not running, this 8772b3787f6Schristos function has no effect. 8782b3787f6Schristos 8792b3787f6Schristos event_base_loopbreak() is typically invoked from this event's callback. 8802b3787f6Schristos This behavior is analogous to the "continue;" statement. 8812b3787f6Schristos 8822b3787f6Schristos Subsequent invocations of event loop will proceed normally. 8832b3787f6Schristos 8842b3787f6Schristos @param eb the event_base structure returned by event_init() 8852b3787f6Schristos @return 0 if successful, or -1 if an error occurred 8862b3787f6Schristos @see event_base_loopbreak() 8872b3787f6Schristos */ 8881b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 8892b3787f6Schristos int event_base_loopcontinue(struct event_base *); 8902b3787f6Schristos 8912b3787f6Schristos /** 8922b3787f6Schristos Checks if the event loop was told to exit by event_base_loopexit(). 8932b3787f6Schristos 8942b3787f6Schristos This function will return true for an event_base at every point after 8952b3787f6Schristos event_loopexit() is called, until the event loop is next entered. 8962b3787f6Schristos 8972b3787f6Schristos @param eb the event_base structure returned by event_init() 8982b3787f6Schristos @return true if event_base_loopexit() was called on this event base, 8992b3787f6Schristos or 0 otherwise 9002b3787f6Schristos @see event_base_loopexit() 9012b3787f6Schristos @see event_base_got_break() 9022b3787f6Schristos */ 9031b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 9042b3787f6Schristos int event_base_got_exit(struct event_base *); 9052b3787f6Schristos 9062b3787f6Schristos /** 9072b3787f6Schristos Checks if the event loop was told to abort immediately by event_base_loopbreak(). 9082b3787f6Schristos 9092b3787f6Schristos This function will return true for an event_base at every point after 9102b3787f6Schristos event_base_loopbreak() is called, until the event loop is next entered. 9112b3787f6Schristos 9122b3787f6Schristos @param eb the event_base structure returned by event_init() 9132b3787f6Schristos @return true if event_base_loopbreak() was called on this event base, 9142b3787f6Schristos or 0 otherwise 9152b3787f6Schristos @see event_base_loopbreak() 9162b3787f6Schristos @see event_base_got_exit() 9172b3787f6Schristos */ 9181b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 9192b3787f6Schristos int event_base_got_break(struct event_base *); 9202b3787f6Schristos 9212b3787f6Schristos /** 9222b3787f6Schristos * @name event flags 9232b3787f6Schristos * 9242b3787f6Schristos * Flags to pass to event_new(), event_assign(), event_pending(), and 9252b3787f6Schristos * anything else with an argument of the form "short events" 9262b3787f6Schristos */ 9272b3787f6Schristos /**@{*/ 9282b3787f6Schristos /** Indicates that a timeout has occurred. It's not necessary to pass 9292b3787f6Schristos * this flag to event_for new()/event_assign() to get a timeout. */ 9302b3787f6Schristos #define EV_TIMEOUT 0x01 9312b3787f6Schristos /** Wait for a socket or FD to become readable */ 9322b3787f6Schristos #define EV_READ 0x02 9332b3787f6Schristos /** Wait for a socket or FD to become writeable */ 9342b3787f6Schristos #define EV_WRITE 0x04 9352b3787f6Schristos /** Wait for a POSIX signal to be raised*/ 9362b3787f6Schristos #define EV_SIGNAL 0x08 9372b3787f6Schristos /** 9382b3787f6Schristos * Persistent event: won't get removed automatically when activated. 9392b3787f6Schristos * 9402b3787f6Schristos * When a persistent event with a timeout becomes activated, its timeout 9412b3787f6Schristos * is reset to 0. 9422b3787f6Schristos */ 9432b3787f6Schristos #define EV_PERSIST 0x10 9442b3787f6Schristos /** Select edge-triggered behavior, if supported by the backend. */ 9452b3787f6Schristos #define EV_ET 0x20 9461b6f2cd4Schristos /** 9471b6f2cd4Schristos * If this option is provided, then event_del() will not block in one thread 9481b6f2cd4Schristos * while waiting for the event callback to complete in another thread. 9491b6f2cd4Schristos * 9501b6f2cd4Schristos * To use this option safely, you may need to use event_finalize() or 9511b6f2cd4Schristos * event_free_finalize() in order to safely tear down an event in a 9521b6f2cd4Schristos * multithreaded application. See those functions for more information. 9531b6f2cd4Schristos * 9541b6f2cd4Schristos * THIS IS AN EXPERIMENTAL API. IT MIGHT CHANGE BEFORE THE LIBEVENT 2.1 SERIES 9551b6f2cd4Schristos * BECOMES STABLE. 9561b6f2cd4Schristos **/ 9571b6f2cd4Schristos #define EV_FINALIZE 0x40 9581b6f2cd4Schristos /** 9591b6f2cd4Schristos * Detects connection close events. You can use this to detect when a 9601b6f2cd4Schristos * connection has been closed, without having to read all the pending data 9611b6f2cd4Schristos * from a connection. 9621b6f2cd4Schristos * 9631b6f2cd4Schristos * Not all backends support EV_CLOSED. To detect or require it, use the 9641b6f2cd4Schristos * feature flag EV_FEATURE_EARLY_CLOSE. 9651b6f2cd4Schristos **/ 9661b6f2cd4Schristos #define EV_CLOSED 0x80 9672b3787f6Schristos /**@}*/ 9682b3787f6Schristos 9692b3787f6Schristos /** 9702b3787f6Schristos @name evtimer_* macros 9712b3787f6Schristos 9722b3787f6Schristos Aliases for working with one-shot timer events */ 9732b3787f6Schristos /**@{*/ 9742b3787f6Schristos #define evtimer_assign(ev, b, cb, arg) \ 9752b3787f6Schristos event_assign((ev), (b), -1, 0, (cb), (arg)) 9762b3787f6Schristos #define evtimer_new(b, cb, arg) event_new((b), -1, 0, (cb), (arg)) 9772b3787f6Schristos #define evtimer_add(ev, tv) event_add((ev), (tv)) 9782b3787f6Schristos #define evtimer_del(ev) event_del(ev) 9792b3787f6Schristos #define evtimer_pending(ev, tv) event_pending((ev), EV_TIMEOUT, (tv)) 9802b3787f6Schristos #define evtimer_initialized(ev) event_initialized(ev) 9812b3787f6Schristos /**@}*/ 9822b3787f6Schristos 9832b3787f6Schristos /** 9842b3787f6Schristos @name evsignal_* macros 9852b3787f6Schristos 9862b3787f6Schristos Aliases for working with signal events 9872b3787f6Schristos */ 9882b3787f6Schristos /**@{*/ 9892b3787f6Schristos #define evsignal_add(ev, tv) event_add((ev), (tv)) 9902b3787f6Schristos #define evsignal_assign(ev, b, x, cb, arg) \ 9912b3787f6Schristos event_assign((ev), (b), (x), EV_SIGNAL|EV_PERSIST, cb, (arg)) 9922b3787f6Schristos #define evsignal_new(b, x, cb, arg) \ 9932b3787f6Schristos event_new((b), (x), EV_SIGNAL|EV_PERSIST, (cb), (arg)) 9942b3787f6Schristos #define evsignal_del(ev) event_del(ev) 9952b3787f6Schristos #define evsignal_pending(ev, tv) event_pending((ev), EV_SIGNAL, (tv)) 9962b3787f6Schristos #define evsignal_initialized(ev) event_initialized(ev) 9972b3787f6Schristos /**@}*/ 9982b3787f6Schristos 9992b3787f6Schristos /** 10002b3787f6Schristos A callback function for an event. 10012b3787f6Schristos 10022b3787f6Schristos It receives three arguments: 10032b3787f6Schristos 10042b3787f6Schristos @param fd An fd or signal 10052b3787f6Schristos @param events One or more EV_* flags 10062b3787f6Schristos @param arg A user-supplied argument. 10072b3787f6Schristos 10082b3787f6Schristos @see event_new() 10092b3787f6Schristos */ 10102b3787f6Schristos typedef void (*event_callback_fn)(evutil_socket_t, short, void *); 10112b3787f6Schristos 10122b3787f6Schristos /** 10132b3787f6Schristos Return a value used to specify that the event itself must be used as the callback argument. 10142b3787f6Schristos 10152b3787f6Schristos The function event_new() takes a callback argument which is passed 10162b3787f6Schristos to the event's callback function. To specify that the argument to be 10172b3787f6Schristos passed to the callback function is the event that event_new() returns, 10182b3787f6Schristos pass in the return value of event_self_cbarg() as the callback argument 10192b3787f6Schristos for event_new(). 10202b3787f6Schristos 10212b3787f6Schristos For example: 10222b3787f6Schristos <pre> 10232b3787f6Schristos struct event *ev = event_new(base, sock, events, callback, %event_self_cbarg()); 10242b3787f6Schristos </pre> 10252b3787f6Schristos 10262b3787f6Schristos For consistency with event_new(), it is possible to pass the return value 10272b3787f6Schristos of this function as the callback argument for event_assign() – this 10282b3787f6Schristos achieves the same result as passing the event in directly. 10292b3787f6Schristos 10302b3787f6Schristos @return a value to be passed as the callback argument to event_new() or 10312b3787f6Schristos event_assign(). 10322b3787f6Schristos @see event_new(), event_assign() 10332b3787f6Schristos */ 10341b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 10352b3787f6Schristos void *event_self_cbarg(void); 10362b3787f6Schristos 10372b3787f6Schristos /** 10382b3787f6Schristos Allocate and asssign a new event structure, ready to be added. 10392b3787f6Schristos 10402b3787f6Schristos The function event_new() returns a new event that can be used in 10412b3787f6Schristos future calls to event_add() and event_del(). The fd and events 10422b3787f6Schristos arguments determine which conditions will trigger the event; the 10432b3787f6Schristos callback and callback_arg arguments tell Libevent what to do when the 10442b3787f6Schristos event becomes active. 10452b3787f6Schristos 10462b3787f6Schristos If events contains one of EV_READ, EV_WRITE, or EV_READ|EV_WRITE, then 10472b3787f6Schristos fd is a file descriptor or socket that should get monitored for 10482b3787f6Schristos readiness to read, readiness to write, or readiness for either operation 10492b3787f6Schristos (respectively). If events contains EV_SIGNAL, then fd is a signal 10502b3787f6Schristos number to wait for. If events contains none of those flags, then the 10512b3787f6Schristos event can be triggered only by a timeout or by manual activation with 10522b3787f6Schristos event_active(): In this case, fd must be -1. 10532b3787f6Schristos 10542b3787f6Schristos The EV_PERSIST flag can also be passed in the events argument: it makes 10552b3787f6Schristos event_add() persistent until event_del() is called. 10562b3787f6Schristos 10572b3787f6Schristos The EV_ET flag is compatible with EV_READ and EV_WRITE, and supported 10582b3787f6Schristos only by certain backends. It tells Libevent to use edge-triggered 10592b3787f6Schristos events. 10602b3787f6Schristos 10612b3787f6Schristos The EV_TIMEOUT flag has no effect here. 10622b3787f6Schristos 10632b3787f6Schristos It is okay to have multiple events all listening on the same fds; but 10642b3787f6Schristos they must either all be edge-triggered, or all not be edge triggerd. 10652b3787f6Schristos 10662b3787f6Schristos When the event becomes active, the event loop will run the provided 10672b3787f6Schristos callbuck function, with three arguments. The first will be the provided 10682b3787f6Schristos fd value. The second will be a bitfield of the events that triggered: 10692b3787f6Schristos EV_READ, EV_WRITE, or EV_SIGNAL. Here the EV_TIMEOUT flag indicates 10702b3787f6Schristos that a timeout occurred, and EV_ET indicates that an edge-triggered 10712b3787f6Schristos event occurred. The third event will be the callback_arg pointer that 10722b3787f6Schristos you provide. 10732b3787f6Schristos 10742b3787f6Schristos @param base the event base to which the event should be attached. 10752b3787f6Schristos @param fd the file descriptor or signal to be monitored, or -1. 10762b3787f6Schristos @param events desired events to monitor: bitfield of EV_READ, EV_WRITE, 10772b3787f6Schristos EV_SIGNAL, EV_PERSIST, EV_ET. 10782b3787f6Schristos @param callback callback function to be invoked when the event occurs 10792b3787f6Schristos @param callback_arg an argument to be passed to the callback function 10802b3787f6Schristos 10812b3787f6Schristos @return a newly allocated struct event that must later be freed with 10822b3787f6Schristos event_free(). 10832b3787f6Schristos @see event_free(), event_add(), event_del(), event_assign() 10842b3787f6Schristos */ 10851b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 10862b3787f6Schristos struct event *event_new(struct event_base *, evutil_socket_t, short, event_callback_fn, void *); 10872b3787f6Schristos 10882b3787f6Schristos 10892b3787f6Schristos /** 10902b3787f6Schristos Prepare a new, already-allocated event structure to be added. 10912b3787f6Schristos 10922b3787f6Schristos The function event_assign() prepares the event structure ev to be used 10932b3787f6Schristos in future calls to event_add() and event_del(). Unlike event_new(), it 10942b3787f6Schristos doesn't allocate memory itself: it requires that you have already 10952b3787f6Schristos allocated a struct event, probably on the heap. Doing this will 10962b3787f6Schristos typically make your code depend on the size of the event structure, and 10972b3787f6Schristos thereby create incompatibility with future versions of Libevent. 10982b3787f6Schristos 10992b3787f6Schristos The easiest way to avoid this problem is just to use event_new() and 11002b3787f6Schristos event_free() instead. 11012b3787f6Schristos 11022b3787f6Schristos A slightly harder way to future-proof your code is to use 11032b3787f6Schristos event_get_struct_event_size() to determine the required size of an event 11042b3787f6Schristos at runtime. 11052b3787f6Schristos 11062b3787f6Schristos Note that it is NOT safe to call this function on an event that is 11072b3787f6Schristos active or pending. Doing so WILL corrupt internal data structures in 11082b3787f6Schristos Libevent, and lead to strange, hard-to-diagnose bugs. You _can_ use 11092b3787f6Schristos event_assign to change an existing event, but only if it is not active 11102b3787f6Schristos or pending! 11112b3787f6Schristos 11122b3787f6Schristos The arguments for this function, and the behavior of the events that it 11132b3787f6Schristos makes, are as for event_new(). 11142b3787f6Schristos 11152b3787f6Schristos @param ev an event struct to be modified 11162b3787f6Schristos @param base the event base to which ev should be attached. 11172b3787f6Schristos @param fd the file descriptor to be monitored 11182b3787f6Schristos @param events desired events to monitor; can be EV_READ and/or EV_WRITE 11192b3787f6Schristos @param callback callback function to be invoked when the event occurs 11202b3787f6Schristos @param callback_arg an argument to be passed to the callback function 11212b3787f6Schristos 11222b3787f6Schristos @return 0 if success, or -1 on invalid arguments. 11232b3787f6Schristos 11242b3787f6Schristos @see event_new(), event_add(), event_del(), event_base_once(), 11252b3787f6Schristos event_get_struct_event_size() 11262b3787f6Schristos */ 11271b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 11282b3787f6Schristos int event_assign(struct event *, struct event_base *, evutil_socket_t, short, event_callback_fn, void *); 11292b3787f6Schristos 11302b3787f6Schristos /** 11312b3787f6Schristos Deallocate a struct event * returned by event_new(). 11322b3787f6Schristos 11332b3787f6Schristos If the event is pending or active, first make it non-pending and 11342b3787f6Schristos non-active. 11352b3787f6Schristos */ 11361b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 11372b3787f6Schristos void event_free(struct event *); 11382b3787f6Schristos 11392b3787f6Schristos /** 11401b6f2cd4Schristos * Callback type for event_finalize and event_free_finalize(). 11411b6f2cd4Schristos * 11421b6f2cd4Schristos * THIS IS AN EXPERIMENTAL API. IT MIGHT CHANGE BEFORE THE LIBEVENT 2.1 SERIES 11431b6f2cd4Schristos * BECOMES STABLE. 11441b6f2cd4Schristos * 11451b6f2cd4Schristos **/ 11461b6f2cd4Schristos typedef void (*event_finalize_callback_fn)(struct event *, void *); 11471b6f2cd4Schristos /** 11481b6f2cd4Schristos @name Finalization functions 11491b6f2cd4Schristos 11501b6f2cd4Schristos These functions are used to safely tear down an event in a multithreaded 11511b6f2cd4Schristos application. If you construct your events with EV_FINALIZE to avoid 11521b6f2cd4Schristos deadlocks, you will need a way to remove an event in the certainty that 11531b6f2cd4Schristos it will definitely not be running its callback when you deallocate it 11541b6f2cd4Schristos and its callback argument. 11551b6f2cd4Schristos 11561b6f2cd4Schristos To do this, call one of event_finalize() or event_free_finalize with 11571b6f2cd4Schristos 0 for its first argument, the event to tear down as its second argument, 11581b6f2cd4Schristos and a callback function as its third argument. The callback will be 11591b6f2cd4Schristos invoked as part of the event loop, with the event's priority. 11601b6f2cd4Schristos 11611b6f2cd4Schristos After you call a finalizer function, event_add() and event_active() will 11621b6f2cd4Schristos no longer work on the event, and event_del() will produce a no-op. You 11631b6f2cd4Schristos must not try to change the event's fields with event_assign() or 11641b6f2cd4Schristos event_set() while the finalize callback is in progress. Once the 11651b6f2cd4Schristos callback has been invoked, you should treat the event structure as 11661b6f2cd4Schristos containing uninitialized memory. 11671b6f2cd4Schristos 11681b6f2cd4Schristos The event_free_finalize() function frees the event after it's finalized; 11691b6f2cd4Schristos event_finalize() does not. 11701b6f2cd4Schristos 11711b6f2cd4Schristos A finalizer callback must not make events pending or active. It must not 11721b6f2cd4Schristos add events, activate events, or attempt to "resucitate" the event being 11731b6f2cd4Schristos finalized in any way. 11741b6f2cd4Schristos 11751b6f2cd4Schristos THIS IS AN EXPERIMENTAL API. IT MIGHT CHANGE BEFORE THE LIBEVENT 2.1 SERIES 11761b6f2cd4Schristos BECOMES STABLE. 11771b6f2cd4Schristos 11781b6f2cd4Schristos @return 0 on succes, -1 on failure. 11791b6f2cd4Schristos */ 11801b6f2cd4Schristos /**@{*/ 11811b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 11821b6f2cd4Schristos int event_finalize(unsigned, struct event *, event_finalize_callback_fn); 11831b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 11841b6f2cd4Schristos int event_free_finalize(unsigned, struct event *, event_finalize_callback_fn); 11851b6f2cd4Schristos /**@}*/ 11861b6f2cd4Schristos 11871b6f2cd4Schristos /** 11882b3787f6Schristos Schedule a one-time event 11892b3787f6Schristos 11902b3787f6Schristos The function event_base_once() is similar to event_new(). However, it 11912b3787f6Schristos schedules a callback to be called exactly once, and does not require the 11922b3787f6Schristos caller to prepare an event structure. 11932b3787f6Schristos 11942b3787f6Schristos Note that in Libevent 2.0 and earlier, if the event is never triggered, the 11952b3787f6Schristos internal memory used to hold it will never be freed. In Libevent 2.1, 11962b3787f6Schristos the internal memory will get freed by event_base_free() if the event 11972b3787f6Schristos is never triggered. The 'arg' value, however, will not get freed in either 11982b3787f6Schristos case--you'll need to free that on your own if you want it to go away. 11992b3787f6Schristos 12002b3787f6Schristos @param base an event_base 12012b3787f6Schristos @param fd a file descriptor to monitor, or -1 for no fd. 12022b3787f6Schristos @param events event(s) to monitor; can be any of EV_READ | 12032b3787f6Schristos EV_WRITE, or EV_TIMEOUT 12042b3787f6Schristos @param callback callback function to be invoked when the event occurs 12052b3787f6Schristos @param arg an argument to be passed to the callback function 12062b3787f6Schristos @param timeout the maximum amount of time to wait for the event. NULL 12072b3787f6Schristos makes an EV_READ/EV_WRITE event make forever; NULL makes an 12082b3787f6Schristos EV_TIMEOUT event succees immediately. 12092b3787f6Schristos @return 0 if successful, or -1 if an error occurred 12102b3787f6Schristos */ 12111b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 12122b3787f6Schristos int event_base_once(struct event_base *, evutil_socket_t, short, event_callback_fn, void *, const struct timeval *); 12132b3787f6Schristos 12142b3787f6Schristos /** 12152b3787f6Schristos Add an event to the set of pending events. 12162b3787f6Schristos 12171b6f2cd4Schristos The function event_add() schedules the execution of the event 'ev' when the 12181b6f2cd4Schristos condition specified by event_assign() or event_new() occurs, or when the time 12192b3787f6Schristos specified in timeout has elapesed. If atimeout is NULL, no timeout 12202b3787f6Schristos occurs and the function will only be 12212b3787f6Schristos called if a matching event occurs. The event in the 12222b3787f6Schristos ev argument must be already initialized by event_assign() or event_new() 12232b3787f6Schristos and may not be used 12242b3787f6Schristos in calls to event_assign() until it is no longer pending. 12252b3787f6Schristos 12262b3787f6Schristos If the event in the ev argument already has a scheduled timeout, calling 12272b3787f6Schristos event_add() replaces the old timeout with the new one if tv is non-NULL. 12282b3787f6Schristos 12292b3787f6Schristos @param ev an event struct initialized via event_assign() or event_new() 12302b3787f6Schristos @param timeout the maximum amount of time to wait for the event, or NULL 12312b3787f6Schristos to wait forever 12322b3787f6Schristos @return 0 if successful, or -1 if an error occurred 12332b3787f6Schristos @see event_del(), event_assign(), event_new() 12342b3787f6Schristos */ 12351b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 12362b3787f6Schristos int event_add(struct event *ev, const struct timeval *timeout); 12372b3787f6Schristos 12382b3787f6Schristos /** 12392b3787f6Schristos Remove a timer from a pending event without removing the event itself. 12402b3787f6Schristos 12412b3787f6Schristos If the event has a scheduled timeout, this function unschedules it but 12422b3787f6Schristos leaves the event otherwise pending. 12432b3787f6Schristos 12442b3787f6Schristos @param ev an event struct initialized via event_assign() or event_new() 12452b3787f6Schristos @return 0 on success, or -1 if an error occurrect. 12462b3787f6Schristos */ 12471b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 12482b3787f6Schristos int event_remove_timer(struct event *ev); 12492b3787f6Schristos 12502b3787f6Schristos /** 12512b3787f6Schristos Remove an event from the set of monitored events. 12522b3787f6Schristos 12532b3787f6Schristos The function event_del() will cancel the event in the argument ev. If the 12542b3787f6Schristos event has already executed or has never been added the call will have no 12552b3787f6Schristos effect. 12562b3787f6Schristos 12572b3787f6Schristos @param ev an event struct to be removed from the working set 12582b3787f6Schristos @return 0 if successful, or -1 if an error occurred 12592b3787f6Schristos @see event_add() 12602b3787f6Schristos */ 12611b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 12622b3787f6Schristos int event_del(struct event *); 12632b3787f6Schristos 12641b6f2cd4Schristos /** 12651b6f2cd4Schristos As event_del(), but never blocks while the event's callback is running 12661b6f2cd4Schristos in another thread, even if the event was constructed without the 12671b6f2cd4Schristos EV_FINALIZE flag. 12681b6f2cd4Schristos 12691b6f2cd4Schristos THIS IS AN EXPERIMENTAL API. IT MIGHT CHANGE BEFORE THE LIBEVENT 2.1 SERIES 12701b6f2cd4Schristos BECOMES STABLE. 12711b6f2cd4Schristos */ 12721b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 12731b6f2cd4Schristos int event_del_noblock(struct event *ev); 12741b6f2cd4Schristos /** 12751b6f2cd4Schristos As event_del(), but always blocks while the event's callback is running 12761b6f2cd4Schristos in another thread, even if the event was constructed with the 12771b6f2cd4Schristos EV_FINALIZE flag. 12781b6f2cd4Schristos 12791b6f2cd4Schristos THIS IS AN EXPERIMENTAL API. IT MIGHT CHANGE BEFORE THE LIBEVENT 2.1 SERIES 12801b6f2cd4Schristos BECOMES STABLE. 12811b6f2cd4Schristos */ 12821b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 12831b6f2cd4Schristos int event_del_block(struct event *ev); 12842b3787f6Schristos 12852b3787f6Schristos /** 12862b3787f6Schristos Make an event active. 12872b3787f6Schristos 12882b3787f6Schristos You can use this function on a pending or a non-pending event to make it 12892b3787f6Schristos active, so that its callback will be run by event_base_dispatch() or 12902b3787f6Schristos event_base_loop(). 12912b3787f6Schristos 12922b3787f6Schristos One common use in multithreaded programs is to wake the thread running 12932b3787f6Schristos event_base_loop() from another thread. 12942b3787f6Schristos 12952b3787f6Schristos @param ev an event to make active. 12962b3787f6Schristos @param res a set of flags to pass to the event's callback. 12972b3787f6Schristos @param ncalls an obsolete argument: this is ignored. 12982b3787f6Schristos **/ 12991b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 13002b3787f6Schristos void event_active(struct event *ev, int res, short ncalls); 13012b3787f6Schristos 13022b3787f6Schristos /** 13032b3787f6Schristos Checks if a specific event is pending or scheduled. 13042b3787f6Schristos 13052b3787f6Schristos @param ev an event struct previously passed to event_add() 13062b3787f6Schristos @param events the requested event type; any of EV_TIMEOUT|EV_READ| 13072b3787f6Schristos EV_WRITE|EV_SIGNAL 13082b3787f6Schristos @param tv if this field is not NULL, and the event has a timeout, 13092b3787f6Schristos this field is set to hold the time at which the timeout will 13102b3787f6Schristos expire. 13112b3787f6Schristos 13122b3787f6Schristos @return true if the event is pending on any of the events in 'what', (that 13132b3787f6Schristos is to say, it has been added), or 0 if the event is not added. 13142b3787f6Schristos */ 13151b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 13162b3787f6Schristos int event_pending(const struct event *ev, short events, struct timeval *tv); 13172b3787f6Schristos 13182b3787f6Schristos /** 13192b3787f6Schristos If called from within the callback for an event, returns that event. 13202b3787f6Schristos 13212b3787f6Schristos The behavior of this function is not defined when called from outside the 13222b3787f6Schristos callback function for an event. 13232b3787f6Schristos */ 13241b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 13252b3787f6Schristos struct event *event_base_get_running_event(struct event_base *base); 13262b3787f6Schristos 13272b3787f6Schristos /** 13282b3787f6Schristos Test if an event structure might be initialized. 13292b3787f6Schristos 13302b3787f6Schristos The event_initialized() function can be used to check if an event has been 13312b3787f6Schristos initialized. 13322b3787f6Schristos 13332b3787f6Schristos Warning: This function is only useful for distinguishing a a zeroed-out 13342b3787f6Schristos piece of memory from an initialized event, it can easily be confused by 13352b3787f6Schristos uninitialized memory. Thus, it should ONLY be used to distinguish an 13362b3787f6Schristos initialized event from zero. 13372b3787f6Schristos 13382b3787f6Schristos @param ev an event structure to be tested 13392b3787f6Schristos @return 1 if the structure might be initialized, or 0 if it has not been 13402b3787f6Schristos initialized 13412b3787f6Schristos */ 13421b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 13432b3787f6Schristos int event_initialized(const struct event *ev); 13442b3787f6Schristos 13452b3787f6Schristos /** 13462b3787f6Schristos Get the signal number assigned to a signal event 13472b3787f6Schristos */ 13482b3787f6Schristos #define event_get_signal(ev) ((int)event_get_fd(ev)) 13492b3787f6Schristos 13502b3787f6Schristos /** 13512b3787f6Schristos Get the socket or signal assigned to an event, or -1 if the event has 13522b3787f6Schristos no socket. 13532b3787f6Schristos */ 13541b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 13552b3787f6Schristos evutil_socket_t event_get_fd(const struct event *ev); 13562b3787f6Schristos 13572b3787f6Schristos /** 13582b3787f6Schristos Get the event_base associated with an event. 13592b3787f6Schristos */ 13601b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 13612b3787f6Schristos struct event_base *event_get_base(const struct event *ev); 13622b3787f6Schristos 13632b3787f6Schristos /** 13642b3787f6Schristos Return the events (EV_READ, EV_WRITE, etc) assigned to an event. 13652b3787f6Schristos */ 13661b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 13672b3787f6Schristos short event_get_events(const struct event *ev); 13682b3787f6Schristos 13692b3787f6Schristos /** 13702b3787f6Schristos Return the callback assigned to an event. 13712b3787f6Schristos */ 13721b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 13732b3787f6Schristos event_callback_fn event_get_callback(const struct event *ev); 13742b3787f6Schristos 13752b3787f6Schristos /** 13762b3787f6Schristos Return the callback argument assigned to an event. 13772b3787f6Schristos */ 13781b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 13792b3787f6Schristos void *event_get_callback_arg(const struct event *ev); 13802b3787f6Schristos 13812b3787f6Schristos /** 13822b3787f6Schristos Return the priority of an event. 13832b3787f6Schristos @see event_priority_init(), event_get_priority() 13842b3787f6Schristos */ 13851b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 13862b3787f6Schristos int event_get_priority(const struct event *ev); 13872b3787f6Schristos 13882b3787f6Schristos /** 13892b3787f6Schristos Extract _all_ of arguments given to construct a given event. The 13902b3787f6Schristos event_base is copied into *base_out, the fd is copied into *fd_out, and so 13912b3787f6Schristos on. 13922b3787f6Schristos 13932b3787f6Schristos If any of the "_out" arguments is NULL, it will be ignored. 13942b3787f6Schristos */ 13951b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 13962b3787f6Schristos void event_get_assignment(const struct event *event, 13972b3787f6Schristos struct event_base **base_out, evutil_socket_t *fd_out, short *events_out, 13982b3787f6Schristos event_callback_fn *callback_out, void **arg_out); 13992b3787f6Schristos 14002b3787f6Schristos /** 14012b3787f6Schristos Return the size of struct event that the Libevent library was compiled 14022b3787f6Schristos with. 14032b3787f6Schristos 14042b3787f6Schristos This will be NO GREATER than sizeof(struct event) if you're running with 14052b3787f6Schristos the same version of Libevent that your application was built with, but 14062b3787f6Schristos otherwise might not. 14072b3787f6Schristos 14082b3787f6Schristos Note that it might be SMALLER than sizeof(struct event) if some future 14092b3787f6Schristos version of Libevent adds extra padding to the end of struct event. 14102b3787f6Schristos We might do this to help ensure ABI-compatibility between different 14112b3787f6Schristos versions of Libevent. 14122b3787f6Schristos */ 14131b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 14142b3787f6Schristos size_t event_get_struct_event_size(void); 14152b3787f6Schristos 14162b3787f6Schristos /** 14172b3787f6Schristos Get the Libevent version. 14182b3787f6Schristos 14192b3787f6Schristos Note that this will give you the version of the library that you're 14202b3787f6Schristos currently linked against, not the version of the headers that you've 14212b3787f6Schristos compiled against. 14222b3787f6Schristos 14232b3787f6Schristos @return a string containing the version number of Libevent 14242b3787f6Schristos */ 14251b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 14262b3787f6Schristos const char *event_get_version(void); 14272b3787f6Schristos 14282b3787f6Schristos /** 14292b3787f6Schristos Return a numeric representation of Libevent's version. 14302b3787f6Schristos 14312b3787f6Schristos Note that this will give you the version of the library that you're 14322b3787f6Schristos currently linked against, not the version of the headers you've used to 14332b3787f6Schristos compile. 14342b3787f6Schristos 14352b3787f6Schristos The format uses one byte each for the major, minor, and patchlevel parts of 14362b3787f6Schristos the version number. The low-order byte is unused. For example, version 14372b3787f6Schristos 2.0.1-alpha has a numeric representation of 0x02000100 14382b3787f6Schristos */ 14391b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 14402b3787f6Schristos ev_uint32_t event_get_version_number(void); 14412b3787f6Schristos 14422b3787f6Schristos /** As event_get_version, but gives the version of Libevent's headers. */ 14432b3787f6Schristos #define LIBEVENT_VERSION EVENT__VERSION 14442b3787f6Schristos /** As event_get_version_number, but gives the version number of Libevent's 14452b3787f6Schristos * headers. */ 14462b3787f6Schristos #define LIBEVENT_VERSION_NUMBER EVENT__NUMERIC_VERSION 14472b3787f6Schristos 14482b3787f6Schristos /** Largest number of priorities that Libevent can support. */ 14492b3787f6Schristos #define EVENT_MAX_PRIORITIES 256 14502b3787f6Schristos /** 14512b3787f6Schristos Set the number of different event priorities 14522b3787f6Schristos 14532b3787f6Schristos By default Libevent schedules all active events with the same priority. 14542b3787f6Schristos However, some time it is desirable to process some events with a higher 14552b3787f6Schristos priority than others. For that reason, Libevent supports strict priority 14562b3787f6Schristos queues. Active events with a lower priority are always processed before 14572b3787f6Schristos events with a higher priority. 14582b3787f6Schristos 14592b3787f6Schristos The number of different priorities can be set initially with the 14602b3787f6Schristos event_base_priority_init() function. This function should be called 14612b3787f6Schristos before the first call to event_base_dispatch(). The 14622b3787f6Schristos event_priority_set() function can be used to assign a priority to an 14632b3787f6Schristos event. By default, Libevent assigns the middle priority to all events 14642b3787f6Schristos unless their priority is explicitly set. 14652b3787f6Schristos 14662b3787f6Schristos Note that urgent-priority events can starve less-urgent events: after 14672b3787f6Schristos running all urgent-priority callbacks, Libevent checks for more urgent 14682b3787f6Schristos events again, before running less-urgent events. Less-urgent events 14692b3787f6Schristos will not have their callbacks run until there are no events more urgent 14702b3787f6Schristos than them that want to be active. 14712b3787f6Schristos 14722b3787f6Schristos @param eb the event_base structure returned by event_base_new() 14732b3787f6Schristos @param npriorities the maximum number of priorities 14742b3787f6Schristos @return 0 if successful, or -1 if an error occurred 14752b3787f6Schristos @see event_priority_set() 14762b3787f6Schristos */ 14771b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 14782b3787f6Schristos int event_base_priority_init(struct event_base *, int); 14792b3787f6Schristos 14802b3787f6Schristos /** 14812b3787f6Schristos Get the number of different event priorities. 14822b3787f6Schristos 14832b3787f6Schristos @param eb the event_base structure returned by event_base_new() 14842b3787f6Schristos @return Number of different event priorities 14852b3787f6Schristos @see event_base_priority_init() 14862b3787f6Schristos */ 14871b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 14882b3787f6Schristos int event_base_get_npriorities(struct event_base *eb); 14892b3787f6Schristos 14902b3787f6Schristos /** 14912b3787f6Schristos Assign a priority to an event. 14922b3787f6Schristos 14932b3787f6Schristos @param ev an event struct 14942b3787f6Schristos @param priority the new priority to be assigned 14952b3787f6Schristos @return 0 if successful, or -1 if an error occurred 14962b3787f6Schristos @see event_priority_init(), event_get_priority() 14972b3787f6Schristos */ 14981b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 14992b3787f6Schristos int event_priority_set(struct event *, int); 15002b3787f6Schristos 15012b3787f6Schristos /** 15022b3787f6Schristos Prepare an event_base to use a large number of timeouts with the same 15032b3787f6Schristos duration. 15042b3787f6Schristos 15052b3787f6Schristos Libevent's default scheduling algorithm is optimized for having a large 15062b3787f6Schristos number of timeouts with their durations more or less randomly 15072b3787f6Schristos distributed. But if you have a large number of timeouts that all have 15082b3787f6Schristos the same duration (for example, if you have a large number of 15092b3787f6Schristos connections that all have a 10-second timeout), then you can improve 15102b3787f6Schristos Libevent's performance by telling Libevent about it. 15112b3787f6Schristos 15122b3787f6Schristos To do this, call this function with the common duration. It will return a 15132b3787f6Schristos pointer to a different, opaque timeout value. (Don't depend on its actual 15142b3787f6Schristos contents!) When you use this timeout value in event_add(), Libevent will 15152b3787f6Schristos schedule the event more efficiently. 15162b3787f6Schristos 15172b3787f6Schristos (This optimization probably will not be worthwhile until you have thousands 15182b3787f6Schristos or tens of thousands of events with the same timeout.) 15192b3787f6Schristos */ 15201b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 15212b3787f6Schristos const struct timeval *event_base_init_common_timeout(struct event_base *base, 15222b3787f6Schristos const struct timeval *duration); 15232b3787f6Schristos 15242b3787f6Schristos #if !defined(EVENT__DISABLE_MM_REPLACEMENT) || defined(EVENT_IN_DOXYGEN_) 15252b3787f6Schristos /** 15262b3787f6Schristos Override the functions that Libevent uses for memory management. 15272b3787f6Schristos 15282b3787f6Schristos Usually, Libevent uses the standard libc functions malloc, realloc, and 15292b3787f6Schristos free to allocate memory. Passing replacements for those functions to 15302b3787f6Schristos event_set_mem_functions() overrides this behavior. 15312b3787f6Schristos 15322b3787f6Schristos Note that all memory returned from Libevent will be allocated by the 15332b3787f6Schristos replacement functions rather than by malloc() and realloc(). Thus, if you 15342b3787f6Schristos have replaced those functions, it will not be appropriate to free() memory 15352b3787f6Schristos that you get from Libevent. Instead, you must use the free_fn replacement 15362b3787f6Schristos that you provided. 15372b3787f6Schristos 15382b3787f6Schristos Note also that if you are going to call this function, you should do so 15392b3787f6Schristos before any call to any Libevent function that does allocation. 15402b3787f6Schristos Otherwise, those funtions will allocate their memory using malloc(), but 15412b3787f6Schristos then later free it using your provided free_fn. 15422b3787f6Schristos 15432b3787f6Schristos @param malloc_fn A replacement for malloc. 15442b3787f6Schristos @param realloc_fn A replacement for realloc 15452b3787f6Schristos @param free_fn A replacement for free. 15462b3787f6Schristos **/ 15471b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 15482b3787f6Schristos void event_set_mem_functions( 15492b3787f6Schristos void *(*malloc_fn)(size_t sz), 15502b3787f6Schristos void *(*realloc_fn)(void *ptr, size_t sz), 15512b3787f6Schristos void (*free_fn)(void *ptr)); 15522b3787f6Schristos /** This definition is present if Libevent was built with support for 15532b3787f6Schristos event_set_mem_functions() */ 15542b3787f6Schristos #define EVENT_SET_MEM_FUNCTIONS_IMPLEMENTED 15552b3787f6Schristos #endif 15562b3787f6Schristos 15572b3787f6Schristos /** 15582b3787f6Schristos Writes a human-readable description of all inserted and/or active 15592b3787f6Schristos events to a provided stdio stream. 15602b3787f6Schristos 15612b3787f6Schristos This is intended for debugging; its format is not guaranteed to be the same 15622b3787f6Schristos between libevent versions. 15632b3787f6Schristos 15642b3787f6Schristos @param base An event_base on which to scan the events. 15652b3787f6Schristos @param output A stdio file to write on. 15662b3787f6Schristos */ 15671b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 15682b3787f6Schristos void event_base_dump_events(struct event_base *, FILE *); 15692b3787f6Schristos 15702b3787f6Schristos 15712b3787f6Schristos /** 15721b6f2cd4Schristos Activates all pending events for the given fd and event mask. 15731b6f2cd4Schristos 15741b6f2cd4Schristos This function activates pending events only. Events which have not been 15751b6f2cd4Schristos added will not become active. 15761b6f2cd4Schristos 15771b6f2cd4Schristos @param base the event_base on which to activate the events. 15781b6f2cd4Schristos @param fd An fd to active events on. 15791b6f2cd4Schristos @param events One or more of EV_{READ,WRITE}. 15801b6f2cd4Schristos */ 15811b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 15821b6f2cd4Schristos void event_base_active_by_fd(struct event_base *base, evutil_socket_t fd, short events); 15831b6f2cd4Schristos 15841b6f2cd4Schristos /** 15851b6f2cd4Schristos Activates all pending signals with a given signal number 15861b6f2cd4Schristos 15871b6f2cd4Schristos This function activates pending events only. Events which have not been 15881b6f2cd4Schristos added will not become active. 15891b6f2cd4Schristos 15901b6f2cd4Schristos @param base the event_base on which to activate the events. 15911b6f2cd4Schristos @param fd The signal to active events on. 15921b6f2cd4Schristos */ 15931b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 15941b6f2cd4Schristos void event_base_active_by_signal(struct event_base *base, int sig); 15951b6f2cd4Schristos 15961b6f2cd4Schristos /** 15972b3787f6Schristos * Callback for iterating events in an event base via event_base_foreach_event 15982b3787f6Schristos */ 15992b3787f6Schristos typedef int (*event_base_foreach_event_cb)(const struct event_base *, const struct event *, void *); 16002b3787f6Schristos 16012b3787f6Schristos /** 16022b3787f6Schristos Iterate over all added or active events events in an event loop, and invoke 16032b3787f6Schristos a given callback on each one. 16042b3787f6Schristos 16052b3787f6Schristos The callback must not call any function that modifies the event base, that 16062b3787f6Schristos modifies any event in the event base, or that adds or removes any event to 16072b3787f6Schristos the event base. Doing so is unsupported and will lead to undefined 16082b3787f6Schristos behavior -- likely, to crashes. 16092b3787f6Schristos 16102b3787f6Schristos event_base_foreach_event() holds a lock on the event_base() for the whole 16112b3787f6Schristos time it's running: slow callbacks are not advisable. 16122b3787f6Schristos 16131b6f2cd4Schristos Note that Libevent adds some events of its own to make pieces of its 16141b6f2cd4Schristos functionality work. You must not assume that the only events you'll 16151b6f2cd4Schristos encounter will be the ones you added yourself. 16161b6f2cd4Schristos 16172b3787f6Schristos The callback function must return 0 to continue iteration, or some other 16182b3787f6Schristos integer to stop iterating. 16192b3787f6Schristos 16202b3787f6Schristos @param base An event_base on which to scan the events. 16212b3787f6Schristos @param fn A callback function to receive the events. 16222b3787f6Schristos @param arg An argument passed to the callback function. 16232b3787f6Schristos @return 0 if we iterated over every event, or the value returned by the 16242b3787f6Schristos callback function if the loop exited early. 16252b3787f6Schristos */ 16261b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 16272b3787f6Schristos int event_base_foreach_event(struct event_base *base, event_base_foreach_event_cb fn, void *arg); 16282b3787f6Schristos 16292b3787f6Schristos 16302b3787f6Schristos /** Sets 'tv' to the current time (as returned by gettimeofday()), 16312b3787f6Schristos looking at the cached value in 'base' if possible, and calling 16322b3787f6Schristos gettimeofday() or clock_gettime() as appropriate if there is no 16332b3787f6Schristos cached time. 16342b3787f6Schristos 16352b3787f6Schristos Generally, this value will only be cached while actually 16362b3787f6Schristos processing event callbacks, and may be very inaccuate if your 16372b3787f6Schristos callbacks take a long time to execute. 16382b3787f6Schristos 16392b3787f6Schristos Returns 0 on success, negative on failure. 16402b3787f6Schristos */ 16411b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 16422b3787f6Schristos int event_base_gettimeofday_cached(struct event_base *base, 16432b3787f6Schristos struct timeval *tv); 16442b3787f6Schristos 16452b3787f6Schristos /** Update cached_tv in the 'base' to the current time 16462b3787f6Schristos * 16472b3787f6Schristos * You can use this function is useful for selectively increasing 16482b3787f6Schristos * the accuracy of the cached time value in 'base' during callbacks 16492b3787f6Schristos * that take a long time to execute. 16502b3787f6Schristos * 16512b3787f6Schristos * This function has no effect if the base is currently not in its 16522b3787f6Schristos * event loop, or if timeval caching is disabled via 16532b3787f6Schristos * EVENT_BASE_FLAG_NO_CACHE_TIME. 16542b3787f6Schristos * 16552b3787f6Schristos * @return 0 on success, -1 on failure 16562b3787f6Schristos */ 16571b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 16582b3787f6Schristos int event_base_update_cache_time(struct event_base *base); 16592b3787f6Schristos 16602b3787f6Schristos /** Release up all globally-allocated resources allocated by Libevent. 16612b3787f6Schristos 16622b3787f6Schristos This function does not free developer-controlled resources like 16632b3787f6Schristos event_bases, events, bufferevents, listeners, and so on. It only releases 16642b3787f6Schristos resources like global locks that there is no other way to free. 16652b3787f6Schristos 16662b3787f6Schristos It is not actually necessary to call this function before exit: every 16672b3787f6Schristos resource that it frees would be released anyway on exit. It mainly exists 16682b3787f6Schristos so that resource-leak debugging tools don't see Libevent as holding 16692b3787f6Schristos resources at exit. 16702b3787f6Schristos 16712b3787f6Schristos You should only call this function when no other Libevent functions will 16722b3787f6Schristos be invoked -- e.g., when cleanly exiting a program. 16732b3787f6Schristos */ 16741b6f2cd4Schristos EVENT2_EXPORT_SYMBOL 16752b3787f6Schristos void libevent_global_shutdown(void); 16762b3787f6Schristos 16772b3787f6Schristos #ifdef __cplusplus 16782b3787f6Schristos } 16792b3787f6Schristos #endif 16802b3787f6Schristos 16812b3787f6Schristos #endif /* EVENT2_EVENT_H_INCLUDED_ */ 1682