mirror of
https://github.com/libevent/libevent.git
synced 2025-01-09 00:56:20 +08:00
Revise the event/evbuffer/bufferevent doxygen for clarity and accuracy
This commit is contained in:
parent
e7fe92709e
commit
2888faccd1
11
Doxyfile
11
Doxyfile
@ -45,6 +45,15 @@ OPTIMIZE_OUTPUT_FOR_C = YES
|
|||||||
|
|
||||||
SORT_BRIEF_DOCS = 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
|
# configuration options related to the input files
|
||||||
#---------------------------------------------------------------------------
|
#---------------------------------------------------------------------------
|
||||||
@ -226,7 +235,7 @@ INCLUDE_FILE_PATTERNS =
|
|||||||
# undefined via #undef or recursively expanded use the := operator
|
# undefined via #undef or recursively expanded use the := operator
|
||||||
# instead of 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
|
# 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.
|
# this tag can be used to specify a list of macro names that should be expanded.
|
||||||
|
10
evdns.h
10
evdns.h
@ -27,6 +27,16 @@
|
|||||||
#ifndef _EVDNS_H_
|
#ifndef _EVDNS_H_
|
||||||
#define _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 <event.h>
|
||||||
#include <event2/dns.h>
|
#include <event2/dns.h>
|
||||||
#include <event2/dns_compat.h>
|
#include <event2/dns_compat.h>
|
||||||
|
133
event.h
133
event.h
@ -27,135 +27,14 @@
|
|||||||
#ifndef _EVENT_H_
|
#ifndef _EVENT_H_
|
||||||
#define _EVENT_H_
|
#define _EVENT_H_
|
||||||
|
|
||||||
/** @mainpage
|
/** @file event.h
|
||||||
|
|
||||||
@section intro Introduction
|
A library for writing event-driven network servers.
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
|
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
|
#ifdef __cplusplus
|
||||||
|
10
evhttp.h
10
evhttp.h
@ -27,6 +27,16 @@
|
|||||||
#ifndef _EVHTTP_H_
|
#ifndef _EVHTTP_H_
|
||||||
#define _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 <event.h>
|
||||||
#include <event2/http.h>
|
#include <event2/http.h>
|
||||||
#include <event2/http_struct.h>
|
#include <event2/http_struct.h>
|
||||||
|
10
evrpc.h
10
evrpc.h
@ -27,6 +27,16 @@
|
|||||||
#ifndef _EVRPC_H_
|
#ifndef _EVRPC_H_
|
||||||
#define _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 <event.h>
|
||||||
#include <event2/rpc.h>
|
#include <event2/rpc.h>
|
||||||
#include <event2/rpc_struct.h>
|
#include <event2/rpc_struct.h>
|
||||||
|
8
evutil.h
8
evutil.h
@ -26,6 +26,14 @@
|
|||||||
#ifndef _EVUTIL_H_
|
#ifndef _EVUTIL_H_
|
||||||
#define _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>
|
#include <event2/util.h>
|
||||||
|
|
||||||
#endif /* _EVUTIL_H_ */
|
#endif /* _EVUTIL_H_ */
|
||||||
|
@ -26,20 +26,22 @@
|
|||||||
#ifndef _EVENT2_BUFFER_H_
|
#ifndef _EVENT2_BUFFER_H_
|
||||||
#define _EVENT2_BUFFER_H_
|
#define _EVENT2_BUFFER_H_
|
||||||
|
|
||||||
/** @file buffer.h
|
/** @file event2/buffer.h
|
||||||
|
|
||||||
Functions for buffering data for network sending or receiving.
|
Functions for buffering data for network sending or receiving.
|
||||||
|
|
||||||
An evbuffer can be used for preparing data before sending it to
|
An evbuffer can be used for preparing data before sending it to
|
||||||
the network or conversely for reading data from the network.
|
the network or conversely for reading data from the network.
|
||||||
Evbuffers try to avoid memory copies as much as possible. As a
|
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.
|
incurring the overhead of copying the data.
|
||||||
|
|
||||||
A new evbuffer can be allocated with evbuffer_new(), and can be
|
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
|
- 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
|
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
|
if you use them, you will wind up with fragmented memory in your
|
||||||
buffer.
|
buffer.
|
||||||
|
|
||||||
As the contents of an evbuffer can be stored into multiple different
|
- For high-performance code, you may want to avoid copying data into and out
|
||||||
memory blocks, it cannot be accessed directly. Instead, evbuffer_pullup()
|
of buffers. You can skip the copy step by using
|
||||||
can be used to force a specified number of bytes to be continuous. This
|
evbuffer_reserve_space()/evbuffer_commit_space() when writing into a
|
||||||
will cause memory reallocation and memory copies if the data is split
|
buffer, and evbuffer_peek() when reading.
|
||||||
across multiple blocks.
|
|
||||||
|
|
||||||
|
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
|
#ifdef __cplusplus
|
||||||
@ -75,12 +86,25 @@ extern "C" {
|
|||||||
#endif
|
#endif
|
||||||
#include <event2/util.h>
|
#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
|
@see event2/event.h for more information
|
||||||
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
|
struct evbuffer
|
||||||
modify these values except with evbuffer_ptr_set.
|
#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 {
|
struct evbuffer_ptr {
|
||||||
ev_ssize_t pos;
|
ev_ssize_t pos;
|
||||||
@ -118,7 +142,6 @@ struct evbuffer_iovec {
|
|||||||
*/
|
*/
|
||||||
struct evbuffer *evbuffer_new(void);
|
struct evbuffer *evbuffer_new(void);
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
Deallocate storage for an evbuffer.
|
Deallocate storage for an evbuffer.
|
||||||
|
|
||||||
@ -153,10 +176,10 @@ void evbuffer_lock(struct evbuffer *buf);
|
|||||||
void evbuffer_unlock(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
|
@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);
|
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);
|
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.
|
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
|
@param datlen the new minimum length requirement
|
||||||
@return 0 if successful, or -1 if an error occurred
|
@return 0 if successful, or -1 if an error occurred
|
||||||
*/
|
*/
|
||||||
int evbuffer_expand(struct evbuffer *buf, size_t datlen);
|
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
|
be arbitrarily written to by a user. The space does not become
|
||||||
available for reading until it has been committed with
|
available for reading until it has been committed with
|
||||||
evbuffer_commit_space().
|
evbuffer_commit_space().
|
||||||
|
|
||||||
The space is made available as one or more extents, represented by
|
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
|
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.
|
function more efficient.
|
||||||
|
|
||||||
Multiple subsequent calls to this function will make the same space
|
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.
|
NOTE: The code currently does not ever use more than two extents.
|
||||||
This may change in future versions.
|
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
|
@param size how much space to make available, at minimum. The
|
||||||
total length of the extents may be greater than the requested
|
total length of the extents may be greater than the requested
|
||||||
length.
|
length.
|
||||||
@param vec an array of one or more evbuffer_iovec structures to
|
@param vec an array of one or more evbuffer_iovec structures to
|
||||||
hold pointers to the reserved extents of memory.
|
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.
|
@return the number of provided extents, or -1 on error.
|
||||||
@see evbuffer_commit_space
|
@see evbuffer_commit_space()
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
evbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size,
|
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.
|
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.
|
has been added to the buffer since the space was reserved.
|
||||||
|
|
||||||
If you want to commit less data than you got reserved space for,
|
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
|
modify the iov_len pointer of the appropriate extent to a smaller
|
||||||
that you may have received more space than you requested if it was
|
value. Note that you may have received more space than you
|
||||||
available!
|
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 vec one or two extents returned by evbuffer_reserve_space.
|
||||||
@param n_vecs the number of extents.
|
@param n_vecs the number of extents.
|
||||||
@return 0 on success, -1 on error
|
@return 0 on success, -1 on error
|
||||||
@see evbuffer_reserve_space
|
@see evbuffer_reserve_space()
|
||||||
*/
|
*/
|
||||||
int evbuffer_commit_space(struct evbuffer *buf,
|
int evbuffer_commit_space(struct evbuffer *buf,
|
||||||
struct evbuffer_iovec *vec, int n_vecs);
|
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.
|
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 data pointer to the beginning of the data buffer
|
||||||
@param datlen the number of bytes to be copied from the data buffer
|
@param datlen the number of bytes to be copied from the data buffer
|
||||||
@return 0 on success, -1 on failure.
|
@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 data the destination buffer to store the result
|
||||||
@param datlen the maximum size of the destination buffer
|
@param datlen the maximum size of the destination buffer
|
||||||
@return the number of bytes read, or -1 if we can't drain the 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);
|
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
|
If more bytes are requested than are available in the evbuffer, we
|
||||||
@param data the destination buffer to store the result
|
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
|
@param datlen the maximum size of the destination buffer
|
||||||
@return the number of bytes read, or -1 if we can't drain the 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);
|
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
|
Read data from an evbuffer into another evbuffer, draining
|
||||||
the bytes from the src buffer read. This function avoids memcpy
|
the bytes from the source buffer. This function avoids copy
|
||||||
as possible.
|
operations to the extent possible.
|
||||||
|
|
||||||
@param src the event buffer to be read from
|
If more bytes are requested than are available in src, the src
|
||||||
@param dst the destination event buffer to store the result into
|
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
|
@param datlen the maximum numbers of bytes to transfer
|
||||||
@return the number of bytes read
|
@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.
|
/** Used to tell evbuffer_readln what kind of line-ending to look for.
|
||||||
*/
|
*/
|
||||||
enum evbuffer_eol_style {
|
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,
|
EVBUFFER_EOL_ANY,
|
||||||
/** An EOL is an LF, optionally preceded by a CR. This style is
|
/** An EOL is an LF, optionally preceded by a CR. This style is
|
||||||
* most useful for implementing text-based internet protocols. */
|
* 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
|
* 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
|
* 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);
|
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
|
This is a destructive add. The data from one buffer moves into
|
||||||
the other buffer. However, no unnecessary memory copies occur.
|
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 outbuf the output buffer
|
||||||
@param inbuf the input buffer
|
@param inbuf the input buffer
|
||||||
@return 0 if successful, or -1 if an error occurred
|
@return 0 if successful, or -1 if an error occurred
|
||||||
|
|
||||||
|
@see evbuffer_remove_buffer()
|
||||||
*/
|
*/
|
||||||
int evbuffer_add_buffer(struct evbuffer *outbuf, struct evbuffer *inbuf);
|
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,
|
typedef void (*evbuffer_ref_cleanup_cb)(const void *data,
|
||||||
size_t datalen, void *extra);
|
size_t datalen, void *extra);
|
||||||
|
|
||||||
@ -348,44 +396,48 @@ typedef void (*evbuffer_ref_cleanup_cb)(const void *data,
|
|||||||
@param data the memory to reference
|
@param data the memory to reference
|
||||||
@param datlen how memory to reference
|
@param datlen how memory to reference
|
||||||
@param cleanupfn callback to be invoked when the memory is no longer
|
@param cleanupfn callback to be invoked when the memory is no longer
|
||||||
referenced
|
referenced by this evbuffer.
|
||||||
@param extra optional argument to the cleanup callback
|
@param cleanupfn_arg optional argument to the cleanup callback
|
||||||
@return 0 if successful, or -1 if an error occurred
|
@return 0 if successful, or -1 if an error occurred
|
||||||
*/
|
*/
|
||||||
int evbuffer_add_reference(struct evbuffer *outbuf,
|
int evbuffer_add_reference(struct evbuffer *outbuf,
|
||||||
const void *data, size_t datlen,
|
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
|
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
|
The function owns the resulting file descriptor and will close it
|
||||||
when finished transferring data.
|
when finished transferring data.
|
||||||
|
|
||||||
The results of using evbuffer_remove() or evbuffer_pullup() are
|
The results of using evbuffer_remove() or evbuffer_pullup() on
|
||||||
undefined.
|
evbuffers whose data was added using this function are undefined.
|
||||||
|
|
||||||
@param outbuf the output buffer
|
@param outbuf the output buffer
|
||||||
@param fd the file descriptor
|
@param fd the file descriptor
|
||||||
@param off the offset from which to read data
|
@param offset the offset from which to read data
|
||||||
@param length how much data to read
|
@param length how much data to read
|
||||||
@return 0 if successful, or -1 if an error occurred
|
@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);
|
ev_off_t length);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
Append a formatted string to the end of an evbuffer.
|
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 buf the evbuffer that will be appended to
|
||||||
@param fmt a format string
|
@param fmt a format string
|
||||||
@param ... arguments that will be passed to printf(3)
|
@param ... arguments that will be passed to printf(3)
|
||||||
@return The number of bytes added if successful, or -1 if an error occurred.
|
@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, ...)
|
int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...)
|
||||||
#ifdef __GNUC__
|
#ifdef __GNUC__
|
||||||
@ -393,7 +445,6 @@ int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...)
|
|||||||
#endif
|
#endif
|
||||||
;
|
;
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
Append a va_list formatted string to the end of an evbuffer.
|
Append a va_list formatted string to the end of an evbuffer.
|
||||||
|
|
||||||
@ -445,7 +496,7 @@ int evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd,
|
|||||||
/**
|
/**
|
||||||
Read from a file descriptor and store the result in an evbuffer.
|
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 fd the file descriptor to read from
|
||||||
@param howmuch the number of bytes to be read
|
@param howmuch the number of bytes to be read
|
||||||
@return the number of bytes read, or -1 if an error occurred
|
@return the number of bytes read, or -1 if an error occurred
|
||||||
@ -482,6 +533,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);
|
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 {
|
enum evbuffer_ptr_how {
|
||||||
/** Sets the pointer to the position; can be called on with an
|
/** Sets the pointer to the position; can be called on with an
|
||||||
uninitialized evbuffer_ptr. */
|
uninitialized evbuffer_ptr. */
|
||||||
@ -503,7 +558,7 @@ enum evbuffer_ptr_how {
|
|||||||
@returns 0 on success or -1 otherwise
|
@returns 0 on success or -1 otherwise
|
||||||
*/
|
*/
|
||||||
int
|
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);
|
size_t position, enum evbuffer_ptr_how how);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@ -524,14 +579,6 @@ struct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer,
|
|||||||
struct evbuffer_ptr *start, size_t *eol_len_out,
|
struct evbuffer_ptr *start, size_t *eol_len_out,
|
||||||
enum evbuffer_eol_style eol_style);
|
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
|
/** Function to peek at data inside an evbuffer without removing it or
|
||||||
copying it out.
|
copying it out.
|
||||||
|
|
||||||
@ -562,6 +609,21 @@ int evbuffer_peek(struct evbuffer *buffer, ev_ssize_t len,
|
|||||||
struct evbuffer_ptr *start_at,
|
struct evbuffer_ptr *start_at,
|
||||||
struct evbuffer_iovec *vec_out, int n_vec);
|
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
|
/** Type definition for a callback that is invoked whenever data is added or
|
||||||
removed from an evbuffer.
|
removed from an evbuffer.
|
||||||
|
|
||||||
@ -617,7 +679,10 @@ int evbuffer_remove_cb_entry(struct evbuffer *buffer,
|
|||||||
int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);
|
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
|
/** 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
|
#define EVBUFFER_CB_ENABLED 1
|
||||||
|
|
||||||
/** Change the flags that are set for a callback on a buffer by adding more.
|
/** Change the flags that are set for a callback on a buffer by adding more.
|
||||||
|
@ -27,7 +27,7 @@
|
|||||||
#ifndef _EVENT2_BUFFER_COMPAT_H_
|
#ifndef _EVENT2_BUFFER_COMPAT_H_
|
||||||
#define _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
|
Obsolete and deprecated versions of the functions in buffer.h: provided
|
||||||
only for backward compatibility.
|
only for backward compatibility.
|
||||||
|
@ -27,27 +27,51 @@
|
|||||||
#ifndef _EVENT2_BUFFEREVENT_H_
|
#ifndef _EVENT2_BUFFEREVENT_H_
|
||||||
#define _EVENT2_BUFFEREVENT_H_
|
#define _EVENT2_BUFFEREVENT_H_
|
||||||
|
|
||||||
/** @file bufferevent.h
|
/**
|
||||||
|
@file event2/bufferevent.h
|
||||||
|
|
||||||
Functions for buffering data for network sending or receiving. Bufferevents
|
Functions for buffering data for network sending or receiving. Bufferevents
|
||||||
are higher level than evbuffers: each has an underlying evbuffer for reading
|
are higher level than evbuffers: each has an underlying evbuffer for reading
|
||||||
and one for writing, and callbacks that are invoked under certain
|
and one for writing, and callbacks that are invoked under certain
|
||||||
circumstances.
|
circumstances.
|
||||||
|
|
||||||
Libevent provides an abstraction on top of the regular event callbacks.
|
A bufferevent provides input and output buffers that get filled and
|
||||||
This abstraction is called a buffered event. A buffered event provides
|
drained automatically. The user of a bufferevent no longer deals
|
||||||
input and output buffers that get filled and drained automatically. The
|
directly with the I/O, but instead is reading from input and writing
|
||||||
user of a buffered event no longer deals directly with the I/O, but
|
to output buffers.
|
||||||
instead is reading from input and writing to output buffers.
|
|
||||||
|
|
||||||
Once initialized, the bufferevent structure can be used repeatedly with
|
Once initialized, the bufferevent structure can be used repeatedly
|
||||||
bufferevent_enable() and bufferevent_disable().
|
with bufferevent_enable() and bufferevent_disable().
|
||||||
|
|
||||||
When read enabled the bufferevent will try to read from the file descriptor
|
When reading is enabled, the bufferevent will try to read from the
|
||||||
and call the read callback. The write callback is executed whenever the
|
file descriptor onto its input buffer, and and call the read callback.
|
||||||
output buffer is drained below the write low watermark, which is 0 by
|
When writing is enabled, the bufferevent will try to write data onto its
|
||||||
default.
|
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
|
#ifdef __cplusplus
|
||||||
@ -65,20 +89,36 @@ extern "C" {
|
|||||||
/* For int types. */
|
/* For int types. */
|
||||||
#include <event2/util.h>
|
#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_READING 0x01 /**< error encountered while reading */
|
||||||
#define BEV_EVENT_WRITING 0x02 /**< error encountered while writing */
|
#define BEV_EVENT_WRITING 0x02 /**< error encountered while writing */
|
||||||
#define BEV_EVENT_EOF 0x10 /**< eof file reached */
|
#define BEV_EVENT_EOF 0x10 /**< eof file reached */
|
||||||
#define BEV_EVENT_ERROR 0x20 /**< unrecoverable error encountered */
|
#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. */
|
#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 event_base;
|
||||||
struct evbuffer;
|
struct evbuffer;
|
||||||
struct sockaddr;
|
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
|
The read callback is triggered when new data arrives in the input
|
||||||
buffer and the amount of readable data exceed the low watermark
|
buffer and the amount of readable data exceed the low watermark
|
||||||
@ -88,14 +128,14 @@ struct sockaddr;
|
|||||||
exhausted or fell below its low watermark.
|
exhausted or fell below its low watermark.
|
||||||
|
|
||||||
@param bev the bufferevent that triggered the callback
|
@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);
|
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.
|
unrecoverable error was encountered.
|
||||||
|
|
||||||
@param bev the bufferevent for which the error condition was reached
|
@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,
|
and one of the following flags: BEV_EVENT_EOF, BEV_EVENT_ERROR,
|
||||||
BEV_EVENT_TIMEOUT, BEV_EVENT_CONNECTED.
|
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);
|
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).
|
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
|
It is safe to set the fd to -1, so long as you later
|
||||||
set it with bufferevent_setfd or bufferevent_socket_connect().
|
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
|
@return a pointer to a newly allocated bufferevent struct, or NULL if an
|
||||||
error occurred
|
error occurred
|
||||||
@see bufferevent_free()
|
@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);
|
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,
|
Launch a connect() attempt with a socket-based bufferevent.
|
||||||
the eventcb will be invoked with BEV_EVENT_CONNECTED set.
|
|
||||||
|
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
|
If the bufferevent does not already have a socket set, we allocate a new
|
||||||
socket here and make it nonblocking before we begin.
|
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
|
may block while it waits for a DNS response. This is probably not
|
||||||
what you want.
|
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);
|
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);
|
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
|
A bufferevent's timeout will fire the first time that the indicated
|
||||||
amount of time has elapsed since a successful read or write operation,
|
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
|
Triggers the bufferevent to produce more data if possible.
|
||||||
data if possible.
|
|
||||||
|
|
||||||
@param bufev the bufferevent object
|
@param bufev the bufferevent object
|
||||||
@param iotype either EV_READ or EV_WRITE or both.
|
@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);
|
enum bufferevent_flush_mode mode);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
Support for filtering input and output of bufferevents.
|
@name Filtering support
|
||||||
*/
|
|
||||||
|
|
||||||
|
@{
|
||||||
|
*/
|
||||||
/**
|
/**
|
||||||
Values that filters can return.
|
Values that filters can return.
|
||||||
*/
|
*/
|
||||||
@ -533,6 +576,7 @@ bufferevent_filter_new(struct bufferevent *underlying,
|
|||||||
int options,
|
int options,
|
||||||
void (*free_context)(void *),
|
void (*free_context)(void *),
|
||||||
void *ctx);
|
void *ctx);
|
||||||
|
/**@}*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
Allocate a pair of linked bufferevents. The bufferevents behave as would
|
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). */
|
/** Remove 'bev' from its current rate-limit group (if any). */
|
||||||
int bufferevent_remove_from_rate_limit_group(struct bufferevent *bev);
|
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.
|
Return the current read or write bucket size for a bufferevent.
|
||||||
If it is not configured with a per-bufferevent ratelimit, return
|
If it is not configured with a per-bufferevent ratelimit, return
|
||||||
EV_SSIZE_MAX. This function does not inspect the group limit, if any.
|
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
|
Note that it can return a negative value if the bufferevent has been
|
||||||
made to read or write more than its limit.
|
made to read or write more than its limit.
|
||||||
|
|
||||||
|
@{
|
||||||
*/
|
*/
|
||||||
ev_ssize_t bufferevent_get_read_limit(struct bufferevent *bev);
|
ev_ssize_t bufferevent_get_read_limit(struct bufferevent *bev);
|
||||||
ev_ssize_t bufferevent_get_write_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_read(struct bufferevent *bev);
|
||||||
ev_ssize_t bufferevent_get_max_to_write(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
|
Return the read or write bucket size for a bufferevent rate limit
|
||||||
group. Note that it can return a negative value if bufferevents in
|
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.
|
the group have been made to read or write more than their limits.
|
||||||
|
|
||||||
|
@{
|
||||||
*/
|
*/
|
||||||
ev_ssize_t bufferevent_rate_limit_group_get_read_limit(
|
ev_ssize_t bufferevent_rate_limit_group_get_read_limit(
|
||||||
struct bufferevent_rate_limit_group *);
|
struct bufferevent_rate_limit_group *);
|
||||||
@ -707,8 +757,9 @@ ev_ssize_t bufferevent_rate_limit_group_get_write_limit(
|
|||||||
struct bufferevent_rate_limit_group *);
|
struct bufferevent_rate_limit_group *);
|
||||||
/*@}*/
|
/*@}*/
|
||||||
|
|
||||||
/*@{*/
|
|
||||||
/**
|
/**
|
||||||
|
@name Rate limit manipulation
|
||||||
|
|
||||||
Subtract a number of bytes from a bufferevent's read or write bucket.
|
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 decrement value can be negative, if you want to manually refill
|
||||||
the bucket. If the change puts the bucket above or below zero, the
|
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.
|
group, if any.
|
||||||
|
|
||||||
Returns 0 on success, -1 on internal error.
|
Returns 0 on success, -1 on internal error.
|
||||||
|
|
||||||
|
@{
|
||||||
*/
|
*/
|
||||||
int bufferevent_decrement_read_limit(struct bufferevent *bev, ev_ssize_t decr);
|
int bufferevent_decrement_read_limit(struct bufferevent *bev, ev_ssize_t decr);
|
||||||
int bufferevent_decrement_write_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
|
Subtract a number of bytes from a bufferevent rate-limiting group's
|
||||||
read or write bucket. The decrement value can be negative, if you
|
read or write bucket. The decrement value can be negative, if you
|
||||||
want to manually refill the bucket. If the change puts the bucket
|
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.
|
suspend reading writing as appropriate.
|
||||||
|
|
||||||
Returns 0 on success, -1 on internal error.
|
Returns 0 on success, -1 on internal error.
|
||||||
|
|
||||||
|
@{
|
||||||
*/
|
*/
|
||||||
int bufferevent_rate_limit_group_decrement_read(
|
int bufferevent_rate_limit_group_decrement_read(
|
||||||
struct bufferevent_rate_limit_group *, ev_ssize_t);
|
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
|
* ever read on grp, and the variable pointed to by total_written_out to the
|
||||||
* total number of bytes ever written on grp. */
|
* total number of bytes ever written on grp. */
|
||||||
void bufferevent_rate_limit_group_get_totals(
|
void bufferevent_rate_limit_group_get_totals(
|
||||||
struct bufferevent_rate_limit_group *grp,
|
struct bufferevent_rate_limit_group *grp,
|
||||||
ev_uint64_t *total_read_out, ev_uint64_t *total_written_out);
|
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(). */
|
* bufferevent_rate_limit_group_reset_totals(). */
|
||||||
void
|
void
|
||||||
bufferevent_rate_limit_group_reset_totals(
|
bufferevent_rate_limit_group_reset_totals(
|
||||||
|
@ -54,6 +54,10 @@
|
|||||||
If multiple bases are in use, bufferevent_base_set() must be called before
|
If multiple bases are in use, bufferevent_base_set() must be called before
|
||||||
enabling the bufferevent for the first time.
|
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.
|
@param fd the file descriptor from which data is read and written to.
|
||||||
This file descriptor is not allowed to be a pipe(2).
|
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
|
@param readcb callback to invoke when there is data to be read, or NULL if
|
||||||
|
@ -26,7 +26,7 @@
|
|||||||
#ifndef _EVENT2_BUFFEREVENT_SSL_H_
|
#ifndef _EVENT2_BUFFEREVENT_SSL_H_
|
||||||
#define _EVENT2_BUFFEREVENT_SSL_H_
|
#define _EVENT2_BUFFEREVENT_SSL_H_
|
||||||
|
|
||||||
/** @file bufferevent_ssl.h
|
/** @file event2/bufferevent_ssl.h
|
||||||
|
|
||||||
OpenSSL support for bufferevents.
|
OpenSSL support for bufferevents.
|
||||||
*/
|
*/
|
||||||
@ -39,15 +39,31 @@
|
|||||||
extern "C" {
|
extern "C" {
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
|
/* This is what openssl's SSL objects are underneath. */
|
||||||
struct ssl_st;
|
struct ssl_st;
|
||||||
|
|
||||||
|
/**
|
||||||
|
The state of an SSL object to be used when creating a new
|
||||||
|
SSL bufferevent.
|
||||||
|
*/
|
||||||
enum bufferevent_ssl_state {
|
enum bufferevent_ssl_state {
|
||||||
BUFFEREVENT_SSL_OPEN = 0,
|
BUFFEREVENT_SSL_OPEN = 0,
|
||||||
BUFFEREVENT_SSL_CONNECTING = 1,
|
BUFFEREVENT_SSL_CONNECTING = 1,
|
||||||
BUFFEREVENT_SSL_ACCEPTING = 2
|
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 *
|
struct bufferevent *
|
||||||
bufferevent_openssl_filter_new(struct event_base *base,
|
bufferevent_openssl_filter_new(struct event_base *base,
|
||||||
struct bufferevent *underlying,
|
struct bufferevent *underlying,
|
||||||
@ -55,6 +71,16 @@ bufferevent_openssl_filter_new(struct event_base *base,
|
|||||||
enum bufferevent_ssl_state state,
|
enum bufferevent_ssl_state state,
|
||||||
int options);
|
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 *
|
struct bufferevent *
|
||||||
bufferevent_openssl_socket_new(struct event_base *base,
|
bufferevent_openssl_socket_new(struct event_base *base,
|
||||||
evutil_socket_t fd,
|
evutil_socket_t fd,
|
||||||
@ -62,11 +88,14 @@ bufferevent_openssl_socket_new(struct event_base *base,
|
|||||||
enum bufferevent_ssl_state state,
|
enum bufferevent_ssl_state state,
|
||||||
int options);
|
int options);
|
||||||
|
|
||||||
|
/** Return the underlying openssl SSL * object for an SSL bufferevent. */
|
||||||
struct ssl_st *
|
struct ssl_st *
|
||||||
bufferevent_openssl_get_ssl(struct bufferevent *bufev);
|
bufferevent_openssl_get_ssl(struct bufferevent *bufev);
|
||||||
|
|
||||||
|
/** Tells a bufferevent to begin SSL renegotiation. */
|
||||||
int bufferevent_ssl_renegotiate(struct bufferevent *bev);
|
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);
|
unsigned long bufferevent_get_openssl_error(struct bufferevent *bev);
|
||||||
|
|
||||||
#endif
|
#endif
|
||||||
|
@ -27,11 +27,14 @@
|
|||||||
#ifndef _EVENT2_BUFFEREVENT_STRUCT_H_
|
#ifndef _EVENT2_BUFFEREVENT_STRUCT_H_
|
||||||
#define _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
|
Data structures for bufferevents. Using these structures may hurt forward
|
||||||
compatibility with later versions of Libevent: be careful!
|
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
|
#ifdef __cplusplus
|
||||||
|
@ -47,7 +47,7 @@
|
|||||||
* the source verbatim in their source distributions)
|
* the source verbatim in their source distributions)
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/** @file dns.h
|
/** @file event2/dns.h
|
||||||
*
|
*
|
||||||
* Welcome, gentle reader
|
* Welcome, gentle reader
|
||||||
*
|
*
|
||||||
|
@ -27,11 +27,12 @@
|
|||||||
#ifndef _EVENT2_DNS_COMPAT_H_
|
#ifndef _EVENT2_DNS_COMPAT_H_
|
||||||
#define _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
|
Potentially non-threadsafe versions of the functions in dns.h: provided
|
||||||
only for backwards compatibility.
|
only for backwards compatibility.
|
||||||
|
|
||||||
|
|
||||||
*/
|
*/
|
||||||
|
|
||||||
#ifdef __cplusplus
|
#ifdef __cplusplus
|
||||||
|
@ -27,7 +27,7 @@
|
|||||||
#ifndef _EVENT2_DNS_STRUCT_H_
|
#ifndef _EVENT2_DNS_STRUCT_H_
|
||||||
#define _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
|
Data structures for dns. Using these structures may hurt forward
|
||||||
compatibility with later versions of Libevent: be careful!
|
compatibility with later versions of Libevent: be careful!
|
||||||
|
File diff suppressed because it is too large
Load Diff
@ -27,11 +27,19 @@
|
|||||||
#ifndef _EVENT2_EVENT_COMPAT_H_
|
#ifndef _EVENT2_EVENT_COMPAT_H_
|
||||||
#define _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
|
Potentially non-threadsafe versions of the functions in event.h: provided
|
||||||
only for backwards compatibility.
|
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
|
#ifdef __cplusplus
|
||||||
@ -67,31 +75,26 @@ struct event_base *event_init(void);
|
|||||||
/**
|
/**
|
||||||
Loop to process events.
|
Loop to process events.
|
||||||
|
|
||||||
In order to process events, an application needs to call
|
Like event_base_dispatch(), but uses the "current" base.
|
||||||
event_dispatch(). This function only returns on error, and should
|
|
||||||
replace the event core of the application program.
|
|
||||||
|
|
||||||
@deprecated This function is deprecated because it is easily confused by
|
@deprecated This function is deprecated because it is easily confused by
|
||||||
multiple calls to event_init(), and because it is not safe for
|
multiple calls to event_init(), and because it is not safe for
|
||||||
multithreaded use. The replacement is event_base_dispatch().
|
multithreaded use. The replacement is event_base_dispatch().
|
||||||
|
|
||||||
@see event_base_dispatch()
|
@see event_base_dispatch(), event_init()
|
||||||
*/
|
*/
|
||||||
int event_dispatch(void);
|
int event_dispatch(void);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
Handle events.
|
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
|
@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
|
the last call to event_init, and is therefore not safe for multithreaded
|
||||||
use. The replacement is event_base_loop().
|
use. The replacement is event_base_loop().
|
||||||
|
|
||||||
@param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK
|
@see event_base_loop(), event_init()
|
||||||
@return 0 if successful, -1 if an error occurred, or 1 if no events were
|
|
||||||
registered.
|
|
||||||
@see event_base_loopexit(), event_base_loop()
|
|
||||||
*/
|
*/
|
||||||
int event_loop(int);
|
int event_loop(int);
|
||||||
|
|
||||||
@ -99,19 +102,14 @@ int event_loop(int);
|
|||||||
/**
|
/**
|
||||||
Exit the event loop after the specified time.
|
Exit the event loop after the specified time.
|
||||||
|
|
||||||
The next event_loop() iteration after the given timer expires will
|
This function behaves like event_base_loopexit(), except that it uses the
|
||||||
complete normally (handling all queued events) then exit without
|
"current" base.
|
||||||
blocking for events again.
|
|
||||||
|
|
||||||
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
|
@see event_init, event_base_loopexit()
|
||||||
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()
|
|
||||||
*/
|
*/
|
||||||
int event_loopexit(const struct timeval *);
|
int event_loopexit(const struct timeval *);
|
||||||
|
|
||||||
@ -119,42 +117,25 @@ int event_loopexit(const struct timeval *);
|
|||||||
/**
|
/**
|
||||||
Abort the active event_loop() immediately.
|
Abort the active event_loop() immediately.
|
||||||
|
|
||||||
event_loop() will abort the loop after the next event is completed;
|
This function behaves like event_base_loopbreakt(), except that it uses the
|
||||||
event_loopbreak() is typically invoked from this event's callback.
|
"current" base.
|
||||||
This behavior is analogous to the "break;" statement.
|
|
||||||
|
|
||||||
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
|
@see event_base_loopbreak(), event_init()
|
||||||
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()
|
|
||||||
*/
|
*/
|
||||||
int event_loopbreak(void);
|
int event_loopbreak(void);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
Schedule a one-time event to occur.
|
Schedule a one-time event to occur.
|
||||||
|
|
||||||
The function event_once() is similar to event_set(). However, it schedules
|
@deprecated This function is obsolete, and has been replaced by
|
||||||
a callback to be called exactly once and does not require the caller to
|
event_base_once(). Its use is deprecated because it relies on the
|
||||||
prepare an event structure.
|
"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_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()
|
|
||||||
|
|
||||||
|
@see event_base_once()
|
||||||
*/
|
*/
|
||||||
int event_once(evutil_socket_t , short,
|
int event_once(evutil_socket_t , short,
|
||||||
void (*)(evutil_socket_t, short, void *), void *, const struct timeval *);
|
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.
|
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
|
@see event_base_get_method()
|
||||||
multiple calls to event_init(), and because it is not safe for
|
|
||||||
multithreaded use. The replacement is event_base_get_method().
|
|
||||||
*/
|
*/
|
||||||
const char *event_get_method(void);
|
const char *event_get_method(void);
|
||||||
|
|
||||||
@ -175,61 +156,19 @@ const char *event_get_method(void);
|
|||||||
/**
|
/**
|
||||||
Set the number of different event priorities.
|
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
|
@deprecated This function is deprecated because it is easily confused by
|
||||||
multiple calls to event_init(), and because it is not safe for
|
multiple calls to event_init(), and because it is not safe for
|
||||||
multithreaded use. The replacement is event_base_priority_init().
|
multithreaded use. The replacement is event_base_priority_init().
|
||||||
|
|
||||||
@param npriorities the maximum number of priorities
|
@see event_base_priority_init()
|
||||||
@return 0 if successful, or -1 if an error occurred
|
|
||||||
@see event_base_priority_init(), event_priority_set()
|
|
||||||
|
|
||||||
*/
|
*/
|
||||||
int event_priority_init(int);
|
int event_priority_init(int);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
Prepare an event structure to be added.
|
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
|
@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.
|
Use event_assign() or event_new() instead.
|
||||||
*/
|
*/
|
||||||
void event_set(struct event *, evutil_socket_t, short, void (*)(evutil_socket_t, short, void *), void *);
|
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.
|
@name timeout_* macros
|
||||||
*
|
|
||||||
* @param ev the event struct to be disabled
|
@deprecated These macros are deprecated because their naming is inconsisten
|
||||||
* @param tv the timeout value, in seconds
|
with the rest of Libevent. Use the evtimer_* macros instead.
|
||||||
*
|
@{
|
||||||
* @deprecated This macro is deprecated because its naming is inconsistent.
|
|
||||||
* The recommend macro is evtimer_add().
|
|
||||||
*/
|
*/
|
||||||
#define timeout_add(ev, tv) event_add((ev), (tv))
|
#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))
|
#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)
|
#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))
|
#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)
|
#define timeout_initialized(ev) event_initialized(ev)
|
||||||
|
/**@}*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@deprecated This macro is deprecated because its naming is inconsistent.
|
@name signal_* macros
|
||||||
The recommend macro is evsignal_add().
|
|
||||||
*/
|
@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))
|
#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) \
|
#define signal_set(ev, x, cb, arg) \
|
||||||
event_set((ev), (x), EV_SIGNAL|EV_PERSIST, (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)
|
#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))
|
#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)
|
#define signal_initialized(ev) event_initialized(ev)
|
||||||
|
/**@}*/
|
||||||
|
|
||||||
#ifndef EVENT_FD
|
#ifndef EVENT_FD
|
||||||
/* These macros are obsolete; use event_get_fd and event_get_signal instead. */
|
/* These macros are obsolete; use event_get_fd and event_get_signal instead. */
|
||||||
|
@ -27,11 +27,13 @@
|
|||||||
#ifndef _EVENT2_EVENT_STRUCT_H_
|
#ifndef _EVENT2_EVENT_STRUCT_H_
|
||||||
#define _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
|
Structures used by event.h. Using these structures directly WILL harm
|
||||||
forward compatibility: be careful!
|
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
|
#ifdef __cplusplus
|
||||||
|
@ -38,7 +38,7 @@ extern "C" {
|
|||||||
struct evbuffer;
|
struct evbuffer;
|
||||||
struct event_base;
|
struct event_base;
|
||||||
|
|
||||||
/** @file http.h
|
/** @file event2/http.h
|
||||||
*
|
*
|
||||||
* Basic support for HTTP serving.
|
* Basic support for HTTP serving.
|
||||||
*
|
*
|
||||||
|
@ -27,7 +27,7 @@
|
|||||||
#ifndef _EVENT2_HTTP_COMPAT_H_
|
#ifndef _EVENT2_HTTP_COMPAT_H_
|
||||||
#define _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
|
Potentially non-threadsafe versions of the functions in http.h: provided
|
||||||
only for backwards compatibility.
|
only for backwards compatibility.
|
||||||
|
@ -27,7 +27,7 @@
|
|||||||
#ifndef _EVENT2_HTTP_STRUCT_H_
|
#ifndef _EVENT2_HTTP_STRUCT_H_
|
||||||
#define _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
|
Data structures for http. Using these structures may hurt forward
|
||||||
compatibility with later versions of Libevent: be careful!
|
compatibility with later versions of Libevent: be careful!
|
||||||
|
@ -27,7 +27,7 @@
|
|||||||
#ifndef _EVENT2_RPC_COMPAT_H_
|
#ifndef _EVENT2_RPC_COMPAT_H_
|
||||||
#define _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
|
Deprecated versions of the functions in rpc.h: provided only for
|
||||||
backwards compatibility.
|
backwards compatibility.
|
||||||
|
@ -31,7 +31,7 @@
|
|||||||
extern "C" {
|
extern "C" {
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
/** @file rpc_struct.h
|
/** @file event2/rpc_struct.h
|
||||||
|
|
||||||
Structures used by rpc.h. Using these structures directly may harm
|
Structures used by rpc.h. Using these structures directly may harm
|
||||||
forward compatibility: be careful!
|
forward compatibility: be careful!
|
||||||
|
@ -27,7 +27,7 @@
|
|||||||
#ifndef _EVENT2_TAG_H_
|
#ifndef _EVENT2_TAG_H_
|
||||||
#define _EVENT2_TAG_H_
|
#define _EVENT2_TAG_H_
|
||||||
|
|
||||||
/** @file tag.h
|
/** @file event2/tag.h
|
||||||
|
|
||||||
Helper functions for reading and writing tagged data onto buffers.
|
Helper functions for reading and writing tagged data onto buffers.
|
||||||
|
|
||||||
|
@ -27,13 +27,23 @@
|
|||||||
#ifndef _EVENT2_TAG_COMPAT_H_
|
#ifndef _EVENT2_TAG_COMPAT_H_
|
||||||
#define _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
|
Obsolete/deprecated functions from tag.h; provided only for backwards
|
||||||
compatibility.
|
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_int(evbuf, number) evtag_encode_int((evbuf), (number))
|
||||||
#define encode_int64(evbuf, number) evtag_encode_int64((evbuf), (number))
|
#define encode_int64(evbuf, number) evtag_encode_int64((evbuf), (number))
|
||||||
|
/**@}*/
|
||||||
|
|
||||||
#endif /* _EVENT2_TAG_H_ */
|
#endif /* _EVENT2_TAG_H_ */
|
||||||
|
@ -26,7 +26,7 @@
|
|||||||
#ifndef _EVENT2_THREAD_H_
|
#ifndef _EVENT2_THREAD_H_
|
||||||
#define _EVENT2_THREAD_H_
|
#define _EVENT2_THREAD_H_
|
||||||
|
|
||||||
/** @file thread.h
|
/** @file event2/thread.h
|
||||||
|
|
||||||
Functions for multi-threaded applications using Libevent.
|
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
|
_must_ be set up before an event_base is created if you want the base to
|
||||||
use them.
|
use them.
|
||||||
|
|
||||||
A multi-threaded application must provide locking functions to
|
Most programs will either be using Windows threads or Posix threads. You
|
||||||
Libevent via evthread_set_locking_callback(). Libevent will invoke
|
can configure Libevent to use one of these event_use_windows_threads() or
|
||||||
this callback whenever a lock needs to be acquired or released.
|
event_use_pthreads() respectively. If you're using another threading
|
||||||
|
library, you'll need to configure threading functions manually using
|
||||||
The total number of locks employed by Libevent can be determined
|
evthread_set_lock_callbacks() and evthread_set_condition_callbacks().
|
||||||
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().
|
|
||||||
|
|
||||||
*/
|
*/
|
||||||
|
|
||||||
@ -59,6 +52,11 @@ extern "C" {
|
|||||||
|
|
||||||
#include <event2/event-config.h>
|
#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
|
/** 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. */
|
* read-write lock, and we want to acquire or release the lock for writing. */
|
||||||
#define EVTHREAD_WRITE 0x04
|
#define EVTHREAD_WRITE 0x04
|
||||||
@ -69,11 +67,16 @@ extern "C" {
|
|||||||
* for the lock; if we can't get the lock immediately, we will instead
|
* for the lock; if we can't get the lock immediately, we will instead
|
||||||
* return nonzero from the locking callback. */
|
* return nonzero from the locking callback. */
|
||||||
#define EVTHREAD_TRY 0x10
|
#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
|
#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
|
/** 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
|
* 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. */
|
* 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
|
/* A read-write lock is one that allows multiple simultaneous readers, but
|
||||||
* where any one writer excludes all other writers and readers. */
|
* where any one writer excludes all other writers and readers. */
|
||||||
#define EVTHREAD_LOCKTYPE_READWRITE 2
|
#define EVTHREAD_LOCKTYPE_READWRITE 2
|
||||||
|
/**@}*/
|
||||||
|
|
||||||
/** This structure describes the interface a threading library uses for
|
/** 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.
|
* locking on this platform.
|
||||||
*/
|
*/
|
||||||
struct evthread_lock_callbacks {
|
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
|
* Note that if you're using Windows or the Pthreads threading library, you
|
||||||
* probably shouldn't call this function; instead, use
|
* 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(
|
int evthread_set_condition_callbacks(
|
||||||
const struct evthread_condition_callbacks *);
|
const struct evthread_condition_callbacks *);
|
||||||
@ -183,38 +187,45 @@ int evthread_set_condition_callbacks(
|
|||||||
void evthread_set_id_callback(
|
void evthread_set_id_callback(
|
||||||
unsigned long (*id_fn)(void));
|
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
|
/** 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);
|
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
|
#define EVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED 1
|
||||||
#endif
|
#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.
|
/** Sets up Libevent for use with Pthreads locking and thread ID functions.
|
||||||
Unavailable if Libevent is not build for use with pthreads. Requires
|
Unavailable if Libevent is not build for use with pthreads. Requires
|
||||||
libraries to link against Libevent_pthreads as well as Libevent.
|
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);
|
int evthread_use_pthreads(void);
|
||||||
|
/** Defined if Libevent was built with support for evthread_use_pthreads() */
|
||||||
#define EVTHREAD_USE_PTHREADS_IMPLEMENTED 1
|
#define EVTHREAD_USE_PTHREADS_IMPLEMENTED 1
|
||||||
|
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
/** Enable debugging wrappers around the current lock callbacks. If Libevent
|
/** Enable debugging wrappers around the current lock callbacks. If Libevent
|
||||||
* makes one of several common locking errors, exit with an assertion failure.
|
* 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);
|
void evthread_enable_lock_debuging(void);
|
||||||
|
|
||||||
#endif /* _EVENT_DISABLE_THREAD_SUPPORT */
|
#endif /* _EVENT_DISABLE_THREAD_SUPPORT */
|
||||||
|
|
||||||
struct event_base;
|
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.
|
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);
|
int evthread_make_base_notifiable(struct event_base *base);
|
||||||
|
|
||||||
|
@ -69,19 +69,39 @@ extern "C" {
|
|||||||
#include <sys/socket.h>
|
#include <sys/socket.h>
|
||||||
#endif
|
#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
|
* 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,
|
* 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
|
* your C headers are now over 10 years out of date. You should bug them to
|
||||||
* do something about this.)
|
* do something about this.)
|
||||||
*
|
*
|
||||||
* We define:
|
* 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.
|
* <dl>
|
||||||
* ev_int64_t, ev_int32_t, ev_int16_t, ev_int8_t -- signed integer
|
* <dt>ev_uint64_t, ev_uint32_t, ev_uint16_t, ev_uint8_t</dt>
|
||||||
* types of exactly 64, 32, 16, and 8 bits respectively.
|
* <dd>unsigned integer types of exactly 64, 32, 16, and 8 bits
|
||||||
* ev_uintptr_t, ev_intptr_t -- unsigned/signed integers large enough
|
* respectively.</dd>
|
||||||
* to hold a pointer without loss of bits.
|
* <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
|
#ifdef _EVENT_HAVE_UINT64_T
|
||||||
#define ev_uint64_t uint64_t
|
#define ev_uint64_t uint64_t
|
||||||
@ -95,6 +115,9 @@ extern "C" {
|
|||||||
#elif _EVENT_SIZEOF_LONG == 8
|
#elif _EVENT_SIZEOF_LONG == 8
|
||||||
#define ev_uint64_t unsigned long
|
#define ev_uint64_t unsigned long
|
||||||
#define ev_int64_t long
|
#define ev_int64_t long
|
||||||
|
#elif defined(_EVENT_IN_DOXYGEN)
|
||||||
|
#define ev_uint64_t ...
|
||||||
|
#define ev_int64_t ...
|
||||||
#else
|
#else
|
||||||
#error "No way to define ev_uint64_t"
|
#error "No way to define ev_uint64_t"
|
||||||
#endif
|
#endif
|
||||||
@ -111,6 +134,9 @@ extern "C" {
|
|||||||
#elif _EVENT_SIZEOF_INT == 4
|
#elif _EVENT_SIZEOF_INT == 4
|
||||||
#define ev_uint32_t unsigned int
|
#define ev_uint32_t unsigned int
|
||||||
#define ev_int32_t signed int
|
#define ev_int32_t signed int
|
||||||
|
#elif defined(_EVENT_IN_DOXYGEN)
|
||||||
|
#define ev_uint32_t ...
|
||||||
|
#define ev_int32_t ...
|
||||||
#else
|
#else
|
||||||
#error "No way to define ev_uint32_t"
|
#error "No way to define ev_uint32_t"
|
||||||
#endif
|
#endif
|
||||||
@ -127,6 +153,9 @@ extern "C" {
|
|||||||
#elif _EVENT_SIZEOF_SHORT == 2
|
#elif _EVENT_SIZEOF_SHORT == 2
|
||||||
#define ev_uint16_t unsigned short
|
#define ev_uint16_t unsigned short
|
||||||
#define ev_int16_t signed short
|
#define ev_int16_t signed short
|
||||||
|
#elif defined(_EVENT_IN_DOXYGEN)
|
||||||
|
#define ev_uint16_t ...
|
||||||
|
#define ev_int16_t ...
|
||||||
#else
|
#else
|
||||||
#error "No way to define ev_uint16_t"
|
#error "No way to define ev_uint16_t"
|
||||||
#endif
|
#endif
|
||||||
@ -134,16 +163,14 @@ extern "C" {
|
|||||||
#ifdef _EVENT_HAVE_UINT8_T
|
#ifdef _EVENT_HAVE_UINT8_T
|
||||||
#define ev_uint8_t uint8_t
|
#define ev_uint8_t uint8_t
|
||||||
#define ev_int8_t int8_t
|
#define ev_int8_t int8_t
|
||||||
|
#elif defined(_EVENT_IN_DOXYGEN)
|
||||||
|
#define ev_uint8_t ...
|
||||||
|
#define ev_int8_t ...
|
||||||
#else
|
#else
|
||||||
#define ev_uint8_t unsigned char
|
#define ev_uint8_t unsigned char
|
||||||
#define ev_int8_t signed char
|
#define ev_int8_t signed char
|
||||||
#endif
|
#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
|
#ifdef _EVENT_HAVE_UINTPTR_T
|
||||||
#define ev_uintptr_t uintptr_t
|
#define ev_uintptr_t uintptr_t
|
||||||
#define ev_intptr_t intptr_t
|
#define ev_intptr_t intptr_t
|
||||||
@ -153,6 +180,9 @@ extern "C" {
|
|||||||
#elif _EVENT_SIZEOF_VOID_P <= 8
|
#elif _EVENT_SIZEOF_VOID_P <= 8
|
||||||
#define ev_uintptr_t ev_uint64_t
|
#define ev_uintptr_t ev_uint64_t
|
||||||
#define ev_intptr_t ev_int64_t
|
#define ev_intptr_t ev_int64_t
|
||||||
|
#elif defined(_EVENT_IN_DOXYGEN)
|
||||||
|
#define ev_uintptr_t ...
|
||||||
|
#define ev_intptr_t ...
|
||||||
#else
|
#else
|
||||||
#error "No way to define ev_uintptr_t"
|
#error "No way to define ev_uintptr_t"
|
||||||
#endif
|
#endif
|
||||||
@ -168,6 +198,7 @@ extern "C" {
|
|||||||
#else
|
#else
|
||||||
#define ev_off_t off_t
|
#define ev_off_t off_t
|
||||||
#endif
|
#endif
|
||||||
|
/**@}*/
|
||||||
|
|
||||||
/* Limits for integer types.
|
/* Limits for integer types.
|
||||||
|
|
||||||
@ -176,6 +207,14 @@ extern "C" {
|
|||||||
- The platform does signed arithmetic in two's complement.
|
- 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_UINT64_MAX ((((ev_uint64_t)0xffffffffUL) << 32) | 0xffffffffUL)
|
||||||
#define EV_INT64_MAX ((((ev_int64_t) 0x7fffffffL) << 32) | 0xffffffffL)
|
#define EV_INT64_MAX ((((ev_int64_t) 0x7fffffffL) << 32) | 0xffffffffL)
|
||||||
#define EV_INT64_MIN ((-EV_INT64_MAX) - 1)
|
#define EV_INT64_MIN ((-EV_INT64_MAX) - 1)
|
||||||
@ -188,18 +227,28 @@ extern "C" {
|
|||||||
#define EV_UINT8_MAX 255
|
#define EV_UINT8_MAX 255
|
||||||
#define EV_INT8_MAX 127
|
#define EV_INT8_MAX 127
|
||||||
#define EV_INT8_MIN ((-EV_INT8_MAX) - 1)
|
#define EV_INT8_MIN ((-EV_INT8_MAX) - 1)
|
||||||
|
/** @} */
|
||||||
|
|
||||||
|
/**
|
||||||
|
@name Limits for SIZE_T and SSIZE_T
|
||||||
|
|
||||||
|
@{
|
||||||
|
*/
|
||||||
#if _EVENT_SIZEOF_SIZE_T == 8
|
#if _EVENT_SIZEOF_SIZE_T == 8
|
||||||
#define EV_SIZE_MAX EV_UINT64_MAX
|
#define EV_SIZE_MAX EV_UINT64_MAX
|
||||||
#define EV_SSIZE_MAX EV_INT64_MAX
|
#define EV_SSIZE_MAX EV_INT64_MAX
|
||||||
#elif _EVENT_SIZEOF_SIZE_T == 4
|
#elif _EVENT_SIZEOF_SIZE_T == 4
|
||||||
#define EV_SIZE_MAX EV_UINT32_MAX
|
#define EV_SIZE_MAX EV_UINT32_MAX
|
||||||
#define EV_SSIZE_MAX EV_INT32_MAX
|
#define EV_SSIZE_MAX EV_INT32_MAX
|
||||||
|
#elif defined(_EVENT_IN_DOXYGEN)
|
||||||
|
#define EV_SIZE_MAX ...
|
||||||
|
#define EV_SSIZE_MAX ...
|
||||||
#else
|
#else
|
||||||
#error "No way to define SIZE_MAX"
|
#error "No way to define SIZE_MAX"
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
#define EV_SSIZE_MIN ((-EV_SSIZE_MAX) - 1)
|
#define EV_SSIZE_MIN ((-EV_SSIZE_MAX) - 1)
|
||||||
|
/**@}*/
|
||||||
|
|
||||||
#ifdef WIN32
|
#ifdef WIN32
|
||||||
#define ev_socklen_t int
|
#define ev_socklen_t int
|
||||||
@ -216,17 +265,20 @@ extern "C" {
|
|||||||
#endif
|
#endif
|
||||||
#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. */
|
* Windows, this is an intptr_t; elsewhere, it is an int. */
|
||||||
|
#ifdef WIN32
|
||||||
#define evutil_socket_t intptr_t
|
#define evutil_socket_t intptr_t
|
||||||
#else
|
#else
|
||||||
#define evutil_socket_t int
|
#define evutil_socket_t int
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
/** Create two new sockets that are connected to each other. On Unix, this
|
/** Create two new sockets that are connected to each other.
|
||||||
simply calls socketpair(). On Windows, it uses the loopback network
|
|
||||||
interface on 127.0.0.1, and only AF_INET,SOCK_STREAM are supported.
|
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
|
(This may fail on some Windows hosts where firewall software has cleverly
|
||||||
decided to keep 127.0.0.1 from talking to itself.)
|
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);
|
int evutil_make_socket_nonblocking(evutil_socket_t sock);
|
||||||
|
|
||||||
/** Do platform-specific operations on a listener socket to make sure that
|
/** Do platform-specific operations to make a listener socket reusable.
|
||||||
another program will be able to bind this address right after we've
|
|
||||||
closed the listener
|
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
|
@param sock The socket to make reusable
|
||||||
@return 0 on success, -1 on failure
|
@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);
|
int evutil_closesocket(evutil_socket_t sock);
|
||||||
#define EVUTIL_CLOSESOCKET(s) evutil_closesocket(s)
|
#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
|
#ifdef WIN32
|
||||||
/** Return the most recent socket error. Not idempotent on all platforms. */
|
/** 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);
|
int evutil_socket_geterror(evutil_socket_t sock);
|
||||||
/** Convert a socket error to a string. */
|
/** Convert a socket error to a string. */
|
||||||
const char *evutil_socket_error_to_string(int errcode);
|
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
|
#else
|
||||||
#define EVUTIL_SOCKET_ERROR() (errno)
|
#define EVUTIL_SOCKET_ERROR() (errno)
|
||||||
#define EVUTIL_SET_SOCKET_ERROR(errcode) \
|
#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))
|
#define evutil_socket_error_to_string(errcode) (strerror(errcode))
|
||||||
#endif
|
#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.
|
* for timeradd, timersub, timerclear, timercmp, and timerisset.
|
||||||
|
*
|
||||||
|
* @{
|
||||||
*/
|
*/
|
||||||
#ifdef _EVENT_HAVE_TIMERADD
|
#ifdef _EVENT_HAVE_TIMERADD
|
||||||
#define evutil_timeradd(tvp, uvp, vvp) timeradd((tvp), (uvp), (vvp))
|
#define evutil_timeradd(tvp, uvp, vvp) timeradd((tvp), (uvp), (vvp))
|
||||||
@ -324,6 +404,7 @@ const char *evutil_socket_error_to_string(int errcode);
|
|||||||
#else
|
#else
|
||||||
#define evutil_timerclear(tvp) (tvp)->tv_sec = (tvp)->tv_usec = 0
|
#define evutil_timerclear(tvp) (tvp)->tv_sec = (tvp)->tv_usec = 0
|
||||||
#endif
|
#endif
|
||||||
|
/**@}*/
|
||||||
|
|
||||||
/** Return true iff the tvp is related to uvp according to the relational
|
/** Return true iff the tvp is related to uvp according to the relational
|
||||||
* operator cmp. Recognized values for cmp are ==, <=, <, >=, and >. */
|
* 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)
|
#define evutil_timerisset(tvp) ((tvp)->tv_sec || (tvp)->tv_usec)
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
/* Replacement for offsetof on platforms that don't define it. */
|
/** Replacement for offsetof on platforms that don't define it. */
|
||||||
#ifdef offsetof
|
#ifdef offsetof
|
||||||
#define evutil_offsetof(type, field) offsetof(type, field)
|
#define evutil_offsetof(type, field) offsetof(type, field)
|
||||||
#else
|
#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. */
|
/** 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);
|
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
|
#ifdef _EVENT_HAVE_GETTIMEOFDAY
|
||||||
#define evutil_gettimeofday(tv, tz) gettimeofday((tv), (tz))
|
#define evutil_gettimeofday(tv, tz) gettimeofday((tv), (tz))
|
||||||
#else
|
#else
|
||||||
@ -365,6 +446,9 @@ int evutil_snprintf(char *buf, size_t buflen, const char *format, ...)
|
|||||||
__attribute__((format(printf, 3, 4)))
|
__attribute__((format(printf, 3, 4)))
|
||||||
#endif
|
#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);
|
int evutil_vsnprintf(char *buf, size_t buflen, const char *format, va_list ap);
|
||||||
|
|
||||||
/** Replacement for inet_ntop for platforms which lack it. */
|
/** 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);
|
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(). */
|
* if this system has no getaddrinfo(). */
|
||||||
#ifdef _EVENT_HAVE_STRUCT_ADDRINFO
|
#ifdef _EVENT_HAVE_STRUCT_ADDRINFO
|
||||||
#define evutil_addrinfo addrinfo
|
#define evutil_addrinfo addrinfo
|
||||||
#else
|
#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 {
|
struct evutil_addrinfo {
|
||||||
int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
|
int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
|
||||||
int ai_family; /* PF_xxx */
|
int ai_family; /* PF_xxx */
|
||||||
@ -428,6 +517,13 @@ struct evutil_addrinfo {
|
|||||||
struct evutil_addrinfo *ai_next; /* next structure in linked list */
|
struct evutil_addrinfo *ai_next; /* next structure in linked list */
|
||||||
};
|
};
|
||||||
#endif
|
#endif
|
||||||
|
/** @name evutil_getaddrinfo() error codes
|
||||||
|
|
||||||
|
These values are possible error codes for evutil_getaddrinfo() and
|
||||||
|
related functions.
|
||||||
|
|
||||||
|
@{
|
||||||
|
*/
|
||||||
#ifdef EAI_ADDRFAMILY
|
#ifdef EAI_ADDRFAMILY
|
||||||
#define EVUTIL_EAI_ADDRFAMILY EAI_ADDRFAMILY
|
#define EVUTIL_EAI_ADDRFAMILY EAI_ADDRFAMILY
|
||||||
#else
|
#else
|
||||||
@ -524,9 +620,11 @@ struct evutil_addrinfo {
|
|||||||
#else
|
#else
|
||||||
#define EVUTIL_AI_ADDRCONFIG 0x40000
|
#define EVUTIL_AI_ADDRCONFIG 0x40000
|
||||||
#endif
|
#endif
|
||||||
|
/**@}*/
|
||||||
|
|
||||||
struct evutil_addrinfo;
|
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.
|
* details, see RFC 3493, section 6.1.
|
||||||
*
|
*
|
||||||
* Limitations:
|
* Limitations:
|
||||||
@ -539,12 +637,12 @@ struct evutil_addrinfo;
|
|||||||
int evutil_getaddrinfo(const char *nodename, const char *servname,
|
int evutil_getaddrinfo(const char *nodename, const char *servname,
|
||||||
const struct evutil_addrinfo *hints_in, struct evutil_addrinfo **res);
|
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);
|
void evutil_freeaddrinfo(struct evutil_addrinfo *ai);
|
||||||
|
|
||||||
const char *evutil_gai_strerror(int err);
|
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
|
* By default, Libevent uses an ARC4-based random number generator, seeded
|
||||||
* using the platform's entropy source (/dev/urandom on Unix-like systems;
|
* using the platform's entropy source (/dev/urandom on Unix-like systems;
|
||||||
|
Loading…
x
Reference in New Issue
Block a user