deimos.event2.bufferevent

@file event2/bufferevent.h

Functions for buffering data for network sending or receiving. Bufferevents are higher level than evbuffers: each has an underlying evbuffer for reading and one for writing, and callbacks that are invoked under certain circumstances.

A bufferevent provides input and output buffers that get filled and drained automatically. The user of a bufferevent no longer deals directly with the I/O, but instead is reading from input and writing to output buffers.

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

When reading is enabled, the bufferevent will try to read from the file descriptor onto its input buffer, and and call the read callback. When writing is enabled, the bufferevent will try to write data onto its file descriptor when writing is enabled, and call the write callback when the output buffer is sufficiently drained.

Bufferevents come in several flavors, including:

<dl> <dt>Socket-based bufferevents</dt> <dd>A bufferevent that reads and writes data onto a network socket. Created with bufferevent_socket_new().</dd>

<dt>Paired bufferevents</dt> <dd>A pair of bufferevents that send and receive data to one another without touching the network. Created with bufferevent_pair_new().</dd>

<dt>Filtering bufferevents</dt> <dd>A bufferevent that transforms data, and sends or receives it over another underlying bufferevent. Created with bufferevent_filter_new().</dd>

<dt>SSL-backed bufferevents</dt> <dd>A bufferevent that uses the openssl library to send and receive data over an encrypted connection. Created with bufferevent_openssl_socket_new() or bufferevent_openssl_filter_new().</dd> </dl>

Public Imports

deimos.event2.event_struct public import deimos.event2.event_struct;

deimos.event2.util public import deimos.event2.util;

Members

Aliases

bufferevent_data_cb alias bufferevent_data_cb = ExternC!(void function(bufferevent* bev, void* ctx)): A read or write callback for a bufferevent.
bufferevent_event_cb alias bufferevent_event_cb = ExternC!(void function(bufferevent* bev, short what, void* ctx)): An event/error callback for a bufferevent.
bufferevent_filter_cb alias bufferevent_filter_cb = ExternC!(bufferevent_filter_result function(evbuffer* src, evbuffer* dst, ev_ssize_t dst_limit, bufferevent_flush_mode mode, void* ctx)): A callback function to implement a filter for a bufferevent.

Enums

bufferevent_filter_result enum bufferevent_filter_result: Values that filters can return.
bufferevent_flush_mode enum bufferevent_flush_mode: Flags that can be passed into filters to let them know how to deal with the incoming data.
bufferevent_options enum bufferevent_options: Options that can be specified when creating a bufferevent

Functions

