Functions for buffering data for network sending or receiving. More...

#include <event2/event-config.h>
#include <event2/util.h>

Defines
#define	BEV_EVENT_CONNECTED 0x80
	connect operation finished.
#define	BEV_EVENT_EOF 0x10
	eof file reached
#define	BEV_EVENT_ERROR 0x20
	unrecoverable error encountered
#define	BEV_EVENT_READING 0x01
	error encountered while reading
#define	BEV_EVENT_TIMEOUT 0x40
	user specified timeout reached
#define	BEV_EVENT_WRITING 0x02
	error encountered while writing
#define	EV_RATE_LIMIT_MAX EV_SSIZE_MAX
	Maximum configurable rate- or burst-limit.
Typedefs
typedef void(*	bufferevent_data_cb )(struct bufferevent bev, void ctx)
	type definition for the read or write callback.
typedef void(*	bufferevent_event_cb )(struct bufferevent bev, short what, void ctx)
	type definition for the error callback of a bufferevent.
typedef enum bufferevent_filter_result(*	bufferevent_filter_cb )(struct evbuffer src, struct evbuffer dst, ev_ssize_t dst_limit, enum bufferevent_flush_mode mode, void *ctx)
	A callback function to implement a filter for a bufferevent.
Enumerations
enum	bufferevent_filter_result { BEV_OK = 0, BEV_NEED_MORE = 1, BEV_ERROR = 2 }
	Support for filtering input and output of bufferevents. More...
enum	bufferevent_flush_mode { BEV_NORMAL = 0, BEV_FLUSH = 1, BEV_FINISHED = 2 }
	Flags that can be passed into filters to let them know how to deal with the incoming data. More...
enum	bufferevent_options { BEV_OPT_CLOSE_ON_FREE = (1<<0), BEV_OPT_THREADSAFE = (1<<1), BEV_OPT_DEFER_CALLBACKS = (1<<2), BEV_OPT_UNLOCK_CALLBACKS = (1<<3) }
	Options that can be specified when creating a bufferevent. More...
Functions
int	bufferevent_add_to_rate_limit_group (struct bufferevent bev, struct bufferevent_rate_limit_group g)
	Add 'bev' to the list of bufferevents whose aggregate reading and writing is restricted by 'g'.
int	bufferevent_base_set (struct event_base base, struct bufferevent bufev)
	Assign a bufferevent to a specific event_base.
int	bufferevent_disable (struct bufferevent *bufev, short event)
	Disable a bufferevent.
int	bufferevent_enable (struct bufferevent *bufev, short event)
	Enable a bufferevent.
struct bufferevent *	bufferevent_filter_new (struct bufferevent underlying, bufferevent_filter_cb input_filter, bufferevent_filter_cb output_filter, int options, void(free_context)(void ), void ctx)
	Allocate a new filtering bufferevent on top of an existing bufferevent.
int	bufferevent_flush (struct bufferevent *bufev, short iotype, enum bufferevent_flush_mode mode)
	Triggers the bufferevent to produce more data if possible.
void	bufferevent_free (struct bufferevent *bufev)
	Deallocate the storage associated with a bufferevent structure.
struct event_base *	bufferevent_get_base (struct bufferevent *bev)
	Return the event_base used by a bufferevent.
short	bufferevent_get_enabled (struct bufferevent *bufev)
	Return the events that are enabled on a given bufferevent.
struct evbuffer *	bufferevent_get_input (struct bufferevent *bufev)
	Returns the input buffer.
ev_ssize_t	bufferevent_get_max_to_read (struct bufferevent *bev)
ev_ssize_t	bufferevent_get_max_to_write (struct bufferevent *bev)
struct evbuffer *	bufferevent_get_output (struct bufferevent *bufev)
	Returns the output buffer.
struct bufferevent *	bufferevent_get_underlying (struct bufferevent *bufev)
	Returns the underlying bufferevent associated with a bufferevent (if the bufferevent is a wrapper), or NULL if there is no underlying bufferevent.
