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