include/event2/bufferevent.h File Reference

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

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

Go to the source code of this file.

Defines
#define	EVBUFFER_EOF   0x10
	eof file reached
#define	EVBUFFER_ERROR   0x20
	unrecoverable error encountered
#define	EVBUFFER_INPUT(x)   bufferevent_get_input(x)
	macro for getting access to the input buffer of a bufferevent
#define	EVBUFFER_OUTPUT(x)   bufferevent_get_output(x)
	macro for getting access to the output buffer of a bufferevent
#define	EVBUFFER_READ   0x01
	error encountered while reading
#define	EVBUFFER_TIMEOUT   0x40
	user specified timeout reached
#define	EVBUFFER_WRITE   0x02
	error encountered while writing
Typedefs
typedef void(*	evbuffercb )(struct bufferevent *bev, void *ctx)
	type definition for the read or write callback.
typedef void(*	everrorcb )(struct bufferevent *bev, short what, void *ctx)
	type defintion for the error callback of 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) }
	Options that can be specified when creating a bufferevent. More...
Functions
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, enum bufferevent_options 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 state)
	Triggers the bufferevent to produce more data if possible.
void	bufferevent_free (struct bufferevent *bufev)
	Deallocate the storage associated with a bufferevent structure.
struct evbuffer *	bufferevent_get_input (struct bufferevent *bufev)
	Returns the input buffer.
struct evbuffer *	bufferevent_get_output (struct bufferevent *bufev)
	Returns the outut buffer.
int	bufferevent_pair_new (struct event_base *base, enum bufferevent_options 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.
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.
void	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, evbuffercb readcb, evbuffercb writecb, everrorcb errorcb, void *cbarg)
	Changes the callbacks for a bufferevent.
void	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.
struct bufferevent *	bufferevent_socket_new (struct event_base *base, evutil_socket_t fd, enum bufferevent_options options)
	Create a new socket bufferevent over an existing socket.
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.
Variables
enum bufferevent_filter_result(*	bufferevent_filter_cb )(struct evbuffer *src, struct evbuffer *dst, ssize_t dst_limit, enum bufferevent_flush_mode mode, void *ctx)
	A callback function to implement a filter for a bufferevent.

---

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.

---

Typedef Documentation

typedef void(* evbuffercb)(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(* everrorcb)(struct bufferevent *bev, short what, void *ctx)

type defintion 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: EVBUFFER_READ or EVBUFFER write to indicate if the error was encountered on the read or write path, and one of the following flags: EVBUFFER_EOF, EVBUFFER_ERROR or EVBUFFER_TIMEOUT.
	ctx	the user specified context for this bufferevent

---

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 enountered 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.

---

Function Documentation

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

Assign a bufferevent to a specific event_base.

Parameters:

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

Returns:

0 if successful, or -1 if an error occurred

See also:

bufferevent_new()

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,
		enum bufferevent_options	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	state
	)

Triggers the bufferevent to produce more data if possible.

Parameters:

	bufev	the bufferevent object
	iotype	either EV_READ or EV_WRITE or both.
	state	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.

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 buffervent 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 outut 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 buffervent from which to get the evbuffer

Returns:

the evbuffer object for the output buffer

int bufferevent_pair_new	(	struct event_base *	base,
		enum bufferevent_options	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 internel 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.

Parameters:

	bufev	a bufferevent struct
	pri	the priority to be assigned

Returns:

0 if successful, or -1 if an error occurred

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.

void 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.

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,
		evbuffercb	readcb,
		evbuffercb	writecb,
		everrorcb	errorcb,
		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
	errorcb	callback to invoke when there is an error on the file descriptor
	cbarg	an argument that will be supplied to each of the callbacks (readcb, writecb, and errorcb)

See also:

bufferevent_new()

void bufferevent_setfd	(	struct bufferevent *	bufev,
		evutil_socket_t	fd
	)

Changes the file descriptor on which the bufferevent operates.

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 buffevent 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

struct bufferevent* bufferevent_socket_new	(	struct event_base *	base,
		evutil_socket_t	fd,
		enum bufferevent_options	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).

Returns:

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

See also:

bufferevent_free()

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()

---

Variable Documentation

enum bufferevent_filter_result(* bufferevent_filter_cb)(struct evbuffer *src, struct evbuffer *dst, 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".
	state	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 (BEF_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.