evutil_socket_t	bufferevent_getfd (struct bufferevent *bufev)
	Returns the file descriptor associated with a bufferevent, or -1 if no file descriptor is associated with the bufferevent.
void	bufferevent_lock (struct bufferevent *bufev)
	Acquire the lock on a bufferevent.
struct bufferevent *	bufferevent_pair_get_partner (struct bufferevent *bev)
	Given one bufferevent returned by bufferevent_pair_new(), returns the other one if it still exists.
int	bufferevent_pair_new (struct event_base base, int options, struct bufferevent pair[2])
	Allocate a pair of linked bufferevents.
int	bufferevent_priority_set (struct bufferevent *bufev, int pri)
	Assign a priority to a bufferevent.
void	bufferevent_rate_limit_group_free (struct bufferevent_rate_limit_group *)
	Free a rate-limiting group.
void	bufferevent_rate_limit_group_get_totals (struct bufferevent_rate_limit_group grp, ev_uint64_t total_read_out, ev_uint64_t *total_written_out)
	Set the variable pointed to by total_read_out to the total number of bytes ever read on grp, and the variable pointed to by total_written_out to the total number of bytes ever written on grp.
struct bufferevent_rate_limit_group *	bufferevent_rate_limit_group_new (struct event_base base, const struct ev_token_bucket_cfg cfg)
	Create a new rate-limit group for bufferevents.
void	bufferevent_rate_limit_group_reset_totals (struct bufferevent_rate_limit_group *grp)
	Reset the number of bytes read or written on grp as given by bufferevent_rate_limit_group_reset_totals().
int	bufferevent_rate_limit_group_set_cfg (struct bufferevent_rate_limit_group , const struct ev_token_bucket_cfg )
	Change the rate-limiting settings for a given rate-limiting group.
int	bufferevent_rate_limit_group_set_min_share (struct bufferevent_rate_limit_group *, size_t)
	Change the smallest quantum we're willing to allocate to any single bufferevent in a group for reading or writing at a time.
size_t	bufferevent_read (struct bufferevent bufev, void data, size_t size)
	Read data from a bufferevent buffer.
int	bufferevent_read_buffer (struct bufferevent bufev, struct evbuffer buf)
	Read data from a bufferevent buffer into an evbuffer.
int	bufferevent_remove_from_rate_limit_group (struct bufferevent *bev)
	Remove 'bev' from its current rate-limit group (if any).
int	bufferevent_set_rate_limit (struct bufferevent bev, struct ev_token_bucket_cfg cfg)
	Set the rate-limit of a the bufferevent 'bev' to the one specified in 'cfg'.
int	bufferevent_set_timeouts (struct bufferevent bufev, const struct timeval timeout_read, const struct timeval *timeout_write)
	Set the read and write timeout for a buffered event.
void	bufferevent_setcb (struct bufferevent bufev, bufferevent_data_cb readcb, bufferevent_data_cb writecb, bufferevent_event_cb eventcb, void cbarg)
	Changes the callbacks for a bufferevent.
int	bufferevent_setfd (struct bufferevent *bufev, evutil_socket_t fd)
	Changes the file descriptor on which the bufferevent operates.
void	bufferevent_setwatermark (struct bufferevent *bufev, short events, size_t lowmark, size_t highmark)
	Sets the watermarks for read and write events.
int	bufferevent_socket_connect (struct bufferevent , struct sockaddr , int)
	Launch a connect() attempt with a socket.
int	bufferevent_socket_connect_hostname (struct bufferevent b, struct evdns_base , int, const char *, int)
	Resolve the hostname 'hostname' and connect to it as with bufferevent_socket_connect().
int	bufferevent_socket_get_dns_error (struct bufferevent *bev)
	Return the error code for the last failed DNS lookup attempt made by bufferevent_socket_connect_hostname().
struct bufferevent *	bufferevent_socket_new (struct event_base *base, evutil_socket_t fd, int options)
	Create a new socket bufferevent over an existing socket.
