2 * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu>
3 * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
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.
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.
27 #ifndef EVENT2_BUFFEREVENT_H_INCLUDED_
28 #define EVENT2_BUFFEREVENT_H_INCLUDED_
31 @file event2/bufferevent.h
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
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
43 Once initialized, the bufferevent structure can be used repeatedly
44 with bufferevent_enable() and bufferevent_disable().
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.
52 Bufferevents come in several flavors, including:
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>
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>
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>
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>
77 #include <event2/visibility.h>
83 #include <event2/event-config.h>
84 #ifdef EVENT__HAVE_SYS_TYPES_H
85 #include <sys/types.h>
87 #ifdef EVENT__HAVE_SYS_TIME_H
92 #include <event2/util.h>
94 /** @name Bufferevent event codes
96 These flags are passed as arguments to a bufferevent's event callback.
100 #define BEV_EVENT_READING 0x01 /**< error encountered while reading */
101 #define BEV_EVENT_WRITING 0x02 /**< error encountered while writing */
102 #define BEV_EVENT_EOF 0x10 /**< eof file reached */
103 #define BEV_EVENT_ERROR 0x20 /**< unrecoverable error encountered */
104 #define BEV_EVENT_TIMEOUT 0x40 /**< user-specified timeout reached */
105 #define BEV_EVENT_CONNECTED 0x80 /**< connect operation finished. */
109 An opaque type for handling buffered IO
111 @see event2/bufferevent.h
114 #ifdef EVENT_IN_DOXYGEN_
123 A read or write callback for a bufferevent.
125 The read callback is triggered when new data arrives in the input
126 buffer and the amount of readable data exceed the low watermark
127 which is 0 by default.
129 The write callback is triggered if the write buffer has been
130 exhausted or fell below its low watermark.
132 @param bev the bufferevent that triggered the callback
133 @param ctx the user-specified context for this bufferevent
135 typedef void (*bufferevent_data_cb)(struct bufferevent *bev, void *ctx);
138 An event/error callback for a bufferevent.
140 The event callback is triggered if either an EOF condition or another
141 unrecoverable error was encountered.
143 For bufferevents with deferred callbacks, this is a bitwise OR of all errors
144 that have happened on the bufferevent since the last callback invocation.
146 @param bev the bufferevent for which the error condition was reached
147 @param what a conjunction of flags: BEV_EVENT_READING or BEV_EVENT_WRITING
148 to indicate if the error was encountered on the read or write path,
149 and one of the following flags: BEV_EVENT_EOF, BEV_EVENT_ERROR,
150 BEV_EVENT_TIMEOUT, BEV_EVENT_CONNECTED.
152 @param ctx the user-specified context for this bufferevent
154 typedef void (*bufferevent_event_cb)(struct bufferevent *bev, short what, void *ctx);
156 /** Options that can be specified when creating a bufferevent */
157 enum bufferevent_options {
158 /** If set, we close the underlying file
159 * descriptor/bufferevent/whatever when this bufferevent is freed. */
160 BEV_OPT_CLOSE_ON_FREE = (1<<0),
162 /** If set, and threading is enabled, operations on this bufferevent
163 * are protected by a lock */
164 BEV_OPT_THREADSAFE = (1<<1),
166 /** If set, callbacks are run deferred in the event loop. */
167 BEV_OPT_DEFER_CALLBACKS = (1<<2),
169 /** If set, callbacks are executed without locks being held on the
170 * bufferevent. This option currently requires that
171 * BEV_OPT_DEFER_CALLBACKS also be set; a future version of Libevent
172 * might remove the requirement.*/
173 BEV_OPT_UNLOCK_CALLBACKS = (1<<3)
177 Create a new socket bufferevent over an existing socket.
179 @param base the event base to associate with the new bufferevent.
180 @param fd the file descriptor from which data is read and written to.
181 This file descriptor is not allowed to be a pipe(2).
182 It is safe to set the fd to -1, so long as you later
183 set it with bufferevent_setfd or bufferevent_socket_connect().
184 @param options Zero or more BEV_OPT_* flags
185 @return a pointer to a newly allocated bufferevent struct, or NULL if an
187 @see bufferevent_free()
190 struct bufferevent *bufferevent_socket_new(struct event_base *base, evutil_socket_t fd, int options);
193 Launch a connect() attempt with a socket-based bufferevent.
195 When the connect succeeds, the eventcb will be invoked with
196 BEV_EVENT_CONNECTED set.
198 If the bufferevent does not already have a socket set, we allocate a new
199 socket here and make it nonblocking before we begin.
201 If no address is provided, we assume that the socket is already connecting,
202 and configure the bufferevent so that a BEV_EVENT_CONNECTED event will be
203 yielded when it is done connecting.
205 @param bufev an existing bufferevent allocated with
206 bufferevent_socket_new().
207 @param addr the address we should connect to
208 @param socklen The length of the address
209 @return 0 on success, -1 on failure.
212 int bufferevent_socket_connect(struct bufferevent *, struct sockaddr *, int);
216 Resolve the hostname 'hostname' and connect to it as with
217 bufferevent_socket_connect().
219 @param bufev An existing bufferevent allocated with bufferevent_socket_new()
220 @param evdns_base Optionally, an evdns_base to use for resolving hostnames
221 asynchronously. May be set to NULL for a blocking resolve.
222 @param family A preferred address family to resolve addresses to, or
223 AF_UNSPEC for no preference. Only AF_INET, AF_INET6, and AF_UNSPEC are
225 @param hostname The hostname to resolve; see below for notes on recognized
227 @param port The port to connect to on the resolved address.
228 @return 0 if successful, -1 on failure.
230 Recognized hostname formats are:
232 www.example.com (hostname)
233 1.2.3.4 (ipv4address)
235 [::1] ([ipv6address])
237 Performance note: If you do not provide an evdns_base, this function
238 may block while it waits for a DNS response. This is probably not
242 int bufferevent_socket_connect_hostname(struct bufferevent *,
243 struct evdns_base *, int, const char *, int);
246 Return the error code for the last failed DNS lookup attempt made by
247 bufferevent_socket_connect_hostname().
249 @param bev The bufferevent object.
250 @return DNS error code.
251 @see evutil_gai_strerror()
254 int bufferevent_socket_get_dns_error(struct bufferevent *bev);
257 Assign a bufferevent to a specific event_base.
259 NOTE that only socket bufferevents support this function.
261 @param base an event_base returned by event_init()
262 @param bufev a bufferevent struct returned by bufferevent_new()
263 or bufferevent_socket_new()
264 @return 0 if successful, or -1 if an error occurred
265 @see bufferevent_new()
268 int bufferevent_base_set(struct event_base *base, struct bufferevent *bufev);
271 Return the event_base used by a bufferevent
274 struct event_base *bufferevent_get_base(struct bufferevent *bev);
277 Assign a priority to a bufferevent.
279 Only supported for socket bufferevents.
281 @param bufev a bufferevent struct
282 @param pri the priority to be assigned
283 @return 0 if successful, or -1 if an error occurred
286 int bufferevent_priority_set(struct bufferevent *bufev, int pri);
289 Return the priority of a bufferevent.
291 Only supported for socket bufferevents
294 int bufferevent_get_priority(const struct bufferevent *bufev);
297 Deallocate the storage associated with a bufferevent structure.
299 If there is pending data to write on the bufferevent, it probably won't be
300 flushed before the bufferevent is freed.
302 @param bufev the bufferevent structure to be freed.
305 void bufferevent_free(struct bufferevent *bufev);
309 Changes the callbacks for a bufferevent.
311 @param bufev the bufferevent object for which to change callbacks
312 @param readcb callback to invoke when there is data to be read, or NULL if
313 no callback is desired
314 @param writecb callback to invoke when the file descriptor is ready for
315 writing, or NULL if no callback is desired
316 @param eventcb callback to invoke when there is an event on the file
318 @param cbarg an argument that will be supplied to each of the callbacks
319 (readcb, writecb, and errorcb)
320 @see bufferevent_new()
323 void bufferevent_setcb(struct bufferevent *bufev,
324 bufferevent_data_cb readcb, bufferevent_data_cb writecb,
325 bufferevent_event_cb eventcb, void *cbarg);
328 Retrieves the callbacks for a bufferevent.
330 @param bufev the bufferevent to examine.
331 @param readcb_ptr if readcb_ptr is nonnull, *readcb_ptr is set to the current
332 read callback for the bufferevent.
333 @param writecb_ptr if writecb_ptr is nonnull, *writecb_ptr is set to the
334 current write callback for the bufferevent.
335 @param eventcb_ptr if eventcb_ptr is nonnull, *eventcb_ptr is set to the
336 current event callback for the bufferevent.
337 @param cbarg_ptr if cbarg_ptr is nonnull, *cbarg_ptr is set to the current
338 callback argument for the bufferevent.
339 @see buffervent_setcb()
342 void bufferevent_getcb(struct bufferevent *bufev,
343 bufferevent_data_cb *readcb_ptr,
344 bufferevent_data_cb *writecb_ptr,
345 bufferevent_event_cb *eventcb_ptr,
349 Changes the file descriptor on which the bufferevent operates.
350 Not supported for all bufferevent types.
352 @param bufev the bufferevent object for which to change the file descriptor
353 @param fd the file descriptor to operate on
356 int bufferevent_setfd(struct bufferevent *bufev, evutil_socket_t fd);
359 Returns the file descriptor associated with a bufferevent, or -1 if
360 no file descriptor is associated with the bufferevent.
363 evutil_socket_t bufferevent_getfd(struct bufferevent *bufev);
366 Returns the underlying bufferevent associated with a bufferevent (if
367 the bufferevent is a wrapper), or NULL if there is no underlying bufferevent.
370 struct bufferevent *bufferevent_get_underlying(struct bufferevent *bufev);
373 Write data to a bufferevent buffer.
375 The bufferevent_write() function can be used to write data to the file
376 descriptor. The data is appended to the output buffer and written to the
377 descriptor automatically as it becomes available for writing.
379 @param bufev the bufferevent to be written to
380 @param data a pointer to the data to be written
381 @param size the length of the data, in bytes
382 @return 0 if successful, or -1 if an error occurred
383 @see bufferevent_write_buffer()
386 int bufferevent_write(struct bufferevent *bufev,
387 const void *data, size_t size);
391 Write data from an evbuffer to a bufferevent buffer. The evbuffer is
392 being drained as a result.
394 @param bufev the bufferevent to be written to
395 @param buf the evbuffer to be written
396 @return 0 if successful, or -1 if an error occurred
397 @see bufferevent_write()
400 int bufferevent_write_buffer(struct bufferevent *bufev, struct evbuffer *buf);
404 Read data from a bufferevent buffer.
406 The bufferevent_read() function is used to read data from the input buffer.
408 @param bufev the bufferevent to be read from
409 @param data pointer to a buffer that will store the data
410 @param size the size of the data buffer, in bytes
411 @return the amount of data read, in bytes.
414 size_t bufferevent_read(struct bufferevent *bufev, void *data, size_t size);
417 Read data from a bufferevent buffer into an evbuffer. This avoids
420 @param bufev the bufferevent to be read from
421 @param buf the evbuffer to which to add data
422 @return 0 if successful, or -1 if an error occurred.
425 int bufferevent_read_buffer(struct bufferevent *bufev, struct evbuffer *buf);
428 Returns the input buffer.
430 The user MUST NOT set the callback on this buffer.
432 @param bufev the bufferevent from which to get the evbuffer
433 @return the evbuffer object for the input buffer
437 struct evbuffer *bufferevent_get_input(struct bufferevent *bufev);
440 Returns the output buffer.
442 The user MUST NOT set the callback on this buffer.
444 When filters are being used, the filters need to be manually
445 triggered if the output buffer was manipulated.
447 @param bufev the bufferevent from which to get the evbuffer
448 @return the evbuffer object for the output buffer
452 struct evbuffer *bufferevent_get_output(struct bufferevent *bufev);
455 Enable a bufferevent.
457 @param bufev the bufferevent to be enabled
458 @param event any combination of EV_READ | EV_WRITE.
459 @return 0 if successful, or -1 if an error occurred
460 @see bufferevent_disable()
463 int bufferevent_enable(struct bufferevent *bufev, short event);
466 Disable a bufferevent.
468 @param bufev the bufferevent to be disabled
469 @param event any combination of EV_READ | EV_WRITE.
470 @return 0 if successful, or -1 if an error occurred
471 @see bufferevent_enable()
474 int bufferevent_disable(struct bufferevent *bufev, short event);
477 Return the events that are enabled on a given bufferevent.
479 @param bufev the bufferevent to inspect
480 @return A combination of EV_READ | EV_WRITE
483 short bufferevent_get_enabled(struct bufferevent *bufev);
486 Set the read and write timeout for a bufferevent.
488 A bufferevent's timeout will fire the first time that the indicated
489 amount of time has elapsed since a successful read or write operation,
490 during which the bufferevent was trying to read or write.
492 (In other words, if reading or writing is disabled, or if the
493 bufferevent's read or write operation has been suspended because
494 there's no data to write, or not enough banwidth, or so on, the
495 timeout isn't active. The timeout only becomes active when we we're
496 willing to actually read or write.)
498 Calling bufferevent_enable or setting a timeout for a bufferevent
499 whose timeout is already pending resets its timeout.
501 If the timeout elapses, the corresponding operation (EV_READ or
502 EV_WRITE) becomes disabled until you re-enable it again. The
503 bufferevent's event callback is called with the
504 BEV_EVENT_TIMEOUT|BEV_EVENT_READING or
505 BEV_EVENT_TIMEOUT|BEV_EVENT_WRITING.
507 @param bufev the bufferevent to be modified
508 @param timeout_read the read timeout, or NULL
509 @param timeout_write the write timeout, or NULL
512 int bufferevent_set_timeouts(struct bufferevent *bufev,
513 const struct timeval *timeout_read, const struct timeval *timeout_write);
516 Sets the watermarks for read and write events.
518 On input, a bufferevent does not invoke the user read callback unless
519 there is at least low watermark data in the buffer. If the read buffer
520 is beyond the high watermark, the bufferevent stops reading from the network.
522 On output, the user write callback is invoked whenever the buffered data
523 falls below the low watermark. Filters that write to this bufev will try
524 not to write more bytes to this buffer than the high watermark would allow,
525 except when flushing.
527 @param bufev the bufferevent to be modified
528 @param events EV_READ, EV_WRITE or both
529 @param lowmark the lower watermark to set
530 @param highmark the high watermark to set
534 void bufferevent_setwatermark(struct bufferevent *bufev, short events,
535 size_t lowmark, size_t highmark);
538 Retrieves the watermarks for read or write events.
539 Returns non-zero if events contains not only EV_READ or EV_WRITE.
540 Returns zero if events equal EV_READ or EV_WRITE
542 @param bufev the bufferevent to be examined
543 @param events EV_READ or EV_WRITE
544 @param lowmark receives the lower watermark if not NULL
545 @param highmark receives the high watermark if not NULL
548 int bufferevent_getwatermark(struct bufferevent *bufev, short events,
549 size_t *lowmark, size_t *highmark);
552 Acquire the lock on a bufferevent. Has no effect if locking was not
553 enabled with BEV_OPT_THREADSAFE.
556 void bufferevent_lock(struct bufferevent *bufev);
559 Release the lock on a bufferevent. Has no effect if locking was not
560 enabled with BEV_OPT_THREADSAFE.
563 void bufferevent_unlock(struct bufferevent *bufev);
566 Flags that can be passed into filters to let them know how to
567 deal with the incoming data.
569 enum bufferevent_flush_mode {
570 /** usually set when processing data */
573 /** want to checkpoint all data sent. */
576 /** encountered EOF on read or done sending data */
581 Triggers the bufferevent to produce more data if possible.
583 @param bufev the bufferevent object
584 @param iotype either EV_READ or EV_WRITE or both.
585 @param mode either BEV_NORMAL or BEV_FLUSH or BEV_FINISHED
586 @return -1 on failure, 0 if no data was produces, 1 if data was produced
589 int bufferevent_flush(struct bufferevent *bufev,
591 enum bufferevent_flush_mode mode);
594 Flags for bufferevent_trigger(_event) that modify when and how to trigger
597 enum bufferevent_trigger_options {
598 /** trigger the callback regardless of the watermarks */
599 BEV_TRIG_IGNORE_WATERMARKS = (1<<16),
601 /** defer even if the callbacks are not */
602 BEV_TRIG_DEFER_CALLBACKS = BEV_OPT_DEFER_CALLBACKS
604 /* (Note: for internal reasons, these need to be disjoint from
605 * bufferevent_options, except when they mean the same thing. */
609 Triggers bufferevent data callbacks.
611 The function will honor watermarks unless options contain
612 BEV_TRIG_IGNORE_WATERMARKS. If the options contain BEV_OPT_DEFER_CALLBACKS,
613 the callbacks are deferred.
615 @param bufev the bufferevent object
616 @param iotype either EV_READ or EV_WRITE or both.
620 void bufferevent_trigger(struct bufferevent *bufev, short iotype,
624 Triggers the bufferevent event callback.
626 If the options contain BEV_OPT_DEFER_CALLBACKS, the callbacks are deferred.
628 @param bufev the bufferevent object
629 @param what the flags to pass onto the event callback
633 void bufferevent_trigger_event(struct bufferevent *bufev, short what,
637 @name Filtering support
642 Values that filters can return.
644 enum bufferevent_filter_result {
645 /** everything is okay */
648 /** the filter needs to read more data before output */
651 /** the filter encountered a critical error, no further data
656 /** A callback function to implement a filter for a bufferevent.
658 @param src An evbuffer to drain data from.
659 @param dst An evbuffer to add data to.
660 @param limit A suggested upper bound of bytes to write to dst.
661 The filter may ignore this value, but doing so means that
662 it will overflow the high-water mark associated with dst.
664 @param mode Whether we should write data as may be convenient
665 (BEV_NORMAL), or flush as much data as we can (BEV_FLUSH),
666 or flush as much as we can, possibly including an end-of-stream
668 @param ctx A user-supplied pointer.
670 @return BEV_OK if we wrote some data; BEV_NEED_MORE if we can't
671 produce any more output until we get some input; and BEV_ERROR
674 typedef enum bufferevent_filter_result (*bufferevent_filter_cb)(
675 struct evbuffer *src, struct evbuffer *dst, ev_ssize_t dst_limit,
676 enum bufferevent_flush_mode mode, void *ctx);
679 Allocate a new filtering bufferevent on top of an existing bufferevent.
681 @param underlying the underlying bufferevent.
682 @param input_filter The filter to apply to data we read from the underlying
684 @param output_filter The filer to apply to data we write to the underlying
686 @param options A bitfield of bufferevent options.
687 @param free_context A function to use to free the filter context when
688 this bufferevent is freed.
689 @param ctx A context pointer to pass to the filter functions.
693 bufferevent_filter_new(struct bufferevent *underlying,
694 bufferevent_filter_cb input_filter,
695 bufferevent_filter_cb output_filter,
697 void (*free_context)(void *),
702 Allocate a pair of linked bufferevents. The bufferevents behave as would
703 two bufferevent_sock instances connected to opposite ends of a
704 socketpair(), except that no internal socketpair is allocated.
706 @param base The event base to associate with the socketpair.
707 @param options A set of options for this bufferevent
708 @param pair A pointer to an array to hold the two new bufferevent objects.
709 @return 0 on success, -1 on failure.
712 int bufferevent_pair_new(struct event_base *base, int options,
713 struct bufferevent *pair[2]);
716 Given one bufferevent returned by bufferevent_pair_new(), returns the
717 other one if it still exists. Otherwise returns NULL.
720 struct bufferevent *bufferevent_pair_get_partner(struct bufferevent *bev);
723 Abstract type used to configure rate-limiting on a bufferevent or a group
726 struct ev_token_bucket_cfg;
729 A group of bufferevents which are configured to respect the same rate
732 struct bufferevent_rate_limit_group;
734 /** Maximum configurable rate- or burst-limit. */
735 #define EV_RATE_LIMIT_MAX EV_SSIZE_MAX
738 Initialize and return a new object to configure the rate-limiting behavior
741 @param read_rate The maximum number of bytes to read per tick on
743 @param read_burst The maximum number of bytes to read in any single tick.
744 @param write_rate The maximum number of bytes to write per tick on
746 @param write_burst The maximum number of bytes to write in any single tick.
747 @param tick_len The length of a single tick. Defaults to one second.
748 Any fractions of a millisecond are ignored.
750 Note that all rate-limits hare are currently best-effort: future versions
751 of Libevent may implement them more tightly.
754 struct ev_token_bucket_cfg *ev_token_bucket_cfg_new(
755 size_t read_rate, size_t read_burst,
756 size_t write_rate, size_t write_burst,
757 const struct timeval *tick_len);
759 /** Free all storage held in 'cfg'.
761 Note: 'cfg' is not currently reference-counted; it is not safe to free it
762 until no bufferevent is using it.
765 void ev_token_bucket_cfg_free(struct ev_token_bucket_cfg *cfg);
768 Set the rate-limit of a the bufferevent 'bev' to the one specified in
769 'cfg'. If 'cfg' is NULL, disable any per-bufferevent rate-limiting on
772 Note that only some bufferevent types currently respect rate-limiting.
773 They are: socket-based bufferevents (normal and IOCP-based), and SSL-based
776 Return 0 on sucess, -1 on failure.
779 int bufferevent_set_rate_limit(struct bufferevent *bev,
780 struct ev_token_bucket_cfg *cfg);
783 Create a new rate-limit group for bufferevents. A rate-limit group
784 constrains the maximum number of bytes sent and received, in toto,
785 by all of its bufferevents.
787 @param base An event_base to run any necessary timeouts for the group.
788 Note that all bufferevents in the group do not necessarily need to share
790 @param cfg The rate-limit for this group.
792 Note that all rate-limits hare are currently best-effort: future versions
793 of Libevent may implement them more tightly.
795 Note also that only some bufferevent types currently respect rate-limiting.
796 They are: socket-based bufferevents (normal and IOCP-based), and SSL-based
800 struct bufferevent_rate_limit_group *bufferevent_rate_limit_group_new(
801 struct event_base *base,
802 const struct ev_token_bucket_cfg *cfg);
804 Change the rate-limiting settings for a given rate-limiting group.
806 Return 0 on success, -1 on failure.
809 int bufferevent_rate_limit_group_set_cfg(
810 struct bufferevent_rate_limit_group *,
811 const struct ev_token_bucket_cfg *);
814 Change the smallest quantum we're willing to allocate to any single
815 bufferevent in a group for reading or writing at a time.
817 The rationale is that, because of TCP/IP protocol overheads and kernel
818 behavior, if a rate-limiting group is so tight on bandwidth that you're
819 only willing to send 1 byte per tick per bufferevent, you might instead
820 want to batch up the reads and writes so that you send N bytes per
821 1/N of the bufferevents (chosen at random) each tick, so you still wind
822 up send 1 byte per tick per bufferevent on average, but you don't send
823 so many tiny packets.
825 The default min-share is currently 64 bytes.
827 Returns 0 on success, -1 on faulre.
830 int bufferevent_rate_limit_group_set_min_share(
831 struct bufferevent_rate_limit_group *, size_t);
834 Free a rate-limiting group. The group must have no members when
835 this function is called.
838 void bufferevent_rate_limit_group_free(struct bufferevent_rate_limit_group *);
841 Add 'bev' to the list of bufferevents whose aggregate reading and writing
842 is restricted by 'g'. If 'g' is NULL, remove 'bev' from its current group.
844 A bufferevent may belong to no more than one rate-limit group at a time.
845 If 'bev' is already a member of a group, it will be removed from its old
846 group before being added to 'g'.
848 Return 0 on success and -1 on failure.
851 int bufferevent_add_to_rate_limit_group(struct bufferevent *bev,
852 struct bufferevent_rate_limit_group *g);
854 /** Remove 'bev' from its current rate-limit group (if any). */
856 int bufferevent_remove_from_rate_limit_group(struct bufferevent *bev);
859 Set the size limit for single read operation.
861 Set to 0 for a reasonable default.
863 Return 0 on success and -1 on failure.
866 int bufferevent_set_max_single_read(struct bufferevent *bev, size_t size);
869 Set the size limit for single write operation.
871 Set to 0 for a reasonable default.
873 Return 0 on success and -1 on failure.
876 int bufferevent_set_max_single_write(struct bufferevent *bev, size_t size);
878 /** Get the current size limit for single read operation. */
880 ev_ssize_t bufferevent_get_max_single_read(struct bufferevent *bev);
882 /** Get the current size limit for single write operation. */
884 ev_ssize_t bufferevent_get_max_single_write(struct bufferevent *bev);
887 @name Rate limit inspection
889 Return the current read or write bucket size for a bufferevent.
890 If it is not configured with a per-bufferevent ratelimit, return
891 EV_SSIZE_MAX. This function does not inspect the group limit, if any.
892 Note that it can return a negative value if the bufferevent has been
893 made to read or write more than its limit.
898 ev_ssize_t bufferevent_get_read_limit(struct bufferevent *bev);
900 ev_ssize_t bufferevent_get_write_limit(struct bufferevent *bev);
904 ev_ssize_t bufferevent_get_max_to_read(struct bufferevent *bev);
906 ev_ssize_t bufferevent_get_max_to_write(struct bufferevent *bev);
909 const struct ev_token_bucket_cfg *bufferevent_get_token_bucket_cfg(const struct bufferevent * bev);
912 @name Group Rate limit inspection
914 Return the read or write bucket size for a bufferevent rate limit
915 group. Note that it can return a negative value if bufferevents in
916 the group have been made to read or write more than their limits.
921 ev_ssize_t bufferevent_rate_limit_group_get_read_limit(
922 struct bufferevent_rate_limit_group *);
924 ev_ssize_t bufferevent_rate_limit_group_get_write_limit(
925 struct bufferevent_rate_limit_group *);
929 @name Rate limit manipulation
931 Subtract a number of bytes from a bufferevent's read or write bucket.
932 The decrement value can be negative, if you want to manually refill
933 the bucket. If the change puts the bucket above or below zero, the
934 bufferevent will resume or suspend reading writing as appropriate.
935 These functions make no change in the buckets for the bufferevent's
938 Returns 0 on success, -1 on internal error.
943 int bufferevent_decrement_read_limit(struct bufferevent *bev, ev_ssize_t decr);
945 int bufferevent_decrement_write_limit(struct bufferevent *bev, ev_ssize_t decr);
949 @name Group rate limit manipulation
951 Subtract a number of bytes from a bufferevent rate-limiting group's
952 read or write bucket. The decrement value can be negative, if you
953 want to manually refill the bucket. If the change puts the bucket
954 above or below zero, the bufferevents in the group will resume or
955 suspend reading writing as appropriate.
957 Returns 0 on success, -1 on internal error.
962 int bufferevent_rate_limit_group_decrement_read(
963 struct bufferevent_rate_limit_group *, ev_ssize_t);
965 int bufferevent_rate_limit_group_decrement_write(
966 struct bufferevent_rate_limit_group *, ev_ssize_t);
971 * Inspect the total bytes read/written on a group.
973 * Set the variable pointed to by total_read_out to the total number of bytes
974 * ever read on grp, and the variable pointed to by total_written_out to the
975 * total number of bytes ever written on grp. */
977 void bufferevent_rate_limit_group_get_totals(
978 struct bufferevent_rate_limit_group *grp,
979 ev_uint64_t *total_read_out, ev_uint64_t *total_written_out);
982 * Reset the total bytes read/written on a group.
984 * Reset the number of bytes read or written on grp as given by
985 * bufferevent_rate_limit_group_reset_totals(). */
988 bufferevent_rate_limit_group_reset_totals(
989 struct bufferevent_rate_limit_group *grp);
995 #endif /* EVENT2_BUFFEREVENT_H_INCLUDED_ */