1c43e99fdSEd Maste /* 2c43e99fdSEd Maste * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> 3c43e99fdSEd Maste * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 4c43e99fdSEd Maste * 5c43e99fdSEd Maste * Redistribution and use in source and binary forms, with or without 6c43e99fdSEd Maste * modification, are permitted provided that the following conditions 7c43e99fdSEd Maste * are met: 8c43e99fdSEd Maste * 1. Redistributions of source code must retain the above copyright 9c43e99fdSEd Maste * notice, this list of conditions and the following disclaimer. 10c43e99fdSEd Maste * 2. Redistributions in binary form must reproduce the above copyright 11c43e99fdSEd Maste * notice, this list of conditions and the following disclaimer in the 12c43e99fdSEd Maste * documentation and/or other materials provided with the distribution. 13c43e99fdSEd Maste * 3. The name of the author may not be used to endorse or promote products 14c43e99fdSEd Maste * derived from this software without specific prior written permission. 15c43e99fdSEd Maste * 16c43e99fdSEd Maste * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17c43e99fdSEd Maste * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18c43e99fdSEd Maste * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19c43e99fdSEd Maste * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20c43e99fdSEd Maste * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21c43e99fdSEd Maste * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22c43e99fdSEd Maste * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23c43e99fdSEd Maste * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24c43e99fdSEd Maste * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25c43e99fdSEd Maste * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26c43e99fdSEd Maste */ 27c43e99fdSEd Maste #ifndef EVENT2_BUFFEREVENT_H_INCLUDED_ 28c43e99fdSEd Maste #define EVENT2_BUFFEREVENT_H_INCLUDED_ 29c43e99fdSEd Maste 30c43e99fdSEd Maste /** 31c43e99fdSEd Maste @file event2/bufferevent.h 32c43e99fdSEd Maste 33c43e99fdSEd Maste Functions for buffering data for network sending or receiving. Bufferevents 34c43e99fdSEd Maste are higher level than evbuffers: each has an underlying evbuffer for reading 35c43e99fdSEd Maste and one for writing, and callbacks that are invoked under certain 36c43e99fdSEd Maste circumstances. 37c43e99fdSEd Maste 38c43e99fdSEd Maste A bufferevent provides input and output buffers that get filled and 39c43e99fdSEd Maste drained automatically. The user of a bufferevent no longer deals 40c43e99fdSEd Maste directly with the I/O, but instead is reading from input and writing 41c43e99fdSEd Maste to output buffers. 42c43e99fdSEd Maste 43c43e99fdSEd Maste Once initialized, the bufferevent structure can be used repeatedly 44c43e99fdSEd Maste with bufferevent_enable() and bufferevent_disable(). 45c43e99fdSEd Maste 46c43e99fdSEd Maste When reading is enabled, the bufferevent will try to read from the 47c43e99fdSEd Maste file descriptor onto its input buffer, and call the read callback. 48c43e99fdSEd Maste When writing is enabled, the bufferevent will try to write data onto its 49c43e99fdSEd Maste file descriptor when the output buffer has enough data, and call the write 50c43e99fdSEd Maste callback when the output buffer is sufficiently drained. 51c43e99fdSEd Maste 52c43e99fdSEd Maste Bufferevents come in several flavors, including: 53c43e99fdSEd Maste 54c43e99fdSEd Maste <dl> 55c43e99fdSEd Maste <dt>Socket-based bufferevents</dt> 56c43e99fdSEd Maste <dd>A bufferevent that reads and writes data onto a network 57c43e99fdSEd Maste socket. Created with bufferevent_socket_new().</dd> 58c43e99fdSEd Maste 59c43e99fdSEd Maste <dt>Paired bufferevents</dt> 60c43e99fdSEd Maste <dd>A pair of bufferevents that send and receive data to one 61c43e99fdSEd Maste another without touching the network. Created with 62c43e99fdSEd Maste bufferevent_pair_new().</dd> 63c43e99fdSEd Maste 64c43e99fdSEd Maste <dt>Filtering bufferevents</dt> 65c43e99fdSEd Maste <dd>A bufferevent that transforms data, and sends or receives it 66c43e99fdSEd Maste over another underlying bufferevent. Created with 67c43e99fdSEd Maste bufferevent_filter_new().</dd> 68c43e99fdSEd Maste 69c43e99fdSEd Maste <dt>SSL-backed bufferevents</dt> 70c43e99fdSEd Maste <dd>A bufferevent that uses the openssl library to send and 71c43e99fdSEd Maste receive data over an encrypted connection. Created with 72c43e99fdSEd Maste bufferevent_openssl_socket_new() or 73c43e99fdSEd Maste bufferevent_openssl_filter_new().</dd> 74c43e99fdSEd Maste </dl> 75c43e99fdSEd Maste */ 76c43e99fdSEd Maste 77c43e99fdSEd Maste #include <event2/visibility.h> 78c43e99fdSEd Maste 79c43e99fdSEd Maste #ifdef __cplusplus 80c43e99fdSEd Maste extern "C" { 81c43e99fdSEd Maste #endif 82c43e99fdSEd Maste 83c43e99fdSEd Maste #include <event2/event-config.h> 84c43e99fdSEd Maste #ifdef EVENT__HAVE_SYS_TYPES_H 85c43e99fdSEd Maste #include <sys/types.h> 86c43e99fdSEd Maste #endif 87c43e99fdSEd Maste #ifdef EVENT__HAVE_SYS_TIME_H 88c43e99fdSEd Maste #include <sys/time.h> 89c43e99fdSEd Maste #endif 90c43e99fdSEd Maste 91c43e99fdSEd Maste /* For int types. */ 92c43e99fdSEd Maste #include <event2/util.h> 93c43e99fdSEd Maste 94c43e99fdSEd Maste /** @name Bufferevent event codes 95c43e99fdSEd Maste 96c43e99fdSEd Maste These flags are passed as arguments to a bufferevent's event callback. 97c43e99fdSEd Maste 98c43e99fdSEd Maste @{ 99c43e99fdSEd Maste */ 100c43e99fdSEd Maste #define BEV_EVENT_READING 0x01 /**< error encountered while reading */ 101c43e99fdSEd Maste #define BEV_EVENT_WRITING 0x02 /**< error encountered while writing */ 102c43e99fdSEd Maste #define BEV_EVENT_EOF 0x10 /**< eof file reached */ 103c43e99fdSEd Maste #define BEV_EVENT_ERROR 0x20 /**< unrecoverable error encountered */ 104c43e99fdSEd Maste #define BEV_EVENT_TIMEOUT 0x40 /**< user-specified timeout reached */ 105c43e99fdSEd Maste #define BEV_EVENT_CONNECTED 0x80 /**< connect operation finished. */ 106c43e99fdSEd Maste /**@}*/ 107c43e99fdSEd Maste 108c43e99fdSEd Maste /** 109c43e99fdSEd Maste An opaque type for handling buffered IO 110c43e99fdSEd Maste 111c43e99fdSEd Maste @see event2/bufferevent.h 112c43e99fdSEd Maste */ 113c43e99fdSEd Maste struct bufferevent 114c43e99fdSEd Maste #ifdef EVENT_IN_DOXYGEN_ 115c43e99fdSEd Maste {} 116c43e99fdSEd Maste #endif 117c43e99fdSEd Maste ; 118c43e99fdSEd Maste struct event_base; 119c43e99fdSEd Maste struct evbuffer; 120c43e99fdSEd Maste struct sockaddr; 121c43e99fdSEd Maste 122c43e99fdSEd Maste /** 123c43e99fdSEd Maste A read or write callback for a bufferevent. 124c43e99fdSEd Maste 125c43e99fdSEd Maste The read callback is triggered when new data arrives in the input 126c43e99fdSEd Maste buffer and the amount of readable data exceed the low watermark 127c43e99fdSEd Maste which is 0 by default. 128c43e99fdSEd Maste 129c43e99fdSEd Maste The write callback is triggered if the write buffer has been 130c43e99fdSEd Maste exhausted or fell below its low watermark. 131c43e99fdSEd Maste 132c43e99fdSEd Maste @param bev the bufferevent that triggered the callback 133c43e99fdSEd Maste @param ctx the user-specified context for this bufferevent 134c43e99fdSEd Maste */ 135c43e99fdSEd Maste typedef void (*bufferevent_data_cb)(struct bufferevent *bev, void *ctx); 136c43e99fdSEd Maste 137c43e99fdSEd Maste /** 138c43e99fdSEd Maste An event/error callback for a bufferevent. 139c43e99fdSEd Maste 140c43e99fdSEd Maste The event callback is triggered if either an EOF condition or another 141c43e99fdSEd Maste unrecoverable error was encountered. 142c43e99fdSEd Maste 143c43e99fdSEd Maste For bufferevents with deferred callbacks, this is a bitwise OR of all errors 144c43e99fdSEd Maste that have happened on the bufferevent since the last callback invocation. 145c43e99fdSEd Maste 146c43e99fdSEd Maste @param bev the bufferevent for which the error condition was reached 147c43e99fdSEd Maste @param what a conjunction of flags: BEV_EVENT_READING or BEV_EVENT_WRITING 148c43e99fdSEd Maste to indicate if the error was encountered on the read or write path, 149c43e99fdSEd Maste and one of the following flags: BEV_EVENT_EOF, BEV_EVENT_ERROR, 150c43e99fdSEd Maste BEV_EVENT_TIMEOUT, BEV_EVENT_CONNECTED. 151c43e99fdSEd Maste 152c43e99fdSEd Maste @param ctx the user-specified context for this bufferevent 153c43e99fdSEd Maste */ 154c43e99fdSEd Maste typedef void (*bufferevent_event_cb)(struct bufferevent *bev, short what, void *ctx); 155c43e99fdSEd Maste 156c43e99fdSEd Maste /** Options that can be specified when creating a bufferevent */ 157c43e99fdSEd Maste enum bufferevent_options { 158c43e99fdSEd Maste /** If set, we close the underlying file 159c43e99fdSEd Maste * descriptor/bufferevent/whatever when this bufferevent is freed. */ 160c43e99fdSEd Maste BEV_OPT_CLOSE_ON_FREE = (1<<0), 161c43e99fdSEd Maste 162c43e99fdSEd Maste /** If set, and threading is enabled, operations on this bufferevent 163c43e99fdSEd Maste * are protected by a lock */ 164c43e99fdSEd Maste BEV_OPT_THREADSAFE = (1<<1), 165c43e99fdSEd Maste 166c43e99fdSEd Maste /** If set, callbacks are run deferred in the event loop. */ 167c43e99fdSEd Maste BEV_OPT_DEFER_CALLBACKS = (1<<2), 168c43e99fdSEd Maste 169c43e99fdSEd Maste /** If set, callbacks are executed without locks being held on the 170c43e99fdSEd Maste * bufferevent. This option currently requires that 171c43e99fdSEd Maste * BEV_OPT_DEFER_CALLBACKS also be set; a future version of Libevent 172c43e99fdSEd Maste * might remove the requirement.*/ 173c43e99fdSEd Maste BEV_OPT_UNLOCK_CALLBACKS = (1<<3) 174c43e99fdSEd Maste }; 175c43e99fdSEd Maste 176c43e99fdSEd Maste /** 177c43e99fdSEd Maste Create a new socket bufferevent over an existing socket. 178c43e99fdSEd Maste 179c43e99fdSEd Maste @param base the event base to associate with the new bufferevent. 180c43e99fdSEd Maste @param fd the file descriptor from which data is read and written to. 181c43e99fdSEd Maste This file descriptor is not allowed to be a pipe(2). 182c43e99fdSEd Maste It is safe to set the fd to -1, so long as you later 183c43e99fdSEd Maste set it with bufferevent_setfd or bufferevent_socket_connect(). 184c43e99fdSEd Maste @param options Zero or more BEV_OPT_* flags 185c43e99fdSEd Maste @return a pointer to a newly allocated bufferevent struct, or NULL if an 186c43e99fdSEd Maste error occurred 187c43e99fdSEd Maste @see bufferevent_free() 188c43e99fdSEd Maste */ 189c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 190c43e99fdSEd Maste struct bufferevent *bufferevent_socket_new(struct event_base *base, evutil_socket_t fd, int options); 191c43e99fdSEd Maste 192c43e99fdSEd Maste /** 193c43e99fdSEd Maste Launch a connect() attempt with a socket-based bufferevent. 194c43e99fdSEd Maste 195c43e99fdSEd Maste When the connect succeeds, the eventcb will be invoked with 196c43e99fdSEd Maste BEV_EVENT_CONNECTED set. 197c43e99fdSEd Maste 198c43e99fdSEd Maste If the bufferevent does not already have a socket set, we allocate a new 199c43e99fdSEd Maste socket here and make it nonblocking before we begin. 200c43e99fdSEd Maste 201c43e99fdSEd Maste If no address is provided, we assume that the socket is already connecting, 202c43e99fdSEd Maste and configure the bufferevent so that a BEV_EVENT_CONNECTED event will be 203c43e99fdSEd Maste yielded when it is done connecting. 204c43e99fdSEd Maste 205c43e99fdSEd Maste @param bufev an existing bufferevent allocated with 206c43e99fdSEd Maste bufferevent_socket_new(). 207c43e99fdSEd Maste @param addr the address we should connect to 208c43e99fdSEd Maste @param socklen The length of the address 209c43e99fdSEd Maste @return 0 on success, -1 on failure. 210c43e99fdSEd Maste */ 211c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 212c43e99fdSEd Maste int bufferevent_socket_connect(struct bufferevent *, const struct sockaddr *, int); 213c43e99fdSEd Maste 214c43e99fdSEd Maste struct evdns_base; 215c43e99fdSEd Maste /** 216c43e99fdSEd Maste Resolve the hostname 'hostname' and connect to it as with 217c43e99fdSEd Maste bufferevent_socket_connect(). 218c43e99fdSEd Maste 219c43e99fdSEd Maste @param bufev An existing bufferevent allocated with bufferevent_socket_new() 220c43e99fdSEd Maste @param evdns_base Optionally, an evdns_base to use for resolving hostnames 221c43e99fdSEd Maste asynchronously. May be set to NULL for a blocking resolve. 222c43e99fdSEd Maste @param family A preferred address family to resolve addresses to, or 223c43e99fdSEd Maste AF_UNSPEC for no preference. Only AF_INET, AF_INET6, and AF_UNSPEC are 224c43e99fdSEd Maste supported. 225c43e99fdSEd Maste @param hostname The hostname to resolve; see below for notes on recognized 226c43e99fdSEd Maste formats 227c43e99fdSEd Maste @param port The port to connect to on the resolved address. 228c43e99fdSEd Maste @return 0 if successful, -1 on failure. 229c43e99fdSEd Maste 230c43e99fdSEd Maste Recognized hostname formats are: 231c43e99fdSEd Maste 232c43e99fdSEd Maste www.example.com (hostname) 233c43e99fdSEd Maste 1.2.3.4 (ipv4address) 234c43e99fdSEd Maste ::1 (ipv6address) 235c43e99fdSEd Maste [::1] ([ipv6address]) 236c43e99fdSEd Maste 237c43e99fdSEd Maste Performance note: If you do not provide an evdns_base, this function 238c43e99fdSEd Maste may block while it waits for a DNS response. This is probably not 239c43e99fdSEd Maste what you want. 240c43e99fdSEd Maste */ 241c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 242c43e99fdSEd Maste int bufferevent_socket_connect_hostname(struct bufferevent *, 243c43e99fdSEd Maste struct evdns_base *, int, const char *, int); 244c43e99fdSEd Maste 245c43e99fdSEd Maste /** 246c43e99fdSEd Maste Return the error code for the last failed DNS lookup attempt made by 247c43e99fdSEd Maste bufferevent_socket_connect_hostname(). 248c43e99fdSEd Maste 249c43e99fdSEd Maste @param bev The bufferevent object. 250c43e99fdSEd Maste @return DNS error code. 251c43e99fdSEd Maste @see evutil_gai_strerror() 252c43e99fdSEd Maste */ 253c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 254c43e99fdSEd Maste int bufferevent_socket_get_dns_error(struct bufferevent *bev); 255c43e99fdSEd Maste 256c43e99fdSEd Maste /** 257c43e99fdSEd Maste Assign a bufferevent to a specific event_base. 258c43e99fdSEd Maste 259c43e99fdSEd Maste NOTE that only socket bufferevents support this function. 260c43e99fdSEd Maste 261c43e99fdSEd Maste @param base an event_base returned by event_init() 262c43e99fdSEd Maste @param bufev a bufferevent struct returned by bufferevent_new() 263c43e99fdSEd Maste or bufferevent_socket_new() 264c43e99fdSEd Maste @return 0 if successful, or -1 if an error occurred 265c43e99fdSEd Maste @see bufferevent_new() 266c43e99fdSEd Maste */ 267c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 268c43e99fdSEd Maste int bufferevent_base_set(struct event_base *base, struct bufferevent *bufev); 269c43e99fdSEd Maste 270c43e99fdSEd Maste /** 271c43e99fdSEd Maste Return the event_base used by a bufferevent 272c43e99fdSEd Maste */ 273c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 274c43e99fdSEd Maste struct event_base *bufferevent_get_base(struct bufferevent *bev); 275c43e99fdSEd Maste 276c43e99fdSEd Maste /** 277c43e99fdSEd Maste Assign a priority to a bufferevent. 278c43e99fdSEd Maste 279c43e99fdSEd Maste Only supported for socket bufferevents. 280c43e99fdSEd Maste 281c43e99fdSEd Maste @param bufev a bufferevent struct 282c43e99fdSEd Maste @param pri the priority to be assigned 283c43e99fdSEd Maste @return 0 if successful, or -1 if an error occurred 284c43e99fdSEd Maste */ 285c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 286c43e99fdSEd Maste int bufferevent_priority_set(struct bufferevent *bufev, int pri); 287c43e99fdSEd Maste 288c43e99fdSEd Maste /** 289c43e99fdSEd Maste Return the priority of a bufferevent. 290c43e99fdSEd Maste 291c43e99fdSEd Maste Only supported for socket bufferevents 292c43e99fdSEd Maste */ 293c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 294c43e99fdSEd Maste int bufferevent_get_priority(const struct bufferevent *bufev); 295c43e99fdSEd Maste 296c43e99fdSEd Maste /** 297c43e99fdSEd Maste Deallocate the storage associated with a bufferevent structure. 298c43e99fdSEd Maste 299c43e99fdSEd Maste If there is pending data to write on the bufferevent, it probably won't be 300c43e99fdSEd Maste flushed before the bufferevent is freed. 301c43e99fdSEd Maste 302c43e99fdSEd Maste @param bufev the bufferevent structure to be freed. 303c43e99fdSEd Maste */ 304c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 305c43e99fdSEd Maste void bufferevent_free(struct bufferevent *bufev); 306c43e99fdSEd Maste 307c43e99fdSEd Maste 308c43e99fdSEd Maste /** 309c43e99fdSEd Maste Changes the callbacks for a bufferevent. 310c43e99fdSEd Maste 311c43e99fdSEd Maste @param bufev the bufferevent object for which to change callbacks 312c43e99fdSEd Maste @param readcb callback to invoke when there is data to be read, or NULL if 313c43e99fdSEd Maste no callback is desired 314c43e99fdSEd Maste @param writecb callback to invoke when the file descriptor is ready for 315c43e99fdSEd Maste writing, or NULL if no callback is desired 316c43e99fdSEd Maste @param eventcb callback to invoke when there is an event on the file 317c43e99fdSEd Maste descriptor 318c43e99fdSEd Maste @param cbarg an argument that will be supplied to each of the callbacks 319c43e99fdSEd Maste (readcb, writecb, and errorcb) 320c43e99fdSEd Maste @see bufferevent_new() 321c43e99fdSEd Maste */ 322c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 323c43e99fdSEd Maste void bufferevent_setcb(struct bufferevent *bufev, 324c43e99fdSEd Maste bufferevent_data_cb readcb, bufferevent_data_cb writecb, 325c43e99fdSEd Maste bufferevent_event_cb eventcb, void *cbarg); 326c43e99fdSEd Maste 327c43e99fdSEd Maste /** 328c43e99fdSEd Maste Retrieves the callbacks for a bufferevent. 329c43e99fdSEd Maste 330c43e99fdSEd Maste @param bufev the bufferevent to examine. 331c43e99fdSEd Maste @param readcb_ptr if readcb_ptr is nonnull, *readcb_ptr is set to the current 332c43e99fdSEd Maste read callback for the bufferevent. 333c43e99fdSEd Maste @param writecb_ptr if writecb_ptr is nonnull, *writecb_ptr is set to the 334c43e99fdSEd Maste current write callback for the bufferevent. 335c43e99fdSEd Maste @param eventcb_ptr if eventcb_ptr is nonnull, *eventcb_ptr is set to the 336c43e99fdSEd Maste current event callback for the bufferevent. 337c43e99fdSEd Maste @param cbarg_ptr if cbarg_ptr is nonnull, *cbarg_ptr is set to the current 338c43e99fdSEd Maste callback argument for the bufferevent. 339c43e99fdSEd Maste @see buffervent_setcb() 340c43e99fdSEd Maste */ 341c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 342c43e99fdSEd Maste void bufferevent_getcb(struct bufferevent *bufev, 343c43e99fdSEd Maste bufferevent_data_cb *readcb_ptr, 344c43e99fdSEd Maste bufferevent_data_cb *writecb_ptr, 345c43e99fdSEd Maste bufferevent_event_cb *eventcb_ptr, 346c43e99fdSEd Maste void **cbarg_ptr); 347c43e99fdSEd Maste 348c43e99fdSEd Maste /** 349c43e99fdSEd Maste Changes the file descriptor on which the bufferevent operates. 350c43e99fdSEd Maste Not supported for all bufferevent types. 351c43e99fdSEd Maste 352c43e99fdSEd Maste @param bufev the bufferevent object for which to change the file descriptor 353c43e99fdSEd Maste @param fd the file descriptor to operate on 354c43e99fdSEd Maste */ 355c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 356c43e99fdSEd Maste int bufferevent_setfd(struct bufferevent *bufev, evutil_socket_t fd); 357c43e99fdSEd Maste 358c43e99fdSEd Maste /** 359c43e99fdSEd Maste Returns the file descriptor associated with a bufferevent, or -1 if 360c43e99fdSEd Maste no file descriptor is associated with the bufferevent. 361c43e99fdSEd Maste */ 362c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 363c43e99fdSEd Maste evutil_socket_t bufferevent_getfd(struct bufferevent *bufev); 364c43e99fdSEd Maste 365c43e99fdSEd Maste /** 366c43e99fdSEd Maste Returns the underlying bufferevent associated with a bufferevent (if 367c43e99fdSEd Maste the bufferevent is a wrapper), or NULL if there is no underlying bufferevent. 368c43e99fdSEd Maste */ 369c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 370c43e99fdSEd Maste struct bufferevent *bufferevent_get_underlying(struct bufferevent *bufev); 371c43e99fdSEd Maste 372c43e99fdSEd Maste /** 373c43e99fdSEd Maste Write data to a bufferevent buffer. 374c43e99fdSEd Maste 375c43e99fdSEd Maste The bufferevent_write() function can be used to write data to the file 376c43e99fdSEd Maste descriptor. The data is appended to the output buffer and written to the 377c43e99fdSEd Maste descriptor automatically as it becomes available for writing. 378c43e99fdSEd Maste 379c43e99fdSEd Maste @param bufev the bufferevent to be written to 380c43e99fdSEd Maste @param data a pointer to the data to be written 381c43e99fdSEd Maste @param size the length of the data, in bytes 382c43e99fdSEd Maste @return 0 if successful, or -1 if an error occurred 383c43e99fdSEd Maste @see bufferevent_write_buffer() 384c43e99fdSEd Maste */ 385c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 386c43e99fdSEd Maste int bufferevent_write(struct bufferevent *bufev, 387c43e99fdSEd Maste const void *data, size_t size); 388c43e99fdSEd Maste 389c43e99fdSEd Maste 390c43e99fdSEd Maste /** 391c43e99fdSEd Maste Write data from an evbuffer to a bufferevent buffer. The evbuffer is 392c43e99fdSEd Maste being drained as a result. 393c43e99fdSEd Maste 394c43e99fdSEd Maste @param bufev the bufferevent to be written to 395c43e99fdSEd Maste @param buf the evbuffer to be written 396c43e99fdSEd Maste @return 0 if successful, or -1 if an error occurred 397c43e99fdSEd Maste @see bufferevent_write() 398c43e99fdSEd Maste */ 399c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 400c43e99fdSEd Maste int bufferevent_write_buffer(struct bufferevent *bufev, struct evbuffer *buf); 401c43e99fdSEd Maste 402c43e99fdSEd Maste 403c43e99fdSEd Maste /** 404c43e99fdSEd Maste Read data from a bufferevent buffer. 405c43e99fdSEd Maste 406c43e99fdSEd Maste The bufferevent_read() function is used to read data from the input buffer. 407c43e99fdSEd Maste 408c43e99fdSEd Maste @param bufev the bufferevent to be read from 409c43e99fdSEd Maste @param data pointer to a buffer that will store the data 410c43e99fdSEd Maste @param size the size of the data buffer, in bytes 411c43e99fdSEd Maste @return the amount of data read, in bytes. 412c43e99fdSEd Maste */ 413c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 414c43e99fdSEd Maste size_t bufferevent_read(struct bufferevent *bufev, void *data, size_t size); 415c43e99fdSEd Maste 416c43e99fdSEd Maste /** 417c43e99fdSEd Maste Read data from a bufferevent buffer into an evbuffer. This avoids 418c43e99fdSEd Maste memory copies. 419c43e99fdSEd Maste 420c43e99fdSEd Maste @param bufev the bufferevent to be read from 421c43e99fdSEd Maste @param buf the evbuffer to which to add data 422c43e99fdSEd Maste @return 0 if successful, or -1 if an error occurred. 423c43e99fdSEd Maste */ 424c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 425c43e99fdSEd Maste int bufferevent_read_buffer(struct bufferevent *bufev, struct evbuffer *buf); 426c43e99fdSEd Maste 427c43e99fdSEd Maste /** 428c43e99fdSEd Maste Returns the input buffer. 429c43e99fdSEd Maste 430c43e99fdSEd Maste The user MUST NOT set the callback on this buffer. 431c43e99fdSEd Maste 432c43e99fdSEd Maste @param bufev the bufferevent from which to get the evbuffer 433c43e99fdSEd Maste @return the evbuffer object for the input buffer 434c43e99fdSEd Maste */ 435c43e99fdSEd Maste 436c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 437c43e99fdSEd Maste struct evbuffer *bufferevent_get_input(struct bufferevent *bufev); 438c43e99fdSEd Maste 439c43e99fdSEd Maste /** 440c43e99fdSEd Maste Returns the output buffer. 441c43e99fdSEd Maste 442c43e99fdSEd Maste The user MUST NOT set the callback on this buffer. 443c43e99fdSEd Maste 444c43e99fdSEd Maste When filters are being used, the filters need to be manually 445c43e99fdSEd Maste triggered if the output buffer was manipulated. 446c43e99fdSEd Maste 447c43e99fdSEd Maste @param bufev the bufferevent from which to get the evbuffer 448c43e99fdSEd Maste @return the evbuffer object for the output buffer 449c43e99fdSEd Maste */ 450c43e99fdSEd Maste 451c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 452c43e99fdSEd Maste struct evbuffer *bufferevent_get_output(struct bufferevent *bufev); 453c43e99fdSEd Maste 454c43e99fdSEd Maste /** 455c43e99fdSEd Maste Enable a bufferevent. 456c43e99fdSEd Maste 457c43e99fdSEd Maste @param bufev the bufferevent to be enabled 458c43e99fdSEd Maste @param event any combination of EV_READ | EV_WRITE. 459c43e99fdSEd Maste @return 0 if successful, or -1 if an error occurred 460c43e99fdSEd Maste @see bufferevent_disable() 461c43e99fdSEd Maste */ 462c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 463c43e99fdSEd Maste int bufferevent_enable(struct bufferevent *bufev, short event); 464c43e99fdSEd Maste 465c43e99fdSEd Maste /** 466c43e99fdSEd Maste Disable a bufferevent. 467c43e99fdSEd Maste 468c43e99fdSEd Maste @param bufev the bufferevent to be disabled 469c43e99fdSEd Maste @param event any combination of EV_READ | EV_WRITE. 470c43e99fdSEd Maste @return 0 if successful, or -1 if an error occurred 471c43e99fdSEd Maste @see bufferevent_enable() 472c43e99fdSEd Maste */ 473c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 474c43e99fdSEd Maste int bufferevent_disable(struct bufferevent *bufev, short event); 475c43e99fdSEd Maste 476c43e99fdSEd Maste /** 477c43e99fdSEd Maste Return the events that are enabled on a given bufferevent. 478c43e99fdSEd Maste 479c43e99fdSEd Maste @param bufev the bufferevent to inspect 480c43e99fdSEd Maste @return A combination of EV_READ | EV_WRITE 481c43e99fdSEd Maste */ 482c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 483c43e99fdSEd Maste short bufferevent_get_enabled(struct bufferevent *bufev); 484c43e99fdSEd Maste 485c43e99fdSEd Maste /** 486c43e99fdSEd Maste Set the read and write timeout for a bufferevent. 487c43e99fdSEd Maste 488c43e99fdSEd Maste A bufferevent's timeout will fire the first time that the indicated 489c43e99fdSEd Maste amount of time has elapsed since a successful read or write operation, 490c43e99fdSEd Maste during which the bufferevent was trying to read or write. 491c43e99fdSEd Maste 492c43e99fdSEd Maste (In other words, if reading or writing is disabled, or if the 493c43e99fdSEd Maste bufferevent's read or write operation has been suspended because 494*b50261e2SCy Schubert there's no data to write, or not enough bandwidth, or so on, the 495c43e99fdSEd Maste timeout isn't active. The timeout only becomes active when we we're 496c43e99fdSEd Maste willing to actually read or write.) 497c43e99fdSEd Maste 498c43e99fdSEd Maste Calling bufferevent_enable or setting a timeout for a bufferevent 499c43e99fdSEd Maste whose timeout is already pending resets its timeout. 500c43e99fdSEd Maste 501c43e99fdSEd Maste If the timeout elapses, the corresponding operation (EV_READ or 502c43e99fdSEd Maste EV_WRITE) becomes disabled until you re-enable it again. The 503c43e99fdSEd Maste bufferevent's event callback is called with the 504c43e99fdSEd Maste BEV_EVENT_TIMEOUT|BEV_EVENT_READING or 505c43e99fdSEd Maste BEV_EVENT_TIMEOUT|BEV_EVENT_WRITING. 506c43e99fdSEd Maste 507c43e99fdSEd Maste @param bufev the bufferevent to be modified 508c43e99fdSEd Maste @param timeout_read the read timeout, or NULL 509c43e99fdSEd Maste @param timeout_write the write timeout, or NULL 510c43e99fdSEd Maste */ 511c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 512c43e99fdSEd Maste int bufferevent_set_timeouts(struct bufferevent *bufev, 513c43e99fdSEd Maste const struct timeval *timeout_read, const struct timeval *timeout_write); 514c43e99fdSEd Maste 515c43e99fdSEd Maste /** 516c43e99fdSEd Maste Sets the watermarks for read and write events. 517c43e99fdSEd Maste 518c43e99fdSEd Maste On input, a bufferevent does not invoke the user read callback unless 519c43e99fdSEd Maste there is at least low watermark data in the buffer. If the read buffer 520c43e99fdSEd Maste is beyond the high watermark, the bufferevent stops reading from the network. 521*b50261e2SCy Schubert But be aware that bufferevent input/read buffer can overrun high watermark 522*b50261e2SCy Schubert limit (typical example is openssl bufferevent), so you should not relay in 523*b50261e2SCy Schubert this. 524c43e99fdSEd Maste 525c43e99fdSEd Maste On output, the user write callback is invoked whenever the buffered data 526c43e99fdSEd Maste falls below the low watermark. Filters that write to this bufev will try 527c43e99fdSEd Maste not to write more bytes to this buffer than the high watermark would allow, 528c43e99fdSEd Maste except when flushing. 529c43e99fdSEd Maste 530c43e99fdSEd Maste @param bufev the bufferevent to be modified 531c43e99fdSEd Maste @param events EV_READ, EV_WRITE or both 532c43e99fdSEd Maste @param lowmark the lower watermark to set 533c43e99fdSEd Maste @param highmark the high watermark to set 534c43e99fdSEd Maste */ 535c43e99fdSEd Maste 536c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 537c43e99fdSEd Maste void bufferevent_setwatermark(struct bufferevent *bufev, short events, 538c43e99fdSEd Maste size_t lowmark, size_t highmark); 539c43e99fdSEd Maste 540c43e99fdSEd Maste /** 541c43e99fdSEd Maste Retrieves the watermarks for read or write events. 542c43e99fdSEd Maste Returns non-zero if events contains not only EV_READ or EV_WRITE. 543c43e99fdSEd Maste Returns zero if events equal EV_READ or EV_WRITE 544c43e99fdSEd Maste 545c43e99fdSEd Maste @param bufev the bufferevent to be examined 546c43e99fdSEd Maste @param events EV_READ or EV_WRITE 547c43e99fdSEd Maste @param lowmark receives the lower watermark if not NULL 548c43e99fdSEd Maste @param highmark receives the high watermark if not NULL 549c43e99fdSEd Maste */ 550c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 551c43e99fdSEd Maste int bufferevent_getwatermark(struct bufferevent *bufev, short events, 552c43e99fdSEd Maste size_t *lowmark, size_t *highmark); 553c43e99fdSEd Maste 554c43e99fdSEd Maste /** 555c43e99fdSEd Maste Acquire the lock on a bufferevent. Has no effect if locking was not 556c43e99fdSEd Maste enabled with BEV_OPT_THREADSAFE. 557c43e99fdSEd Maste */ 558c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 559c43e99fdSEd Maste void bufferevent_lock(struct bufferevent *bufev); 560c43e99fdSEd Maste 561c43e99fdSEd Maste /** 562c43e99fdSEd Maste Release the lock on a bufferevent. Has no effect if locking was not 563c43e99fdSEd Maste enabled with BEV_OPT_THREADSAFE. 564c43e99fdSEd Maste */ 565c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 566c43e99fdSEd Maste void bufferevent_unlock(struct bufferevent *bufev); 567c43e99fdSEd Maste 568c43e99fdSEd Maste 569c43e99fdSEd Maste /** 570c43e99fdSEd Maste * Public interface to manually increase the reference count of a bufferevent 571c43e99fdSEd Maste * this is useful in situations where a user may reference the bufferevent 572*b50261e2SCy Schubert * somewhere else (unknown to libevent) 573c43e99fdSEd Maste * 574c43e99fdSEd Maste * @param bufev the bufferevent to increase the refcount on 575c43e99fdSEd Maste * 576c43e99fdSEd Maste */ 577c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 578c43e99fdSEd Maste void bufferevent_incref(struct bufferevent *bufev); 579c43e99fdSEd Maste 580c43e99fdSEd Maste /** 581c43e99fdSEd Maste * Public interface to manually decrement the reference count of a bufferevent 582c43e99fdSEd Maste * 583c43e99fdSEd Maste * Warning: make sure you know what you're doing. This is mainly used in 584c43e99fdSEd Maste * conjunction with bufferevent_incref(). This will free up all data associated 585c43e99fdSEd Maste * with a bufferevent if the reference count hits 0. 586c43e99fdSEd Maste * 587c43e99fdSEd Maste * @param bufev the bufferevent to decrement the refcount on 588c43e99fdSEd Maste * 589c43e99fdSEd Maste * @return 1 if the bufferevent was freed, otherwise 0 (still referenced) 590c43e99fdSEd Maste */ 591c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 592c43e99fdSEd Maste int bufferevent_decref(struct bufferevent *bufev); 593c43e99fdSEd Maste 594c43e99fdSEd Maste /** 595c43e99fdSEd Maste Flags that can be passed into filters to let them know how to 596c43e99fdSEd Maste deal with the incoming data. 597c43e99fdSEd Maste */ 598c43e99fdSEd Maste enum bufferevent_flush_mode { 599c43e99fdSEd Maste /** usually set when processing data */ 600c43e99fdSEd Maste BEV_NORMAL = 0, 601c43e99fdSEd Maste 602c43e99fdSEd Maste /** want to checkpoint all data sent. */ 603c43e99fdSEd Maste BEV_FLUSH = 1, 604c43e99fdSEd Maste 605c43e99fdSEd Maste /** encountered EOF on read or done sending data */ 606c43e99fdSEd Maste BEV_FINISHED = 2 607c43e99fdSEd Maste }; 608c43e99fdSEd Maste 609c43e99fdSEd Maste /** 610c43e99fdSEd Maste Triggers the bufferevent to produce more data if possible. 611c43e99fdSEd Maste 612c43e99fdSEd Maste @param bufev the bufferevent object 613c43e99fdSEd Maste @param iotype either EV_READ or EV_WRITE or both. 614c43e99fdSEd Maste @param mode either BEV_NORMAL or BEV_FLUSH or BEV_FINISHED 615c43e99fdSEd Maste @return -1 on failure, 0 if no data was produces, 1 if data was produced 616c43e99fdSEd Maste */ 617c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 618c43e99fdSEd Maste int bufferevent_flush(struct bufferevent *bufev, 619c43e99fdSEd Maste short iotype, 620c43e99fdSEd Maste enum bufferevent_flush_mode mode); 621c43e99fdSEd Maste 622c43e99fdSEd Maste /** 623c43e99fdSEd Maste Flags for bufferevent_trigger(_event) that modify when and how to trigger 624c43e99fdSEd Maste the callback. 625c43e99fdSEd Maste */ 626c43e99fdSEd Maste enum bufferevent_trigger_options { 627c43e99fdSEd Maste /** trigger the callback regardless of the watermarks */ 628c43e99fdSEd Maste BEV_TRIG_IGNORE_WATERMARKS = (1<<16), 629c43e99fdSEd Maste 630c43e99fdSEd Maste /** defer even if the callbacks are not */ 631c43e99fdSEd Maste BEV_TRIG_DEFER_CALLBACKS = BEV_OPT_DEFER_CALLBACKS 632c43e99fdSEd Maste 633c43e99fdSEd Maste /* (Note: for internal reasons, these need to be disjoint from 634c43e99fdSEd Maste * bufferevent_options, except when they mean the same thing. */ 635c43e99fdSEd Maste }; 636c43e99fdSEd Maste 637c43e99fdSEd Maste /** 638c43e99fdSEd Maste Triggers bufferevent data callbacks. 639c43e99fdSEd Maste 640c43e99fdSEd Maste The function will honor watermarks unless options contain 641c43e99fdSEd Maste BEV_TRIG_IGNORE_WATERMARKS. If the options contain BEV_OPT_DEFER_CALLBACKS, 642c43e99fdSEd Maste the callbacks are deferred. 643c43e99fdSEd Maste 644c43e99fdSEd Maste @param bufev the bufferevent object 645c43e99fdSEd Maste @param iotype either EV_READ or EV_WRITE or both. 646c43e99fdSEd Maste @param options 647c43e99fdSEd Maste */ 648c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 649c43e99fdSEd Maste void bufferevent_trigger(struct bufferevent *bufev, short iotype, 650c43e99fdSEd Maste int options); 651c43e99fdSEd Maste 652c43e99fdSEd Maste /** 653c43e99fdSEd Maste Triggers the bufferevent event callback. 654c43e99fdSEd Maste 655c43e99fdSEd Maste If the options contain BEV_OPT_DEFER_CALLBACKS, the callbacks are deferred. 656c43e99fdSEd Maste 657c43e99fdSEd Maste @param bufev the bufferevent object 658c43e99fdSEd Maste @param what the flags to pass onto the event callback 659c43e99fdSEd Maste @param options 660c43e99fdSEd Maste */ 661c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 662c43e99fdSEd Maste void bufferevent_trigger_event(struct bufferevent *bufev, short what, 663c43e99fdSEd Maste int options); 664c43e99fdSEd Maste 665c43e99fdSEd Maste /** 666c43e99fdSEd Maste @name Filtering support 667c43e99fdSEd Maste 668c43e99fdSEd Maste @{ 669c43e99fdSEd Maste */ 670c43e99fdSEd Maste /** 671c43e99fdSEd Maste Values that filters can return. 672c43e99fdSEd Maste */ 673c43e99fdSEd Maste enum bufferevent_filter_result { 674c43e99fdSEd Maste /** everything is okay */ 675c43e99fdSEd Maste BEV_OK = 0, 676c43e99fdSEd Maste 677c43e99fdSEd Maste /** the filter needs to read more data before output */ 678c43e99fdSEd Maste BEV_NEED_MORE = 1, 679c43e99fdSEd Maste 680c43e99fdSEd Maste /** the filter encountered a critical error, no further data 681c43e99fdSEd Maste can be processed. */ 682c43e99fdSEd Maste BEV_ERROR = 2 683c43e99fdSEd Maste }; 684c43e99fdSEd Maste 685c43e99fdSEd Maste /** A callback function to implement a filter for a bufferevent. 686c43e99fdSEd Maste 687c43e99fdSEd Maste @param src An evbuffer to drain data from. 688c43e99fdSEd Maste @param dst An evbuffer to add data to. 689c43e99fdSEd Maste @param limit A suggested upper bound of bytes to write to dst. 690c43e99fdSEd Maste The filter may ignore this value, but doing so means that 691c43e99fdSEd Maste it will overflow the high-water mark associated with dst. 692c43e99fdSEd Maste -1 means "no limit". 693c43e99fdSEd Maste @param mode Whether we should write data as may be convenient 694c43e99fdSEd Maste (BEV_NORMAL), or flush as much data as we can (BEV_FLUSH), 695c43e99fdSEd Maste or flush as much as we can, possibly including an end-of-stream 696c43e99fdSEd Maste marker (BEV_FINISH). 697c43e99fdSEd Maste @param ctx A user-supplied pointer. 698c43e99fdSEd Maste 699c43e99fdSEd Maste @return BEV_OK if we wrote some data; BEV_NEED_MORE if we can't 700c43e99fdSEd Maste produce any more output until we get some input; and BEV_ERROR 701c43e99fdSEd Maste on an error. 702c43e99fdSEd Maste */ 703c43e99fdSEd Maste typedef enum bufferevent_filter_result (*bufferevent_filter_cb)( 704c43e99fdSEd Maste struct evbuffer *src, struct evbuffer *dst, ev_ssize_t dst_limit, 705c43e99fdSEd Maste enum bufferevent_flush_mode mode, void *ctx); 706c43e99fdSEd Maste 707c43e99fdSEd Maste /** 708c43e99fdSEd Maste Allocate a new filtering bufferevent on top of an existing bufferevent. 709c43e99fdSEd Maste 710c43e99fdSEd Maste @param underlying the underlying bufferevent. 711c43e99fdSEd Maste @param input_filter The filter to apply to data we read from the underlying 712c43e99fdSEd Maste bufferevent 713c43e99fdSEd Maste @param output_filter The filer to apply to data we write to the underlying 714c43e99fdSEd Maste bufferevent 715c43e99fdSEd Maste @param options A bitfield of bufferevent options. 716c43e99fdSEd Maste @param free_context A function to use to free the filter context when 717c43e99fdSEd Maste this bufferevent is freed. 718c43e99fdSEd Maste @param ctx A context pointer to pass to the filter functions. 719c43e99fdSEd Maste */ 720c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 721c43e99fdSEd Maste struct bufferevent * 722c43e99fdSEd Maste bufferevent_filter_new(struct bufferevent *underlying, 723c43e99fdSEd Maste bufferevent_filter_cb input_filter, 724c43e99fdSEd Maste bufferevent_filter_cb output_filter, 725c43e99fdSEd Maste int options, 726c43e99fdSEd Maste void (*free_context)(void *), 727c43e99fdSEd Maste void *ctx); 728c43e99fdSEd Maste /**@}*/ 729c43e99fdSEd Maste 730c43e99fdSEd Maste /** 731c43e99fdSEd Maste Allocate a pair of linked bufferevents. The bufferevents behave as would 732c43e99fdSEd Maste two bufferevent_sock instances connected to opposite ends of a 733c43e99fdSEd Maste socketpair(), except that no internal socketpair is allocated. 734c43e99fdSEd Maste 735c43e99fdSEd Maste @param base The event base to associate with the socketpair. 736c43e99fdSEd Maste @param options A set of options for this bufferevent 737c43e99fdSEd Maste @param pair A pointer to an array to hold the two new bufferevent objects. 738c43e99fdSEd Maste @return 0 on success, -1 on failure. 739c43e99fdSEd Maste */ 740c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 741c43e99fdSEd Maste int bufferevent_pair_new(struct event_base *base, int options, 742c43e99fdSEd Maste struct bufferevent *pair[2]); 743c43e99fdSEd Maste 744c43e99fdSEd Maste /** 745c43e99fdSEd Maste Given one bufferevent returned by bufferevent_pair_new(), returns the 746c43e99fdSEd Maste other one if it still exists. Otherwise returns NULL. 747c43e99fdSEd Maste */ 748c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 749c43e99fdSEd Maste struct bufferevent *bufferevent_pair_get_partner(struct bufferevent *bev); 750c43e99fdSEd Maste 751c43e99fdSEd Maste /** 752c43e99fdSEd Maste Abstract type used to configure rate-limiting on a bufferevent or a group 753c43e99fdSEd Maste of bufferevents. 754c43e99fdSEd Maste */ 755c43e99fdSEd Maste struct ev_token_bucket_cfg; 756c43e99fdSEd Maste 757c43e99fdSEd Maste /** 758c43e99fdSEd Maste A group of bufferevents which are configured to respect the same rate 759c43e99fdSEd Maste limit. 760c43e99fdSEd Maste */ 761c43e99fdSEd Maste struct bufferevent_rate_limit_group; 762c43e99fdSEd Maste 763c43e99fdSEd Maste /** Maximum configurable rate- or burst-limit. */ 764c43e99fdSEd Maste #define EV_RATE_LIMIT_MAX EV_SSIZE_MAX 765c43e99fdSEd Maste 766c43e99fdSEd Maste /** 767c43e99fdSEd Maste Initialize and return a new object to configure the rate-limiting behavior 768c43e99fdSEd Maste of bufferevents. 769c43e99fdSEd Maste 770c43e99fdSEd Maste @param read_rate The maximum number of bytes to read per tick on 771c43e99fdSEd Maste average. 772c43e99fdSEd Maste @param read_burst The maximum number of bytes to read in any single tick. 773c43e99fdSEd Maste @param write_rate The maximum number of bytes to write per tick on 774c43e99fdSEd Maste average. 775c43e99fdSEd Maste @param write_burst The maximum number of bytes to write in any single tick. 776c43e99fdSEd Maste @param tick_len The length of a single tick. Defaults to one second. 777c43e99fdSEd Maste Any fractions of a millisecond are ignored. 778c43e99fdSEd Maste 779c43e99fdSEd Maste Note that all rate-limits hare are currently best-effort: future versions 780c43e99fdSEd Maste of Libevent may implement them more tightly. 781c43e99fdSEd Maste */ 782c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 783c43e99fdSEd Maste struct ev_token_bucket_cfg *ev_token_bucket_cfg_new( 784c43e99fdSEd Maste size_t read_rate, size_t read_burst, 785c43e99fdSEd Maste size_t write_rate, size_t write_burst, 786c43e99fdSEd Maste const struct timeval *tick_len); 787c43e99fdSEd Maste 788c43e99fdSEd Maste /** Free all storage held in 'cfg'. 789c43e99fdSEd Maste 790c43e99fdSEd Maste Note: 'cfg' is not currently reference-counted; it is not safe to free it 791c43e99fdSEd Maste until no bufferevent is using it. 792c43e99fdSEd Maste */ 793c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 794c43e99fdSEd Maste void ev_token_bucket_cfg_free(struct ev_token_bucket_cfg *cfg); 795c43e99fdSEd Maste 796c43e99fdSEd Maste /** 797c43e99fdSEd Maste Set the rate-limit of a the bufferevent 'bev' to the one specified in 798c43e99fdSEd Maste 'cfg'. If 'cfg' is NULL, disable any per-bufferevent rate-limiting on 799c43e99fdSEd Maste 'bev'. 800c43e99fdSEd Maste 801c43e99fdSEd Maste Note that only some bufferevent types currently respect rate-limiting. 802c43e99fdSEd Maste They are: socket-based bufferevents (normal and IOCP-based), and SSL-based 803c43e99fdSEd Maste bufferevents. 804c43e99fdSEd Maste 805*b50261e2SCy Schubert Return 0 on success, -1 on failure. 806c43e99fdSEd Maste */ 807c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 808c43e99fdSEd Maste int bufferevent_set_rate_limit(struct bufferevent *bev, 809c43e99fdSEd Maste struct ev_token_bucket_cfg *cfg); 810c43e99fdSEd Maste 811c43e99fdSEd Maste /** 812c43e99fdSEd Maste Create a new rate-limit group for bufferevents. A rate-limit group 813c43e99fdSEd Maste constrains the maximum number of bytes sent and received, in toto, 814c43e99fdSEd Maste by all of its bufferevents. 815c43e99fdSEd Maste 816c43e99fdSEd Maste @param base An event_base to run any necessary timeouts for the group. 817c43e99fdSEd Maste Note that all bufferevents in the group do not necessarily need to share 818c43e99fdSEd Maste this event_base. 819c43e99fdSEd Maste @param cfg The rate-limit for this group. 820c43e99fdSEd Maste 821c43e99fdSEd Maste Note that all rate-limits hare are currently best-effort: future versions 822c43e99fdSEd Maste of Libevent may implement them more tightly. 823c43e99fdSEd Maste 824c43e99fdSEd Maste Note also that only some bufferevent types currently respect rate-limiting. 825c43e99fdSEd Maste They are: socket-based bufferevents (normal and IOCP-based), and SSL-based 826c43e99fdSEd Maste bufferevents. 827c43e99fdSEd Maste */ 828c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 829c43e99fdSEd Maste struct bufferevent_rate_limit_group *bufferevent_rate_limit_group_new( 830c43e99fdSEd Maste struct event_base *base, 831c43e99fdSEd Maste const struct ev_token_bucket_cfg *cfg); 832c43e99fdSEd Maste /** 833c43e99fdSEd Maste Change the rate-limiting settings for a given rate-limiting group. 834c43e99fdSEd Maste 835c43e99fdSEd Maste Return 0 on success, -1 on failure. 836c43e99fdSEd Maste */ 837c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 838c43e99fdSEd Maste int bufferevent_rate_limit_group_set_cfg( 839c43e99fdSEd Maste struct bufferevent_rate_limit_group *, 840c43e99fdSEd Maste const struct ev_token_bucket_cfg *); 841c43e99fdSEd Maste 842c43e99fdSEd Maste /** 843c43e99fdSEd Maste Change the smallest quantum we're willing to allocate to any single 844c43e99fdSEd Maste bufferevent in a group for reading or writing at a time. 845c43e99fdSEd Maste 846c43e99fdSEd Maste The rationale is that, because of TCP/IP protocol overheads and kernel 847c43e99fdSEd Maste behavior, if a rate-limiting group is so tight on bandwidth that you're 848c43e99fdSEd Maste only willing to send 1 byte per tick per bufferevent, you might instead 849c43e99fdSEd Maste want to batch up the reads and writes so that you send N bytes per 850c43e99fdSEd Maste 1/N of the bufferevents (chosen at random) each tick, so you still wind 851c43e99fdSEd Maste up send 1 byte per tick per bufferevent on average, but you don't send 852c43e99fdSEd Maste so many tiny packets. 853c43e99fdSEd Maste 854c43e99fdSEd Maste The default min-share is currently 64 bytes. 855c43e99fdSEd Maste 856*b50261e2SCy Schubert Returns 0 on success, -1 on failure. 857c43e99fdSEd Maste */ 858c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 859c43e99fdSEd Maste int bufferevent_rate_limit_group_set_min_share( 860c43e99fdSEd Maste struct bufferevent_rate_limit_group *, size_t); 861c43e99fdSEd Maste 862c43e99fdSEd Maste /** 863c43e99fdSEd Maste Free a rate-limiting group. The group must have no members when 864c43e99fdSEd Maste this function is called. 865c43e99fdSEd Maste */ 866c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 867c43e99fdSEd Maste void bufferevent_rate_limit_group_free(struct bufferevent_rate_limit_group *); 868c43e99fdSEd Maste 869c43e99fdSEd Maste /** 870c43e99fdSEd Maste Add 'bev' to the list of bufferevents whose aggregate reading and writing 871c43e99fdSEd Maste is restricted by 'g'. If 'g' is NULL, remove 'bev' from its current group. 872c43e99fdSEd Maste 873c43e99fdSEd Maste A bufferevent may belong to no more than one rate-limit group at a time. 874c43e99fdSEd Maste If 'bev' is already a member of a group, it will be removed from its old 875c43e99fdSEd Maste group before being added to 'g'. 876c43e99fdSEd Maste 877c43e99fdSEd Maste Return 0 on success and -1 on failure. 878c43e99fdSEd Maste */ 879c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 880c43e99fdSEd Maste int bufferevent_add_to_rate_limit_group(struct bufferevent *bev, 881c43e99fdSEd Maste struct bufferevent_rate_limit_group *g); 882c43e99fdSEd Maste 883c43e99fdSEd Maste /** Remove 'bev' from its current rate-limit group (if any). */ 884c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 885c43e99fdSEd Maste int bufferevent_remove_from_rate_limit_group(struct bufferevent *bev); 886c43e99fdSEd Maste 887c43e99fdSEd Maste /** 888c43e99fdSEd Maste Set the size limit for single read operation. 889c43e99fdSEd Maste 890c43e99fdSEd Maste Set to 0 for a reasonable default. 891c43e99fdSEd Maste 892c43e99fdSEd Maste Return 0 on success and -1 on failure. 893c43e99fdSEd Maste */ 894c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 895c43e99fdSEd Maste int bufferevent_set_max_single_read(struct bufferevent *bev, size_t size); 896c43e99fdSEd Maste 897c43e99fdSEd Maste /** 898c43e99fdSEd Maste Set the size limit for single write operation. 899c43e99fdSEd Maste 900c43e99fdSEd Maste Set to 0 for a reasonable default. 901c43e99fdSEd Maste 902c43e99fdSEd Maste Return 0 on success and -1 on failure. 903c43e99fdSEd Maste */ 904c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 905c43e99fdSEd Maste int bufferevent_set_max_single_write(struct bufferevent *bev, size_t size); 906c43e99fdSEd Maste 907c43e99fdSEd Maste /** Get the current size limit for single read operation. */ 908c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 909c43e99fdSEd Maste ev_ssize_t bufferevent_get_max_single_read(struct bufferevent *bev); 910c43e99fdSEd Maste 911c43e99fdSEd Maste /** Get the current size limit for single write operation. */ 912c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 913c43e99fdSEd Maste ev_ssize_t bufferevent_get_max_single_write(struct bufferevent *bev); 914c43e99fdSEd Maste 915c43e99fdSEd Maste /** 916c43e99fdSEd Maste @name Rate limit inspection 917c43e99fdSEd Maste 918c43e99fdSEd Maste Return the current read or write bucket size for a bufferevent. 919c43e99fdSEd Maste If it is not configured with a per-bufferevent ratelimit, return 920c43e99fdSEd Maste EV_SSIZE_MAX. This function does not inspect the group limit, if any. 921c43e99fdSEd Maste Note that it can return a negative value if the bufferevent has been 922c43e99fdSEd Maste made to read or write more than its limit. 923c43e99fdSEd Maste 924c43e99fdSEd Maste @{ 925c43e99fdSEd Maste */ 926c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 927c43e99fdSEd Maste ev_ssize_t bufferevent_get_read_limit(struct bufferevent *bev); 928c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 929c43e99fdSEd Maste ev_ssize_t bufferevent_get_write_limit(struct bufferevent *bev); 930c43e99fdSEd Maste /*@}*/ 931c43e99fdSEd Maste 932c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 933c43e99fdSEd Maste ev_ssize_t bufferevent_get_max_to_read(struct bufferevent *bev); 934c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 935c43e99fdSEd Maste ev_ssize_t bufferevent_get_max_to_write(struct bufferevent *bev); 936c43e99fdSEd Maste 937c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 938c43e99fdSEd Maste const struct ev_token_bucket_cfg *bufferevent_get_token_bucket_cfg(const struct bufferevent * bev); 939c43e99fdSEd Maste 940c43e99fdSEd Maste /** 941c43e99fdSEd Maste @name Group Rate limit inspection 942c43e99fdSEd Maste 943c43e99fdSEd Maste Return the read or write bucket size for a bufferevent rate limit 944c43e99fdSEd Maste group. Note that it can return a negative value if bufferevents in 945c43e99fdSEd Maste the group have been made to read or write more than their limits. 946c43e99fdSEd Maste 947c43e99fdSEd Maste @{ 948c43e99fdSEd Maste */ 949c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 950c43e99fdSEd Maste ev_ssize_t bufferevent_rate_limit_group_get_read_limit( 951c43e99fdSEd Maste struct bufferevent_rate_limit_group *); 952c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 953c43e99fdSEd Maste ev_ssize_t bufferevent_rate_limit_group_get_write_limit( 954c43e99fdSEd Maste struct bufferevent_rate_limit_group *); 955c43e99fdSEd Maste /*@}*/ 956c43e99fdSEd Maste 957c43e99fdSEd Maste /** 958c43e99fdSEd Maste @name Rate limit manipulation 959c43e99fdSEd Maste 960c43e99fdSEd Maste Subtract a number of bytes from a bufferevent's read or write bucket. 961c43e99fdSEd Maste The decrement value can be negative, if you want to manually refill 962c43e99fdSEd Maste the bucket. If the change puts the bucket above or below zero, the 963c43e99fdSEd Maste bufferevent will resume or suspend reading writing as appropriate. 964c43e99fdSEd Maste These functions make no change in the buckets for the bufferevent's 965c43e99fdSEd Maste group, if any. 966c43e99fdSEd Maste 967c43e99fdSEd Maste Returns 0 on success, -1 on internal error. 968c43e99fdSEd Maste 969c43e99fdSEd Maste @{ 970c43e99fdSEd Maste */ 971c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 972c43e99fdSEd Maste int bufferevent_decrement_read_limit(struct bufferevent *bev, ev_ssize_t decr); 973c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 974c43e99fdSEd Maste int bufferevent_decrement_write_limit(struct bufferevent *bev, ev_ssize_t decr); 975c43e99fdSEd Maste /*@}*/ 976c43e99fdSEd Maste 977c43e99fdSEd Maste /** 978c43e99fdSEd Maste @name Group rate limit manipulation 979c43e99fdSEd Maste 980c43e99fdSEd Maste Subtract a number of bytes from a bufferevent rate-limiting group's 981c43e99fdSEd Maste read or write bucket. The decrement value can be negative, if you 982c43e99fdSEd Maste want to manually refill the bucket. If the change puts the bucket 983c43e99fdSEd Maste above or below zero, the bufferevents in the group will resume or 984c43e99fdSEd Maste suspend reading writing as appropriate. 985c43e99fdSEd Maste 986c43e99fdSEd Maste Returns 0 on success, -1 on internal error. 987c43e99fdSEd Maste 988c43e99fdSEd Maste @{ 989c43e99fdSEd Maste */ 990c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 991c43e99fdSEd Maste int bufferevent_rate_limit_group_decrement_read( 992c43e99fdSEd Maste struct bufferevent_rate_limit_group *, ev_ssize_t); 993c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 994c43e99fdSEd Maste int bufferevent_rate_limit_group_decrement_write( 995c43e99fdSEd Maste struct bufferevent_rate_limit_group *, ev_ssize_t); 996c43e99fdSEd Maste /*@}*/ 997c43e99fdSEd Maste 998c43e99fdSEd Maste 999c43e99fdSEd Maste /** 1000c43e99fdSEd Maste * Inspect the total bytes read/written on a group. 1001c43e99fdSEd Maste * 1002c43e99fdSEd Maste * Set the variable pointed to by total_read_out to the total number of bytes 1003c43e99fdSEd Maste * ever read on grp, and the variable pointed to by total_written_out to the 1004c43e99fdSEd Maste * total number of bytes ever written on grp. */ 1005c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 1006c43e99fdSEd Maste void bufferevent_rate_limit_group_get_totals( 1007c43e99fdSEd Maste struct bufferevent_rate_limit_group *grp, 1008c43e99fdSEd Maste ev_uint64_t *total_read_out, ev_uint64_t *total_written_out); 1009c43e99fdSEd Maste 1010c43e99fdSEd Maste /** 1011c43e99fdSEd Maste * Reset the total bytes read/written on a group. 1012c43e99fdSEd Maste * 1013c43e99fdSEd Maste * Reset the number of bytes read or written on grp as given by 1014c43e99fdSEd Maste * bufferevent_rate_limit_group_reset_totals(). */ 1015c43e99fdSEd Maste EVENT2_EXPORT_SYMBOL 1016c43e99fdSEd Maste void 1017c43e99fdSEd Maste bufferevent_rate_limit_group_reset_totals( 1018c43e99fdSEd Maste struct bufferevent_rate_limit_group *grp); 1019c43e99fdSEd Maste 1020c43e99fdSEd Maste #ifdef __cplusplus 1021c43e99fdSEd Maste } 1022c43e99fdSEd Maste #endif 1023c43e99fdSEd Maste 1024c43e99fdSEd Maste #endif /* EVENT2_BUFFEREVENT_H_INCLUDED_ */ 1025