OpenMPI  0.1.1
bufferevent.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu>
3  * Copyright (c) 2007-2010 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 and call the read callback.
48  When writing is enabled, the bufferevent will try to write data onto its
49  file descriptor when writing is enabled, and call the write callback
50  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.
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. */
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  */
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 */
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,
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  */
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 */
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  */
526  /** everything is okay */
527  BEV_OK = 0,
528 
529  /** the filter needs to read more data before output */
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  */
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  */
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 */
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  */
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  */
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  */
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  */
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 */
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  */
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 */
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  */
722  struct bufferevent_rate_limit_group *g);
723 
724 /** Remove 'bev' from its current rate-limit group (if any). */
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 GrouprRate 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(
756 ev_ssize_t bufferevent_rate_limit_group_get_write_limit(
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. */
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
815  struct bufferevent_rate_limit_group *grp);
816 
817 #ifdef __cplusplus
818 }
819 #endif
820 
821 #endif /* _EVENT2_BUFFEREVENT_H_ */
Definition: evdns.c:286
void bufferevent_setcb(struct bufferevent *bufev, bufferevent_data_cb readcb, bufferevent_data_cb writecb, bufferevent_event_cb eventcb, void *cbarg)
Changes the callbacks for a bufferevent.
Definition: bufferevent.c:341
void bufferevent_setwatermark(struct bufferevent *bufev, short events, size_t lowmark, size_t highmark)
Sets the watermarks for read and write events.
Definition: bufferevent.c:514
void(* bufferevent_event_cb)(struct bufferevent *bev, short what, void *ctx)
An event/error callback for a bufferevent.
Definition: bufferevent.h:145
evutil_socket_t bufferevent_getfd(struct bufferevent *bufev)
Returns the file descriptor associated with a bufferevent, or -1 if no file descriptor is associated ...
Definition: bufferevent.c:741
int bufferevent_rate_limit_group_set_min_share(struct bufferevent_rate_limit_group *, size_t)
Change the smallest quantum we're willing to allocate to any single bufferevent in a group for readin...
Definition: bufferevent_ratelim.c:678
int bufferevent_socket_get_dns_error(struct bufferevent *bev)
Return the error code for the last failed DNS lookup attempt made by bufferevent_socket_connect_hostn...
Definition: bufferevent_sock.c:502
encountered EOF on read or done sending data
Definition: bufferevent.h:498
Definition: bufferevent-internal.h:66
the filter encountered a critical error, no further data can be processed.
Definition: bufferevent.h:530
int bufferevent_flush(struct bufferevent *bufev, short iotype, enum bufferevent_flush_mode mode)
Triggers the bufferevent to produce more data if possible.
Definition: bufferevent.c:562
int bufferevent_set_timeouts(struct bufferevent *bufev, const struct timeval *timeout_read, const struct timeval *timeout_write)
Set the read and write timeout for a bufferevent.
Definition: bufferevent.c:427
struct bufferevent * bufferevent_pair_get_partner(struct bufferevent *bev)
Given one bufferevent returned by bufferevent_pair_new(), returns the other one if it still exists...
Definition: bufferevent_pair.c:310
Structure to represent a single event.
Definition: event_struct.h:87
usually set when processing data
Definition: bufferevent.h:492
enum bufferevent_filter_result(* bufferevent_filter_cb)(struct evbuffer *src, struct evbuffer *dst, ev_ssize_t dst_limit, enum bufferevent_flush_mode mode, void *ctx)
A callback function to implement a filter for a bufferevent.
Definition: bufferevent.h:551
int bufferevent_write(struct bufferevent *bufev, const void *data, size_t size)
Write data to a bufferevent buffer.
Definition: bufferevent.c:374
size_t write_rate
How many bytes are we willing to write on average per tick?
Definition: ratelim-internal.h:54
void bufferevent_rate_limit_group_get_totals(struct bufferevent_rate_limit_group *grp, ev_uint64_t *total_read_out, ev_uint64_t *total_written_out)
Inspect the total bytes read/written on a group.
Definition: bufferevent_ratelim.c:966
int bufferevent_setfd(struct bufferevent *bufev, evutil_socket_t fd)
Changes the file descriptor on which the bufferevent operates.
Definition: bufferevent.c:728
int bufferevent_rate_limit_group_set_cfg(struct bufferevent_rate_limit_group *, const struct ev_token_bucket_cfg *)
Change the rate-limiting settings for a given rate-limiting group.
Definition: bufferevent_ratelim.c:650
If set, callbacks are executed without locks being held on the bufferevent.
Definition: bufferevent.h:164
everything is okay
Definition: bufferevent.h:523
the filter needs to read more data before output
Definition: bufferevent.h:526
#define evutil_socket_t
A type wide enough to hold the output of "socket()" or "accept()".
Definition: util.h:278
int bufferevent_set_rate_limit(struct bufferevent *bev, struct ev_token_bucket_cfg *cfg)
Set the rate-limit of a the bufferevent 'bev' to the one specified in 'cfg'.
Definition: bufferevent_ratelim.c:542
void bufferevent_unlock(struct bufferevent *bufev)
Release the lock on a bufferevent.
Definition: bufferevent.c:857
int bufferevent_remove_from_rate_limit_group(struct bufferevent *bev)
Remove 'bev' from its current rate-limit group (if any).
Definition: bufferevent_ratelim.c:748
size_t read_rate
How many bytes are we willing to read on average per tick?
Definition: ratelim-internal.h:50
Definition: evbuffer-internal.h:78
int bufferevent_add_to_rate_limit_group(struct bufferevent *bev, struct bufferevent_rate_limit_group *g)
Add 'bev' to the list of bufferevents whose aggregate reading and writing is restricted by 'g'...
Definition: bufferevent_ratelim.c:701
Configuration info for a token bucket or set of token buckets.
Definition: ratelim-internal.h:48
void ev_token_bucket_cfg_free(struct ev_token_bucket_cfg *cfg)
Free all storage held in 'cfg'.
Definition: bufferevent_ratelim.c:173
If set, callbacks are run deferred in the event loop.
Definition: bufferevent.h:158
int bufferevent_write_buffer(struct bufferevent *bufev, struct evbuffer *buf)
Write data from an evbuffer to a bufferevent buffer.
Definition: bufferevent.c:383
Common convenience functions for cross-platform portability and related socket manipulations.
struct event_base * bufferevent_get_base(struct bufferevent *bev)
Return the event_base used by a bufferevent.
Definition: bufferevent.c:368
int bufferevent_disable(struct bufferevent *bufev, short event)
Disable a bufferevent.
Definition: bufferevent.c:495
struct evbuffer * bufferevent_get_output(struct bufferevent *bufev)
Returns the output buffer.
Definition: bufferevent.c:362
If set, and threading is enabled, operations on this bufferevent are protected by a lock...
Definition: bufferevent.h:155
int bufferevent_socket_connect(struct bufferevent *, struct sockaddr *, int)
Launch a connect() attempt with a socket-based bufferevent.
Definition: bufferevent_sock.c:345
int bufferevent_socket_connect_hostname(struct bufferevent *, struct evdns_base *, int, const char *, int)
Resolve the hostname 'hostname' and connect to it as with bufferevent_socket_connect().
Definition: bufferevent_sock.c:460
struct bufferevent_rate_limit_group * bufferevent_rate_limit_group_new(struct event_base *base, const struct ev_token_bucket_cfg *cfg)
Create a new rate-limit group for bufferevents.
Definition: bufferevent_ratelim.c:621
If set, we close the underlying file descriptor/bufferevent/whatever when this bufferevent is freed...
Definition: bufferevent.h:151
struct evbuffer * bufferevent_get_input(struct bufferevent *bufev)
Returns the input buffer.
Definition: bufferevent.c:356
int bufferevent_enable(struct bufferevent *bufev, short event)
Enable a bufferevent.
Definition: bufferevent.c:404
struct bufferevent * bufferevent_get_underlying(struct bufferevent *bufev)
Returns the underlying bufferevent associated with a bufferevent (if the bufferevent is a wrapper)...
Definition: bufferevent.c:764
bufferevent_flush_mode
Flags that can be passed into filters to let them know how to deal with the incoming data...
Definition: bufferevent.h:490
int bufferevent_base_set(struct event_base *base, struct bufferevent *bufev)
Assign a bufferevent to a specific event_base.
Definition: bufferevent_sock.c:655
void(* bufferevent_data_cb)(struct bufferevent *bev, void *ctx)
A read or write callback for a bufferevent.
Definition: bufferevent.h:129
size_t bufferevent_read(struct bufferevent *bufev, void *data, size_t size)
Read data from a bufferevent buffer.
Definition: bufferevent.c:392
Shared implementation of a bufferevent.
Definition: bufferevent_struct.h:70
want to checkpoint all data sent.
Definition: bufferevent.h:495
struct ev_token_bucket_cfg * ev_token_bucket_cfg_new(size_t read_rate, size_t read_burst, size_t write_rate, size_t write_burst, const struct timeval *tick_len)
Initialize and return a new object to configure the rate-limiting behavior of bufferevents.
Definition: bufferevent_ratelim.c:141
void bufferevent_lock(struct bufferevent *bufev)
Acquire the lock on a bufferevent.
Definition: bufferevent.c:851
int bufferevent_pair_new(struct event_base *base, int options, struct bufferevent *pair[2])
Allocate a pair of linked bufferevents.
Definition: bufferevent_pair.c:113
struct bufferevent * bufferevent_filter_new(struct bufferevent *underlying, bufferevent_filter_cb input_filter, bufferevent_filter_cb output_filter, int options, void(*free_context)(void *), void *ctx)
Allocate a new filtering bufferevent on top of an existing bufferevent.
Definition: bufferevent_filter.c:161
void bufferevent_free(struct bufferevent *bufev)
Deallocate the storage associated with a bufferevent structure.
Definition: bufferevent.c:673
bufferevent_options
Options that can be specified when creating a bufferevent.
Definition: bufferevent.h:148
Definition: event-internal.h:167
bufferevent_filter_result
Values that filters can return.
Definition: bufferevent.h:521
struct bufferevent * bufferevent_socket_new(struct event_base *base, evutil_socket_t fd, int options)
Create a new socket bufferevent over an existing socket.
Definition: bufferevent_sock.c:310
int bufferevent_priority_set(struct bufferevent *bufev, int pri)
Assign a priority to a bufferevent.
Definition: bufferevent_sock.c:634
short bufferevent_get_enabled(struct bufferevent *bufev)
Return the events that are enabled on a given bufferevent.
Definition: bufferevent.c:754
void bufferevent_rate_limit_group_reset_totals(struct bufferevent_rate_limit_group *grp)
Reset the total bytes read/written on a group.
Definition: bufferevent_ratelim.c:977
int bufferevent_read_buffer(struct bufferevent *bufev, struct evbuffer *buf)
Read data from a bufferevent buffer into an evbuffer.
Definition: bufferevent.c:398
void bufferevent_rate_limit_group_free(struct bufferevent_rate_limit_group *)
Free a rate-limiting group.
Definition: bufferevent_ratelim.c:690