GitHub/libevent
1
0
Fork 0
mirror of https://github.com/libevent/libevent.git synced 2025-01-09 00:56:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/patches-2.0'

Browse Source 
Conflicts:
	include/event2/buffer.h
	include/event2/thread.h
	include/event2/util.h
This commit is contained in:
Nick Mathewson 2011-07-05 14:38:21 -04:00
commit 21be3dff74
27 changed files with 1141 additions and 620 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
Doxyfile
View File

@ -45,6 +45,15 @@ OPTIMIZE_OUTPUT_FOR_C = YES
SORT_BRIEF_DOCS = YES
# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
# can be used to strip a user-defined part of the path. Stripping is
# only done if one of the specified strings matches the left-hand part of
# the path. The tag can be used to show relative paths in the file list.
# If left blank the directory from which doxygen is run is used as the
# path to strip.
STRIP_FROM_PATH = include/
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
@ -54,21 +63,25 @@ SORT_BRIEF_DOCS = YES
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
INPUT = event.h evdns.h evhttp.h evrpc.h \
include/event2/event.h include/event2/event_struct.h \
include/event2/event_compat.h \
include/event2/buffer_compat.h \
include/event2/buffer.h include/event2/thread.h \
include/event2/tag.h include/event2/bufferevent.h \
include/event2/bufferevent_struct.h \
include/event2/bufferevent_compat.h \
include/event2/util.h \
include/event2/rpc.h include/event2/rpc_struct.h \
include/event2/rpc_compat.h \
include/event2/dns.h include/event2/dns_struct.h \
include/event2/dns_compat.h \
include/event2/http.h include/event2/http_struct.h \
include/event2/http_compat.h
INPUT = \
include/event2/buffer.h \
include/event2/buffer_compat.h \
include/event2/bufferevent.h \
include/event2/bufferevent_compat.h \
include/event2/bufferevent_ssl.h \
include/event2/dns.h \
include/event2/dns_compat.h \
include/event2/event.h \
include/event2/event_compat.h \
include/event2/http.h \
include/event2/http_compat.h \
include/event2/listener.h \
include/event2/rpc.h \
include/event2/rpc_compat.h \
include/event2/tag.h \
include/event2/tag_compat.h \
include/event2/thread.h \
include/event2/util.h
#---------------------------------------------------------------------------
# configuration options related to the HTML output
@ -140,7 +153,7 @@ PDF_HYPERLINKS = NO
# plain latex in the generated Makefile. Set this option to YES to get a
# higher quality PDF documentation.
USE_PDFLATEX = NO
USE_PDFLATEX = YES
# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode.
# command to the generated LaTeX files. This will instruct LaTeX to keep
@ -162,7 +175,7 @@ LATEX_HIDE_INDICES = NO
# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
# generate man pages
GENERATE_MAN = YES
GENERATE_MAN = NO
# The MAN_EXTENSION tag determines the extension that is added to
# the generated man pages (default is the subroutine's section .3)
@ -226,7 +239,7 @@ INCLUDE_FILE_PATTERNS =
# undefined via #undef or recursively expanded use the := operator
# instead of the = operator.
PREDEFINED = TAILQ_ENTRY RB_ENTRY _EVENT_DEFINED_TQENTRY
PREDEFINED = TAILQ_ENTRY RB_ENTRY _EVENT_DEFINED_TQENTRY _EVENT_IN_DOXYGEN
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.

10
evdns.h
View File

@ -27,6 +27,16 @@
#ifndef _EVDNS_H_
#define _EVDNS_H_
/** @file evdns.h
A dns subsystem for Libevent.
The <evdns.h> header is deprecated in Libevent 2.0 and later; please
use <event2/evdns.h> instead. Depending on what functionality you
need, you may also want to include more of the other event2/*.h
headers.
*/
#include <event.h>
#include <event2/dns.h>
#include <event2/dns_compat.h>

133
event.h
View File

@ -27,135 +27,14 @@
#ifndef _EVENT_H_
#define _EVENT_H_
/** @mainpage
/** @file event.h
@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 applications; 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
libevent 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.
event2/event.h
The primary libevent header
event2/buffer.h
Buffer management for network reading and writing
event2/dns.h
Asynchronous DNS resolution
event2/http.h
An embedded libevent-based HTTP server
evrpc.h
A framework for creating RPC servers and clients
*/
/** @file libevent/event.h
A library for writing event-driven network servers
A library for writing event-driven network servers.
The <event.h> header is deprecated in Libevent 2.0 and later; please
use <event2/event.h> instead. Depending on what functionality you
need, you may also want to include more of the other event2/
headers.
*/
#ifdef __cplusplus

10
evhttp.h
View File

@ -27,6 +27,16 @@
#ifndef _EVHTTP_H_
#define _EVHTTP_H_
/** @file evhttp.h
An http implementation subsystem for Libevent.
The <evhttp.h> header is deprecated in Libevent 2.0 and later; please
use <event2/http.h> instead. Depending on what functionality you
need, you may also want to include more of the other event2/*.h
headers.
*/
#include <event.h>
#include <event2/http.h>
#include <event2/http_struct.h>

10
evrpc.h
View File

@ -27,6 +27,16 @@
#ifndef _EVRPC_H_
#define _EVRPC_H_
/** @file evrpc.h
An RPC system for Libevent.
The <evrpc.h> header is deprecated in Libevent 2.0 and later; please
use <event2/rpc.h> instead. Depending on what functionality you
need, you may also want to include more of the other event2/*.h
headers.
*/
#include <event.h>
#include <event2/rpc.h>
#include <event2/rpc_struct.h>

8
evutil.h
View File

@ -26,6 +26,14 @@
#ifndef _EVUTIL_H_
#define _EVUTIL_H_
/** @file evutil.h
Utility and compatibility functions for Libevent.
The <evutil.h> header is deprecated in Libevent 2.0 and later; please
use <event2/util.h> instead.
*/
#include <event2/util.h>
#endif /* _EVUTIL_H_ */

205
include/event2/buffer.h
View File

