1275970Scy/* 2275970Scy * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> 3275970Scy * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 4275970Scy * 5275970Scy * Redistribution and use in source and binary forms, with or without 6275970Scy * modification, are permitted provided that the following conditions 7275970Scy * are met: 8275970Scy * 1. Redistributions of source code must retain the above copyright 9275970Scy * notice, this list of conditions and the following disclaimer. 10275970Scy * 2. Redistributions in binary form must reproduce the above copyright 11275970Scy * notice, this list of conditions and the following disclaimer in the 12275970Scy * documentation and/or other materials provided with the distribution. 13275970Scy * 3. The name of the author may not be used to endorse or promote products 14275970Scy * derived from this software without specific prior written permission. 15275970Scy * 16275970Scy * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17275970Scy * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18275970Scy * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19275970Scy * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20275970Scy * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21275970Scy * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22275970Scy * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23275970Scy * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24275970Scy * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25275970Scy * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26275970Scy */ 27275970Scy#ifndef EVENT2_BUFFEREVENT_H_INCLUDED_ 28275970Scy#define EVENT2_BUFFEREVENT_H_INCLUDED_ 29275970Scy 30275970Scy/** 31275970Scy @file event2/bufferevent.h 32275970Scy 33275970Scy Functions for buffering data for network sending or receiving. Bufferevents 34275970Scy are higher level than evbuffers: each has an underlying evbuffer for reading 35275970Scy and one for writing, and callbacks that are invoked under certain 36275970Scy circumstances. 37275970Scy 38275970Scy A bufferevent provides input and output buffers that get filled and 39275970Scy drained automatically. The user of a bufferevent no longer deals 40275970Scy directly with the I/O, but instead is reading from input and writing 41275970Scy to output buffers. 42275970Scy 43275970Scy Once initialized, the bufferevent structure can be used repeatedly 44275970Scy with bufferevent_enable() and bufferevent_disable(). 45275970Scy 46275970Scy When reading is enabled, the bufferevent will try to read from the 47275970Scy file descriptor onto its input buffer, and call the read callback. 48275970Scy When writing is enabled, the bufferevent will try to write data onto its 49275970Scy file descriptor when the output buffer has enough data, and call the write 50275970Scy callback when the output buffer is sufficiently drained. 51275970Scy 52275970Scy Bufferevents come in several flavors, including: 53275970Scy 54275970Scy <dl> 55275970Scy <dt>Socket-based bufferevents</dt> 56275970Scy <dd>A bufferevent that reads and writes data onto a network 57275970Scy socket. Created with bufferevent_socket_new().</dd> 58275970Scy 59275970Scy <dt>Paired bufferevents</dt> 60275970Scy <dd>A pair of bufferevents that send and receive data to one 61275970Scy another without touching the network. Created with 62275970Scy bufferevent_pair_new().</dd> 63275970Scy 64275970Scy <dt>Filtering bufferevents</dt> 65275970Scy <dd>A bufferevent that transforms data, and sends or receives it 66275970Scy over another underlying bufferevent. Created with 67275970Scy bufferevent_filter_new().</dd> 68275970Scy 69275970Scy <dt>SSL-backed bufferevents</dt> 70275970Scy <dd>A bufferevent that uses the openssl library to send and 71275970Scy receive data over an encrypted connection. Created with 72275970Scy bufferevent_openssl_socket_new() or 73275970Scy bufferevent_openssl_filter_new().</dd> 74275970Scy </dl> 75275970Scy */ 76275970Scy 77275970Scy#include <event2/visibility.h> 78275970Scy 79275970Scy#ifdef __cplusplus 80275970Scyextern "C" { 81275970Scy#endif 82275970Scy 83275970Scy#include <event2/event-config.h> 84275970Scy#ifdef EVENT__HAVE_SYS_TYPES_H 85275970Scy#include <sys/types.h> 86275970Scy#endif 87275970Scy#ifdef EVENT__HAVE_SYS_TIME_H 88275970Scy#include <sys/time.h> 89275970Scy#endif 90275970Scy 91275970Scy/* For int types. */ 92275970Scy#include <event2/util.h> 93275970Scy 94275970Scy/** @name Bufferevent event codes 95275970Scy 96275970Scy These flags are passed as arguments to a bufferevent's event callback. 97275970Scy 98275970Scy @{ 99275970Scy*/ 100275970Scy#define BEV_EVENT_READING 0x01 /**< error encountered while reading */ 101275970Scy#define BEV_EVENT_WRITING 0x02 /**< error encountered while writing */ 102275970Scy#define BEV_EVENT_EOF 0x10 /**< eof file reached */ 103275970Scy#define BEV_EVENT_ERROR 0x20 /**< unrecoverable error encountered */ 104275970Scy#define BEV_EVENT_TIMEOUT 0x40 /**< user-specified timeout reached */ 105275970Scy#define BEV_EVENT_CONNECTED 0x80 /**< connect operation finished. */ 106275970Scy/**@}*/ 107275970Scy 108275970Scy/** 109275970Scy An opaque type for handling buffered IO 110275970Scy 111275970Scy @see event2/bufferevent.h 112275970Scy */ 113275970Scystruct bufferevent 114275970Scy#ifdef EVENT_IN_DOXYGEN_ 115275970Scy{} 116275970Scy#endif 117275970Scy; 118275970Scystruct event_base; 119275970Scystruct evbuffer; 120275970Scystruct sockaddr; 121275970Scy 122275970Scy/** 123275970Scy A read or write callback for a bufferevent. 124275970Scy 125275970Scy The read callback is triggered when new data arrives in the input 126275970Scy buffer and the amount of readable data exceed the low watermark 127275970Scy which is 0 by default. 128275970Scy 129275970Scy The write callback is triggered if the write buffer has been 130275970Scy exhausted or fell below its low watermark. 131275970Scy 132275970Scy @param bev the bufferevent that triggered the callback 133275970Scy @param ctx the user-specified context for this bufferevent 134275970Scy */ 135275970Scytypedef void (*bufferevent_data_cb)(struct bufferevent *bev, void *ctx); 136275970Scy 137275970Scy/** 138275970Scy An event/error callback for a bufferevent. 139275970Scy 140275970Scy The event callback is triggered if either an EOF condition or another 141275970Scy unrecoverable error was encountered. 142275970Scy 143275970Scy For bufferevents with deferred callbacks, this is a bitwise OR of all errors 144275970Scy that have happened on the bufferevent since the last callback invocation. 145275970Scy 146275970Scy @param bev the bufferevent for which the error condition was reached 147275970Scy @param what a conjunction of flags: BEV_EVENT_READING or BEV_EVENT_WRITING 148275970Scy to indicate if the error was encountered on the read or write path, 149275970Scy and one of the following flags: BEV_EVENT_EOF, BEV_EVENT_ERROR, 150275970Scy BEV_EVENT_TIMEOUT, BEV_EVENT_CONNECTED. 151275970Scy 152275970Scy @param ctx the user-specified context for this bufferevent 153275970Scy*/ 154275970Scytypedef void (*bufferevent_event_cb)(struct bufferevent *bev, short what, void *ctx); 155275970Scy 156275970Scy/** Options that can be specified when creating a bufferevent */ 157275970Scyenum bufferevent_options { 158275970Scy /** If set, we close the underlying file 159275970Scy * descriptor/bufferevent/whatever when this bufferevent is freed. */ 160275970Scy BEV_OPT_CLOSE_ON_FREE = (1<<0), 161275970Scy 162275970Scy /** If set, and threading is enabled, operations on this bufferevent 163275970Scy * are protected by a lock */ 164275970Scy BEV_OPT_THREADSAFE = (1<<1), 165275970Scy 166275970Scy /** If set, callbacks are run deferred in the event loop. */ 167275970Scy BEV_OPT_DEFER_CALLBACKS = (1<<2), 168275970Scy 169275970Scy /** If set, callbacks are executed without locks being held on the 170275970Scy * bufferevent. This option currently requires that 171275970Scy * BEV_OPT_DEFER_CALLBACKS also be set; a future version of Libevent 172275970Scy * might remove the requirement.*/ 173275970Scy BEV_OPT_UNLOCK_CALLBACKS = (1<<3) 174275970Scy}; 175275970Scy 176275970Scy/** 177275970Scy Create a new socket bufferevent over an existing socket. 178275970Scy 179275970Scy @param base the event base to associate with the new bufferevent. 180275970Scy @param fd the file descriptor from which data is read and written to. 181275970Scy This file descriptor is not allowed to be a pipe(2). 182275970Scy It is safe to set the fd to -1, so long as you later 183275970Scy set it with bufferevent_setfd or bufferevent_socket_connect(). 184275970Scy @param options Zero or more BEV_OPT_* flags 185275970Scy @return a pointer to a newly allocated bufferevent struct, or NULL if an 186275970Scy error occurred 187275970Scy @see bufferevent_free() 188275970Scy */ 189275970ScyEVENT2_EXPORT_SYMBOL 190275970Scystruct bufferevent *bufferevent_socket_new(struct event_base *base, evutil_socket_t fd, int options); 191275970Scy 192275970Scy/** 193275970Scy Launch a connect() attempt with a socket-based bufferevent. 194275970Scy 195275970Scy When the connect succeeds, the eventcb will be invoked with 196275970Scy BEV_EVENT_CONNECTED set. 197275970Scy 198275970Scy If the bufferevent does not already have a socket set, we allocate a new 199275970Scy socket here and make it nonblocking before we begin. 200275970Scy 201275970Scy If no address is provided, we assume that the socket is already connecting, 202275970Scy and configure the bufferevent so that a BEV_EVENT_CONNECTED event will be 203275970Scy yielded when it is done connecting. 204275970Scy 205275970Scy @param bufev an existing bufferevent allocated with 206275970Scy bufferevent_socket_new(). 207275970Scy @param addr the address we should connect to 208275970Scy @param socklen The length of the address 209275970Scy @return 0 on success, -1 on failure. 210275970Scy */ 211275970ScyEVENT2_EXPORT_SYMBOL 212275970Scyint bufferevent_socket_connect(struct bufferevent *, struct sockaddr *, int); 213275970Scy 214275970Scystruct evdns_base; 215275970Scy/** 216275970Scy Resolve the hostname 'hostname' and connect to it as with 217275970Scy bufferevent_socket_connect(). 218275970Scy 219275970Scy @param bufev An existing bufferevent allocated with bufferevent_socket_new() 220275970Scy @param evdns_base Optionally, an evdns_base to use for resolving hostnames 221275970Scy asynchronously. May be set to NULL for a blocking resolve. 222275970Scy @param family A preferred address family to resolve addresses to, or 223275970Scy AF_UNSPEC for no preference. Only AF_INET, AF_INET6, and AF_UNSPEC are 224275970Scy supported. 225275970Scy @param hostname The hostname to resolve; see below for notes on recognized 226275970Scy formats 227275970Scy @param port The port to connect to on the resolved address. 228275970Scy @return 0 if successful, -1 on failure. 229275970Scy 230275970Scy Recognized hostname formats are: 231275970Scy 232275970Scy www.example.com (hostname) 233275970Scy 1.2.3.4 (ipv4address) 234275970Scy ::1 (ipv6address) 235275970Scy [::1] ([ipv6address]) 236275970Scy 237275970Scy Performance note: If you do not provide an evdns_base, this function 238275970Scy may block while it waits for a DNS response. This is probably not 239275970Scy what you want. 240275970Scy */ 241275970ScyEVENT2_EXPORT_SYMBOL 242275970Scyint bufferevent_socket_connect_hostname(struct bufferevent *, 243275970Scy struct evdns_base *, int, const char *, int); 244275970Scy 245275970Scy/** 246275970Scy Return the error code for the last failed DNS lookup attempt made by 247275970Scy bufferevent_socket_connect_hostname(). 248275970Scy 249275970Scy @param bev The bufferevent object. 250275970Scy @return DNS error code. 251275970Scy @see evutil_gai_strerror() 252275970Scy*/ 253275970ScyEVENT2_EXPORT_SYMBOL 254275970Scyint bufferevent_socket_get_dns_error(struct bufferevent *bev); 255275970Scy 256275970Scy/** 257275970Scy Assign a bufferevent to a specific event_base. 258275970Scy 259275970Scy NOTE that only socket bufferevents support this function. 260275970Scy 261275970Scy @param base an event_base returned by event_init() 262275970Scy @param bufev a bufferevent struct returned by bufferevent_new() 263275970Scy or bufferevent_socket_new() 264275970Scy @return 0 if successful, or -1 if an error occurred 265275970Scy @see bufferevent_new() 266275970Scy */ 267275970ScyEVENT2_EXPORT_SYMBOL 268275970Scyint bufferevent_base_set(struct event_base *base, struct bufferevent *bufev); 269275970Scy 270275970Scy/** 271275970Scy Return the event_base used by a bufferevent 272275970Scy*/ 273275970ScyEVENT2_EXPORT_SYMBOL 274275970Scystruct event_base *bufferevent_get_base(struct bufferevent *bev); 275275970Scy 276275970Scy/** 277275970Scy Assign a priority to a bufferevent. 278275970Scy 279275970Scy Only supported for socket bufferevents. 280275970Scy 281275970Scy @param bufev a bufferevent struct 282275970Scy @param pri the priority to be assigned 283275970Scy @return 0 if successful, or -1 if an error occurred 284275970Scy */ 285275970ScyEVENT2_EXPORT_SYMBOL 286275970Scyint bufferevent_priority_set(struct bufferevent *bufev, int pri); 287275970Scy 288275970Scy/** 289275970Scy Return the priority of a bufferevent. 290275970Scy 291275970Scy Only supported for socket bufferevents 292275970Scy */ 293275970ScyEVENT2_EXPORT_SYMBOL 294275970Scyint bufferevent_get_priority(const struct bufferevent *bufev); 295275970Scy 296275970Scy/** 297275970Scy Deallocate the storage associated with a bufferevent structure. 298275970Scy 299275970Scy If there is pending data to write on the bufferevent, it probably won't be 300275970Scy flushed before the bufferevent is freed. 301275970Scy 302275970Scy @param bufev the bufferevent structure to be freed. 303275970Scy */ 304275970ScyEVENT2_EXPORT_SYMBOL 305275970Scyvoid bufferevent_free(struct bufferevent *bufev); 306275970Scy 307275970Scy 308275970Scy/** 309275970Scy Changes the callbacks for a bufferevent. 310275970Scy 311275970Scy @param bufev the bufferevent object for which to change callbacks 312275970Scy @param readcb callback to invoke when there is data to be read, or NULL if 313275970Scy no callback is desired 314275970Scy @param writecb callback to invoke when the file descriptor is ready for 315275970Scy writing, or NULL if no callback is desired 316275970Scy @param eventcb callback to invoke when there is an event on the file 317275970Scy descriptor 318275970Scy @param cbarg an argument that will be supplied to each of the callbacks 319275970Scy (readcb, writecb, and errorcb) 320275970Scy @see bufferevent_new() 321275970Scy */ 322275970ScyEVENT2_EXPORT_SYMBOL 323275970Scyvoid bufferevent_setcb(struct bufferevent *bufev, 324275970Scy bufferevent_data_cb readcb, bufferevent_data_cb writecb, 325275970Scy bufferevent_event_cb eventcb, void *cbarg); 326275970Scy 327275970Scy/** 328275970Scy Retrieves the callbacks for a bufferevent. 329275970Scy 330275970Scy @param bufev the bufferevent to examine. 331275970Scy @param readcb_ptr if readcb_ptr is nonnull, *readcb_ptr is set to the current 332275970Scy read callback for the bufferevent. 333275970Scy @param writecb_ptr if writecb_ptr is nonnull, *writecb_ptr is set to the 334275970Scy current write callback for the bufferevent. 335275970Scy @param eventcb_ptr if eventcb_ptr is nonnull, *eventcb_ptr is set to the 336275970Scy current event callback for the bufferevent. 337275970Scy @param cbarg_ptr if cbarg_ptr is nonnull, *cbarg_ptr is set to the current 338275970Scy callback argument for the bufferevent. 339275970Scy @see buffervent_setcb() 340275970Scy*/ 341275970ScyEVENT2_EXPORT_SYMBOL 342275970Scyvoid bufferevent_getcb(struct bufferevent *bufev, 343275970Scy bufferevent_data_cb *readcb_ptr, 344275970Scy bufferevent_data_cb *writecb_ptr, 345275970Scy bufferevent_event_cb *eventcb_ptr, 346275970Scy void **cbarg_ptr); 347275970Scy 348275970Scy/** 349275970Scy Changes the file descriptor on which the bufferevent operates. 350275970Scy Not supported for all bufferevent types. 351275970Scy 352275970Scy @param bufev the bufferevent object for which to change the file descriptor 353275970Scy @param fd the file descriptor to operate on 354275970Scy*/ 355275970ScyEVENT2_EXPORT_SYMBOL 356275970Scyint bufferevent_setfd(struct bufferevent *bufev, evutil_socket_t fd); 357275970Scy 358275970Scy/** 359275970Scy Returns the file descriptor associated with a bufferevent, or -1 if 360275970Scy no file descriptor is associated with the bufferevent. 361275970Scy */ 362275970ScyEVENT2_EXPORT_SYMBOL 363275970Scyevutil_socket_t bufferevent_getfd(struct bufferevent *bufev); 364275970Scy 365275970Scy/** 366275970Scy Returns the underlying bufferevent associated with a bufferevent (if 367275970Scy the bufferevent is a wrapper), or NULL if there is no underlying bufferevent. 368275970Scy */ 369275970ScyEVENT2_EXPORT_SYMBOL 370275970Scystruct bufferevent *bufferevent_get_underlying(struct bufferevent *bufev); 371275970Scy 372275970Scy/** 373275970Scy Write data to a bufferevent buffer. 374275970Scy 375275970Scy The bufferevent_write() function can be used to write data to the file 376275970Scy descriptor. The data is appended to the output buffer and written to the 377275970Scy descriptor automatically as it becomes available for writing. 378275970Scy 379275970Scy @param bufev the bufferevent to be written to 380275970Scy @param data a pointer to the data to be written 381275970Scy @param size the length of the data, in bytes 382275970Scy @return 0 if successful, or -1 if an error occurred 383275970Scy @see bufferevent_write_buffer() 384275970Scy */ 385275970ScyEVENT2_EXPORT_SYMBOL 386275970Scyint bufferevent_write(struct bufferevent *bufev, 387275970Scy const void *data, size_t size); 388275970Scy 389275970Scy 390275970Scy/** 391275970Scy Write data from an evbuffer to a bufferevent buffer. The evbuffer is 392275970Scy being drained as a result. 393275970Scy 394275970Scy @param bufev the bufferevent to be written to 395275970Scy @param buf the evbuffer to be written 396275970Scy @return 0 if successful, or -1 if an error occurred 397275970Scy @see bufferevent_write() 398275970Scy */ 399275970ScyEVENT2_EXPORT_SYMBOL 400275970Scyint bufferevent_write_buffer(struct bufferevent *bufev, struct evbuffer *buf); 401275970Scy 402275970Scy 403275970Scy/** 404275970Scy Read data from a bufferevent buffer. 405275970Scy 406275970Scy The bufferevent_read() function is used to read data from the input buffer. 407275970Scy 408275970Scy @param bufev the bufferevent to be read from 409275970Scy @param data pointer to a buffer that will store the data 410275970Scy @param size the size of the data buffer, in bytes 411275970Scy @return the amount of data read, in bytes. 412275970Scy */ 413275970ScyEVENT2_EXPORT_SYMBOL 414275970Scysize_t bufferevent_read(struct bufferevent *bufev, void *data, size_t size); 415275970Scy 416275970Scy/** 417275970Scy Read data from a bufferevent buffer into an evbuffer. This avoids 418275970Scy memory copies. 419275970Scy 420275970Scy @param bufev the bufferevent to be read from 421275970Scy @param buf the evbuffer to which to add data 422275970Scy @return 0 if successful, or -1 if an error occurred. 423275970Scy */ 424275970ScyEVENT2_EXPORT_SYMBOL 425275970Scyint bufferevent_read_buffer(struct bufferevent *bufev, struct evbuffer *buf); 426275970Scy 427275970Scy/** 428275970Scy Returns the input buffer. 429275970Scy 430275970Scy The user MUST NOT set the callback on this buffer. 431275970Scy 432275970Scy @param bufev the bufferevent from which to get the evbuffer 433275970Scy @return the evbuffer object for the input buffer 434275970Scy */ 435275970Scy 436275970ScyEVENT2_EXPORT_SYMBOL 437275970Scystruct evbuffer *bufferevent_get_input(struct bufferevent *bufev); 438275970Scy 439275970Scy/** 440275970Scy Returns the output buffer. 441275970Scy 442275970Scy The user MUST NOT set the callback on this buffer. 443275970Scy 444275970Scy When filters are being used, the filters need to be manually 445275970Scy triggered if the output buffer was manipulated. 446275970Scy 447275970Scy @param bufev the bufferevent from which to get the evbuffer 448275970Scy @return the evbuffer object for the output buffer 449275970Scy */ 450275970Scy 451275970ScyEVENT2_EXPORT_SYMBOL 452275970Scystruct evbuffer *bufferevent_get_output(struct bufferevent *bufev); 453275970Scy 454275970Scy/** 455275970Scy Enable a bufferevent. 456275970Scy 457275970Scy @param bufev the bufferevent to be enabled 458275970Scy @param event any combination of EV_READ | EV_WRITE. 459275970Scy @return 0 if successful, or -1 if an error occurred 460275970Scy @see bufferevent_disable() 461275970Scy */ 462275970ScyEVENT2_EXPORT_SYMBOL 463275970Scyint bufferevent_enable(struct bufferevent *bufev, short event); 464275970Scy 465275970Scy/** 466275970Scy Disable a bufferevent. 467275970Scy 468275970Scy @param bufev the bufferevent to be disabled 469275970Scy @param event any combination of EV_READ | EV_WRITE. 470275970Scy @return 0 if successful, or -1 if an error occurred 471275970Scy @see bufferevent_enable() 472275970Scy */ 473275970ScyEVENT2_EXPORT_SYMBOL 474275970Scyint bufferevent_disable(struct bufferevent *bufev, short event); 475275970Scy 476275970Scy/** 477275970Scy Return the events that are enabled on a given bufferevent. 478275970Scy 479275970Scy @param bufev the bufferevent to inspect 480275970Scy @return A combination of EV_READ | EV_WRITE 481275970Scy */ 482275970ScyEVENT2_EXPORT_SYMBOL 483275970Scyshort bufferevent_get_enabled(struct bufferevent *bufev); 484275970Scy 485275970Scy/** 486275970Scy Set the read and write timeout for a bufferevent. 487275970Scy 488275970Scy A bufferevent's timeout will fire the first time that the indicated 489275970Scy amount of time has elapsed since a successful read or write operation, 490275970Scy during which the bufferevent was trying to read or write. 491275970Scy 492275970Scy (In other words, if reading or writing is disabled, or if the 493275970Scy bufferevent's read or write operation has been suspended because 494275970Scy there's no data to write, or not enough banwidth, or so on, the 495275970Scy timeout isn't active. The timeout only becomes active when we we're 496275970Scy willing to actually read or write.) 497275970Scy 498275970Scy Calling bufferevent_enable or setting a timeout for a bufferevent 499275970Scy whose timeout is already pending resets its timeout. 500275970Scy 501275970Scy If the timeout elapses, the corresponding operation (EV_READ or 502275970Scy EV_WRITE) becomes disabled until you re-enable it again. The 503275970Scy bufferevent's event callback is called with the 504275970Scy BEV_EVENT_TIMEOUT|BEV_EVENT_READING or 505275970Scy BEV_EVENT_TIMEOUT|BEV_EVENT_WRITING. 506275970Scy 507275970Scy @param bufev the bufferevent to be modified 508275970Scy @param timeout_read the read timeout, or NULL 509275970Scy @param timeout_write the write timeout, or NULL 510275970Scy */ 511275970ScyEVENT2_EXPORT_SYMBOL 512275970Scyint bufferevent_set_timeouts(struct bufferevent *bufev, 513275970Scy const struct timeval *timeout_read, const struct timeval *timeout_write); 514275970Scy 515275970Scy/** 516275970Scy Sets the watermarks for read and write events. 517275970Scy 518275970Scy On input, a bufferevent does not invoke the user read callback unless 519275970Scy there is at least low watermark data in the buffer. If the read buffer 520275970Scy is beyond the high watermark, the bufferevent stops reading from the network. 521275970Scy 522275970Scy On output, the user write callback is invoked whenever the buffered data 523275970Scy falls below the low watermark. Filters that write to this bufev will try 524275970Scy not to write more bytes to this buffer than the high watermark would allow, 525275970Scy except when flushing. 526275970Scy 527275970Scy @param bufev the bufferevent to be modified 528275970Scy @param events EV_READ, EV_WRITE or both 529275970Scy @param lowmark the lower watermark to set 530275970Scy @param highmark the high watermark to set 531275970Scy*/ 532275970Scy 533275970ScyEVENT2_EXPORT_SYMBOL 534275970Scyvoid bufferevent_setwatermark(struct bufferevent *bufev, short events, 535275970Scy size_t lowmark, size_t highmark); 536275970Scy 537275970Scy/** 538285612Sdelphij Retrieves the watermarks for read or write events. 539285612Sdelphij Returns non-zero if events contains not only EV_READ or EV_WRITE. 540285612Sdelphij Returns zero if events equal EV_READ or EV_WRITE 541275970Scy 542275970Scy @param bufev the bufferevent to be examined 543275970Scy @param events EV_READ or EV_WRITE 544275970Scy @param lowmark receives the lower watermark if not NULL 545275970Scy @param highmark receives the high watermark if not NULL 546275970Scy*/ 547275970ScyEVENT2_EXPORT_SYMBOL 548285612Sdelphijint bufferevent_getwatermark(struct bufferevent *bufev, short events, 549275970Scy size_t *lowmark, size_t *highmark); 550275970Scy 551275970Scy/** 552275970Scy Acquire the lock on a bufferevent. Has no effect if locking was not 553275970Scy enabled with BEV_OPT_THREADSAFE. 554275970Scy */ 555275970ScyEVENT2_EXPORT_SYMBOL 556275970Scyvoid bufferevent_lock(struct bufferevent *bufev); 557275970Scy 558275970Scy/** 559275970Scy Release the lock on a bufferevent. Has no effect if locking was not 560275970Scy enabled with BEV_OPT_THREADSAFE. 561275970Scy */ 562275970ScyEVENT2_EXPORT_SYMBOL 563275970Scyvoid bufferevent_unlock(struct bufferevent *bufev); 564275970Scy 565275970Scy/** 566275970Scy Flags that can be passed into filters to let them know how to 567275970Scy deal with the incoming data. 568275970Scy*/ 569275970Scyenum bufferevent_flush_mode { 570275970Scy /** usually set when processing data */ 571275970Scy BEV_NORMAL = 0, 572275970Scy 573275970Scy /** want to checkpoint all data sent. */ 574275970Scy BEV_FLUSH = 1, 575275970Scy 576275970Scy /** encountered EOF on read or done sending data */ 577275970Scy BEV_FINISHED = 2 578275970Scy}; 579275970Scy 580275970Scy/** 581275970Scy Triggers the bufferevent to produce more data if possible. 582275970Scy 583275970Scy @param bufev the bufferevent object 584275970Scy @param iotype either EV_READ or EV_WRITE or both. 585275970Scy @param mode either BEV_NORMAL or BEV_FLUSH or BEV_FINISHED 586275970Scy @return -1 on failure, 0 if no data was produces, 1 if data was produced 587275970Scy */ 588275970ScyEVENT2_EXPORT_SYMBOL 589275970Scyint bufferevent_flush(struct bufferevent *bufev, 590275970Scy short iotype, 591275970Scy enum bufferevent_flush_mode mode); 592275970Scy 593275970Scy/** 594275970Scy Flags for bufferevent_trigger(_event) that modify when and how to trigger 595275970Scy the callback. 596275970Scy*/ 597275970Scyenum bufferevent_trigger_options { 598275970Scy /** trigger the callback regardless of the watermarks */ 599275970Scy BEV_TRIG_IGNORE_WATERMARKS = (1<<16), 600275970Scy 601275970Scy /** defer even if the callbacks are not */ 602285612Sdelphij BEV_TRIG_DEFER_CALLBACKS = BEV_OPT_DEFER_CALLBACKS 603275970Scy 604275970Scy /* (Note: for internal reasons, these need to be disjoint from 605275970Scy * bufferevent_options, except when they mean the same thing. */ 606275970Scy}; 607275970Scy 608275970Scy/** 609275970Scy Triggers bufferevent data callbacks. 610275970Scy 611275970Scy The function will honor watermarks unless options contain 612275970Scy BEV_TRIG_IGNORE_WATERMARKS. If the options contain BEV_OPT_DEFER_CALLBACKS, 613275970Scy the callbacks are deferred. 614275970Scy 615275970Scy @param bufev the bufferevent object 616275970Scy @param iotype either EV_READ or EV_WRITE or both. 617275970Scy @param options 618275970Scy */ 619275970ScyEVENT2_EXPORT_SYMBOL 620275970Scyvoid bufferevent_trigger(struct bufferevent *bufev, short iotype, 621275970Scy int options); 622275970Scy 623275970Scy/** 624275970Scy Triggers the bufferevent event callback. 625275970Scy 626275970Scy If the options contain BEV_OPT_DEFER_CALLBACKS, the callbacks are deferred. 627275970Scy 628275970Scy @param bufev the bufferevent object 629275970Scy @param what the flags to pass onto the event callback 630275970Scy @param options 631275970Scy */ 632275970ScyEVENT2_EXPORT_SYMBOL 633275970Scyvoid bufferevent_trigger_event(struct bufferevent *bufev, short what, 634275970Scy int options); 635275970Scy 636275970Scy/** 637275970Scy @name Filtering support 638275970Scy 639275970Scy @{ 640275970Scy*/ 641275970Scy/** 642275970Scy Values that filters can return. 643275970Scy */ 644275970Scyenum bufferevent_filter_result { 645275970Scy /** everything is okay */ 646275970Scy BEV_OK = 0, 647275970Scy 648275970Scy /** the filter needs to read more data before output */ 649275970Scy BEV_NEED_MORE = 1, 650275970Scy 651275970Scy /** the filter encountered a critical error, no further data 652275970Scy can be processed. */ 653275970Scy BEV_ERROR = 2 654275970Scy}; 655275970Scy 656275970Scy/** A callback function to implement a filter for a bufferevent. 657275970Scy 658275970Scy @param src An evbuffer to drain data from. 659275970Scy @param dst An evbuffer to add data to. 660275970Scy @param limit A suggested upper bound of bytes to write to dst. 661275970Scy The filter may ignore this value, but doing so means that 662275970Scy it will overflow the high-water mark associated with dst. 663275970Scy -1 means "no limit". 664275970Scy @param mode Whether we should write data as may be convenient 665275970Scy (BEV_NORMAL), or flush as much data as we can (BEV_FLUSH), 666275970Scy or flush as much as we can, possibly including an end-of-stream 667275970Scy marker (BEV_FINISH). 668275970Scy @param ctx A user-supplied pointer. 669275970Scy 670275970Scy @return BEV_OK if we wrote some data; BEV_NEED_MORE if we can't 671275970Scy produce any more output until we get some input; and BEV_ERROR 672275970Scy on an error. 673275970Scy */ 674275970Scytypedef enum bufferevent_filter_result (*bufferevent_filter_cb)( 675275970Scy struct evbuffer *src, struct evbuffer *dst, ev_ssize_t dst_limit, 676275970Scy enum bufferevent_flush_mode mode, void *ctx); 677275970Scy 678275970Scy/** 679275970Scy Allocate a new filtering bufferevent on top of an existing bufferevent. 680275970Scy 681275970Scy @param underlying the underlying bufferevent. 682275970Scy @param input_filter The filter to apply to data we read from the underlying 683275970Scy bufferevent 684275970Scy @param output_filter The filer to apply to data we write to the underlying 685275970Scy bufferevent 686275970Scy @param options A bitfield of bufferevent options. 687275970Scy @param free_context A function to use to free the filter context when 688275970Scy this bufferevent is freed. 689275970Scy @param ctx A context pointer to pass to the filter functions. 690275970Scy */ 691275970ScyEVENT2_EXPORT_SYMBOL 692275970Scystruct bufferevent * 693275970Scybufferevent_filter_new(struct bufferevent *underlying, 694275970Scy bufferevent_filter_cb input_filter, 695275970Scy bufferevent_filter_cb output_filter, 696275970Scy int options, 697275970Scy void (*free_context)(void *), 698275970Scy void *ctx); 699275970Scy/**@}*/ 700275970Scy 701275970Scy/** 702275970Scy Allocate a pair of linked bufferevents. The bufferevents behave as would 703275970Scy two bufferevent_sock instances connected to opposite ends of a 704275970Scy socketpair(), except that no internal socketpair is allocated. 705275970Scy 706275970Scy @param base The event base to associate with the socketpair. 707275970Scy @param options A set of options for this bufferevent 708275970Scy @param pair A pointer to an array to hold the two new bufferevent objects. 709275970Scy @return 0 on success, -1 on failure. 710275970Scy */ 711275970ScyEVENT2_EXPORT_SYMBOL 712275970Scyint bufferevent_pair_new(struct event_base *base, int options, 713275970Scy struct bufferevent *pair[2]); 714275970Scy 715275970Scy/** 716275970Scy Given one bufferevent returned by bufferevent_pair_new(), returns the 717275970Scy other one if it still exists. Otherwise returns NULL. 718275970Scy */ 719275970ScyEVENT2_EXPORT_SYMBOL 720275970Scystruct bufferevent *bufferevent_pair_get_partner(struct bufferevent *bev); 721275970Scy 722275970Scy/** 723275970Scy Abstract type used to configure rate-limiting on a bufferevent or a group 724275970Scy of bufferevents. 725275970Scy */ 726275970Scystruct ev_token_bucket_cfg; 727275970Scy 728275970Scy/** 729275970Scy A group of bufferevents which are configured to respect the same rate 730275970Scy limit. 731275970Scy*/ 732275970Scystruct bufferevent_rate_limit_group; 733275970Scy 734275970Scy/** Maximum configurable rate- or burst-limit. */ 735275970Scy#define EV_RATE_LIMIT_MAX EV_SSIZE_MAX 736275970Scy 737275970Scy/** 738275970Scy Initialize and return a new object to configure the rate-limiting behavior 739275970Scy of bufferevents. 740275970Scy 741275970Scy @param read_rate The maximum number of bytes to read per tick on 742275970Scy average. 743275970Scy @param read_burst The maximum number of bytes to read in any single tick. 744275970Scy @param write_rate The maximum number of bytes to write per tick on 745275970Scy average. 746275970Scy @param write_burst The maximum number of bytes to write in any single tick. 747275970Scy @param tick_len The length of a single tick. Defaults to one second. 748275970Scy Any fractions of a millisecond are ignored. 749275970Scy 750275970Scy Note that all rate-limits hare are currently best-effort: future versions 751275970Scy of Libevent may implement them more tightly. 752275970Scy */ 753275970ScyEVENT2_EXPORT_SYMBOL 754275970Scystruct ev_token_bucket_cfg *ev_token_bucket_cfg_new( 755275970Scy size_t read_rate, size_t read_burst, 756275970Scy size_t write_rate, size_t write_burst, 757275970Scy const struct timeval *tick_len); 758275970Scy 759275970Scy/** Free all storage held in 'cfg'. 760275970Scy 761275970Scy Note: 'cfg' is not currently reference-counted; it is not safe to free it 762275970Scy until no bufferevent is using it. 763275970Scy */ 764275970ScyEVENT2_EXPORT_SYMBOL 765275970Scyvoid ev_token_bucket_cfg_free(struct ev_token_bucket_cfg *cfg); 766275970Scy 767275970Scy/** 768275970Scy Set the rate-limit of a the bufferevent 'bev' to the one specified in 769275970Scy 'cfg'. If 'cfg' is NULL, disable any per-bufferevent rate-limiting on 770275970Scy 'bev'. 771275970Scy 772275970Scy Note that only some bufferevent types currently respect rate-limiting. 773275970Scy They are: socket-based bufferevents (normal and IOCP-based), and SSL-based 774275970Scy bufferevents. 775275970Scy 776275970Scy Return 0 on sucess, -1 on failure. 777275970Scy */ 778275970ScyEVENT2_EXPORT_SYMBOL 779275970Scyint bufferevent_set_rate_limit(struct bufferevent *bev, 780275970Scy struct ev_token_bucket_cfg *cfg); 781275970Scy 782275970Scy/** 783275970Scy Create a new rate-limit group for bufferevents. A rate-limit group 784275970Scy constrains the maximum number of bytes sent and received, in toto, 785275970Scy by all of its bufferevents. 786275970Scy 787275970Scy @param base An event_base to run any necessary timeouts for the group. 788275970Scy Note that all bufferevents in the group do not necessarily need to share 789275970Scy this event_base. 790275970Scy @param cfg The rate-limit for this group. 791275970Scy 792275970Scy Note that all rate-limits hare are currently best-effort: future versions 793275970Scy of Libevent may implement them more tightly. 794275970Scy 795275970Scy Note also that only some bufferevent types currently respect rate-limiting. 796275970Scy They are: socket-based bufferevents (normal and IOCP-based), and SSL-based 797275970Scy bufferevents. 798275970Scy */ 799275970ScyEVENT2_EXPORT_SYMBOL 800275970Scystruct bufferevent_rate_limit_group *bufferevent_rate_limit_group_new( 801275970Scy struct event_base *base, 802275970Scy const struct ev_token_bucket_cfg *cfg); 803275970Scy/** 804275970Scy Change the rate-limiting settings for a given rate-limiting group. 805275970Scy 806275970Scy Return 0 on success, -1 on failure. 807275970Scy*/ 808275970ScyEVENT2_EXPORT_SYMBOL 809275970Scyint bufferevent_rate_limit_group_set_cfg( 810275970Scy struct bufferevent_rate_limit_group *, 811275970Scy const struct ev_token_bucket_cfg *); 812275970Scy 813275970Scy/** 814275970Scy Change the smallest quantum we're willing to allocate to any single 815275970Scy bufferevent in a group for reading or writing at a time. 816275970Scy 817275970Scy The rationale is that, because of TCP/IP protocol overheads and kernel 818275970Scy behavior, if a rate-limiting group is so tight on bandwidth that you're 819275970Scy only willing to send 1 byte per tick per bufferevent, you might instead 820275970Scy want to batch up the reads and writes so that you send N bytes per 821275970Scy 1/N of the bufferevents (chosen at random) each tick, so you still wind 822275970Scy up send 1 byte per tick per bufferevent on average, but you don't send 823275970Scy so many tiny packets. 824275970Scy 825275970Scy The default min-share is currently 64 bytes. 826275970Scy 827275970Scy Returns 0 on success, -1 on faulre. 828275970Scy */ 829275970ScyEVENT2_EXPORT_SYMBOL 830275970Scyint bufferevent_rate_limit_group_set_min_share( 831275970Scy struct bufferevent_rate_limit_group *, size_t); 832275970Scy 833275970Scy/** 834275970Scy Free a rate-limiting group. The group must have no members when 835275970Scy this function is called. 836275970Scy*/ 837275970ScyEVENT2_EXPORT_SYMBOL 838275970Scyvoid bufferevent_rate_limit_group_free(struct bufferevent_rate_limit_group *); 839275970Scy 840275970Scy/** 841275970Scy Add 'bev' to the list of bufferevents whose aggregate reading and writing 842275970Scy is restricted by 'g'. If 'g' is NULL, remove 'bev' from its current group. 843275970Scy 844275970Scy A bufferevent may belong to no more than one rate-limit group at a time. 845275970Scy If 'bev' is already a member of a group, it will be removed from its old 846275970Scy group before being added to 'g'. 847275970Scy 848275970Scy Return 0 on success and -1 on failure. 849275970Scy */ 850275970ScyEVENT2_EXPORT_SYMBOL 851275970Scyint bufferevent_add_to_rate_limit_group(struct bufferevent *bev, 852275970Scy struct bufferevent_rate_limit_group *g); 853275970Scy 854275970Scy/** Remove 'bev' from its current rate-limit group (if any). */ 855275970ScyEVENT2_EXPORT_SYMBOL 856275970Scyint bufferevent_remove_from_rate_limit_group(struct bufferevent *bev); 857275970Scy 858275970Scy/** 859275970Scy Set the size limit for single read operation. 860275970Scy 861275970Scy Set to 0 for a reasonable default. 862275970Scy 863275970Scy Return 0 on success and -1 on failure. 864275970Scy */ 865275970ScyEVENT2_EXPORT_SYMBOL 866275970Scyint bufferevent_set_max_single_read(struct bufferevent *bev, size_t size); 867275970Scy 868275970Scy/** 869275970Scy Set the size limit for single write operation. 870275970Scy 871275970Scy Set to 0 for a reasonable default. 872275970Scy 873275970Scy Return 0 on success and -1 on failure. 874275970Scy */ 875275970ScyEVENT2_EXPORT_SYMBOL 876275970Scyint bufferevent_set_max_single_write(struct bufferevent *bev, size_t size); 877275970Scy 878275970Scy/** Get the current size limit for single read operation. */ 879275970ScyEVENT2_EXPORT_SYMBOL 880275970Scyev_ssize_t bufferevent_get_max_single_read(struct bufferevent *bev); 881275970Scy 882275970Scy/** Get the current size limit for single write operation. */ 883275970ScyEVENT2_EXPORT_SYMBOL 884275970Scyev_ssize_t bufferevent_get_max_single_write(struct bufferevent *bev); 885275970Scy 886275970Scy/** 887275970Scy @name Rate limit inspection 888275970Scy 889275970Scy Return the current read or write bucket size for a bufferevent. 890275970Scy If it is not configured with a per-bufferevent ratelimit, return 891275970Scy EV_SSIZE_MAX. This function does not inspect the group limit, if any. 892275970Scy Note that it can return a negative value if the bufferevent has been 893275970Scy made to read or write more than its limit. 894275970Scy 895275970Scy @{ 896275970Scy */ 897275970ScyEVENT2_EXPORT_SYMBOL 898275970Scyev_ssize_t bufferevent_get_read_limit(struct bufferevent *bev); 899275970ScyEVENT2_EXPORT_SYMBOL 900275970Scyev_ssize_t bufferevent_get_write_limit(struct bufferevent *bev); 901275970Scy/*@}*/ 902275970Scy 903275970ScyEVENT2_EXPORT_SYMBOL 904275970Scyev_ssize_t bufferevent_get_max_to_read(struct bufferevent *bev); 905275970ScyEVENT2_EXPORT_SYMBOL 906275970Scyev_ssize_t bufferevent_get_max_to_write(struct bufferevent *bev); 907275970Scy 908275970ScyEVENT2_EXPORT_SYMBOL 909275970Scyconst struct ev_token_bucket_cfg *bufferevent_get_token_bucket_cfg(const struct bufferevent * bev); 910275970Scy 911275970Scy/** 912275970Scy @name Group Rate limit inspection 913275970Scy 914275970Scy Return the read or write bucket size for a bufferevent rate limit 915275970Scy group. Note that it can return a negative value if bufferevents in 916275970Scy the group have been made to read or write more than their limits. 917275970Scy 918275970Scy @{ 919275970Scy */ 920275970ScyEVENT2_EXPORT_SYMBOL 921275970Scyev_ssize_t bufferevent_rate_limit_group_get_read_limit( 922275970Scy struct bufferevent_rate_limit_group *); 923275970ScyEVENT2_EXPORT_SYMBOL 924275970Scyev_ssize_t bufferevent_rate_limit_group_get_write_limit( 925275970Scy struct bufferevent_rate_limit_group *); 926275970Scy/*@}*/ 927275970Scy 928275970Scy/** 929275970Scy @name Rate limit manipulation 930275970Scy 931275970Scy Subtract a number of bytes from a bufferevent's read or write bucket. 932275970Scy The decrement value can be negative, if you want to manually refill 933275970Scy the bucket. If the change puts the bucket above or below zero, the 934275970Scy bufferevent will resume or suspend reading writing as appropriate. 935275970Scy These functions make no change in the buckets for the bufferevent's 936275970Scy group, if any. 937275970Scy 938275970Scy Returns 0 on success, -1 on internal error. 939275970Scy 940275970Scy @{ 941275970Scy */ 942275970ScyEVENT2_EXPORT_SYMBOL 943275970Scyint bufferevent_decrement_read_limit(struct bufferevent *bev, ev_ssize_t decr); 944275970ScyEVENT2_EXPORT_SYMBOL 945275970Scyint bufferevent_decrement_write_limit(struct bufferevent *bev, ev_ssize_t decr); 946275970Scy/*@}*/ 947275970Scy 948275970Scy/** 949275970Scy @name Group rate limit manipulation 950275970Scy 951275970Scy Subtract a number of bytes from a bufferevent rate-limiting group's 952275970Scy read or write bucket. The decrement value can be negative, if you 953275970Scy want to manually refill the bucket. If the change puts the bucket 954275970Scy above or below zero, the bufferevents in the group will resume or 955275970Scy suspend reading writing as appropriate. 956275970Scy 957275970Scy Returns 0 on success, -1 on internal error. 958275970Scy 959275970Scy @{ 960275970Scy */ 961275970ScyEVENT2_EXPORT_SYMBOL 962275970Scyint bufferevent_rate_limit_group_decrement_read( 963275970Scy struct bufferevent_rate_limit_group *, ev_ssize_t); 964275970ScyEVENT2_EXPORT_SYMBOL 965275970Scyint bufferevent_rate_limit_group_decrement_write( 966275970Scy struct bufferevent_rate_limit_group *, ev_ssize_t); 967275970Scy/*@}*/ 968275970Scy 969275970Scy 970275970Scy/** 971275970Scy * Inspect the total bytes read/written on a group. 972275970Scy * 973275970Scy * Set the variable pointed to by total_read_out to the total number of bytes 974275970Scy * ever read on grp, and the variable pointed to by total_written_out to the 975275970Scy * total number of bytes ever written on grp. */ 976275970ScyEVENT2_EXPORT_SYMBOL 977275970Scyvoid bufferevent_rate_limit_group_get_totals( 978275970Scy struct bufferevent_rate_limit_group *grp, 979275970Scy ev_uint64_t *total_read_out, ev_uint64_t *total_written_out); 980275970Scy 981275970Scy/** 982275970Scy * Reset the total bytes read/written on a group. 983275970Scy * 984275970Scy * Reset the number of bytes read or written on grp as given by 985275970Scy * bufferevent_rate_limit_group_reset_totals(). */ 986275970ScyEVENT2_EXPORT_SYMBOL 987275970Scyvoid 988275970Scybufferevent_rate_limit_group_reset_totals( 989275970Scy struct bufferevent_rate_limit_group *grp); 990275970Scy 991275970Scy#ifdef __cplusplus 992275970Scy} 993275970Scy#endif 994275970Scy 995275970Scy#endif /* EVENT2_BUFFEREVENT_H_INCLUDED_ */ 996