forked from libevent/libevent-book
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Ref7_evbuffer.txt
817 lines (661 loc) · 26.7 KB
/
Ref7_evbuffer.txt
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
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
include::license.txt[]
:language: C
Evbuffers: utility functionality for buffered IO
------------------------------------------------
Libevent's evbuffer functionality implements a queue of bytes,
optimized for adding data to the end and removing it from the front.
Evbuffers are meant to be generally useful for doing the "buffer"
part of buffered network IO. They do not provide functions to
schedule the IO or trigger the IO when it's ready: that is what
bufferevents do.
The functions in this chapter are declared in event2/buffer.h unless
otherwise noted.
Creating or freeing an evbuffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Interface
[code]
--------
struct evbuffer *evbuffer_new(void);
void evbuffer_free(struct evbuffer *buf);
--------
These functions should be relatively clear: evbuffer_new() allocates
and returns a new empty evbuffer, and evbuffer_free() deletes one and
all of its contents.
These functions have existed since before Libevent 1.0.
Evbuffers and Thread-safety
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Interface
[code]
--------
int evbuffer_enable_locking(struct evbuffer *buf, void *lock);
void evbuffer_lock(struct evbuffer *buf);
void evbuffer_unlock(struct evbuffer *buf);
--------
By default, it is not safe to access an evbuffer from multiple threads
at once. If you need to do this, you can call
evbuffer_enable_locking() on the evbuffer. If its 'lock' argument is
NULL, Libevent allocates a new lock using the lock creation function
that was provided to evthread_set_lock_creation_callback. Otherwise,
it uses the argument as the lock.
The evbuffer_lock() and evbuffer_unlock() functions acquire and
release the lock on an evbuffer respectively. You can use them to
make a set of operations atomic. If locking has not been enabled on
the evbuffer, these functions do nothing.
(Note that you do not need to call evbuffer_lock() and
evbuffer_unlock() around _invididual_ operations: if locking is
enabled on the evbuffer, individual operations are already atomic.
You only need to lock the evbuffer manually when you have more than
one operation that need to execute without another thread butting in.)
These functions were all introduced in Libevent 2.0.1-alpha.
Inspecting an evbuffer
~~~~~~~~~~~~~~~~~~~~~~
.Interface
[code]
--------
size_t evbuffer_get_length(const struct evbuffer *buf);
--------
This function returns the number of bytes stored in an evbuffer.
It was introduced in Libevent 2.0.1-alpha.
.Interface
[code]
--------
size_t evbuffer_get_contiguous_space(const struct evbuffer *buf);
--------
This function returns the number of bytes stored contiguously at the
front of the evbuffer. The bytes in an evbuffer may be stored in
multiple separate chunks of memory; this function returns the number
of bytes currently stored in the _first_ chunk.
It was introduced in Libevent 2.0.1-alpha.
Adding data to an evbuffer
~~~~~~~~~~~~~~~~~~~~~~~~~~
.Interface
[code]
--------
int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen);
--------
This function appends the 'datlen' bytes in 'data' to the end of
'buf'. It returns 0 on success, and -1 on failure.
.Interface
[code]
--------
int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...)
int evbuffer_add_vprintf(struct evbuffer *buf, const char *fmt, va_list ap);
--------
These functions append formatted data to the end of 'buf'. The format
argument and other remaining arguments are handled as if by the C
library functions "printf" and "vprintf" respectively. The functions
return the number of bytes appended.
.Interface
[code]
--------
int evbuffer_expand(struct evbuffer *buf, size_t datlen);
--------
This function alters the last chunk of memory in the buffer, or adds a
new chunk, such that the buffer is now large enough to contain datlen
bytes without any further allocations.
// COMMENTED OUT because I want to deprecate these functions for
// sucking.
//.Interface
//[code]
//--------
//unsigned char *evbuffer_reserve_space(struct evbuffer *buf, size_t size);
//int evbuffer_commit_space(struct evbuffer *buf, size_t size);
//--------
//
//These functions ensure that an extent of space is available at the end
//of the buffer, and commit some bytes that we have manually added to
//that extent, respectively.
//
//Because they force the memory to be contiguous, they can wind up
//leaving gaps in the buffer. Note that evbuffer_reserve_space() does
//not prevent any other functions from adding data to the end of the
//buffer before evbuffer_commit_space() is called; if other functions
//alter the buffer between these calls, unexpected results may occur.
.Examples
[code]
--------
/* Here are three ways to add "Hello world 2.0.1" to a buffer. */
/* Directly: */
evbuffer_add(buf, "Hello world 2.0.1", 17);
/* Via printf: */
evbuffer_printf(buf, "Hello %s %d.%d.%d", "world", 2, 0, 1);
--------
// /* Via reserving and committing: */
//evbuffer_lock(buf); /* prevent race condition */
//char *cp = evbuffer_reserve_space(buf, 64); /* more than enough */
//memcpy(cp, "Hello world 2.0.1", 17);
//evbuffer_commit_space(buf, 17);
//evbuffer_unlock(buf);
The evbuffer_add(), evbuffer_add_printf(), and evbuffer_expand() functions
were introduced before Libevent 1.0; and evbuffer_add_printf() first
appeared in Libevent 1.1.
Moving data from one evbuffer to another
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For efficiency, Libevent has optimized functions for moving data from
one evbuffer to another.
.Interface
[code]
--------
int evbuffer_add_buffer(struct evbuffer *dst, struct evbuffer *src);
int evbuffer_remove_buffer(struct evbuffer *src, struct evbuffer *dst,
size_t datlen);
--------
The evbuffer_add_buffer() function moves all data from 'src' to the
end of 'src'. It returns 0 on success, -1 on failure.
The evbuffer_remove_buffer() function moves exactly 'datlen' bytes
from 'src' to the end of 'dst', copying as little as possible. If
there are fewer than 'datlen' bytes to move, it moves all the bytes.
It returns the number of bytes moved.
We introduced evbuffer_add_buffer() before Libevent 1.0;
evbuffer_remove_buffer() was new in Libevent 2.0.1-alpha.
Adding data to the front of an evbuffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Interface
[code]
--------
int evbuffer_prepend(struct evbuffer *buf, const void *data, size_t size);
int evbuffer_prepend_buffer(struct evbuffer *dst, struct evbuffer* src);
--------
These functions behave as evbuffer_add() and evbuffer_add_buffer()
respectively, except that they move data to the _front_ of the
destination buffer.
These functions should be used with caution, and never on an evbuffer
shared with a bufferevent. They were new in Libevent 2.0.1-alpha.
Rearranging the internal layout of an evbuffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes you want to peek at the the first N bytes of data in the
front of an evbuffer, and see it as a contiguous array of bytes. To
do this, you must first ensure that the fron of the buffer really _is_
contiguous.
.Interface
[code]
--------
unsigned char *evbuffer_pullup(struct evbuffer *buf, ev_ssize_t size);
--------
The evbuffer_pullup() function "linearizes" the first 'size' bytes of
'buf', copying or moving them as needed to ensure that they are all
contiguous and occupying the same chunk of memory. If 'size' is
negative, the function linearizes the entire buffer. If 'size' is
greater than the number of bytes in the buffer, the function returns
NULL. Otherwise, evbuffer_pullup() returns a pointer to the first
byte in buf.
Calling evbuffer_pullup() with a large size can be quite slow, since
it potentially needs to copy the entire buffer's contents.
.Example
[code]
--------
/* Let's parse the start of a SOCKS4 request! The format is easy:
* 1 byte of version, 1 byte of command, 2 bytes destport, 4 bytes of
* destip. */
unsigned char *mem;
ev_uint16_t port;
ev_uint32_t addr;
mem = evbuffer_pullup(buf, 8);
if (mem == NULL || mem[0] != 4 || mem[1] != 1) {
/* Not enough data, or unrecognized protocol or command */
} else {
memcpy(&port, mem+2, 2);
memcpy(&addr, mem+4, 4);
port = ntohs(port);
addr = ntohl(addr);
/* Actually remove the data from the buffer now that we know we
like it. */
evbuffer_drain(buf, 8);
}
--------
.Note
Calling evbuffer_pullup() with size equal to the value returned by
evbuffer_get_contiguous_space() will not result in any data being
copied or moved.
The evbuffer_pullup() function was new in Libevent 2.0.1-alpha:
previous versions of Libevent always kept evbuffer data contiguous,
regardless of the cost.
Removing data from an evbuffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Interface
[code]
--------
int evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen);
int evbuffer_drain(struct evbuffer *buf, size_t len);
--------
The evbuffer_remove() function copies the first 'datlen' bytes from
the front of 'buf' into the memory at 'data'. If there are fewer than
'datlen' bytes available, the function copies all the bytes there
are. The return value is -1 on failure, and is otherwise the number
of bytes copied.
The evbuffer_drain() function behaves as evbuffer_remove(), except
that it does not copy the data: it just removes it from the front of
the buffer. It returns 0 on success and -1 on failure.
These functions have existed since before Libevent 1.0.
Line-oriented input
~~~~~~~~~~~~~~~~~~~
.Interface
[code]
--------
enum evbuffer_eol_style {
EVBUFFER_EOL_ANY,
EVBUFFER_EOL_CRLF,
EVBUFFER_EOL_CRLF_STRICT,
EVBUFFER_EOL_LF
};
char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out,
enum evbuffer_eol_style eol_style);
--------
Many Internet protocols use line-based formats. The evbuffer_readln()
function extracts a line from the front of an evbuffer and returns it
in a newly allocated NUL-terminated string. If 'n_read_out' is not
NULL, *'n_read_out' is set to the number of bytes in the string
returned. If there is not a whole line to read, the function returns
NULL. The line terminator is not included in the copied string.
The evbuffer_readln() function understands 4 line termination formats:
EVBUFFER_EOL_LF::
The end of a line is a single linefeed character. (This is also
known as "\n". It is ASCII value is 0x0A.)
EVBUFFER_EOL_CRLF_STRICT::
The end of a line is a single carriage return, followed by a
single linefeed. (This is also known as "\r\n". The ASCII values
are 0x0D 0x0A).
EVBUFFER_EOL_CRLF::
The end of the line is an optional carriage return, followed by a
linefeed. (In other words, it is either a "\r\n" or an "\n".)
This format is useful in parsing text-based Internet
protocols, since the standards generally prescribe a "\r\n"
line-terminator, but nonconformant clients sometimes say just
"\n".
EVBUFFER_EOL_ANY::
The end of line is any sequence of any number of carriage return
and linefeed characters. This format is not very useful; it
exists mainly for backward compatibility.
(Note that if you used event_set_mem_functions() to override the
default malloc, the string returned by evbuffer_readln will be
allocated by the malloc-replacement you specified.)
.Example
[code]
--------
char *request_line;
size_t len;
request_line = evbuffer_readln(buf, &len, EVBUFFER_EOL_CRLF);
if (!request_line) {
/* The first line has not arrived yet. */
} else {
if (!strncmp(request_line, "HTTP/1.0 ", 9)) {
/* HTTP 1.0 detected ... */
}
free(request_line);
}
--------
The evbuffer_readln() interface was new in Libevent 2.0.1-alpha.
Searching within an evbuffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The evbuffer_ptr structure points to a location within an evbuffer,
and contains data that you can use to iterate through an evbuffer.
.Interface
[code]
--------
struct evbuffer_ptr {
ev_ssize_t pos;
struct {
/* internal fields */
} _internal;
};
--------
The 'pos' field is the only public field; the others should not be
used by user code. It indicates a position in the evbuffer as an
offset from the start.
.Interface
[code]
--------
struct evbuffer_ptr evbuffer_search(struct evbuffer *buffer,
const char *what, size_t len, const struct evbuffer_ptr *start);
--------
This function scands the buffer for an occurrence of the
'len'-character string 'what'. It returns an evbuffer_ptr containing
the position of the string, or -1 if the string was not found. If the
'start' argument is provided, it's the position at which the search
should begin; otherwise, the search is from the start of the string.
.Interface
[code]
--------
enum evbuffer_ptr_how {
EVBUFFER_PTR_SET,
EVBUFFER_PTR_ADD
};
int evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *pos,
size_t position, enum evbuffer_ptr_how how);
--------
The evbuffer_ptr_set function manipulates the position of an
evbuffer_ptr 'pos' within 'buffer'. If 'how' is EVBUFFER_PTR_SET, the
pointer is moved to an absolute position 'position' within the buffer.
If it is EVBUFFER_PTR_ADD, the pointer moves 'position' bytes
forward. This function returns 0 on success and -1 on failure.
.Example
[code]
--------
/* Count the total occurrences of 'str' in 'buf'.
int count_instances(struct evbuffer *buf, const char *str)
{
size_t len = strlen(str);
int total = 0;
struct evbuffer_ptr p;
if (!len)
return -1; /* Don't try to count the 0-length strings. */
evbuffer_ptr_set(buf, &p, 0, EVBUFFER_PTR_SET);
while (1) {
p = evbuffer_search(buf, str, len, &p);
if (p.pos < 0)
break;
total++;
evbuffer_ptr_set(buf, &p, 1, EVBUFFER_PTR_ADD);
}
return total;
}
--------
.WARNING
Any call that modifies an evbuffer or its layout invalidates all
outstanding evbuffer_ptr values, and makes them unsafe to use.
These interfaces were new in Libevent 2.0.1-alpha.
Network IO with evbuffers
~~~~~~~~~~~~~~~~~~~~~~~~~
The most common use case for evbuffers in Libevent is network IO.
The interface for performing network IO on an evbuffer is:
.Interface
[code]
--------
int evbuffer_write(struct evbuffer *buffer, evutil_socket_t fd);
int evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd,
ev_ssize_t howmuch);
int evbuffer_read(struct evbuffer *buffer, evutil_socket_t fd, int howmuch);
--------
The evbuffer_read() function reads up to 'howmuch' bytes from the
socket 'fd' onto the end of 'buffer'. It returns a number of bytes read on
success, 0 on EOF, and -1 on an error. Note that the error may
indicate that a nonblocking operation would not succeed; you need to
check the error code for EAGAIN (or WSAEWOULDBLOCK on Windows).
If 'howmuch' is negative, evbuffer_read() tries to guess how much to
read itself.
The evbuffer_write_atmost() function tries to write up to 'howmuch'
bytes from the front of 'buffer' onto the socket 'fd'. It returns a
number of bytes written on success, and -1 on failure. As with
evbuffer_read(), you need to check the error code to see whether the
error is real, or just indicates that nonblocking IO could not be
completed immediately. If you give a negative value for 'howmuch',
we try to write the entire contents of the buffer.
Calling evbuffer_write() is the same as calling
evbuffer_write_atmost() with a negative 'howmuch' argument: it
attempts to flush as much of the buffer as it can.
On Unix, these functions should work on any file descriptor that
supports read and write. On Windows, only sockets are supported.
Not that when you are using bufferevents, you do not need to call
these IO functions; the buferevents code does it for you.
The evbuffer_write_atmost() function was introduced in Libevent 2.0.1-alpha.
Evbuffers and callbacks
~~~~~~~~~~~~~~~~~~~~~~~
Users of evbuffers frequently want to know when data is added to or
removed from an evbuffer. To support this, Libevent provides a
generic evbuffer callback mechanism.
.Interface
[code]
--------
struct evbuffer_cb_info {
size_t orig_size;
size_t n_added;
size_t n_deleted;
};
typedef void (*evbuffer_cb_func)(struct evbuffer *buffer,
const struct evbuffer_cb_info *info, void *arg);
--------
An evbuffer callback is invoked whenever data is added to or removed
from the evbuffer. It receives the buffer, a pointer to an
evbuffer_cb_info structure, and a user-supplied argument. The
evbuffer_cb_info structure's orig_size field records how many bytes
there were on the buffer before its size changed; its n_added field
records how many bytes were added to the buffer, and its n_deleted
field records how many bytes were removed.
.Interface
[code]
--------
struct evbuffer_cb_entry;
struct evbuffer_cb_entry *evbuffer_add_cb(struct evbuffer *buffer,
evbuffer_cb_func cb, void *cbarg);
--------
The evbuffer_add_cb() function adds a callback to an evbuffer, and
returns an opaque pointer that can later be used to refer to this
particular callback instance. The 'cb' argument is the function that
will be invoked, and the 'cbarg' is the user-supplied pointer to pass
to the funtion.
You can have multiple callbacks set on a single evbuffer. Adding a
new callback does not remove old callbacks.
.Example
[code]
--------
/* Here's a callback that remembers how many bytes we have drained in
total from the buffer, and prints a dot every time we hit a
megabyte. */
struct total_processed {
size_t n;
};
void count_megabytes_cb(struct evbuffer *buffer,
const struct evbuffer_cb_info *info, void *arg)
{
struct total_processed *tp = arg;
size_t old_n = tp->n;
int megabytes, i;
tp->n += info->n_deleted;
megabytes = ((tp->n) >> 20) - (old_n >> 20);
for (i=0; i<megabytes; ++i)
putc('.');
}
/* ... */
struct total_processed *tp = malloc(sizeof(tp));
struct evbuffer *buf = evbuffer_new();
tp->n = 0;
evbuffer_add_cb(buf, count_megabytes_cb, tp);
/* Use the evbuffer for a while. When we're done: */
evbuffer_free(buf);
free(tp);
--------
Note in passing that freeing a nonempty evbuffer does not count as
draining data from it, and that freeing an evbuffer does not free the
user-supplied data pointer for its callbacks.
If you don't want a callback to be permanently active on a buffer, you
can _remove_ it (to make it gone for good), or disable it (to turn it
off for a while):
.Interface
[code]
--------
int evbuffer_remove_cb_entry(struct evbuffer *buffer,
struct evbuffer_cb_entry *ent);
int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb,
void *cbarg);
#define EVBUFFER_CB_ENABLED 1
int evbuffer_cb_set_flags(struct evbuffer *buffer,
struct evbuffer_cb_entry *cb,
ev_uint32_t flags);
int evbuffer_cb_clear_flags(struct evbuffer *buffer,
struct evbuffer_cb_entry *cb,
ev_uint32_t flags);
--------
You can remove a callback either by the evbuffer_cb_entry you got when
you added it, or by the callback and pointer you used. The
evbuffer_remove_cb() functions return 0 on success and -1 on failure.
The evbuffer_cb_set_flags() function and the evbuffer_cb_clear_flags()
fuction make a given flag be set or cleared on a given callback
respectively. Right now, only one user-visible flag is supported:
'EVBUFFER_CB_ENABLED'. The flag is set by default. When it is
cleared, modifications to the evbuffer do not cause this callback to
get invoked.
.Interface
[code]
--------
int evbuffer_defer_callbacks(struct evbuffer *buffer, struct event_base *base);
--------
As with bufferevent callbacks, you can cause evbuffer callbacks to not
run immediately when the evbuffer is changed, but rather to be
'deferred' and run as part of the event loop of a given event base.
This can be helpful if you have multiple evbuffers whose callbacks
potentially cause data to be added and removed from one another, and
you want to avoid smashing the stack.
If an evbuffer's callbacks are deferred, then when they are finally
invoked, they may summarize the results for multiple operations.
Like bufferevents, evbuffers are internally reference-counted, so that
it is safe to free an evbuffer even if it has deferred callbacks that
have not yet executed.
This entire callback system was new in Libevent 2.0.1-alpha. The
evbuffer_cb_(set|clear)_flags() functions have existed with their
present interfaces since 2.0.2-alpha.
Avoiding data copies with evbuffer-based IO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Really fast network programming often calls for doing as few data
copies as possible. Libevent provides some mechanisms to help out
with this.
.Interface
[code]
--------
typedef void (*evbuffer_ref_cleanup_cb)(const void *data,
size_t datalen, void *extra);
int evbuffer_add_reference(struct evbuffer *outbuf,
const void *data, size_t datlen,
evbuffer_ref_cleanup_cb cleanupfn, void *extra);
--------
This function adds a piece of data to the end of an evbuffer by
reference. No copy is performed: instead, the evbuffer just stores a
pointer to the 'datlen' bytes stored at 'data'. Therefore, the
pointer must remain valid for as long as the evbuffer is using it.
When the evbuffer no longer needs data, it will call the provided
"cleanupfn" function with the provided "data" pointer, "datlen" value,
and "extra" pointer as arguments.
This function returns 0 on success, -1 on failure.
.Example
[code]
--------
/* In this example, we have a bunch of evbuffers that we want to use to
spool a one-megabyte resource out to the network. We do this
without keeping any more copies of the resource in memory than
necessary. */
#define HUGE_RESOURCE_SIZE 1024*1024;
struct huge_resource {
/* We keep a count of the references that exist to this structure,
so that we know when we can free it. */
int reference_count;
char data[HUGE_RESOURCE_SIZE];
};
struct huge_resource *new_resource(void) {
struct huge_resource *hr = malloc(sizeof(struct huge_resource));
hr->reference_count = 1;
/* Here we should fill hr->data with something. In real life,
we'd probably load something or do a complex calculation.
Here, we'll just fill it with EEs. */
memset(hr->data, 0xEE sizeof(hr->data));
return hr;
}
void free_resource(struct huge_resource *hr) {
--hr->reference_count;
if (hr->reference_count == 0)
free(hr);
}
static void cleanup(const void *data, size_t len, void *arg) {
free_resource(arg);
}
/* This is the function that actually adds the resource to the
buffer. */
void spool_resource_to_evbuffer(struct evbuffer *buf,
struct huge_resource *hr)
{
++hr->reference_count;
evbuffer_add_reference(buf, hr->data, HUGE_RESOURCE_SIZE,
cleanup, hr);
}
--------
Some operating systems provide ways to write files to the network
without ever copying the data to userspace. You can access these
mechanisms, where available, with:
.Interface
[code]
--------
int evbuffer_add_file(struct evbuffer *output, int fd, off_t offset,
size_t length);
--------
The evbuffer_add_file() function assumes that it has an open file
descriptor (not a socket, for once!) 'fd' that is available for
reading. It adds 'length' bytes from the file, starting at position
'offset', to the end of 'output'. It returns 0 on success, or -1 on
failure.
.WARNING
As of Libevent 2.0.2-alpha, the only reliable thing to do with data
added this way is to send it to the network with evbuffer_write*(),
drain it with evbuffer_drain(), or move it to another evbuffer with
evbuffer_*_buffer(). You can't reliably extract it from the buffer
with evbuffer_remove(), linearize it with evbuffer_pullup(), and so
on.
If your operating system supports splice() or sendfile(), Libevent
will use it to send data from 'fd' to the network directly when call
evbuffer_write(), without copying the data to user RAM at all. If
splice/sendfile don't exist, but you have mmap(), Libevent will mmap
the file, and your kernel can hopefully figure out that it never needs
to copy the data to userspace. Otherwise, Libevent will just read the
data from disk into RAM.
The file descriptor will be closed after the data is flushed from the
evbuffer, or when the evbuffer is freed.
Both functions in this section were introduced in Libevent
2.0.1-alpha. The evbuffer_add_reference() function has had is present
interface since 2.0.2-alpha.
Making an evbuffer add- or remove-only
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Interface
[code]
--------
int evbuffer_freeze(struct evbuffer *buf, int at_front);
int evbuffer_unfreeze(struct evbuffer *buf, int at_front);
--------
You can use these functions to temporarily disable changes to the
front or end of an evbuffer. The bufferevent code uses them
internally to prevent accidental modifications to the front of an
output buffer, or the end of an input buffer.
The evbuffer_freeze() functions were introduced in Libevent
2.0.1-alpha.
Obsolete evbuffer functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The evbuffer interface changed a lot in Libevent 2.0. Before then,
every evbuffers was implemented as a contiguous chunk of RAM, which
made access very inefficient.
The event.h header used to expose the internals of struct evbuffer.
These are no longer available; they changed too much between 1.4 and
2.0 for any code that relied on them to work.
To access the number of bytes in an evbuffer, there was an
EVBUFFER_LENGTH() macro. The actual data was available with
EVBUFFER_DATA(). These are both available in event2/buffer_compat.h.
Watch out, though: EVBUFFER_DATA(b) is an alias for evbuffer_pullup(b,
-1), which can be very expensive.
Some other deprecated interfaces are:
.Deprecated Interface
[code]
--------
char *evbuffer_readline(struct evbuffer *buffer);
unsigned char *evbuffer_find(struct evbuffer *buffer,
const unsigned char *what, size_t len);
--------
The evbuffer_readline() function worked like the current
evbufer_readln(buffer, NULL, EVBUFFER_EOL_ANY).
The evbuffer_find() function would search for the first occurrence of
a string in a buffer, and return a pointer to it. Unlike
evbuffer_search(), it could only find the first string. To stay
compatible with old code that uses this function, it now linearizes
the entire buffer up to the end of the located string.
The callback interface was different too:
.Deprecated Interface
[code]
---------
typedef void (*evbuffer_cb)(struct evbuffer *buffer,
size_t old_len, size_t new_len, void *arg);
void evbuffer_setcb(struct evbuffer *buffer, evbuffer_cb cb, void *cbarg);
---------
An evbuffer could only have one callback set at a time, so setting a
new callback would disable the previous callback, and setting a
callback of NULL was the preferred way to disable a callbacks.
Instead of getting an evbuffer_cb_info_structure, the function was
called with the old and new lengths of the evbuffer. Thus, if old_len
was greater than new_len, data was drained. If new_len was greater
than old_len, data was added. It was not possible to defer callbacks,
and so adds and deletes were never batched into a single callback
invocation.
The obsolete functions here are still available in event2/buffer_compat.h.