void	bufferevent_unlock (struct bufferevent *bufev)
	Release the lock on a bufferevent.
int	bufferevent_write (struct bufferevent bufev, const void data, size_t size)
	Write data to a bufferevent buffer.
int	bufferevent_write_buffer (struct bufferevent bufev, struct evbuffer buf)
	Write data from an evbuffer to a bufferevent buffer.
void	ev_token_bucket_cfg_free (struct ev_token_bucket_cfg *cfg)
	Free all storage held in 'cfg'.
struct ev_token_bucket_cfg *	ev_token_bucket_cfg_new (size_t read_rate, size_t read_burst, size_t write_rate, size_t write_burst, const struct timeval *tick_len)
	Initialize and return a new object to configure the rate-limiting behavior of bufferevents.

ev_ssize_t	bufferevent_get_read_limit (struct bufferevent *bev)
	Return the current read or write bucket size for a bufferevent.
ev_ssize_t	bufferevent_get_write_limit (struct bufferevent *bev)

ev_ssize_t	bufferevent_rate_limit_group_get_read_limit (struct bufferevent_rate_limit_group *)
	Return the read or write bucket size for a bufferevent rate limit group.
ev_ssize_t	bufferevent_rate_limit_group_get_write_limit (struct bufferevent_rate_limit_group *)

int	bufferevent_decrement_read_limit (struct bufferevent *bev, ev_ssize_t decr)
	Subtract a number of bytes from a bufferevent's read or write bucket.
int	bufferevent_decrement_write_limit (struct bufferevent *bev, ev_ssize_t decr)

int	bufferevent_rate_limit_group_decrement_read (struct bufferevent_rate_limit_group *, ev_ssize_t)
	Subtract a number of bytes from a bufferevent rate-limiting group's read or write bucket.
int	bufferevent_rate_limit_group_decrement_write (struct bufferevent_rate_limit_group *, ev_ssize_t)

Detailed Description

Functions for buffering data for network sending or receiving.

Bufferevents are higher level than evbuffers: each has an underlying evbuffer for reading and one for writing, and callbacks that are invoked under certain circumstances.

Libevent provides an abstraction on top of the regular event callbacks. This abstraction is called a buffered event. A buffered event provides input and output buffers that get filled and drained automatically. The user of a buffered event no longer deals directly with the I/O, but instead is reading from input and writing to output buffers.

Once initialized, the bufferevent structure can be used repeatedly with bufferevent_enable() and bufferevent_disable().

When read enabled the bufferevent will try to read from the file descriptor and call the read callback. The write callback is executed whenever the output buffer is drained below the write low watermark, which is 0 by default.

Define Documentation

#define BEV_EVENT_CONNECTED 0x80

connect operation finished.

#define EV_RATE_LIMIT_MAX EV_SSIZE_MAX

Maximum configurable rate- or burst-limit.

Typedef Documentation

typedef void(* bufferevent_data_cb)(struct bufferevent *bev, void *ctx)

type definition for the read or write callback.

The read callback is triggered when new data arrives in the input buffer and the amount of readable data exceed the low watermark which is 0 by default.

The write callback is triggered if the write buffer has been exhausted or fell below its low watermark.

Parameters:

bev	the bufferevent that triggered the callback
ctx	the user specified context for this bufferevent

typedef void(* bufferevent_event_cb)(struct bufferevent *bev, short what, void *ctx)

type definition for the error callback of a bufferevent.

The error callback is triggered if either an EOF condition or another unrecoverable error was encountered.

Parameters:

bev	the bufferevent for which the error condition was reached
what	a conjunction of flags: BEV_EVENT_READING or BEV_EVENT_WRITING to indicate if the error was encountered on the read or write path, and one of the following flags: BEV_EVENT_EOF, BEV_EVENT_ERROR, BEV_EVENT_TIMEOUT, BEV_EVENT_CONNECTED.
ctx	the user specified context for this bufferevent