bufferevent_add_to_rate_limit_group int bufferevent_add_to_rate_limit_group(bufferevent* bev, 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.
bufferevent_base_set int bufferevent_base_set(event_base* base, bufferevent* bufev): Assign a bufferevent to a specific event_base.
bufferevent_decrement_read_limit int bufferevent_decrement_read_limit(bufferevent* bev, ev_ssize_t decr): @name Rate limit manipulation
bufferevent_decrement_write_limit int bufferevent_decrement_write_limit(bufferevent* bev, ev_ssize_t decr): Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
bufferevent_disable int bufferevent_disable(bufferevent* bufev, short event): Disable a bufferevent.
bufferevent_enable int bufferevent_enable(bufferevent* bufev, short event): Enable a bufferevent.
bufferevent_filter_new bufferevent* bufferevent_filter_new(bufferevent* underlying, bufferevent_filter_cb input_filter, bufferevent_filter_cb output_filter, int options, ExternC!(void function(void*)) free_context, void* ctx): Allocate a new filtering bufferevent on top of an existing bufferevent.
bufferevent_flush int bufferevent_flush(bufferevent* bufev, short iotype, bufferevent_flush_mode mode): Triggers the bufferevent to produce more data if possible.
bufferevent_free void bufferevent_free(bufferevent* bufev): Deallocate the storage associated with a bufferevent structure.
bufferevent_get_base event_base* bufferevent_get_base(bufferevent* bev): Return the event_base used by a bufferevent
bufferevent_get_enabled short bufferevent_get_enabled(bufferevent* bufev): Return the events that are enabled on a given bufferevent.
bufferevent_get_input evbuffer* bufferevent_get_input(bufferevent* bufev): Returns the input buffer.
bufferevent_get_max_to_read ev_ssize_t bufferevent_get_max_to_read(bufferevent* bev): Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
bufferevent_get_max_to_write ev_ssize_t bufferevent_get_max_to_write(bufferevent* bev): Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
bufferevent_get_output evbuffer* bufferevent_get_output(bufferevent* bufev): Returns the output buffer.
bufferevent_get_read_limit ev_ssize_t bufferevent_get_read_limit(bufferevent* bev): @name Rate limit inspection
bufferevent_get_underlying bufferevent* bufferevent_get_underlying(bufferevent* bufev): Returns the underlying bufferevent associated with a bufferevent (if the bufferevent is a wrapper), or NULL if there is no underlying bufferevent.
bufferevent_get_write_limit ev_ssize_t bufferevent_get_write_limit(bufferevent* bev): Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
bufferevent_getfd evutil_socket_t bufferevent_getfd(bufferevent* bufev): Returns the file descriptor associated with a bufferevent, or -1 if no file descriptor is associated with the bufferevent.
bufferevent_lock void bufferevent_lock(bufferevent* bufev): Acquire the lock on a bufferevent. Has no effect if locking was not enabled with BEV_OPT_THREADSAFE.
bufferevent_pair_get_partner bufferevent* bufferevent_pair_get_partner(bufferevent* bev): Given one bufferevent returned by bufferevent_pair_new(), returns the other one if it still exists. Otherwise returns NULL.
bufferevent_pair_new int bufferevent_pair_new(event_base* base, int options, bufferevent*[2] pair): 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.
bufferevent_priority_set int bufferevent_priority_set(bufferevent* bufev, int pri): Assign a priority to a bufferevent.
bufferevent_rate_limit_group_decrement_read int bufferevent_rate_limit_group_decrement_read(bufferevent_rate_limit_group* , ev_ssize_t ): @name Group rate limit manipulation
bufferevent_rate_limit_group_decrement_write int bufferevent_rate_limit_group_decrement_write(bufferevent_rate_limit_group* , ev_ssize_t ): Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
bufferevent_rate_limit_group_free void bufferevent_rate_limit_group_free(bufferevent_rate_limit_group* ): Free a rate-limiting group. The group must have no members when this function is called.
bufferevent_rate_limit_group_get_read_limit ev_ssize_t bufferevent_rate_limit_group_get_read_limit(bufferevent_rate_limit_group* ): @name GrouprRate limit inspection
bufferevent_rate_limit_group_get_totals void bufferevent_rate_limit_group_get_totals(bufferevent_rate_limit_group* grp, ev_uint64_t* total_read_out, ev_uint64_t* total_written_out): * Inspect the total bytes read/written on a group. * * Set the variable pointed to by total_read_out to the total number of bytes * ever read on grp, and the variable pointed to by total_written_out to the * total number of bytes ever written on grp.
bufferevent_rate_limit_group_get_write_limit ev_ssize_t bufferevent_rate_limit_group_get_write_limit(bufferevent_rate_limit_group* ): Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
bufferevent_rate_limit_group_new bufferevent_rate_limit_group* bufferevent_rate_limit_group_new(event_base* base, const(ev_token_bucket_cfg)* cfg): 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.
bufferevent_rate_limit_group_reset_totals void bufferevent_rate_limit_group_reset_totals(bufferevent_rate_limit_group* grp): * 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_set_cfg int bufferevent_rate_limit_group_set_cfg(bufferevent_rate_limit_group* , const(ev_token_bucket_cfg)* ): Change the rate-limiting settings for a given rate-limiting group.
bufferevent_rate_limit_group_set_min_share int bufferevent_rate_limit_group_set_min_share(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.
bufferevent_read size_t bufferevent_read(bufferevent* bufev, void* data, size_t size): Read data from a bufferevent buffer.
bufferevent_read_buffer int bufferevent_read_buffer(bufferevent* bufev, evbuffer* buf): Read data from a bufferevent buffer into an evbuffer. This avoids memory copies.
bufferevent_remove_from_rate_limit_group int bufferevent_remove_from_rate_limit_group(bufferevent* bev): Remove 'bev' from its current rate-limit group (if any).
bufferevent_set_rate_limit int bufferevent_set_rate_limit(bufferevent* bev, 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'.
bufferevent_set_timeouts int bufferevent_set_timeouts(bufferevent* bufev, const(timeval)* timeout_read, const(timeval)* timeout_write): Set the read and write timeout for a bufferevent.
bufferevent_setcb void bufferevent_setcb(bufferevent* bufev, bufferevent_data_cb readcb, bufferevent_data_cb writecb, bufferevent_event_cb eventcb, void* cbarg): Changes the callbacks for a bufferevent.
bufferevent_setfd int bufferevent_setfd(bufferevent* bufev, evutil_socket_t fd): Changes the file descriptor on which the bufferevent operates. Not supported for all bufferevent types.
bufferevent_setwatermark void bufferevent_setwatermark(bufferevent* bufev, short events, size_t lowmark, size_t highmark): Sets the watermarks for read and write events.
bufferevent_socket_connect int bufferevent_socket_connect(bufferevent* , sockaddr* , int ): Launch a connect() attempt with a socket-based bufferevent.
bufferevent_socket_connect_hostname int bufferevent_socket_connect_hostname(bufferevent* , evdns_base* , int , const(char)* , int ): Resolve the hostname 'hostname' and connect to it as with bufferevent_socket_connect().
bufferevent_socket_get_dns_error int bufferevent_socket_get_dns_error(bufferevent* bev): Return the error code for the last failed DNS lookup attempt made by bufferevent_socket_connect_hostname().
bufferevent_socket_new bufferevent* bufferevent_socket_new(event_base* base, evutil_socket_t fd, int options): Create a new socket bufferevent over an existing socket.
bufferevent_unlock void bufferevent_unlock(bufferevent* bufev): Release the lock on a bufferevent. Has no effect if locking was not enabled with BEV_OPT_THREADSAFE.
bufferevent_write int bufferevent_write(bufferevent* bufev, const(void)* data, size_t size): Write data to a bufferevent buffer.
bufferevent_write_buffer int bufferevent_write_buffer(bufferevent* bufev, evbuffer* buf): Write data from an evbuffer to a bufferevent buffer. The evbuffer is being drained as a result.
ev_token_bucket_cfg_free void ev_token_bucket_cfg_free(ev_token_bucket_cfg* cfg): Free all storage held in 'cfg'.
ev_token_bucket_cfg_new 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(timeval)* tick_len): Initialize and return a new object to configure the rate-limiting behavior of bufferevents.

Manifest constants

BEV_EVENT_CONNECTED enum BEV_EVENT_CONNECTED;: < connect operation finished.
BEV_EVENT_EOF enum BEV_EVENT_EOF;: < eof file reached
BEV_EVENT_ERROR enum BEV_EVENT_ERROR;: < unrecoverable error encountered
BEV_EVENT_READING enum BEV_EVENT_READING;: @name Bufferevent event codes
BEV_EVENT_TIMEOUT enum BEV_EVENT_TIMEOUT;: < user-specified timeout reached
BEV_EVENT_WRITING enum BEV_EVENT_WRITING;: < error encountered while writing
EV_RATE_LIMIT_MAX enum EV_RATE_LIMIT_MAX;: Maximum configurable rate- or burst-limit.

Structs

bufferevent struct bufferevent: An opaque type for handling buffered IO
bufferevent_rate_limit_group struct bufferevent_rate_limit_group: A group of bufferevents which are configured to respect the same rate limit.
ev_token_bucket_cfg struct ev_token_bucket_cfg: Abstract type used to configure rate-limiting on a bufferevent or a group of bufferevents.