@ -26,20 +26,22 @@
#ifndef _EVENT2_BUFFER_H_
#define _EVENT2_BUFFER_H_
/** @file buffer.h
/** @file event2/buffer.h
Functions for buffering data for network sending or receiving.
An evbuffer can be used for preparing data before sending it to
the network or conversely for reading data from the network.
Evbuffers try to avoid memory copies as much as possible. As a
result evbuffers can be used to pass data around without actually
result, evbuffers can be used to pass data around without actually
incurring the overhead of copying the data.
A new evbuffer can be allocated with evbuffer_new(), and can be
freed with evbuffer_free().
freed with evbuffer_free(). Most users will be using evbuffers via
the bufferevent interface. To access a bufferevent's evbuffers, use
bufferevent_get_input() and bufferevent_get_output().
There are several guide lines for using evbuffers.
There are several guidelines for using evbuffers.
- if you already know how much data you are going to add as a result
of calling evbuffer_add() multiple times, it makes sense to use
@ -53,12 +55,21 @@
if you use them, you will wind up with fragmented memory in your
buffer.
As the contents of an evbuffer can be stored into multiple different
memory blocks, it cannot be accessed directly. Instead, evbuffer_pullup()
can be used to force a specified number of bytes to be continuous. This
will cause memory reallocation and memory copies if the data is split
across multiple blocks.
- For high-performance code, you may want to avoid copying data into and out
of buffers. You can skip the copy step by using
evbuffer_reserve_space()/evbuffer_commit_space() when writing into a
buffer, and evbuffer_peek() when reading.
In Libevent 2.0 and later, evbuffers are represented using a linked
list of memory chunks, with pointers to the first and last chunk in
the chain.
As the contents of an evbuffer can be stored in multiple different
memory blocks, it cannot be accessed directly. Instead, evbuffer_pullup()
can be used to force a specified number of bytes to be contiguous. This
will cause memory reallocation and memory copies if the data is split
across multiple blocks. It is more efficient, however, to use
evbuffer_peek() if you don't require that the memory to be contiguous.
*/
#ifdef __cplusplus
@ -75,12 +86,25 @@ extern "C" {
#endif
#include <event2/util.h>
struct evbuffer;
/**
An evbuffer is an opaque data type for efficiently buffering data to be
sent or received on the network.
/** Points to a position within an evbuffer. Used when repeatedly searching
through a buffer. Calls to any function that modifies or re-packs the
buffer contents may invalidate all evbuffer_ptrs for that buffer. Do not
modify these values except with evbuffer_ptr_set.
@see event2/event.h for more information
*/
struct evbuffer
#ifdef _EVENT_IN_DOXYGEN
{}
#endif
;
/**
Pointer to a position within an evbuffer.
Used when repeatedly searching through a buffer. Calling any function
that modifies or re-packs the buffer contents may invalidate all
evbuffer_ptrs for that buffer. Do not modify these values except with
evbuffer_ptr_set.
*/
struct evbuffer_ptr {
ev_ssize_t pos;
@ -118,7 +142,6 @@ struct evbuffer_iovec {
*/
struct evbuffer *evbuffer_new(void);
/**
Deallocate storage for an evbuffer.
@ -153,10 +176,10 @@ void evbuffer_lock(struct evbuffer *buf);
void evbuffer_unlock(struct evbuffer *buf);
/**
Returns the total number of bytes stored in the event buffer
Returns the total number of bytes stored in the evbuffer
@param buf pointer to the evbuffer
@return the number of bytes stored in the event buffer
@return the number of bytes stored in the evbuffer
*/
size_t evbuffer_get_length(const struct evbuffer *buf);
@ -175,28 +198,28 @@ size_t evbuffer_get_length(const struct evbuffer *buf);
size_t evbuffer_get_contiguous_space(const struct evbuffer *buf);
/**
Expands the available space in an event buffer.
Expands the available space in an evbuffer.
Expands the available space in the event buffer to at least datlen, so that
Expands the available space in the evbuffer to at least datlen, so that
appending datlen additional bytes will not require any new allocations.
@param buf the event buffer to be expanded
@param buf the evbuffer 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 *buf, size_t datlen);
/**
Reserves space in the last chain of an event buffer.
Reserves space in the last chain or chains of an evbuffer.
Makes space available in the last chain of an event buffer that can
Makes space available in the last chain or chains of an evbuffer that can
be arbitrarily written to by a user. The space does not become
available for reading until it has been committed with
evbuffer_commit_space().
The space is made available as one or more extents, represented by
an initial pointer and a length. You can force the memory to be
available as only one extent. Allowing more, however, makes the
available as only one extent. Allowing more extents, however, makes the
function more efficient.
Multiple subsequent calls to this function will make the same space
@ -208,19 +231,20 @@ int evbuffer_expand(struct evbuffer *buf, size_t datlen);
NOTE: The code currently does not ever use more than two extents.
This may change in future versions.
@param buf the event buffer in which to reserve space.
@param buf the evbuffer in which to reserve space.
@param size how much space to make available, at minimum. The
total length of the extents may be greater than the requested
length.
@param vec an array of one or more evbuffer_iovec structures to
hold pointers to the reserved extents of memory.
@param n_vec The length of the vec array. Must be at least 1.
@param n_vec The length of the vec array. Must be at least 1;
2 is more efficient.
@return the number of provided extents, or -1 on error.
@see evbuffer_commit_space
@see evbuffer_commit_space()
*/
int
evbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size,
struct evbuffer_iovec *vec, int n_vecs);
struct evbuffer_iovec *vec, int n_vec);
/**
Commits previously reserved space.
@ -233,15 +257,15 @@ evbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size,
has been added to the buffer since the space was reserved.
If you want to commit less data than you got reserved space for,
modify the iov_len pointer of the buffer to a smaller value. Note
that you may have received more space than you requested if it was
available!
modify the iov_len pointer of the appropriate extent to a smaller
value. Note that you may have received more space than you
requested if it was available!
@param buf the event buffer in which to reserve space.
@param buf the evbuffer in which to reserve space.
@param vec one or two extents returned by evbuffer_reserve_space.
@param n_vecs the number of extents.
@return 0 on success, -1 on error
@see evbuffer_reserve_space
@see evbuffer_reserve_space()
*/
int evbuffer_commit_space(struct evbuffer *buf,
struct evbuffer_iovec *vec, int n_vecs);
@ -249,7 +273,7 @@ int evbuffer_commit_space(struct evbuffer *buf,
/**
Append data to the end of an evbuffer.
@param buf the event buffer to be appended to
@param buf the evbuffer 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
@return 0 on success, -1 on failure.
@ -258,9 +282,12 @@ int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen);
/**
Read data from an event buffer and drain the bytes read.
Read data from an evbuffer and drain the bytes read.
@param buf the event buffer to be read from
If more bytes are requested than are available in the evbuffer, we
only extract as many bytes as were available.
@param buf the evbuffer 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, or -1 if we can't drain the buffer.
@ -268,22 +295,28 @@ int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen);
int evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen);
/**
Read data from an event buffer, and leave the buffer unchanged.
Read data from an evbuffer, and leave the buffer unchanged.
@param buf the event buffer to be read from
@param data the destination buffer to store the result
If more bytes are requested than are available in the evbuffer, we
only extract as many bytes as were available.
@param buf the evbuffer to be read from
@param data_out the destination buffer to store the result
@param datlen the maximum size of the destination buffer
@return the number of bytes read, or -1 if we can't drain the buffer.
*/
ev_ssize_t evbuffer_copyout(struct evbuffer *buf, void *data_out, size_t datlen);
/**
Read data from an event buffer into another event buffer draining
the bytes from the src buffer read. This function avoids memcpy
as possible.
Read data from an evbuffer into another evbuffer, draining
the bytes from the source buffer. This function avoids copy
operations to the extent possible.
@param src the event buffer to be read from
@param dst the destination event buffer to store the result into
If more bytes are requested than are available in src, the src
buffer is drained completely.
@param src the evbuffer to be read from
@param dst the destination evbuffer to store the result into
@param datlen the maximum numbers of bytes to transfer
@return the number of bytes read
*/
@ -293,7 +326,15 @@ int evbuffer_remove_buffer(struct evbuffer *src, struct evbuffer *dst,
/** 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. */
/** Any sequence of CR and LF characters is acceptable as an
* EOL.
*
* Note that this style can produce ambiguous results: the
* sequence "CRLF" will be treated as a single EOL if it is
* all in the buffer at once, but if you first read a CR from
* the network and later read an LF from the network, it will
* be treated as two EOLs.
*/
EVBUFFER_EOL_ANY,
/** An EOL is an LF, optionally preceded by a CR. This style is
* most useful for implementing text-based internet protocols. */
@ -305,7 +346,7 @@ enum evbuffer_eol_style {
};
/**
* Read a single line from an event buffer.
* Read a single line from an evbuffer.
*
* 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
@ -322,7 +363,7 @@ 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.
Move all data from one evbuffer into another evbuffer.
This is a destructive add. The data from one buffer moves into
the other buffer. However, no unnecessary memory copies occur.
@ -330,10 +371,17 @@ char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out,
@param outbuf the output buffer
@param inbuf the input buffer
@return 0 if successful, or -1 if an error occurred
@see evbuffer_remove_buffer()
*/
int evbuffer_add_buffer(struct evbuffer *outbuf, struct evbuffer *inbuf);
/**
A cleanup function for a piece of memory added to an evbuffer by
reference.
@see evbuffer_add_reference()
*/
typedef void (*evbuffer_ref_cleanup_cb)(const void *data,
size_t datalen, void *extra);
@ -348,37 +396,46 @@ typedef void (*evbuffer_ref_cleanup_cb)(const void *data,
@param data the memory to reference
@param datlen how memory to reference
@param cleanupfn callback to be invoked when the memory is no longer
referenced
@param extra optional argument to the cleanup callback
referenced by this evbuffer.
@param cleanupfn_arg optional argument to the cleanup callback
@return 0 if successful, or -1 if an error occurred
*/
int evbuffer_add_reference(struct evbuffer *outbuf,
const void *data, size_t datlen,
evbuffer_ref_cleanup_cb cleanupfn, void *extra);
evbuffer_ref_cleanup_cb cleanupfn, void *cleanupfn_arg);
/**
Move data from a file into the evbuffer for writing to a socket.
Copy data from a file into the evbuffer for writing to a socket.
This function avoids unnecessary data copies between userland and
kernel. Where available, it uses sendfile or splice.
kernel. Where available, it uses sendfile or splice; failing those,
it tries to use mmap.
The function owns the resulting file descriptor and will close it
when finished transferring data.
The results of using evbuffer_remove() or evbuffer_pullup() are
undefined.
The results of using evbuffer_remove() or evbuffer_pullup() on
evbuffers whose data was added using this function are undefined.
For more fine-grained control, use evbuffer_add_file_segment.
@param outbuf the output buffer
@param fd the file descriptor
<<<<<<< HEAD
@param off the offset from which to read data
@param length how much data to read, or -1 to read as much as possible.
(-1 requires that 'fd' support fstat.)
||||||| merged common ancestors
@param off the offset from which to read data
@param length how much data to read
=======
@param offset the offset from which to read data
@param length how much data to read
>>>>>>> origin/patches-2.0
@return 0 if successful, or -1 if an error occurred
*/
int evbuffer_add_file(struct evbuffer *output, int fd, ev_off_t offset,
int evbuffer_add_file(struct evbuffer *outbuf, int fd, ev_off_t offset,
ev_off_t length);
/**
@ -482,11 +539,14 @@ int evbuffer_add_file_segment(struct evbuffer *buf,
/**
Append a formatted string to the end of an evbuffer.
The string is formated as printf.
@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.
@see evutil_printf(), evbuffer_add_vprintf()
*/
int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...)
#ifdef __GNUC__
@ -494,7 +554,6 @@ int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...)
#endif
;
/**
Append a va_list formatted string to the end of an evbuffer.
@ -546,7 +605,7 @@ int evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd,
/**
Read from a file descriptor and store the result in an evbuffer.
@param buf the evbuffer to store the result
@param buffer 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
@ -583,6 +642,10 @@ struct evbuffer_ptr evbuffer_search(struct evbuffer *buffer, const char *what, s
*/
struct evbuffer_ptr evbuffer_search_range(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start, const struct evbuffer_ptr *end);
/**
Defines how to adjust an evbuffer_ptr by evbuffer_ptr_set()
@see evbuffer_ptr_set() */
enum evbuffer_ptr_how {
/** Sets the pointer to the position; can be called on with an
uninitialized evbuffer_ptr. */
@ -604,7 +667,7 @@ enum evbuffer_ptr_how {
@returns 0 on success or -1 otherwise
*/
int
evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *pos,
evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *ptr,
size_t position, enum evbuffer_ptr_how how);
/**
@ -625,14 +688,6 @@ struct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer,
struct evbuffer_ptr *start, size_t *eol_len_out,
enum evbuffer_eol_style eol_style);
/** Structure passed to an evbuffer callback */
struct evbuffer_cb_info {
/** The size of */
size_t orig_size;
size_t n_added;
size_t n_deleted;
};
/** Function to peek at data inside an evbuffer without removing it or
copying it out.
@ -663,6 +718,21 @@ int evbuffer_peek(struct evbuffer *buffer, ev_ssize_t len,
struct evbuffer_ptr *start_at,
struct evbuffer_iovec *vec_out, int n_vec);
/** Structure passed to an evbuffer_cb_func evbuffer callback
@see evbuffer_cb_func, evbuffer_add_cb()
*/
struct evbuffer_cb_info {
/** The number of bytes in this evbuffer when callbacks were last
* invoked. */
size_t orig_size;
/** The number of bytes added since callbacks were last invoked. */
size_t n_added;
/** The number of bytes removed since callbacks were last invoked. */
size_t n_deleted;
};
/** Type definition for a callback that is invoked whenever data is added or
removed from an evbuffer.
@ -718,7 +788,10 @@ int evbuffer_remove_cb_entry(struct evbuffer *buffer,
int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);
/** If this flag is not set, then a callback is temporarily disabled, and
* should not be invoked. */
* should not be invoked.
*
* @see evbuffer_cb_set_flags(), evbuffer_cb_clear_flags()
*/
#define EVBUFFER_CB_ENABLED 1
/** Change the flags that are set for a callback on a buffer by adding more.

2
include/event2/buffer_compat.h
View File

@ -27,7 +27,7 @@
#ifndef _EVENT2_BUFFER_COMPAT_H_
#define _EVENT2_BUFFER_COMPAT_H_
/** @file buffer_compat.h
/** @file event2/buffer_compat.h
Obsolete and deprecated versions of the functions in buffer.h: provided
only for backward compatibility.

130
include/event2/bufferevent.h
View File

@ -27,27 +27,51 @@
#ifndef _EVENT2_BUFFEREVENT_H_
#define _EVENT2_BUFFEREVENT_H_
/** @file bufferevent.h
/**
@file event2/bufferevent.h
Functions for buffering data for network sending or receiving. Bufferevents
are higher level than evbuffers: each has an underlying evbuffer for reading
and one for writing, and callbacks that are invoked under certain
circumstances.
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.
A bufferevent provides input and output buffers that get filled and
drained automatically. The user of a bufferevent 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().
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.
When reading is enabled, the bufferevent will try to read from the
file descriptor onto its input buffer, and and call the read callback.
When writing is enabled, the bufferevent will try to write data onto its
file descriptor when writing is enabled, and call the write callback
when the output buffer is sufficiently drained.
Bufferevents come in several flavors, including:
<dl>
<dt>Socket-based bufferevents</dt>
<dd>A bufferevent that reads and writes data onto a network
socket. Created with bufferevent_socket_new().</dd>
<dt>Paired bufferevents</dt>
<dd>A pair of bufferevents that send and receive data to one
another without touching the network. Created with
bufferevent_pair_new().</dd>
<dt>Filtering bufferevents</dt>
<dd>A bufferevent that transforms data, and sends or receives it
over another underlying bufferevent. Created with
bufferevent_filter_new().</dd>
<dt>SSL-backed bufferevents</dt>
<dd>A bufferevent that uses the openssl library to send and
receive data over an encrypted connection. Created with
bufferevent_openssl_socket_new() or
bufferevent_openssl_filter_new().</dd>
</dl>
*/
#ifdef __cplusplus
@ -65,20 +89,36 @@ extern "C" {
/* For int types. */
#include <event2/util.h>
/* Just for error reporting - use other constants otherwise */
/** @name Bufferevent event codes
These flags are passed as arguments to a bufferevent's event callback.
@{
*/
#define BEV_EVENT_READING 0x01 /**< error encountered while reading */
#define BEV_EVENT_WRITING 0x02 /**< error encountered while writing */
#define BEV_EVENT_EOF 0x10 /**< eof file reached */
#define BEV_EVENT_ERROR 0x20 /**< unrecoverable error encountered */
#define BEV_EVENT_TIMEOUT 0x40 /**< user specified timeout reached */
#define BEV_EVENT_TIMEOUT 0x40 /**< user-specified timeout reached */
#define BEV_EVENT_CONNECTED 0x80 /**< connect operation finished. */
struct bufferevent;
/**@}*/
/**
An opaque type for handling buffered IO
@see event2/bufferevent.h
*/
struct bufferevent
#ifdef _EVENT_IN_DOXYGEN
{}
#endif
;
struct event_base;
struct evbuffer;
struct sockaddr;
/**
type definition for the read or write callback.
A read or write callback for a bufferevent.
The read callback is triggered when new data arrives in the input
buffer and the amount of readable data exceed the low watermark
@ -88,14 +128,14 @@ struct sockaddr;
exhausted or fell below its low watermark.
@param bev the bufferevent that triggered the callback
@param ctx the user specified context for this bufferevent
@param ctx the user-specified context for this bufferevent
*/
typedef void (*bufferevent_data_cb)(struct bufferevent *bev, void *ctx);
/**
type definition for the error callback of a bufferevent.
An event/error callback for a bufferevent.
The error callback is triggered if either an EOF condition or another
The event callback is triggered if either an EOF condition or another
unrecoverable error was encountered.
@param bev the bufferevent for which the error condition was reached
@ -104,7 +144,7 @@ typedef void (*bufferevent_data_cb)(struct bufferevent *bev, void *ctx);
and one of the following flags: BEV_EVENT_EOF, BEV_EVENT_ERROR,
BEV_EVENT_TIMEOUT, BEV_EVENT_CONNECTED.
@param ctx the user specified context for this bufferevent
@param ctx the user-specified context for this bufferevent
*/
typedef void (*bufferevent_event_cb)(struct bufferevent *bev, short what, void *ctx);
@ -136,6 +176,7 @@ enum bufferevent_options {
This file descriptor is not allowed to be a pipe(2).
It is safe to set the fd to -1, so long as you later
set it with bufferevent_setfd or bufferevent_socket_connect().
@param options Zero or more BEV_OPT_* flags
@return a pointer to a newly allocated bufferevent struct, or NULL if an
error occurred
@see bufferevent_free()
@ -143,8 +184,10 @@ enum bufferevent_options {
struct bufferevent *bufferevent_socket_new(struct event_base *base, evutil_socket_t fd, int options);
/**
Launch a connect() attempt with a socket. When the connect succeeds,
the eventcb will be invoked with BEV_EVENT_CONNECTED set.
Launch a connect() attempt with a socket-based bufferevent.
When the connect succeeds, the eventcb will be invoked with
BEV_EVENT_CONNECTED set.
If the bufferevent does not already have a socket set, we allocate a new
socket here and make it nonblocking before we begin.
@ -188,7 +231,7 @@ struct evdns_base;
may block while it waits for a DNS response. This is probably not
what you want.
*/
int bufferevent_socket_connect_hostname(struct bufferevent *b,
int bufferevent_socket_connect_hostname(struct bufferevent *,
struct evdns_base *, int, const char *, int);
/**
@ -383,7 +426,7 @@ int bufferevent_disable(struct bufferevent *bufev, short event);
short bufferevent_get_enabled(struct bufferevent *bufev);
/**
Set the read and write timeout for a buffered event.
Set the read and write timeout for a bufferevent.
A bufferevent's timeout will fire the first time that the indicated
amount of time has elapsed since a successful read or write operation,
@ -460,8 +503,7 @@ enum bufferevent_flush_mode {
};
/**
Triggers the bufferevent to produce more
data if possible.
Triggers the bufferevent to produce more data if possible.
@param bufev the bufferevent object
@param iotype either EV_READ or EV_WRITE or both.
@ -473,9 +515,10 @@ int bufferevent_flush(struct bufferevent *bufev,
enum bufferevent_flush_mode mode);
/**
Support for filtering input and output of bufferevents.
*/
@name Filtering support
@{
*/
/**
Values that filters can return.
*/
@ -533,6 +576,7 @@ bufferevent_filter_new(struct bufferevent *underlying,
int options,
void (*free_context)(void *),
void *ctx);
/**@}*/
/**
Allocate a pair of linked bufferevents. The bufferevents behave as would
@ -680,13 +724,16 @@ int bufferevent_add_to_rate_limit_group(struct bufferevent *bev,
/** Remove 'bev' from its current rate-limit group (if any). */
int bufferevent_remove_from_rate_limit_group(struct bufferevent *bev);
/*@{*/
/**
@name Rate limit inspection
Return the current read or write bucket size for a bufferevent.
If it is not configured with a per-bufferevent ratelimit, return
EV_SSIZE_MAX. This function does not inspect the group limit, if any.
Note that it can return a negative value if the bufferevent has been
made to read or write more than its limit.
@{
*/
ev_ssize_t bufferevent_get_read_limit(struct bufferevent *bev);
ev_ssize_t bufferevent_get_write_limit(struct bufferevent *bev);
@ -695,11 +742,14 @@ ev_ssize_t bufferevent_get_write_limit(struct bufferevent *bev);
ev_ssize_t bufferevent_get_max_to_read(struct bufferevent *bev);
ev_ssize_t bufferevent_get_max_to_write(struct bufferevent *bev);
/*@{*/
/**
@name GrouprRate limit inspection
Return the read or write bucket size for a bufferevent rate limit
group. Note that it can return a negative value if bufferevents in
the group have been made to read or write more than their limits.
@{
*/
ev_ssize_t bufferevent_rate_limit_group_get_read_limit(
struct bufferevent_rate_limit_group *);
@ -707,8 +757,9 @@ ev_ssize_t bufferevent_rate_limit_group_get_write_limit(
struct bufferevent_rate_limit_group *);
/*@}*/
/*@{*/
/**
@name Rate limit manipulation
Subtract a number of bytes from a bufferevent's read or write bucket.
The decrement value can be negative, if you want to manually refill
the bucket. If the change puts the bucket above or below zero, the
@ -717,13 +768,16 @@ ev_ssize_t bufferevent_rate_limit_group_get_write_limit(
group, if any.
Returns 0 on success, -1 on internal error.
@{
*/
int bufferevent_decrement_read_limit(struct bufferevent *bev, ev_ssize_t decr);
int bufferevent_decrement_write_limit(struct bufferevent *bev, ev_ssize_t decr);
/*@}*/
/*@{*/
/**
@name Group rate limit manipulation
Subtract a number of bytes from a bufferevent rate-limiting group's
read or write bucket. The decrement value can be negative, if you
want to manually refill the bucket. If the change puts the bucket
@ -731,6 +785,8 @@ int bufferevent_decrement_write_limit(struct bufferevent *bev, ev_ssize_t decr);
suspend reading writing as appropriate.
Returns 0 on success, -1 on internal error.
@{
*/
int bufferevent_rate_limit_group_decrement_read(
struct bufferevent_rate_limit_group *, ev_ssize_t);
@ -739,14 +795,20 @@ int bufferevent_rate_limit_group_decrement_write(
/*@}*/
/** Set the variable pointed to by total_read_out to the total number of bytes
/**
* Inspect the total bytes read/written on a group.
*
* Set the variable pointed to by total_read_out to the total number of bytes
* ever read on grp, and the variable pointed to by total_written_out to the
* total number of bytes ever written on grp. */
void bufferevent_rate_limit_group_get_totals(
struct bufferevent_rate_limit_group *grp,
ev_uint64_t *total_read_out, ev_uint64_t *total_written_out);
/** Reset the number of bytes read or written on grp as given by
/**
* Reset the total bytes read/written on a group.
*
* Reset the number of bytes read or written on grp as given by
* bufferevent_rate_limit_group_reset_totals(). */
void
bufferevent_rate_limit_group_reset_totals(

4
include/event2/bufferevent_compat.h
View File

@ -54,6 +54,10 @@
If multiple bases are in use, bufferevent_base_set() must be called before
enabling the bufferevent for the first time.
@deprecated This function is deprecated because it uses the current
event base, and as such can be error prone for multithreaded programs.
Use bufferevent_socket_new() instead.
@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

33
include/event2/bufferevent_ssl.h
View File

@ -26,7 +26,7 @@
#ifndef _EVENT2_BUFFEREVENT_SSL_H_
#define _EVENT2_BUFFEREVENT_SSL_H_
/** @file bufferevent_ssl.h
/** @file event2/bufferevent_ssl.h
OpenSSL support for bufferevents.
*/
@ -39,15 +39,31 @@
extern "C" {
#endif
/* This is what openssl's SSL objects are underneath. */
struct ssl_st;
/**
The state of an SSL object to be used when creating a new
SSL bufferevent.
*/
enum bufferevent_ssl_state {
BUFFEREVENT_SSL_OPEN = 0,
BUFFEREVENT_SSL_CONNECTING = 1,
BUFFEREVENT_SSL_ACCEPTING = 2
};
#ifdef _EVENT_HAVE_OPENSSL
#if defined(_EVENT_HAVE_OPENSSL) || defined(_EVENT_IN_DOXYGEN)
/**
Create a new SSL bufferevent to send its data over another bufferevent.
@param base An event_base to use to detect reading and writing. It
must also be the base for the underlying bufferevent.
@param underlying A socket to use for this SSL
@param ssl A SSL* object from openssl.
@param state The current state of the SSL connection
@param options One or more bufferevent_options
@return A new bufferevent on success, or NULL on failure
*/
struct bufferevent *
bufferevent_openssl_filter_new(struct event_base *base,
struct bufferevent *underlying,
@ -55,6 +71,16 @@ bufferevent_openssl_filter_new(struct event_base *base,
enum bufferevent_ssl_state state,
int options);
/**
Create a new SSL bufferevent to send its data over an SSL * on a socket.
@param base An event_base to use to detect reading and writing
@param fd A socket to use for this SSL
@param ssl A SSL* object from openssl.
@param state The current state of the SSL connection
@param options One or more bufferevent_options
@return A new bufferevent on success, or NULL on failure.
*/
struct bufferevent *
bufferevent_openssl_socket_new(struct event_base *base,
evutil_socket_t fd,
@ -62,11 +88,14 @@ bufferevent_openssl_socket_new(struct event_base *base,
enum bufferevent_ssl_state state,
int options);
/** Return the underlying openssl SSL * object for an SSL bufferevent. */
struct ssl_st *
bufferevent_openssl_get_ssl(struct bufferevent *bufev);
/** Tells a bufferevent to begin SSL renegotiation. */
int bufferevent_ssl_renegotiate(struct bufferevent *bev);
/** Return the most recent OpenSSL error reported on an SSL bufferevent. */
unsigned long bufferevent_get_openssl_error(struct bufferevent *bev);
#endif

5
include/event2/bufferevent_struct.h
View File

@ -27,11 +27,14 @@
#ifndef _EVENT2_BUFFEREVENT_STRUCT_H_
#define _EVENT2_BUFFEREVENT_STRUCT_H_
/** @file bufferevent_struct.h
/** @file event2/bufferevent_struct.h
Data structures for bufferevents. Using these structures may hurt forward
compatibility with later versions of Libevent: be careful!
@deprecated Use of bufferevent_struct.h is completely deprecated; these
structures are only exposed for backward compatibility with programs
written before Libevent 2.0 that used them.
*/
#ifdef __cplusplus

2
include/event2/dns.h
View File

@ -47,7 +47,7 @@
* the source verbatim in their source distributions)
*/
/** @file dns.h
/** @file event2/dns.h
*
* Welcome, gentle reader
*

3
include/event2/dns_compat.h
View File

@ -27,11 +27,12 @@
#ifndef _EVENT2_DNS_COMPAT_H_
#define _EVENT2_DNS_COMPAT_H_
/** @file dns_compat.h
/** @file event2/dns_compat.h
Potentially non-threadsafe versions of the functions in dns.h: provided
only for backwards compatibility.
*/
#ifdef __cplusplus

2
include/event2/dns_struct.h
View File

@ -27,7 +27,7 @@
#ifndef _EVENT2_DNS_STRUCT_H_
#define _EVENT2_DNS_STRUCT_H_
/** @file dns_struct.h
/** @file event2/dns_struct.h
Data structures for dns. Using these structures may hurt forward
compatibility with later versions of Libevent: be careful!

698
include/event2/event.h
View File

File diff suppressed because it is too large Load Diff

200
include/event2/event_compat.h
View File

@ -27,11 +27,19 @@
#ifndef _EVENT2_EVENT_COMPAT_H_
#define _EVENT2_EVENT_COMPAT_H_
/** @file event_compat.h
/** @file event2/event_compat.h
Potentially non-threadsafe versions of the functions in event.h: provided
only for backwards compatibility.
In the oldest versions of Libevent, event_base was not a first-class
structure. Instead, there was a single event base that every function
manipulated. Later, when separate event bases were added, the old functions
that didn't take an event_base argument needed to work by manipulating the
"current" event base. This could lead to thread-safety issues, and obscure,
hard-to-diagnose bugs.
@deprecated All functions in this file are by definition deprecated.
*/
#ifdef __cplusplus
@ -67,31 +75,26 @@ struct event_base *event_init(void);
/**
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.
Like event_base_dispatch(), but uses the "current" base.
@deprecated This function is deprecated because it is easily confused by
multiple calls to event_init(), and because it is not safe for
multithreaded use. The replacement is event_base_dispatch().
@see event_base_dispatch()
@see event_base_dispatch(), event_init()
*/
int event_dispatch(void);
/**
Handle events.
This is a more flexible version of event_dispatch().
This function behaves like event_base_loop(), but uses the "current" base
@deprecated This function is deprecated because it uses the event base from
the last call to event_init, and is therefore not safe for multithreaded
use. The replacement is event_base_loop().
@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_base_loopexit(), event_base_loop()
@see event_base_loop(), event_init()
*/
int event_loop(int);
@ -99,19 +102,14 @@ int event_loop(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.
This function behaves like event_base_loopexit(), except that it uses the
"current" base.
Subsequent invocations of event_loop() will proceed normally.
@deprecated This function is deprecated because it uses the event base from
the last call to event_init, and is therefore not safe for multithreaded
use. The replacement is event_base_loopexit().
@deprecated This function is deprecated because it is easily confused by
multiple calls to event_init(), and because it is not safe for
multithreaded use. The replacement is event_base_loopexit().
@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()
@see event_init, event_base_loopexit()
*/
int event_loopexit(const struct timeval *);
@ -119,42 +117,25 @@ int event_loopexit(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.
This function behaves like event_base_loopbreakt(), except that it uses the
"current" base.
Subsequent invocations of event_loop() will proceed normally.
@deprecated This function is deprecated because it uses the event base from
the last call to event_init, and is therefore not safe for multithreaded
use. The replacement is event_base_loopbreak().
@deprecated This function is deprecated because it is easily confused by
multiple calls to event_init(), and because it is not safe for
multithreaded use. The replacement is event_base_loopbreak().
@return 0 if successful, or -1 if an error occurred
@see event_base_loopbreak(), event_loopexit()
@see event_base_loopbreak(), event_init()
*/
int event_loopbreak(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.
@deprecated This function is deprecated because it is easily confused by
multiple calls to event_init(), and because it is not safe for
multithreaded use. The replacement is event_base_once().
@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()
@deprecated This function is obsolete, and has been replaced by
event_base_once(). Its use is deprecated because it relies on the
"current" base configured by event_init().
@see event_base_once()
*/
int event_once(evutil_socket_t , short,
void (*)(evutil_socket_t, short, void *), void *, const struct timeval *);
@ -163,11 +144,11 @@ int event_once(evutil_socket_t , short,
/**
Get the kernel event notification mechanism used by Libevent.
@return a string identifying the kernel event mechanism (kqueue, epoll, etc.)
@deprecated This function is obsolete, and has been replaced by
event_base_get_method(). Its use is deprecated because it relies on the
"current" base configured by event_init().
@deprecated This function is deprecated because it is easily confused by
multiple calls to event_init(), and because it is not safe for
multithreaded use. The replacement is event_base_get_method().
@see event_base_get_method()
*/
const char *event_get_method(void);
@ -175,61 +156,19 @@ 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.
@deprecated This function is deprecated because it is easily confused by
multiple calls to event_init(), and because it is not safe for
multithreaded use. The replacement is event_base_priority_init().
@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()
@see event_base_priority_init()
*/
int event_priority_init(int);
/**
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.
For read and write events, edge-triggered behavior can be requested
with the EV_ET flag. Not all backends support edge-triggered
behavior. When an edge-triggered event is activated, the EV_ET flag
is added to its events argument.
@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()
@deprecated event_set() is not recommended for new code, because it requires
a subsequent call to event_base_set() to be safe under many circumstances.
a subsequent call to event_base_set() to be safe under most circumstances.
Use event_assign() or event_new() instead.
*/
void event_set(struct event *, evutil_socket_t, short, void (*)(evutil_socket_t, short, void *), void *);
@ -240,76 +179,33 @@ void event_set(struct event *, evutil_socket_t, short, void (*)(evutil_socket_t,
/**
* Add a timeout event.
*
* @param ev the event struct to be disabled
* @param tv the timeout value, in seconds
*
* @deprecated This macro is deprecated because its naming is inconsistent.
* The recommend macro is evtimer_add().
@name timeout_* macros
@deprecated These macros are deprecated because their naming is inconsisten
with the rest of Libevent. Use the evtimer_* macros instead.
@{
*/
#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
*
* @deprecated This macro is deprecated because its naming is inconsistent.
* The recommend macro is evtimer_set().
*/
#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
*
* @deprecated This macro is deprecated because its naming is inconsistent.
* The recommend macro is evtimer_del().
*/
#define timeout_del(ev) event_del(ev)
/**
@deprecated This macro is deprecated because its naming is inconsistent.
The recommend macro is evtimer_pending().
*/
#define timeout_pending(ev, tv) event_pending((ev), EV_TIMEOUT, (tv))
/**
@deprecated This macro is deprecated because its naming is inconsistent.
The recommend macro is evtimer_initialized().
*/
#define timeout_initialized(ev) event_initialized(ev)
/**@}*/
/**
@deprecated This macro is deprecated because its naming is inconsistent.
The recommend macro is evsignal_add().
*/
@name signal_* macros
@deprecated These macros are deprecated because their naming is inconsisten
with the rest of Libevent. Use the evsignal_* macros instead.
@{
*/
#define signal_add(ev, tv) event_add((ev), (tv))
/**
@deprecated This macro is deprecated because its naming is inconsistent.
The recommend macro is evsignal_set().
*/
#define signal_set(ev, x, cb, arg) \
event_set((ev), (x), EV_SIGNAL|EV_PERSIST, (cb), (arg))
/**
@deprecated This macro is deprecated because its naming is inconsistent.
The recommend macro is evsignal_del().
*/
#define signal_del(ev) event_del(ev)
/**
@deprecated This macro is deprecated because its naming is inconsistent.
The recommend macro is evsignal_pending().
*/
#define signal_pending(ev, tv) event_pending((ev), EV_SIGNAL, (tv))
/**
@deprecated This macro is deprecated because its naming is inconsistent.
The recommend macro is evsignal_initialized().
*/
#define signal_initialized(ev) event_initialized(ev)
/**@}*/
#ifndef EVENT_FD
/* These macros are obsolete; use event_get_fd and event_get_signal instead. */

8
include/event2/event_struct.h
View File

@ -27,11 +27,13 @@
#ifndef _EVENT2_EVENT_STRUCT_H_
#define _EVENT2_EVENT_STRUCT_H_
/** @file event_struct.h
/** @file event2/event_struct.h
Structures used by event.h. Using these structures directly may harm
forward compatibility: be careful!
Structures used by event.h. Using these structures directly WILL harm
forward compatibility: be careful.
No field declared in this file should be used directly in user code. Except
for historical reasons, these fields would not be exposed at all.
*/
#ifdef __cplusplus

2
include/event2/http.h
View File

@ -38,7 +38,7 @@ extern "C" {
struct evbuffer;
struct event_base;
/** @file http.h
/** @file event2/http.h
*
* Basic support for HTTP serving.
*

2
include/event2/http_compat.h
View File

@ -27,7 +27,7 @@
#ifndef _EVENT2_HTTP_COMPAT_H_
#define _EVENT2_HTTP_COMPAT_H_
/** @file http_compat.h
/** @file event2/http_compat.h
Potentially non-threadsafe versions of the functions in http.h: provided
only for backwards compatibility.

2
include/event2/http_struct.h
View File

@ -27,7 +27,7 @@
#ifndef _EVENT2_HTTP_STRUCT_H_
#define _EVENT2_HTTP_STRUCT_H_
/** @file http_struct.h
/** @file event2/http_struct.h
Data structures for http. Using these structures may hurt forward
compatibility with later versions of Libevent: be careful!

2
include/event2/rpc_compat.h
View File

@ -27,7 +27,7 @@
#ifndef _EVENT2_RPC_COMPAT_H_
#define _EVENT2_RPC_COMPAT_H_
/** @file rpc_compat.h
/** @file event2/rpc_compat.h
Deprecated versions of the functions in rpc.h: provided only for
backwards compatibility.

2
include/event2/rpc_struct.h
View File

@ -31,7 +31,7 @@
extern "C" {
#endif
/** @file rpc_struct.h
/** @file event2/rpc_struct.h
Structures used by rpc.h. Using these structures directly may harm
forward compatibility: be careful!

2
include/event2/tag.h
View File

@ -27,7 +27,7 @@
#ifndef _EVENT2_TAG_H_
#define _EVENT2_TAG_H_
/** @file tag.h
/** @file event2/tag.h
Helper functions for reading and writing tagged data onto buffers.

12
include/event2/tag_compat.h
View File

@ -27,13 +27,23 @@
#ifndef _EVENT2_TAG_COMPAT_H_
#define _EVENT2_TAG_COMPAT_H_
/** @file tag_compat.h
/** @file event2/tag_compat.h
Obsolete/deprecated functions from tag.h; provided only for backwards
compatibility.
*/
/**
@name Misnamed functions
@deprecated These macros are deprecated because their names don't follow
Libevent's naming conventions. Use evtag_encode_int and
evtag_encode_int64 instead.
@{
*/
#define encode_int(evbuf, number) evtag_encode_int((evbuf), (number))
#define encode_int64(evbuf, number) evtag_encode_int64((evbuf), (number))
/**@}*/
#endif /* _EVENT2_TAG_H_ */

61
include/event2/thread.h
View File

@ -26,7 +26,7 @@
#ifndef _EVENT2_THREAD_H_
#define _EVENT2_THREAD_H_
/** @file thread.h
/** @file event2/thread.h
Functions for multi-threaded applications using Libevent.
@ -38,18 +38,11 @@
_must_ be set up before an event_base is created if you want the base to
use them.
A multi-threaded application must provide locking functions to
Libevent via evthread_set_locking_callback(). Libevent will invoke
this callback whenever a lock needs to be acquired or released.
The total number of locks employed by Libevent can be determined
via the evthread_num_locks() function. An application must provision
that many locks.
If the owner of an event base is waiting for events to happen,
Libevent may signal the thread via a special file descriptor to wake
up. To enable this feature, an application needs to provide a
thread identity function via evthread_set_id_callback().
Most programs will either be using Windows threads or Posix threads. You
can configure Libevent to use one of these event_use_windows_threads() or
event_use_pthreads() respectively. If you're using another threading
library, you'll need to configure threading functions manually using
evthread_set_lock_callbacks() and evthread_set_condition_callbacks().
*/
@ -59,6 +52,11 @@ extern "C" {
#include <event2/event-config.h>
/**
@name Flags passed to lock functions
@{
*/
/** A flag passed to a locking callback when the lock was allocated as a
* read-write lock, and we want to acquire or release the lock for writing. */
#define EVTHREAD_WRITE 0x04
@ -69,11 +67,16 @@ extern "C" {
* for the lock; if we can't get the lock immediately, we will instead
* return nonzero from the locking callback. */
#define EVTHREAD_TRY 0x10
/**@}*/
#ifndef _EVENT_DISABLE_THREAD_SUPPORT
#if !defined(_EVENT_DISABLE_THREAD_SUPPORT) || defined(_EVENT_IN_DOXYGEN)
#define EVTHREAD_LOCK_API_VERSION 1
/**
@name Types of locks
@{*/
/** A recursive lock is one that can be acquired multiple times at once by the
* same thread. No other process can allocate the lock until the thread that
* has been holding it has unlocked it as many times as it locked it. */
@ -81,9 +84,10 @@ extern "C" {
/* A read-write lock is one that allows multiple simultaneous readers, but
* where any one writer excludes all other writers and readers. */
#define EVTHREAD_LOCKTYPE_READWRITE 2
/**@}*/
/** This structure describes the interface a threading library uses for
* locking. It's used to tell evthread_set_lock_callbacks how to use
* locking. It's used to tell evthread_set_lock_callbacks() how to use
* locking on this platform.
*/
struct evthread_lock_callbacks {
@ -168,7 +172,7 @@ struct evthread_condition_callbacks {
*
* Note that if you're using Windows or the Pthreads threading library, you
* probably shouldn't call this function; instead, use
* evthread_use_windows_threads() or evthread_use_posix_threads() if you can.
* evthread_use_windows_threads() or evthread_use_pthreads() if you can.
*/
int evthread_set_condition_callbacks(
const struct evthread_condition_callbacks *);
@ -183,38 +187,45 @@ int evthread_set_condition_callbacks(
void evthread_set_id_callback(
unsigned long (*id_fn)(void));
#if defined(_WIN32) && !defined(_EVENT_DISABLE_THREAD_SUPPORT)
#if (defined(_WIN32) && !defined(_EVENT_DISABLE_THREAD_SUPPORT)) || defined(_EVENT_IN_DOXYGEN)
/** Sets up Libevent for use with Windows builtin locking and thread ID
functions. Unavailable if Libevent is not built for Windows.
functions. Unavailable if Libevent is not built for Windows.
@return 0 on success, -1 on failure. */
@return 0 on success, -1 on failure. */
int evthread_use_windows_threads(void);
/**
Defined if Libevent was built with support for evthread_use_windows_threads()
*/
#define EVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED 1
#endif
#if defined(_EVENT_HAVE_PTHREADS)
#if defined(_EVENT_HAVE_PTHREADS) || defined(_EVENT_IN_DOXYGEN)
/** Sets up Libevent for use with Pthreads locking and thread ID functions.
Unavailable if Libevent is not build for use with pthreads. Requires
libraries to link against Libevent_pthreads as well as Libevent.
Unavailable if Libevent is not build for use with pthreads. Requires
libraries to link against Libevent_pthreads as well as Libevent.
@return 0 on success, -1 on failure. */
@return 0 on success, -1 on failure. */
int evthread_use_pthreads(void);
/** Defined if Libevent was built with support for evthread_use_pthreads() */
#define EVTHREAD_USE_PTHREADS_IMPLEMENTED 1
#endif
/** Enable debugging wrappers around the current lock callbacks. If Libevent
* makes one of several common locking errors, exit with an assertion failure.
*
* If you're going to call this function, you must do so before any locks are
* allocated.
**/
void evthread_enable_lock_debuging(void);
#endif /* _EVENT_DISABLE_THREAD_SUPPORT */
struct event_base;
/** Make sure it's safe to tell an event base to wake up from another thread.
/** Make sure it's safe to tell an event base to wake up from another thread
or a signal handler.
@return 0 on success, -1 on failure.
@return 0 on success, -1 on failure.
*/
int evthread_make_base_notifiable(struct event_base *base);

164
include/event2/util.h
View File

@ -69,19 +69,39 @@ extern "C" {
#include <sys/socket.h>
#endif
/* Integer type definitions for types that are supposed to be defined in the
/* Some openbsd autoconf versions get the name of this macro wrong. */
#if defined(_EVENT_SIZEOF_VOID__) && !defined(_EVENT_SIZEOF_VOID_P)
#define _EVENT_SIZEOF_VOID_P _EVENT_SIZEOF_VOID__
#endif
/**
* @name Standard integer types.
*
* Integer type definitions for types that are supposed to be defined in the
* C99-specified stdint.h. Shamefully, some platforms do not include
* stdint.h, so we need to replace it. (If you are on a platform like this,
* your C headers are now over 10 years out of date. You should bug them to
* do something about this.)
*
* We define:
* ev_uint64_t, ev_uint32_t, ev_uint16_t, ev_uint8_t -- unsigned integer
* types of exactly 64, 32, 16, and 8 bits respectively.
* ev_int64_t, ev_int32_t, ev_int16_t, ev_int8_t -- signed integer
* types of exactly 64, 32, 16, and 8 bits respectively.
* ev_uintptr_t, ev_intptr_t -- unsigned/signed integers large enough
* to hold a pointer without loss of bits.
*
* <dl>
* <dt>ev_uint64_t, ev_uint32_t, ev_uint16_t, ev_uint8_t</dt>
* <dd>unsigned integer types of exactly 64, 32, 16, and 8 bits
* respectively.</dd>
* <dt>ev_int64_t, ev_int32_t, ev_int16_t, ev_int8_t</dt>
* <dd>signed integer types of exactly 64, 32, 16, and 8 bits
* respectively.</dd>
* <dt>ev_uintptr_t, ev_intptr_t</dt>
* <dd>unsigned/signed integers large enough
* to hold a pointer without loss of bits.</dd>
* <dt>ev_ssize_t</dt>
* <dd>A signed type of the same size as size_t</dd>
* <dt>ev_off_t</dt>
* <dd>A signed type typically used to represent offsets within a
* (potentially large) file</dd>
*
* @{
*/
#ifdef _EVENT_HAVE_UINT64_T
#define ev_uint64_t uint64_t
@ -95,6 +115,9 @@ extern "C" {
#elif _EVENT_SIZEOF_LONG == 8
#define ev_uint64_t unsigned long
#define ev_int64_t long
#elif defined(_EVENT_IN_DOXYGEN)
#define ev_uint64_t ...
#define ev_int64_t ...
#else
#error "No way to define ev_uint64_t"
#endif
@ -111,6 +134,9 @@ extern "C" {
#elif _EVENT_SIZEOF_INT == 4
#define ev_uint32_t unsigned int
#define ev_int32_t signed int
#elif defined(_EVENT_IN_DOXYGEN)
#define ev_uint32_t ...
#define ev_int32_t ...
#else
#error "No way to define ev_uint32_t"
#endif
@ -127,6 +153,9 @@ extern "C" {
#elif _EVENT_SIZEOF_SHORT == 2
#define ev_uint16_t unsigned short
#define ev_int16_t signed short
#elif defined(_EVENT_IN_DOXYGEN)
#define ev_uint16_t ...
#define ev_int16_t ...
#else
#error "No way to define ev_uint16_t"
#endif
@ -134,16 +163,14 @@ extern "C" {
#ifdef _EVENT_HAVE_UINT8_T
#define ev_uint8_t uint8_t
#define ev_int8_t int8_t
#elif defined(_EVENT_IN_DOXYGEN)
#define ev_uint8_t ...
#define ev_int8_t ...
#else
#define ev_uint8_t unsigned char
#define ev_int8_t signed char
#endif
/* Some openbsd autoconf versions get the name of this macro wrong. */
#if defined(_EVENT_SIZEOF_VOID__) && !defined(_EVENT_SIZEOF_VOID_P)
#define _EVENT_SIZEOF_VOID_P _EVENT_SIZEOF_VOID__
#endif
#ifdef _EVENT_HAVE_UINTPTR_T
#define ev_uintptr_t uintptr_t
#define ev_intptr_t intptr_t
@ -153,6 +180,9 @@ extern "C" {
#elif _EVENT_SIZEOF_VOID_P <= 8
#define ev_uintptr_t ev_uint64_t
#define ev_intptr_t ev_int64_t
#elif defined(_EVENT_IN_DOXYGEN)
#define ev_uintptr_t ...
#define ev_intptr_t ...
#else
#error "No way to define ev_uintptr_t"
#endif
@ -168,6 +198,7 @@ extern "C" {
#else
#define ev_off_t off_t
#endif
/**@}*/
/* Limits for integer types.
@ -176,6 +207,14 @@ extern "C" {
- The platform does signed arithmetic in two's complement.
*/
/**
@name Limits for integer types
These macros hold the largest or smallest values possible for the
ev_[u]int*_t types.
@{
*/
#define EV_UINT64_MAX ((((ev_uint64_t)0xffffffffUL) << 32) | 0xffffffffUL)
#define EV_INT64_MAX ((((ev_int64_t) 0x7fffffffL) << 32) | 0xffffffffL)
#define EV_INT64_MIN ((-EV_INT64_MAX) - 1)
@ -188,18 +227,28 @@ extern "C" {
#define EV_UINT8_MAX 255
#define EV_INT8_MAX 127
#define EV_INT8_MIN ((-EV_INT8_MAX) - 1)
/** @} */
/**
@name Limits for SIZE_T and SSIZE_T
@{
*/
#if _EVENT_SIZEOF_SIZE_T == 8
#define EV_SIZE_MAX EV_UINT64_MAX
#define EV_SSIZE_MAX EV_INT64_MAX
#elif _EVENT_SIZEOF_SIZE_T == 4
#define EV_SIZE_MAX EV_UINT32_MAX
#define EV_SSIZE_MAX EV_INT32_MAX
#elif defined(_EVENT_IN_DOXYGEN)
#define EV_SIZE_MAX ...
#define EV_SSIZE_MAX ...
#else
#error "No way to define SIZE_MAX"
#endif
#define EV_SSIZE_MIN ((-EV_SSIZE_MAX) - 1)
/**@}*/
#ifdef _WIN32
#define ev_socklen_t int
@ -216,17 +265,20 @@ extern "C" {
#endif
#endif
#ifdef _WIN32
/** A type wide enough to hold the output of "socket()" or "accept()". On
/**
* A type wide enough to hold the output of "socket()" or "accept()". On
* Windows, this is an intptr_t; elsewhere, it is an int. */
#ifdef _WIN32
#define evutil_socket_t intptr_t
#else
#define evutil_socket_t int
#endif
/** Create two new sockets that are connected to each other. On Unix, this
simply calls socketpair(). On Windows, it uses the loopback network
interface on 127.0.0.1, and only AF_INET,SOCK_STREAM are supported.
/** Create two new sockets that are connected to each other.
On Unix, this simply calls socketpair(). On Windows, it uses the
loopback network interface on 127.0.0.1, and only
AF_INET,SOCK_STREAM are supported.
(This may fail on some Windows hosts where firewall software has cleverly
decided to keep 127.0.0.1 from talking to itself.)
@ -241,9 +293,13 @@ int evutil_socketpair(int d, int type, int protocol, evutil_socket_t sv[2]);
*/
int evutil_make_socket_nonblocking(evutil_socket_t sock);
/** Do platform-specific operations on a listener socket to make sure that
another program will be able to bind this address right after we've
closed the listener
/** Do platform-specific operations to make a listener socket reusable.
Specifically, we want to make sure that another program will be able
to bind this address right after we've closed the listener.
This differs from Windows's interpretation of "reusable", which
allows multiple listeners to bind the same address at the same time.
@param sock The socket to make reusable
@return 0 on success, -1 on failure
@ -267,11 +323,6 @@ int evutil_make_socket_closeonexec(evutil_socket_t sock);
int evutil_closesocket(evutil_socket_t sock);
#define EVUTIL_CLOSESOCKET(s) evutil_closesocket(s)
/* Winsock handles socket errors differently from the rest of the world.
* Elsewhere, a socket error is like any other error and is stored in errno.
* But winsock functions require you to retrieve the error with a special
* function, and don't let you use strerror for the error codes. And handling
* EWOULDBLOCK is ... different. */
#ifdef _WIN32
/** Return the most recent socket error. Not idempotent on all platforms. */
@ -283,6 +334,30 @@ int evutil_closesocket(evutil_socket_t sock);
int evutil_socket_geterror(evutil_socket_t sock);
/** Convert a socket error to a string. */
const char *evutil_socket_error_to_string(int errcode);
#elif defined(_EVENT_IN_DOXYGEN)
/**
@name Socket error functions
These functions are needed for making programs compatible between
Windows and Unix-like platforms.
You see, Winsock handles socket errors differently from the rest of
the world. Elsewhere, a socket error is like any other error and is
stored in errno. But winsock functions require you to retrieve the
error with a special function, and don't let you use strerror for
the error codes. And handling EWOULDBLOCK is ... different.
@{
*/
/** Return the most recent socket error. Not idempotent on all platforms. */
#define EVUTIL_SOCKET_ERROR() ...
/** Replace the most recent socket error with errcode */
#define EVUTIL_SET_SOCKET_ERROR(errcode) ...
/** Return the most recent socket error to occur on sock. */
#define evutil_socket_geterror(sock) ...
/** Convert a socket error to a string. */
#define evutil_socket_error_to_string(errcode) ...
/**@}*/
#else
#define EVUTIL_SOCKET_ERROR() (errno)
#define EVUTIL_SET_SOCKET_ERROR(errcode) \
@ -291,9 +366,14 @@ const char *evutil_socket_error_to_string(int errcode);
#define evutil_socket_error_to_string(errcode) (strerror(errcode))
#endif
/*
* Manipulation macros for struct timeval. We define replacements
/**
* @name Manipulation macros for struct timeval.
*
* We define replacements
* for timeradd, timersub, timerclear, timercmp, and timerisset.
*
* @{
*/
#ifdef _EVENT_HAVE_TIMERADD
#define evutil_timeradd(tvp, uvp, vvp) timeradd((tvp), (uvp), (vvp))
@ -324,6 +404,7 @@ const char *evutil_socket_error_to_string(int errcode);
#else
#define evutil_timerclear(tvp) (tvp)->tv_sec = (tvp)->tv_usec = 0
#endif
/**@}*/
/** Return true iff the tvp is related to uvp according to the relational
* operator cmp. Recognized values for cmp are ==, <=, <, >=, and >. */
@ -338,7 +419,7 @@ const char *evutil_socket_error_to_string(int errcode);
#define evutil_timerisset(tvp) ((tvp)->tv_sec || (tvp)->tv_usec)
#endif
/* Replacement for offsetof on platforms that don't define it. */
/** Replacement for offsetof on platforms that don't define it. */
#ifdef offsetof
#define evutil_offsetof(type, field) offsetof(type, field)
#else
@ -349,7 +430,7 @@ const char *evutil_socket_error_to_string(int errcode);
/** Parse a 64-bit value from a string. Arguments are as for strtol. */
ev_int64_t evutil_strtoll(const char *s, char **endptr, int base);
/* Replacement for gettimeofday on platforms that lack it. */
/** Replacement for gettimeofday on platforms that lack it. */
#ifdef _EVENT_HAVE_GETTIMEOFDAY
#define evutil_gettimeofday(tv, tz) gettimeofday((tv), (tz))
#else
@ -365,6 +446,9 @@ int evutil_snprintf(char *buf, size_t buflen, const char *format, ...)
__attribute__((format(printf, 3, 4)))
#endif
;
/** Replacement for vsnprintf to get consistent behavior on platforms for
which the return value of snprintf does not conform to C99.
*/
int evutil_vsnprintf(char *buf, size_t buflen, const char *format, va_list ap);
/** Replacement for inet_ntop for platforms which lack it. */
@ -412,11 +496,16 @@ int evutil_ascii_strcasecmp(const char *str1, const char *str2);
*/
int evutil_ascii_strncasecmp(const char *str1, const char *str2, size_t n);
/* Here we define evutil_addrinfo to the native addrinfo type, or redefinte it
/* Here we define evutil_addrinfo to the native addrinfo type, or redefine it
* if this system has no getaddrinfo(). */
#ifdef _EVENT_HAVE_STRUCT_ADDRINFO
#define evutil_addrinfo addrinfo
#else
/** A definition of struct addrinfo for systems that lack it.
(This is just an alias for struct addrinfo if the system defines
struct addrinfo.)
*/
struct evutil_addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
int ai_family; /* PF_xxx */
@ -428,6 +517,13 @@ struct evutil_addrinfo {
struct evutil_addrinfo *ai_next; /* next structure in linked list */
};
#endif
/** @name evutil_getaddrinfo() error codes
These values are possible error codes for evutil_getaddrinfo() and
related functions.
@{
*/
#ifdef EAI_ADDRFAMILY
#define EVUTIL_EAI_ADDRFAMILY EAI_ADDRFAMILY
#else
@ -524,9 +620,11 @@ struct evutil_addrinfo {
#else
#define EVUTIL_AI_ADDRCONFIG 0x40000
#endif
/**@}*/
struct evutil_addrinfo;
/* This function clones getaddrinfo for systems that don't have it. For full
/**
* This function clones getaddrinfo for systems that don't have it. For full
* details, see RFC 3493, section 6.1.
*
* Limitations:
@ -539,12 +637,12 @@ struct evutil_addrinfo;
int evutil_getaddrinfo(const char *nodename, const char *servname,
const struct evutil_addrinfo *hints_in, struct evutil_addrinfo **res);
/* Release storage allocated by evutil_getaddrinfo or evdns_getaddrinfo. */
/** Release storage allocated by evutil_getaddrinfo or evdns_getaddrinfo. */
void evutil_freeaddrinfo(struct evutil_addrinfo *ai);
const char *evutil_gai_strerror(int err);
/* Generate n bytes of secure pseudorandom data, and store them in buf.
/** Generate n bytes of secure pseudorandom data, and store them in buf.
*
* By default, Libevent uses an ARC4-based random number generator, seeded
* using the platform's entropy source (/dev/urandom on Unix-like systems;