typedef enum bufferevent_filter_result(* bufferevent_filter_cb)(struct evbuffer *src, struct evbuffer *dst, ev_ssize_t dst_limit, enum bufferevent_flush_mode mode, void *ctx)

A callback function to implement a filter for a bufferevent.

Parameters:

src	An evbuffer to drain data from.
dst	An evbuffer to add data to.
limit	A suggested upper bound of bytes to write to dst. The filter may ignore this value, but doing so means that it will overflow the high-water mark associated with dst. -1 means "no limit".
mode	Whether we should write data as may be convenient (BEV_NORMAL), or flush as much data as we can (BEV_FLUSH), or flush as much as we can, possibly including an end-of-stream marker (BEV_FINISH).
ctx	A user-supplied pointer.

Returns:: BEV_OK if we wrote some data; BEV_NEED_MORE if we can't produce any more output until we get some input; and BEV_ERROR on an error.

Enumeration Type Documentation

enum bufferevent_filter_result

Support for filtering input and output of bufferevents.

Values that filters can return.

Enumerator:

BEV_OK	everything is okay
BEV_NEED_MORE	the filter needs to read more data before output
BEV_ERROR	the filter encountered a critical error, no further data can be processed.

enum bufferevent_flush_mode

Flags that can be passed into filters to let them know how to deal with the incoming data.

Enumerator:

BEV_NORMAL	usually set when processing data
BEV_FLUSH	want to checkpoint all data sent.
BEV_FINISHED	encountered EOF on read or done sending data

enum bufferevent_options

Options that can be specified when creating a bufferevent.

Enumerator:

BEV_OPT_CLOSE_ON_FREE	If set, we close the underlying file descriptor/bufferevent/whatever when this bufferevent is freed.
BEV_OPT_THREADSAFE	If set, and threading is enabled, operations on this bufferevent are protected by a lock.
BEV_OPT_DEFER_CALLBACKS	If set, callbacks are run deferred in the event loop.
BEV_OPT_UNLOCK_CALLBACKS	If set, callbacks are executed without locks being held on the bufferevent. This option currently requires that BEV_OPT_DEFER_CALLBACKS also be set; a future version of Libevent might remove the requirement.

Function Documentation

int bufferevent_add_to_rate_limit_group	(	struct bufferevent *	bev,
		struct bufferevent_rate_limit_group *	g
	)

Add 'bev' to the list of bufferevents whose aggregate reading and writing is restricted by 'g'.

If 'g' is NULL, remove 'bev' from its current group.

A bufferevent may belong to no more than one rate-limit group at a time. If 'bev' is already a member of a group, it will be removed from its old group before being added to 'g'.

Return 0 on success and -1 on failure.

int bufferevent_base_set	(	struct event_base *	base,
		struct bufferevent *	bufev
	)

Assign a bufferevent to a specific event_base.

NOTE that only socket bufferevents support this function.

Parameters:

base	an event_base returned by event_init()
bufev	a bufferevent struct returned by bufferevent_new() or bufferevent_socket_new()

Returns:: 0 if successful, or -1 if an error occurred

See also:: bufferevent_new()

int bufferevent_decrement_read_limit	(	struct bufferevent *	bev,
		ev_ssize_t	decr
	)

Subtract a number of bytes from a bufferevent's read or write bucket.

The decrement value can be negative, if you want to manually refill the bucket. If the change puts the bucket above or below zero, the bufferevent will resume or suspend reading writing as appropriate. These functions make no change in the buckets for the bufferevent's group, if any.

Returns 0 on success, -1 on internal error.

int bufferevent_disable	(	struct bufferevent *	bufev,
		short	event
	)

Disable a bufferevent.

Parameters:

bufev	the bufferevent to be disabled
event	any combination of EV_READ \| EV_WRITE.

Returns:: 0 if successful, or -1 if an error occurred

See also:: bufferevent_enable()

int bufferevent_enable	(	struct bufferevent *	bufev,
		short	event
	)

Enable a bufferevent.

Parameters:

