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