Index: third_party/libevent/event.h |
diff --git a/third_party/libevent/event.h b/third_party/libevent/event.h |
deleted file mode 100644 |
index f0887b9616353b046a6610fe99758cf57e16b4e1..0000000000000000000000000000000000000000 |
--- a/third_party/libevent/event.h |
+++ /dev/null |
@@ -1,1212 +0,0 @@ |
-/* |
- * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> |
- * All rights reserved. |
- * |
- * Redistribution and use in source and binary forms, with or without |
- * modification, are permitted provided that the following conditions |
- * are met: |
- * 1. Redistributions of source code must retain the above copyright |
- * notice, this list of conditions and the following disclaimer. |
- * 2. Redistributions in binary form must reproduce the above copyright |
- * notice, this list of conditions and the following disclaimer in the |
- * documentation and/or other materials provided with the distribution. |
- * 3. The name of the author may not be used to endorse or promote products |
- * derived from this software without specific prior written permission. |
- * |
- * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
- * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
- * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
- * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, |
- * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
- * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
- * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
- */ |
-#ifndef _EVENT_H_ |
-#define _EVENT_H_ |
- |
-/** @mainpage |
- |
- @section intro Introduction |
- |
- libevent is an event notification library for developing scalable network |
- servers. The libevent API provides a mechanism to execute a callback |
- function when a specific event occurs on a file descriptor or after a |
- timeout has been reached. Furthermore, libevent also support callbacks due |
- to signals or regular timeouts. |
- |
- libevent is meant to replace the event loop found in event driven network |
- servers. An application just needs to call event_dispatch() and then add or |
- remove events dynamically without having to change the event loop. |
- |
- Currently, libevent supports /dev/poll, kqueue(2), select(2), poll(2) and |
- epoll(4). It also has experimental support for real-time signals. The |
- internal event mechanism is completely independent of the exposed event API, |
- and a simple update of libevent can provide new functionality without having |
- to redesign the applications. As a result, Libevent allows for portable |
- application development and provides the most scalable event notification |
- mechanism available on an operating system. Libevent can also be used for |
- multi-threaded aplications; see Steven Grimm's explanation. Libevent should |
- compile on Linux, *BSD, Mac OS X, Solaris and Windows. |
- |
- @section usage Standard usage |
- |
- Every program that uses libevent must include the <event.h> header, and pass |
- the -levent flag to the linker. Before using any of the functions in the |
- library, you must call event_init() or event_base_new() to perform one-time |
- initialization of the libevent library. |
- |
- @section event Event notification |
- |
- For each file descriptor that you wish to monitor, you must declare an event |
- structure and call event_set() to initialize the members of the structure. |
- To enable notification, you add the structure to the list of monitored |
- events by calling event_add(). The event structure must remain allocated as |
- long as it is active, so it should be allocated on the heap. Finally, you |
- call event_dispatch() to loop and dispatch events. |
- |
- @section bufferevent I/O Buffers |
- |
- libevent provides an abstraction on top of the regular event callbacks. This |
- abstraction is called a buffered event. A buffered event provides input and |
- output buffers that get filled and drained automatically. The user of a |
- buffered event no longer deals directly with the I/O, but instead is reading |
- from input and writing to output buffers. |
- |
- Once initialized via bufferevent_new(), the bufferevent structure can be |
- used repeatedly with bufferevent_enable() and bufferevent_disable(). |
- Instead of reading and writing directly to a socket, you would call |
- bufferevent_read() and bufferevent_write(). |
- |
- When read enabled the bufferevent will try to read from the file descriptor |
- and call the read callback. The write callback is executed whenever the |
- output buffer is drained below the write low watermark, which is 0 by |
- default. |
- |
- @section timers Timers |
- |
- libevent can also be used to create timers that invoke a callback after a |
- certain amount of time has expired. The evtimer_set() function prepares an |
- event struct to be used as a timer. To activate the timer, call |
- evtimer_add(). Timers can be deactivated by calling evtimer_del(). |
- |
- @section timeouts Timeouts |
- |
- In addition to simple timers, libevent can assign timeout events to file |
- descriptors that are triggered whenever a certain amount of time has passed |
- with no activity on a file descriptor. The timeout_set() function |
- initializes an event struct for use as a timeout. Once initialized, the |
- event must be activated by using timeout_add(). To cancel the timeout, call |
- timeout_del(). |
- |
- @section evdns Asynchronous DNS resolution |
- |
- libevent provides an asynchronous DNS resolver that should be used instead |
- of the standard DNS resolver functions. These functions can be imported by |
- including the <evdns.h> header in your program. Before using any of the |
- resolver functions, you must call evdns_init() to initialize the library. To |
- convert a hostname to an IP address, you call the evdns_resolve_ipv4() |
- function. To perform a reverse lookup, you would call the |
- evdns_resolve_reverse() function. All of these functions use callbacks to |
- avoid blocking while the lookup is performed. |
- |
- @section evhttp Event-driven HTTP servers |
- |
- libevent provides a very simple event-driven HTTP server that can be |
- embedded in your program and used to service HTTP requests. |
- |
- To use this capability, you need to include the <evhttp.h> header in your |
- program. You create the server by calling evhttp_new(). Add addresses and |
- ports to listen on with evhttp_bind_socket(). You then register one or more |
- callbacks to handle incoming requests. Each URI can be assigned a callback |
- via the evhttp_set_cb() function. A generic callback function can also be |
- registered via evhttp_set_gencb(); this callback will be invoked if no other |
- callbacks have been registered for a given URI. |
- |
- @section evrpc A framework for RPC servers and clients |
- |
- libevents provides a framework for creating RPC servers and clients. It |
- takes care of marshaling and unmarshaling all data structures. |
- |
- @section api API Reference |
- |
- To browse the complete documentation of the libevent API, click on any of |
- the following links. |
- |
- event.h |
- The primary libevent header |
- |
- evdns.h |
- Asynchronous DNS resolution |
- |
- evhttp.h |
- An embedded libevent-based HTTP server |
- |
- evrpc.h |
- A framework for creating RPC servers and clients |
- |
- */ |
- |
-/** @file event.h |
- |
- A library for writing event-driven network servers |
- |
- */ |
- |
-#ifdef __cplusplus |
-extern "C" { |
-#endif |
- |
-#include "event-config.h" |
-#ifdef _EVENT_HAVE_SYS_TYPES_H |
-#include <sys/types.h> |
-#endif |
-#ifdef _EVENT_HAVE_SYS_TIME_H |
-#include <sys/time.h> |
-#endif |
-#ifdef _EVENT_HAVE_STDINT_H |
-#include <stdint.h> |
-#endif |
-#include <stdarg.h> |
- |
-/* For int types. */ |
-#include "evutil.h" |
- |
-#ifdef WIN32 |
-#define WIN32_LEAN_AND_MEAN |
-#include <windows.h> |
-#undef WIN32_LEAN_AND_MEAN |
-typedef unsigned char u_char; |
-typedef unsigned short u_short; |
-#endif |
- |
-#define EVLIST_TIMEOUT 0x01 |
-#define EVLIST_INSERTED 0x02 |
-#define EVLIST_SIGNAL 0x04 |
-#define EVLIST_ACTIVE 0x08 |
-#define EVLIST_INTERNAL 0x10 |
-#define EVLIST_INIT 0x80 |
- |
-/* EVLIST_X_ Private space: 0x1000-0xf000 */ |
-#define EVLIST_ALL (0xf000 | 0x9f) |
- |
-#define EV_TIMEOUT 0x01 |
-#define EV_READ 0x02 |
-#define EV_WRITE 0x04 |
-#define EV_SIGNAL 0x08 |
-#define EV_PERSIST 0x10 /* Persistant event */ |
- |
-/* Fix so that ppl dont have to run with <sys/queue.h> */ |
-#ifndef TAILQ_ENTRY |
-#define _EVENT_DEFINED_TQENTRY |
-#define TAILQ_ENTRY(type) \ |
-struct { \ |
- struct type *tqe_next; /* next element */ \ |
- struct type **tqe_prev; /* address of previous next element */ \ |
-} |
-#endif /* !TAILQ_ENTRY */ |
- |
-struct event_base; |
-#ifndef EVENT_NO_STRUCT |
-struct event { |
- TAILQ_ENTRY (event) ev_next; |
- TAILQ_ENTRY (event) ev_active_next; |
- TAILQ_ENTRY (event) ev_signal_next; |
- unsigned int min_heap_idx; /* for managing timeouts */ |
- |
- struct event_base *ev_base; |
- |
- int ev_fd; |
- short ev_events; |
- short ev_ncalls; |
- short *ev_pncalls; /* Allows deletes in callback */ |
- |
- struct timeval ev_timeout; |
- |
- int ev_pri; /* smaller numbers are higher priority */ |
- |
- void (*ev_callback)(int, short, void *arg); |
- void *ev_arg; |
- |
- int ev_res; /* result passed to event callback */ |
- int ev_flags; |
-}; |
-#else |
-struct event; |
-#endif |
- |
-#define EVENT_SIGNAL(ev) (int)(ev)->ev_fd |
-#define EVENT_FD(ev) (int)(ev)->ev_fd |
- |
-/* |
- * Key-Value pairs. Can be used for HTTP headers but also for |
- * query argument parsing. |
- */ |
-struct evkeyval { |
- TAILQ_ENTRY(evkeyval) next; |
- |
- char *key; |
- char *value; |
-}; |
- |
-#ifdef _EVENT_DEFINED_TQENTRY |
-#undef TAILQ_ENTRY |
-struct event_list; |
-struct evkeyvalq; |
-#undef _EVENT_DEFINED_TQENTRY |
-#else |
-TAILQ_HEAD (event_list, event); |
-TAILQ_HEAD (evkeyvalq, evkeyval); |
-#endif /* _EVENT_DEFINED_TQENTRY */ |
- |
-/** |
- Initialize the event API. |
- |
- Use event_base_new() to initialize a new event base, but does not set |
- the current_base global. If using only event_base_new(), each event |
- added must have an event base set with event_base_set() |
- |
- @see event_base_set(), event_base_free(), event_init() |
- */ |
-struct event_base *event_base_new(void); |
- |
-/** |
- Initialize the event API. |
- |
- The event API needs to be initialized with event_init() before it can be |
- used. Sets the current_base global representing the default base for |
- events that have no base associated with them. |
- |
- @see event_base_set(), event_base_new() |
- */ |
-struct event_base *event_init(void); |
- |
-/** |
- Reinitialized the event base after a fork |
- |
- Some event mechanisms do not survive across fork. The event base needs |
- to be reinitialized with the event_reinit() function. |
- |
- @param base the event base that needs to be re-initialized |
- @return 0 if successful, or -1 if some events could not be re-added. |
- @see event_base_new(), event_init() |
-*/ |
-int event_reinit(struct event_base *base); |
- |
-/** |
- Loop to process events. |
- |
- In order to process events, an application needs to call |
- event_dispatch(). This function only returns on error, and should |
- replace the event core of the application program. |
- |
- @see event_base_dispatch() |
- */ |
-int event_dispatch(void); |
- |
- |
-/** |
- Threadsafe event dispatching loop. |
- |
- @param eb the event_base structure returned by event_init() |
- @see event_init(), event_dispatch() |
- */ |
-int event_base_dispatch(struct event_base *); |
- |
- |
-/** |
- Get the kernel event notification mechanism used by libevent. |
- |
- @param eb the event_base structure returned by event_base_new() |
- @return a string identifying the kernel event mechanism (kqueue, epoll, etc.) |
- */ |
-const char *event_base_get_method(struct event_base *); |
- |
- |
-/** |
- Deallocate all memory associated with an event_base, and free the base. |
- |
- Note that this function will not close any fds or free any memory passed |
- to event_set as the argument to callback. |
- |
- @param eb an event_base to be freed |
- */ |
-void event_base_free(struct event_base *); |
- |
- |
-#define _EVENT_LOG_DEBUG 0 |
-#define _EVENT_LOG_MSG 1 |
-#define _EVENT_LOG_WARN 2 |
-#define _EVENT_LOG_ERR 3 |
-typedef void (*event_log_cb)(int severity, const char *msg); |
-/** |
- Redirect libevent's log messages. |
- |
- @param cb a function taking two arguments: an integer severity between |
- _EVENT_LOG_DEBUG and _EVENT_LOG_ERR, and a string. If cb is NULL, |
- then the default log is used. |
- */ |
-void event_set_log_callback(event_log_cb cb); |
- |
-/** |
- Associate a different event base with an event. |
- |
- @param eb the event base |
- @param ev the event |
- */ |
-int event_base_set(struct event_base *, struct event *); |
- |
-/** |
- event_loop() flags |
- */ |
-/*@{*/ |
-#define EVLOOP_ONCE 0x01 /**< Block at most once. */ |
-#define EVLOOP_NONBLOCK 0x02 /**< Do not block. */ |
-/*@}*/ |
- |
-/** |
- Handle events. |
- |
- This is a more flexible version of event_dispatch(). |
- |
- @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK |
- @return 0 if successful, -1 if an error occurred, or 1 if no events were |
- registered. |
- @see event_loopexit(), event_base_loop() |
-*/ |
-int event_loop(int); |
- |
-/** |
- Handle events (threadsafe version). |
- |
- This is a more flexible version of event_base_dispatch(). |
- |
- @param eb the event_base structure returned by event_init() |
- @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK |
- @return 0 if successful, -1 if an error occurred, or 1 if no events were |
- registered. |
- @see event_loopexit(), event_base_loop() |
- */ |
-int event_base_loop(struct event_base *, int); |
- |
-/** |
- Exit the event loop after the specified time. |
- |
- The next event_loop() iteration after the given timer expires will |
- complete normally (handling all queued events) then exit without |
- blocking for events again. |
- |
- Subsequent invocations of event_loop() will proceed normally. |
- |
- @param tv the amount of time after which the loop should terminate. |
- @return 0 if successful, or -1 if an error occurred |
- @see event_loop(), event_base_loop(), event_base_loopexit() |
- */ |
-int event_loopexit(const struct timeval *); |
- |
- |
-/** |
- Exit the event loop after the specified time (threadsafe variant). |
- |
- The next event_base_loop() iteration after the given timer expires will |
- complete normally (handling all queued events) then exit without |
- blocking for events again. |
- |
- Subsequent invocations of event_base_loop() will proceed normally. |
- |
- @param eb the event_base structure returned by event_init() |
- @param tv the amount of time after which the loop should terminate. |
- @return 0 if successful, or -1 if an error occurred |
- @see event_loopexit() |
- */ |
-int event_base_loopexit(struct event_base *, const struct timeval *); |
- |
-/** |
- Abort the active event_loop() immediately. |
- |
- event_loop() will abort the loop after the next event is completed; |
- event_loopbreak() is typically invoked from this event's callback. |
- This behavior is analogous to the "break;" statement. |
- |
- Subsequent invocations of event_loop() will proceed normally. |
- |
- @return 0 if successful, or -1 if an error occurred |
- @see event_base_loopbreak(), event_loopexit() |
- */ |
-int event_loopbreak(void); |
- |
-/** |
- Abort the active event_base_loop() immediately. |
- |
- event_base_loop() will abort the loop after the next event is completed; |
- event_base_loopbreak() is typically invoked from this event's callback. |
- This behavior is analogous to the "break;" statement. |
- |
- Subsequent invocations of event_loop() will proceed normally. |
- |
- @param eb the event_base structure returned by event_init() |
- @return 0 if successful, or -1 if an error occurred |
- @see event_base_loopexit |
- */ |
-int event_base_loopbreak(struct event_base *); |
- |
- |
-/** |
- Add a timer event. |
- |
- @param ev the event struct |
- @param tv timeval struct |
- */ |
-#define evtimer_add(ev, tv) event_add(ev, tv) |
- |
- |
-/** |
- Define a timer event. |
- |
- @param ev event struct to be modified |
- @param cb callback function |
- @param arg argument that will be passed to the callback function |
- */ |
-#define evtimer_set(ev, cb, arg) event_set(ev, -1, 0, cb, arg) |
- |
- |
-/** |
- * Delete a timer event. |
- * |
- * @param ev the event struct to be disabled |
- */ |
-#define evtimer_del(ev) event_del(ev) |
-#define evtimer_pending(ev, tv) event_pending(ev, EV_TIMEOUT, tv) |
-#define evtimer_initialized(ev) ((ev)->ev_flags & EVLIST_INIT) |
- |
-/** |
- * Add a timeout event. |
- * |
- * @param ev the event struct to be disabled |
- * @param tv the timeout value, in seconds |
- */ |
-#define timeout_add(ev, tv) event_add(ev, tv) |
- |
- |
-/** |
- * Define a timeout event. |
- * |
- * @param ev the event struct to be defined |
- * @param cb the callback to be invoked when the timeout expires |
- * @param arg the argument to be passed to the callback |
- */ |
-#define timeout_set(ev, cb, arg) event_set(ev, -1, 0, cb, arg) |
- |
- |
-/** |
- * Disable a timeout event. |
- * |
- * @param ev the timeout event to be disabled |
- */ |
-#define timeout_del(ev) event_del(ev) |
- |
-#define timeout_pending(ev, tv) event_pending(ev, EV_TIMEOUT, tv) |
-#define timeout_initialized(ev) ((ev)->ev_flags & EVLIST_INIT) |
- |
-#define signal_add(ev, tv) event_add(ev, tv) |
-#define signal_set(ev, x, cb, arg) \ |
- event_set(ev, x, EV_SIGNAL|EV_PERSIST, cb, arg) |
-#define signal_del(ev) event_del(ev) |
-#define signal_pending(ev, tv) event_pending(ev, EV_SIGNAL, tv) |
-#define signal_initialized(ev) ((ev)->ev_flags & EVLIST_INIT) |
- |
-/** |
- Prepare an event structure to be added. |
- |
- The function event_set() prepares the event structure ev to be used in |
- future calls to event_add() and event_del(). The event will be prepared to |
- call the function specified by the fn argument with an int argument |
- indicating the file descriptor, a short argument indicating the type of |
- event, and a void * argument given in the arg argument. The fd indicates |
- the file descriptor that should be monitored for events. The events can be |
- either EV_READ, EV_WRITE, or both. Indicating that an application can read |
- or write from the file descriptor respectively without blocking. |
- |
- The function fn will be called with the file descriptor that triggered the |
- event and the type of event which will be either EV_TIMEOUT, EV_SIGNAL, |
- EV_READ, or EV_WRITE. The additional flag EV_PERSIST makes an event_add() |
- persistent until event_del() has been called. |
- |
- @param ev an event struct to be modified |
- @param fd the file descriptor to be monitored |
- @param event desired events to monitor; can be EV_READ and/or EV_WRITE |
- @param fn callback function to be invoked when the event occurs |
- @param arg an argument to be passed to the callback function |
- |
- @see event_add(), event_del(), event_once() |
- |
- */ |
-void event_set(struct event *, int, short, void (*)(int, short, void *), void *); |
- |
-/** |
- Schedule a one-time event to occur. |
- |
- The function event_once() is similar to event_set(). However, it schedules |
- a callback to be called exactly once and does not require the caller to |
- prepare an event structure. |
- |
- @param fd a file descriptor to monitor |
- @param events event(s) to monitor; can be any of EV_TIMEOUT | EV_READ | |
- EV_WRITE |
- @param callback callback function to be invoked when the event occurs |
- @param arg an argument to be passed to the callback function |
- @param timeout the maximum amount of time to wait for the event, or NULL |
- to wait forever |
- @return 0 if successful, or -1 if an error occurred |
- @see event_set() |
- |
- */ |
-int event_once(int, short, void (*)(int, short, void *), void *, |
- const struct timeval *); |
- |
- |
-/** |
- Schedule a one-time event (threadsafe variant) |
- |
- The function event_base_once() is similar to event_set(). However, it |
- schedules a callback to be called exactly once and does not require the |
- caller to prepare an event structure. |
- |
- @param base an event_base returned by event_init() |
- @param fd a file descriptor to monitor |
- @param events event(s) to monitor; can be any of EV_TIMEOUT | EV_READ | |
- EV_WRITE |
- @param callback callback function to be invoked when the event occurs |
- @param arg an argument to be passed to the callback function |
- @param timeout the maximum amount of time to wait for the event, or NULL |
- to wait forever |
- @return 0 if successful, or -1 if an error occurred |
- @see event_once() |
- */ |
-int event_base_once(struct event_base *base, int fd, short events, |
- void (*callback)(int, short, void *), void *arg, |
- const struct timeval *timeout); |
- |
- |
-/** |
- Add an event to the set of monitored events. |
- |
- The function event_add() schedules the execution of the ev event when the |
- event specified in event_set() occurs or in at least the time specified in |
- the tv. If tv is NULL, no timeout occurs and the function will only be |
- called if a matching event occurs on the file descriptor. The event in the |
- ev argument must be already initialized by event_set() and may not be used |
- in calls to event_set() until it has timed out or been removed with |
- event_del(). If the event in the ev argument already has a scheduled |
- timeout, the old timeout will be replaced by the new one. |
- |
- @param ev an event struct initialized via event_set() |
- @param timeout the maximum amount of time to wait for the event, or NULL |
- to wait forever |
- @return 0 if successful, or -1 if an error occurred |
- @see event_del(), event_set() |
- */ |
-int event_add(struct event *ev, const struct timeval *timeout); |
- |
- |
-/** |
- Remove an event from the set of monitored events. |
- |
- The function event_del() will cancel the event in the argument ev. If the |
- event has already executed or has never been added the call will have no |
- effect. |
- |
- @param ev an event struct to be removed from the working set |
- @return 0 if successful, or -1 if an error occurred |
- @see event_add() |
- */ |
-int event_del(struct event *); |
- |
-void event_active(struct event *, int, short); |
- |
- |
-/** |
- Checks if a specific event is pending or scheduled. |
- |
- @param ev an event struct previously passed to event_add() |
- @param event the requested event type; any of EV_TIMEOUT|EV_READ| |
- EV_WRITE|EV_SIGNAL |
- @param tv an alternate timeout (FIXME - is this true?) |
- |
- @return 1 if the event is pending, or 0 if the event has not occurred |
- |
- */ |
-int event_pending(struct event *ev, short event, struct timeval *tv); |
- |
- |
-/** |
- Test if an event structure has been initialized. |
- |
- The event_initialized() macro can be used to check if an event has been |
- initialized. |
- |
- @param ev an event structure to be tested |
- @return 1 if the structure has been initialized, or 0 if it has not been |
- initialized |
- */ |
-#ifdef WIN32 |
-#define event_initialized(ev) ((ev)->ev_flags & EVLIST_INIT && (ev)->ev_fd != (int)INVALID_HANDLE_VALUE) |
-#else |
-#define event_initialized(ev) ((ev)->ev_flags & EVLIST_INIT) |
-#endif |
- |
- |
-/** |
- Get the libevent version number. |
- |
- @return a string containing the version number of libevent |
- */ |
-const char *event_get_version(void); |
- |
- |
-/** |
- Get the kernel event notification mechanism used by libevent. |
- |
- @return a string identifying the kernel event mechanism (kqueue, epoll, etc.) |
- */ |
-const char *event_get_method(void); |
- |
- |
-/** |
- Set the number of different event priorities. |
- |
- By default libevent schedules all active events with the same priority. |
- However, some time it is desirable to process some events with a higher |
- priority than others. For that reason, libevent supports strict priority |
- queues. Active events with a lower priority are always processed before |
- events with a higher priority. |
- |
- The number of different priorities can be set initially with the |
- event_priority_init() function. This function should be called before the |
- first call to event_dispatch(). The event_priority_set() function can be |
- used to assign a priority to an event. By default, libevent assigns the |
- middle priority to all events unless their priority is explicitly set. |
- |
- @param npriorities the maximum number of priorities |
- @return 0 if successful, or -1 if an error occurred |
- @see event_base_priority_init(), event_priority_set() |
- |
- */ |
-int event_priority_init(int); |
- |
- |
-/** |
- Set the number of different event priorities (threadsafe variant). |
- |
- See the description of event_priority_init() for more information. |
- |
- @param eb the event_base structure returned by event_init() |
- @param npriorities the maximum number of priorities |
- @return 0 if successful, or -1 if an error occurred |
- @see event_priority_init(), event_priority_set() |
- */ |
-int event_base_priority_init(struct event_base *, int); |
- |
- |
-/** |
- Assign a priority to an event. |
- |
- @param ev an event struct |
- @param priority the new priority to be assigned |
- @return 0 if successful, or -1 if an error occurred |
- @see event_priority_init() |
- */ |
-int event_priority_set(struct event *, int); |
- |
- |
-/* These functions deal with buffering input and output */ |
- |
-struct evbuffer { |
- u_char *buffer; |
- u_char *orig_buffer; |
- |
- size_t misalign; |
- size_t totallen; |
- size_t off; |
- |
- void (*cb)(struct evbuffer *, size_t, size_t, void *); |
- void *cbarg; |
-}; |
- |
-/* Just for error reporting - use other constants otherwise */ |
-#define EVBUFFER_READ 0x01 |
-#define EVBUFFER_WRITE 0x02 |
-#define EVBUFFER_EOF 0x10 |
-#define EVBUFFER_ERROR 0x20 |
-#define EVBUFFER_TIMEOUT 0x40 |
- |
-struct bufferevent; |
-typedef void (*evbuffercb)(struct bufferevent *, void *); |
-typedef void (*everrorcb)(struct bufferevent *, short what, void *); |
- |
-struct event_watermark { |
- size_t low; |
- size_t high; |
-}; |
- |
-#ifndef EVENT_NO_STRUCT |
-struct bufferevent { |
- struct event_base *ev_base; |
- |
- struct event ev_read; |
- struct event ev_write; |
- |
- struct evbuffer *input; |
- struct evbuffer *output; |
- |
- struct event_watermark wm_read; |
- struct event_watermark wm_write; |
- |
- evbuffercb readcb; |
- evbuffercb writecb; |
- everrorcb errorcb; |
- void *cbarg; |
- |
- int timeout_read; /* in seconds */ |
- int timeout_write; /* in seconds */ |
- |
- short enabled; /* events that are currently enabled */ |
-}; |
-#endif |
- |
-/** |
- Create a new bufferevent. |
- |
- libevent provides an abstraction on top of the regular event callbacks. |
- This abstraction is called a buffered event. A buffered event provides |
- input and output buffers that get filled and drained automatically. The |
- user of a buffered event no longer deals directly with the I/O, but |
- instead is reading from input and writing to output buffers. |
- |
- Once initialized, the bufferevent structure can be used repeatedly with |
- bufferevent_enable() and bufferevent_disable(). |
- |
- When read enabled the bufferevent will try to read from the file descriptor |
- and call the read callback. The write callback is executed whenever the |
- output buffer is drained below the write low watermark, which is 0 by |
- default. |
- |
- If multiple bases are in use, bufferevent_base_set() must be called before |
- enabling the bufferevent for the first time. |
- |
- @param fd the file descriptor from which data is read and written to. |
- This file descriptor is not allowed to be a pipe(2). |
- @param readcb callback to invoke when there is data to be read, or NULL if |
- no callback is desired |
- @param writecb callback to invoke when the file descriptor is ready for |
- writing, or NULL if no callback is desired |
- @param errorcb callback to invoke when there is an error on the file |
- descriptor |
- @param cbarg an argument that will be supplied to each of the callbacks |
- (readcb, writecb, and errorcb) |
- @return a pointer to a newly allocated bufferevent struct, or NULL if an |
- error occurred |
- @see bufferevent_base_set(), bufferevent_free() |
- */ |
-struct bufferevent *bufferevent_new(int fd, |
- evbuffercb readcb, evbuffercb writecb, everrorcb errorcb, void *cbarg); |
- |
- |
-/** |
- Assign a bufferevent to a specific event_base. |
- |
- @param base an event_base returned by event_init() |
- @param bufev a bufferevent struct returned by bufferevent_new() |
- @return 0 if successful, or -1 if an error occurred |
- @see bufferevent_new() |
- */ |
-int bufferevent_base_set(struct event_base *base, struct bufferevent *bufev); |
- |
- |
-/** |
- Assign a priority to a bufferevent. |
- |
- @param bufev a bufferevent struct |
- @param pri the priority to be assigned |
- @return 0 if successful, or -1 if an error occurred |
- */ |
-int bufferevent_priority_set(struct bufferevent *bufev, int pri); |
- |
- |
-/** |
- Deallocate the storage associated with a bufferevent structure. |
- |
- @param bufev the bufferevent structure to be freed. |
- */ |
-void bufferevent_free(struct bufferevent *bufev); |
- |
- |
-/** |
- Changes the callbacks for a bufferevent. |
- |
- @param bufev the bufferevent object for which to change callbacks |
- @param readcb callback to invoke when there is data to be read, or NULL if |
- no callback is desired |
- @param writecb callback to invoke when the file descriptor is ready for |
- writing, or NULL if no callback is desired |
- @param errorcb callback to invoke when there is an error on the file |
- descriptor |
- @param cbarg an argument that will be supplied to each of the callbacks |
- (readcb, writecb, and errorcb) |
- @see bufferevent_new() |
- */ |
-void bufferevent_setcb(struct bufferevent *bufev, |
- evbuffercb readcb, evbuffercb writecb, everrorcb errorcb, void *cbarg); |
- |
-/** |
- Changes the file descriptor on which the bufferevent operates. |
- |
- @param bufev the bufferevent object for which to change the file descriptor |
- @param fd the file descriptor to operate on |
-*/ |
-void bufferevent_setfd(struct bufferevent *bufev, int fd); |
- |
-/** |
- Write data to a bufferevent buffer. |
- |
- The bufferevent_write() function can be used to write data to the file |
- descriptor. The data is appended to the output buffer and written to the |
- descriptor automatically as it becomes available for writing. |
- |
- @param bufev the bufferevent to be written to |
- @param data a pointer to the data to be written |
- @param size the length of the data, in bytes |
- @return 0 if successful, or -1 if an error occurred |
- @see bufferevent_write_buffer() |
- */ |
-int bufferevent_write(struct bufferevent *bufev, |
- const void *data, size_t size); |
- |
- |
-/** |
- Write data from an evbuffer to a bufferevent buffer. The evbuffer is |
- being drained as a result. |
- |
- @param bufev the bufferevent to be written to |
- @param buf the evbuffer to be written |
- @return 0 if successful, or -1 if an error occurred |
- @see bufferevent_write() |
- */ |
-int bufferevent_write_buffer(struct bufferevent *bufev, struct evbuffer *buf); |
- |
- |
-/** |
- Read data from a bufferevent buffer. |
- |
- The bufferevent_read() function is used to read data from the input buffer. |
- |
- @param bufev the bufferevent to be read from |
- @param data pointer to a buffer that will store the data |
- @param size the size of the data buffer, in bytes |
- @return the amount of data read, in bytes. |
- */ |
-size_t bufferevent_read(struct bufferevent *bufev, void *data, size_t size); |
- |
-/** |
- Enable a bufferevent. |
- |
- @param bufev the bufferevent to be enabled |
- @param event any combination of EV_READ | EV_WRITE. |
- @return 0 if successful, or -1 if an error occurred |
- @see bufferevent_disable() |
- */ |
-int bufferevent_enable(struct bufferevent *bufev, short event); |
- |
- |
-/** |
- Disable a bufferevent. |
- |
- @param bufev the bufferevent to be disabled |
- @param event any combination of EV_READ | EV_WRITE. |
- @return 0 if successful, or -1 if an error occurred |
- @see bufferevent_enable() |
- */ |
-int bufferevent_disable(struct bufferevent *bufev, short event); |
- |
- |
-/** |
- Set the read and write timeout for a buffered event. |
- |
- @param bufev the bufferevent to be modified |
- @param timeout_read the read timeout |
- @param timeout_write the write timeout |
- */ |
-void bufferevent_settimeout(struct bufferevent *bufev, |
- int timeout_read, int timeout_write); |
- |
- |
-/** |
- Sets the watermarks for read and write events. |
- |
- On input, a bufferevent does not invoke the user read callback unless |
- there is at least low watermark data in the buffer. If the read buffer |
- is beyond the high watermark, the buffevent stops reading from the network. |
- |
- On output, the user write callback is invoked whenever the buffered data |
- falls below the low watermark. |
- |
- @param bufev the bufferevent to be modified |
- @param events EV_READ, EV_WRITE or both |
- @param lowmark the lower watermark to set |
- @param highmark the high watermark to set |
-*/ |
- |
-void bufferevent_setwatermark(struct bufferevent *bufev, short events, |
- size_t lowmark, size_t highmark); |
- |
-#define EVBUFFER_LENGTH(x) (x)->off |
-#define EVBUFFER_DATA(x) (x)->buffer |
-#define EVBUFFER_INPUT(x) (x)->input |
-#define EVBUFFER_OUTPUT(x) (x)->output |
- |
- |
-/** |
- Allocate storage for a new evbuffer. |
- |
- @return a pointer to a newly allocated evbuffer struct, or NULL if an error |
- occurred |
- */ |
-struct evbuffer *evbuffer_new(void); |
- |
- |
-/** |
- Deallocate storage for an evbuffer. |
- |
- @param pointer to the evbuffer to be freed |
- */ |
-void evbuffer_free(struct evbuffer *); |
- |
- |
-/** |
- Expands the available space in an event buffer. |
- |
- Expands the available space in the event buffer to at least datlen |
- |
- @param buf the event buffer to be expanded |
- @param datlen the new minimum length requirement |
- @return 0 if successful, or -1 if an error occurred |
-*/ |
-int evbuffer_expand(struct evbuffer *, size_t); |
- |
- |
-/** |
- Append data to the end of an evbuffer. |
- |
- @param buf the event buffer to be appended to |
- @param data pointer to the beginning of the data buffer |
- @param datlen the number of bytes to be copied from the data buffer |
- */ |
-int evbuffer_add(struct evbuffer *, const void *, size_t); |
- |
- |
- |
-/** |
- Read data from an event buffer and drain the bytes read. |
- |
- @param buf the event buffer to be read from |
- @param data the destination buffer to store the result |
- @param datlen the maximum size of the destination buffer |
- @return the number of bytes read |
- */ |
-int evbuffer_remove(struct evbuffer *, void *, size_t); |
- |
- |
-/** |
- * Read a single line from an event buffer. |
- * |
- * Reads a line terminated by either '\r\n', '\n\r' or '\r' or '\n'. |
- * The returned buffer needs to be freed by the caller. |
- * |
- * @param buffer the evbuffer to read from |
- * @return pointer to a single line, or NULL if an error occurred |
- */ |
-char *evbuffer_readline(struct evbuffer *); |
- |
- |
-/** Used to tell evbuffer_readln what kind of line-ending to look for. |
- */ |
-enum evbuffer_eol_style { |
- /** Any sequence of CR and LF characters is acceptable as an EOL. */ |
- EVBUFFER_EOL_ANY, |
- /** An EOL is an LF, optionally preceded by a CR. This style is |
- * most useful for implementing text-based internet protocols. */ |
- EVBUFFER_EOL_CRLF, |
- /** An EOL is a CR followed by an LF. */ |
- EVBUFFER_EOL_CRLF_STRICT, |
- /** An EOL is a LF. */ |
- EVBUFFER_EOL_LF |
-}; |
- |
-/** |
- * Read a single line from an event buffer. |
- * |
- * Reads a line terminated by an EOL as determined by the evbuffer_eol_style |
- * argument. Returns a newly allocated nul-terminated string; the caller must |
- * free the returned value. The EOL is not included in the returned string. |
- * |
- * @param buffer the evbuffer to read from |
- * @param n_read_out if non-NULL, points to a size_t that is set to the |
- * number of characters in the returned string. This is useful for |
- * strings that can contain NUL characters. |
- * @param eol_style the style of line-ending to use. |
- * @return pointer to a single line, or NULL if an error occurred |
- */ |
-char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out, |
- enum evbuffer_eol_style eol_style); |
- |
- |
-/** |
- Move data from one evbuffer into another evbuffer. |
- |
- This is a destructive add. The data from one buffer moves into |
- the other buffer. The destination buffer is expanded as needed. |
- |
- @param outbuf the output buffer |
- @param inbuf the input buffer |
- @return 0 if successful, or -1 if an error occurred |
- */ |
-int evbuffer_add_buffer(struct evbuffer *, struct evbuffer *); |
- |
- |
-/** |
- Append a formatted string to the end of an evbuffer. |
- |
- @param buf the evbuffer that will be appended to |
- @param fmt a format string |
- @param ... arguments that will be passed to printf(3) |
- @return The number of bytes added if successful, or -1 if an error occurred. |
- */ |
-int evbuffer_add_printf(struct evbuffer *, const char *fmt, ...) |
-#ifdef __GNUC__ |
- __attribute__((format(printf, 2, 3))) |
-#endif |
-; |
- |
- |
-/** |
- Append a va_list formatted string to the end of an evbuffer. |
- |
- @param buf the evbuffer that will be appended to |
- @param fmt a format string |
- @param ap a varargs va_list argument array that will be passed to vprintf(3) |
- @return The number of bytes added if successful, or -1 if an error occurred. |
- */ |
-int evbuffer_add_vprintf(struct evbuffer *, const char *fmt, va_list ap); |
- |
- |
-/** |
- Remove a specified number of bytes data from the beginning of an evbuffer. |
- |
- @param buf the evbuffer to be drained |
- @param len the number of bytes to drain from the beginning of the buffer |
- */ |
-void evbuffer_drain(struct evbuffer *, size_t); |
- |
- |
-/** |
- Write the contents of an evbuffer to a file descriptor. |
- |
- The evbuffer will be drained after the bytes have been successfully written. |
- |
- @param buffer the evbuffer to be written and drained |
- @param fd the file descriptor to be written to |
- @return the number of bytes written, or -1 if an error occurred |
- @see evbuffer_read() |
- */ |
-int evbuffer_write(struct evbuffer *, int); |
- |
- |
-/** |
- Read from a file descriptor and store the result in an evbuffer. |
- |
- @param buf the evbuffer to store the result |
- @param fd the file descriptor to read from |
- @param howmuch the number of bytes to be read |
- @return the number of bytes read, or -1 if an error occurred |
- @see evbuffer_write() |
- */ |
-int evbuffer_read(struct evbuffer *, int, int); |
- |
- |
-/** |
- Find a string within an evbuffer. |
- |
- @param buffer the evbuffer to be searched |
- @param what the string to be searched for |
- @param len the length of the search string |
- @return a pointer to the beginning of the search string, or NULL if the search failed. |
- */ |
-u_char *evbuffer_find(struct evbuffer *, const u_char *, size_t); |
- |
-/** |
- Set a callback to invoke when the evbuffer is modified. |
- |
- @param buffer the evbuffer to be monitored |
- @param cb the callback function to invoke when the evbuffer is modified |
- @param cbarg an argument to be provided to the callback function |
- */ |
-void evbuffer_setcb(struct evbuffer *, void (*)(struct evbuffer *, size_t, size_t, void *), void *); |
- |
-/* |
- * Marshaling tagged data - We assume that all tags are inserted in their |
- * numeric order - so that unknown tags will always be higher than the |
- * known ones - and we can just ignore the end of an event buffer. |
- */ |
- |
-void evtag_init(void); |
- |
-void evtag_marshal(struct evbuffer *evbuf, ev_uint32_t tag, const void *data, |
- ev_uint32_t len); |
- |
-/** |
- Encode an integer and store it in an evbuffer. |
- |
- We encode integer's by nibbles; the first nibble contains the number |
- of significant nibbles - 1; this allows us to encode up to 64-bit |
- integers. This function is byte-order independent. |
- |
- @param evbuf evbuffer to store the encoded number |
- @param number a 32-bit integer |
- */ |
-void encode_int(struct evbuffer *evbuf, ev_uint32_t number); |
- |
-void evtag_marshal_int(struct evbuffer *evbuf, ev_uint32_t tag, |
- ev_uint32_t integer); |
- |
-void evtag_marshal_string(struct evbuffer *buf, ev_uint32_t tag, |
- const char *string); |
- |
-void evtag_marshal_timeval(struct evbuffer *evbuf, ev_uint32_t tag, |
- struct timeval *tv); |
- |
-int evtag_unmarshal(struct evbuffer *src, ev_uint32_t *ptag, |
- struct evbuffer *dst); |
-int evtag_peek(struct evbuffer *evbuf, ev_uint32_t *ptag); |
-int evtag_peek_length(struct evbuffer *evbuf, ev_uint32_t *plength); |
-int evtag_payload_length(struct evbuffer *evbuf, ev_uint32_t *plength); |
-int evtag_consume(struct evbuffer *evbuf); |
- |
-int evtag_unmarshal_int(struct evbuffer *evbuf, ev_uint32_t need_tag, |
- ev_uint32_t *pinteger); |
- |
-int evtag_unmarshal_fixed(struct evbuffer *src, ev_uint32_t need_tag, |
- void *data, size_t len); |
- |
-int evtag_unmarshal_string(struct evbuffer *evbuf, ev_uint32_t need_tag, |
- char **pstring); |
- |
-int evtag_unmarshal_timeval(struct evbuffer *evbuf, ev_uint32_t need_tag, |
- struct timeval *ptv); |
- |
-#ifdef __cplusplus |
-} |
-#endif |
- |
-#endif /* _EVENT_H_ */ |