bufev	the bufferevent to be enabled
event	any combination of EV_READ \| EV_WRITE.

Returns:: 0 if successful, or -1 if an error occurred

See also:: bufferevent_disable()

struct bufferevent* bufferevent_filter_new	(	struct bufferevent *	underlying,
		bufferevent_filter_cb	input_filter,
		bufferevent_filter_cb	output_filter,
		int	options,
		void()(void )	free_context,
		void *	ctx
	)		`[read]`

Allocate a new filtering bufferevent on top of an existing bufferevent.

Parameters:

underlying	the underlying bufferevent.
input_filter	The filter to apply to data we read from the underlying bufferevent
output_filter	The filer to apply to data we write to the underlying bufferevent
options	A bitfield of bufferevent options.
free_context	A function to use to free the filter context when this bufferevent is freed.
ctx	A context pointer to pass to the filter functions.

int bufferevent_flush	(	struct bufferevent *	bufev,
		short	iotype,
		enum bufferevent_flush_mode	mode
	)

Triggers the bufferevent to produce more data if possible.

Parameters:

bufev	the bufferevent object
iotype	either EV_READ or EV_WRITE or both.
mode	either BEV_NORMAL or BEV_FLUSH or BEV_FINISHED

Returns:: -1 on failure, 0 if no data was produces, 1 if data was produced

void bufferevent_free ( struct bufferevent * bufev )

Deallocate the storage associated with a bufferevent structure.

Parameters:

bufev the bufferevent structure to be freed.

short bufferevent_get_enabled ( struct bufferevent * bufev )

Return the events that are enabled on a given bufferevent.

Parameters:

bufev the bufferevent to inspect

Returns:: A combination of EV_READ | EV_WRITE

struct evbuffer* bufferevent_get_input ( struct bufferevent * bufev ) [read]

Returns the input buffer.

The user MUST NOT set the callback on this buffer.

Parameters:

bufev the bufferevent from which to get the evbuffer

Returns:: the evbuffer object for the input buffer

struct evbuffer* bufferevent_get_output ( struct bufferevent * bufev ) [read]

Returns the output buffer.

The user MUST NOT set the callback on this buffer.

When filters are being used, the filters need to be manually triggered if the output buffer was manipulated.

Parameters:

bufev the bufferevent from which to get the evbuffer

Returns:: the evbuffer object for the output buffer

ev_ssize_t bufferevent_get_read_limit ( struct bufferevent * bev )

Return the current read or write bucket size for a bufferevent.

If it is not configured with a per-bufferevent ratelimit, return EV_SSIZE_MAX. This function does not inspect the group limit, if any. Note that it can return a negative value if the bufferevent has been made to read or write more than its limit.

void bufferevent_lock ( struct bufferevent * bufev )

Acquire the lock on a bufferevent.

Has no effect if locking was not enabled with BEV_OPT_THREADSAFE.

struct bufferevent* bufferevent_pair_get_partner ( struct bufferevent * bev ) [read]

Given one bufferevent returned by bufferevent_pair_new(), returns the other one if it still exists.

Otherwise returns NULL.

int bufferevent_pair_new	(	struct event_base *	base,
		int	options,
		struct bufferevent *	pair[2]
	)

Allocate a pair of linked bufferevents.

The bufferevents behave as would two bufferevent_sock instances connected to opposite ends of a socketpair(), except that no internal socketpair is allocated.

Parameters:

base	The event base to associate with the socketpair.
options	A set of options for this bufferevent
pair	A pointer to an array to hold the two new bufferevent objects.

Returns:: 0 on success, -1 on failure.

int bufferevent_priority_set	(	struct bufferevent *	bufev,
		int	pri
	)

Assign a priority to a bufferevent.

Only supported for socket bufferevents.

Parameters:

bufev	a bufferevent struct
pri	the priority to be assigned

Returns:: 0 if successful, or -1 if an error occurred

int bufferevent_rate_limit_group_decrement_read	(	struct bufferevent_rate_limit_group *	,
		ev_ssize_t
	)

