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