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