Subtract a number of bytes from a bufferevent rate-limiting group's read or write bucket.

The decrement value can be negative, if you want to manually refill the bucket. If the change puts the bucket above or below zero, the bufferevents in the group will resume or suspend reading writing as appropriate.

Returns 0 on success, -1 on internal error.

void bufferevent_rate_limit_group_free ( struct bufferevent_rate_limit_group * )

Free a rate-limiting group.

The group must have no members when this function is called.

ev_ssize_t bufferevent_rate_limit_group_get_read_limit ( struct bufferevent_rate_limit_group * )

Return the read or write bucket size for a bufferevent rate limit group.

Note that it can return a negative value if bufferevents in the group have been made to read or write more than their limits.

void bufferevent_rate_limit_group_get_totals	(	struct bufferevent_rate_limit_group *	grp,
		ev_uint64_t *	total_read_out,
		ev_uint64_t *	total_written_out
	)

Set the variable pointed to by total_read_out to the total number of bytes ever read on grp, and the variable pointed to by total_written_out to the total number of bytes ever written on grp.

struct bufferevent_rate_limit_group* bufferevent_rate_limit_group_new	(	struct event_base *	base,
		const struct ev_token_bucket_cfg *	cfg
	)		`[read]`

Create a new rate-limit group for bufferevents.

A rate-limit group constrains the maximum number of bytes sent and received, in toto, by all of its bufferevents.

Parameters:

base	An event_base to run any necessary timeouts for the group. Note that all bufferevents in the group do not necessarily need to share this event_base.
cfg	The rate-limit for this group.

Note that all rate-limits hare are currently best-effort: future versions of Libevent may implement them more tightly.

Note also that only some bufferevent types currently respect rate-limiting. They are: socket-based bufferevents (normal and IOCP-based), and SSL-based bufferevents.

void bufferevent_rate_limit_group_reset_totals ( struct bufferevent_rate_limit_group * grp )

Reset the number of bytes read or written on grp as given by bufferevent_rate_limit_group_reset_totals().

int bufferevent_rate_limit_group_set_cfg	(	struct bufferevent_rate_limit_group *	,
		const struct ev_token_bucket_cfg *
	)

Change the rate-limiting settings for a given rate-limiting group.

Return 0 on success, -1 on failure.

int bufferevent_rate_limit_group_set_min_share	(	struct bufferevent_rate_limit_group *	,
		size_t
	)

Change the smallest quantum we're willing to allocate to any single bufferevent in a group for reading or writing at a time.

The rationale is that, because of TCP/IP protocol overheads and kernel behavior, if a rate-limiting group is so tight on bandwidth that you're only willing to send 1 byte per tick per bufferevent, you might instead want to batch up the reads and writes so that you send N bytes per 1/N of the bufferevents (chosen at random) each tick, so you still wind up send 1 byte per tick per bufferevent on average, but you don't send so many tiny packets.

The default min-share is currently 64 bytes.

Returns 0 on success, -1 on faulre.

size_t bufferevent_read	(	struct bufferevent *	bufev,
		void *	data,
		size_t	size
	)

Read data from a bufferevent buffer.

The bufferevent_read() function is used to read data from the input buffer.

Parameters:

bufev	the bufferevent to be read from
data	pointer to a buffer that will store the data
size	the size of the data buffer, in bytes

Returns:: the amount of data read, in bytes.

int bufferevent_read_buffer	(	struct bufferevent *	bufev,
		struct evbuffer *	buf
	)

Read data from a bufferevent buffer into an evbuffer.

This avoids memory copies.

Parameters:

bufev	the bufferevent to be read from
buf	the evbuffer to which to add data

Returns:: 0 if successful, or -1 if an error occurred.

int bufferevent_remove_from_rate_limit_group ( struct bufferevent * bev )

Remove 'bev' from its current rate-limit group (if any).

int bufferevent_set_rate_limit	(	struct bufferevent *	bev,
		struct ev_token_bucket_cfg *	cfg
	)

Set the rate-limit of a the bufferevent 'bev' to the one specified in 'cfg'.

If 'cfg' is NULL, disable any per-bufferevent rate-limiting on 'bev'.

Note that only some bufferevent types currently respect rate-limiting. They are: socket-based bufferevents (normal and IOCP-based), and SSL-based bufferevents.

Return 0 on sucess, -1 on failure.

int bufferevent_set_timeouts	(	struct bufferevent *	bufev,
		const struct timeval *	timeout_read,
		const struct timeval *	timeout_write
	)

Set the read and write timeout for a buffered event.

A bufferevent's timeout will fire the first time that the indicated amount of time has elapsed since a successful read or write operation, during which the bufferevent was trying to read or write.

(In other words, if reading or writing is disabled, or if the bufferevent's read or write operation has been suspended because there's no data to write, or not enough banwidth, or so on, the timeout isn't active. The timeout only becomes active when we we're willing to actually read or write.)

Calling bufferevent_enable or setting a timeout for a bufferevent whose timeout is already pending resets its timeout.

If the timeout elapses, the corresponding operation (EV_READ or EV_WRITE) becomes disabled until you re-enable it again. The bufferevent's event callback is called with the BEV_EVENT_TIMEOUT|BEV_EVENT_READING or BEV_EVENT_TIMEOUT|BEV_EVENT_WRITING.

Parameters:

bufev	the bufferevent to be modified
timeout_read	the read timeout, or NULL
timeout_write	the write timeout, or NULL

void bufferevent_setcb	(	struct bufferevent *	bufev,
		bufferevent_data_cb	readcb,
		bufferevent_data_cb	writecb,
		bufferevent_event_cb	eventcb,
		void *	cbarg
	)

Changes the callbacks for a bufferevent.

Parameters:

bufev	the bufferevent object for which to change callbacks
readcb	callback to invoke when there is data to be read, or NULL if no callback is desired
writecb	callback to invoke when the file descriptor is ready for writing, or NULL if no callback is desired
eventcb	callback to invoke when there is an event on the file descriptor
cbarg	an argument that will be supplied to each of the callbacks (readcb, writecb, and errorcb)

See also:: bufferevent_new()

int bufferevent_setfd	(	struct bufferevent *	bufev,
		evutil_socket_t	fd
	)

Changes the file descriptor on which the bufferevent operates.

Not supported for all bufferevent types.

Parameters:

bufev	the bufferevent object for which to change the file descriptor
fd	the file descriptor to operate on

void bufferevent_setwatermark	(	struct bufferevent *	bufev,
		short	events,
		size_t	lowmark,
		size_t	highmark
	)

Sets the watermarks for read and write events.

On input, a bufferevent does not invoke the user read callback unless there is at least low watermark data in the buffer. If the read buffer is beyond the high watermark, the bufferevent stops reading from the network.

On output, the user write callback is invoked whenever the buffered data falls below the low watermark. Filters that write to this bufev will try not to write more bytes to this buffer than the high watermark would allow, except when flushing.

Parameters:

bufev	the bufferevent to be modified
events	EV_READ, EV_WRITE or both
lowmark	the lower watermark to set
highmark	the high watermark to set

int bufferevent_socket_connect	(	struct bufferevent *	,
		struct sockaddr *	,
		int
	)

Launch a connect() attempt with a socket.

When the connect succeeds, the eventcb will be invoked with BEV_EVENT_CONNECTED set.

If the bufferevent does not already have a socket set, we allocate a new socket here and make it nonblocking before we begin.

If no address is provided, we assume that the socket is already connecting, and configure the bufferevent so that a BEV_EVENT_CONNECTED event will be yielded when it is done connecting.

Parameters:

bufev	an existing bufferevent allocated with bufferevent_socket_new().
addr	the address we should connect to
socklen	The length of the address

Returns:: 0 on success, -1 on failure.

int bufferevent_socket_connect_hostname	(	struct bufferevent *	b,
		struct evdns_base *	,
		int	,
		const char *	,
		int
	)

Resolve the hostname 'hostname' and connect to it as with bufferevent_socket_connect().

Parameters:

bufev	An existing bufferevent allocated with bufferevent_socket_new()
evdns_base	Optionally, an evdns_base to use for resolving hostnames asynchronously. May be set to NULL for a blocking resolve.
family	A preferred address family to resolve addresses to, or AF_UNSPEC for no preference. Only AF_INET, AF_INET6, and AF_UNSPEC are supported.
hostname	The hostname to resolve; see below for notes on recognized formats
port	The port to connect to on the resolved address.

Returns:: 0 if successful, -1 on failure.

Recognized hostname formats are:

www.example.com (hostname) 1.2.3.4 (ipv4address) ::1 (ipv6address) [::1] ([ipv6address])

Performance note: If you do not provide an evdns_base, this function may block while it waits for a DNS response. This is probably not what you want.

int bufferevent_socket_get_dns_error ( struct bufferevent * bev )

Return the error code for the last failed DNS lookup attempt made by bufferevent_socket_connect_hostname().

Parameters:

bev	The bufferevent object.

Returns:: DNS error code.

See also:: evutil_gai_strerror()

struct bufferevent* bufferevent_socket_new	(	struct event_base *	base,
		evutil_socket_t	fd,
		int	options
	)		`[read]`

Create a new socket bufferevent over an existing socket.

Parameters:

base	the event base to associate with the new bufferevent.
fd	the file descriptor from which data is read and written to. This file descriptor is not allowed to be a pipe(2). It is safe to set the fd to -1, so long as you later set it with bufferevent_setfd or bufferevent_socket_connect().

Returns:: a pointer to a newly allocated bufferevent struct, or NULL if an error occurred

See also:: bufferevent_free()

void bufferevent_unlock ( struct bufferevent * bufev )

Release the lock on a bufferevent.

Has no effect if locking was not enabled with BEV_OPT_THREADSAFE.

int bufferevent_write	(	struct bufferevent *	bufev,
		const void *	data,
		size_t	size
	)

Write data to a bufferevent buffer.

The bufferevent_write() function can be used to write data to the file descriptor. The data is appended to the output buffer and written to the descriptor automatically as it becomes available for writing.

Parameters:

bufev	the bufferevent to be written to
data	a pointer to the data to be written
size	the length of the data, in bytes

Returns:: 0 if successful, or -1 if an error occurred

See also:: bufferevent_write_buffer()

int bufferevent_write_buffer	(	struct bufferevent *	bufev,
		struct evbuffer *	buf
	)

Write data from an evbuffer to a bufferevent buffer.

The evbuffer is being drained as a result.

Parameters:

bufev	the bufferevent to be written to
buf	the evbuffer to be written

Returns:: 0 if successful, or -1 if an error occurred

See also:: bufferevent_write()

void ev_token_bucket_cfg_free ( struct ev_token_bucket_cfg * cfg )

Free all storage held in 'cfg'.

Note: 'cfg' is not currently reference-counted; it is not safe to free it until no bufferevent is using it.

struct ev_token_bucket_cfg* ev_token_bucket_cfg_new	(	size_t	read_rate,
		size_t	read_burst,
		size_t	write_rate,
		size_t	write_burst,
		const struct timeval *	tick_len
	)		`[read]`

Initialize and return a new object to configure the rate-limiting behavior of bufferevents.

Parameters:

read_rate	The maximum number of bytes to read per tick on average.
read_burst	The maximum number of bytes to read in any single tick.
write_rate	The maximum number of bytes to write per tick on average.
write_burst	The maximum number of bytes to write in any single tick.
tick_len	The length of a single tick. Defaults to one second. Any fractions of a millisecond are ignored.

Note that all rate-limits hare are currently best-effort: future versions of Libevent may implement them more tightly.

include/event2/bufferevent.h File Reference

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation