OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

buffer.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2007-2010 Niels Provos and Nick Mathewson
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 * 1. Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * 3. The name of the author may not be used to endorse or promote products
13 * derived from this software without specific prior written permission.
14 *
15 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 */
26 #ifndef _EVENT2_BUFFER_H_
27 #define _EVENT2_BUFFER_H_
28
29 /** @file event2/buffer.h
30
31 Functions for buffering data for network sending or receiving.
32
33 An evbuffer can be used for preparing data before sending it to
34 the network or conversely for reading data from the network.
35 Evbuffers try to avoid memory copies as much as possible. As a
36 result, evbuffers can be used to pass data around without actually
37 incurring the overhead of copying the data.
38
39 A new evbuffer can be allocated with evbuffer_new(), and can be
40 freed with evbuffer_free(). Most users will be using evbuffers via
41 the bufferevent interface. To access a bufferevent's evbuffers, use
42 bufferevent_get_input() and bufferevent_get_output().
43
44 There are several guidelines for using evbuffers.
45
46 - if you already know how much data you are going to add as a result
47 of calling evbuffer_add() multiple times, it makes sense to use
48 evbuffer_expand() first to make sure that enough memory is allocated
49 before hand.
50
51 - evbuffer_add_buffer() adds the contents of one buffer to the other
52 without incurring any unnecessary memory copies.
53
54 - evbuffer_add() and evbuffer_add_buffer() do not mix very well:
55 if you use them, you will wind up with fragmented memory in your
56 buffer.
57
58 - For high-performance code, you may want to avoid copying data into and out
59 of buffers. You can skip the copy step by using
60 evbuffer_reserve_space()/evbuffer_commit_space() when writing into a
61 buffer, and evbuffer_peek() when reading.
62
63 In Libevent 2.0 and later, evbuffers are represented using a linked
64 list of memory chunks, with pointers to the first and last chunk in
65 the chain.
66
67 As the contents of an evbuffer can be stored in multiple different
68 memory blocks, it cannot be accessed directly. Instead, evbuffer_pullup()
69 can be used to force a specified number of bytes to be contiguous. This
70 will cause memory reallocation and memory copies if the data is split
71 across multiple blocks. It is more efficient, however, to use
72 evbuffer_peek() if you don't require that the memory to be contiguous.
73 */
74
75 #ifdef __cplusplus
76 extern "C" {
77 #endif
78
79 #include <event2/event-config.h>
80 #include <stdarg.h>
81 #ifdef _EVENT_HAVE_SYS_TYPES_H
82 #include <sys/types.h>
83 #endif
84 #ifdef _EVENT_HAVE_SYS_UIO_H
85 #include <sys/uio.h>
86 #endif
87 #include <event2/util.h>
88
89 /**
90 An evbuffer is an opaque data type for efficiently buffering data to be
91 sent or received on the network.
92
93 @see event2/event.h for more information
94 */
95 struct evbuffer
96 #ifdef _EVENT_IN_DOXYGEN
97 {}
98 #endif
99 ;
100
101 /**
102 Pointer to a position within an evbuffer.
103
104 Used when repeatedly searching through a buffer. Calling any function
105 that modifies or re-packs the buffer contents may invalidate all
106 evbuffer_ptrs for that buffer. Do not modify these values except with
107 evbuffer_ptr_set.
108 */
109 struct evbuffer_ptr {
110 ev_ssize_t pos;
111
112 /* Do not alter the values of fields. */
113 struct {
114 void *chain;
115 size_t pos_in_chain;
116 } _internal;
117 };
118
119 /** Describes a single extent of memory inside an evbuffer. Used for
120 direct-access functions.
121
122 @see evbuffer_reserve_space, evbuffer_commit_space, evbuffer_peek
123 */
124 #ifdef _EVENT_HAVE_SYS_UIO_H
125 #define evbuffer_iovec iovec
126 /* Internal use -- defined only if we are using the native struct iovec */
127 #define _EVBUFFER_IOVEC_IS_NATIVE
128 #else
129 struct evbuffer_iovec {
130 /**** OMPI CHANGE ****/
131 /* Added windows check */
132 #ifndef __WINDOWS__
133 /** The start of the extent of memory. */
134 void *iov_base;
135 /** The length of the extent of memory. */
136 size_t iov_len;
137 #else
138 WSABUF data;
139 #endif
140 /**** END OMPI CHANGE ****/
141 };
142 #endif
143
144 /**
145 Allocate storage for a new evbuffer.
146
147 @return a pointer to a newly allocated evbuffer struct, or NULL if an error
148 occurred
149 */
150 struct evbuffer *evbuffer_new(void);
151
152 /**
153 Deallocate storage for an evbuffer.
154
155 @param buf pointer to the evbuffer to be freed
156 */
157 void evbuffer_free(struct evbuffer *buf);
158
159 /**
160 Enable locking on an evbuffer so that it can safely be used by multiple
161 threads at the same time.
162
163 NOTE: when locking is enabled, the lock will be held when callbacks are
164 invoked. This could result in deadlock if you aren't careful. Plan
165 accordingly!
166
167 @param buf An evbuffer to make lockable.
168 @param lock A lock object, or NULL if we should allocate our own.
169 @return 0 on success, -1 on failure.
170 */
171 int evbuffer_enable_locking(struct evbuffer *buf, void *lock);
172
173 /**
174 Acquire the lock on an evbuffer. Has no effect if locking was not enabled
175 with evbuffer_enable_locking.
176 */
177 void evbuffer_lock(struct evbuffer *buf);
178
179 /**
180 Release the lock on an evbuffer. Has no effect if locking was not enabled
181 with evbuffer_enable_locking.
182 */
183 void evbuffer_unlock(struct evbuffer *buf);
184
185 /**
186 Returns the total number of bytes stored in the evbuffer
187
188 @param buf pointer to the evbuffer
189 @return the number of bytes stored in the evbuffer
190 */
191 size_t evbuffer_get_length(const struct evbuffer *buf);
192
193 /**
194 Returns the number of contiguous available bytes in the first buffer chain.
195
196 This is useful when processing data that might be split into multiple
197 chains, or that might all be in the first chain. Calls to
198 evbuffer_pullup() that cause reallocation and copying of data can thus be
199 avoided.
200
201 @param buf pointer to the evbuffer
202 @return 0 if no data is available, otherwise the number of available bytes
203 in the first buffer chain.
204 */
205 size_t evbuffer_get_contiguous_space(const struct evbuffer *buf);
206
207 /**
208 Expands the available space in an evbuffer.
209
210 Expands the available space in the evbuffer to at least datlen, so that
211 appending datlen additional bytes will not require any new allocations.
212
213 @param buf the evbuffer to be expanded
214 @param datlen the new minimum length requirement
215 @return 0 if successful, or -1 if an error occurred
216 */
217 int evbuffer_expand(struct evbuffer *buf, size_t datlen);
218
219 /**
220 Reserves space in the last chain or chains of an evbuffer.
221
222 Makes space available in the last chain or chains of an evbuffer that can
223 be arbitrarily written to by a user. The space does not become
224 available for reading until it has been committed with
225 evbuffer_commit_space().
226
227 The space is made available as one or more extents, represented by
228 an initial pointer and a length. You can force the memory to be
229 available as only one extent. Allowing more extents, however, makes the
230 function more efficient.
231
232 Multiple subsequent calls to this function will make the same space
233 available until evbuffer_commit_space() has been called.
234
235 It is an error to do anything that moves around the buffer's internal
236 memory structures before committing the space.
237
238 NOTE: The code currently does not ever use more than two extents.
239 This may change in future versions.
240
241 @param buf the evbuffer in which to reserve space.
242 @param size how much space to make available, at minimum. The
243 total length of the extents may be greater than the requested
244 length.
245 @param vec an array of one or more evbuffer_iovec structures to
246 hold pointers to the reserved extents of memory.
247 @param n_vec The length of the vec array. Must be at least 1;
248 2 is more efficient.
249 @return the number of provided extents, or -1 on error.
250 @see evbuffer_commit_space()
251 */
252 int
253 evbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size,
254 struct evbuffer_iovec *vec, int n_vec);
255
256 /**
257 Commits previously reserved space.
258
259 Commits some of the space previously reserved with
260 evbuffer_reserve_space(). It then becomes available for reading.
261
262 This function may return an error if the pointer in the extents do
263 not match those returned from evbuffer_reserve_space, or if data
264 has been added to the buffer since the space was reserved.
265
266 If you want to commit less data than you got reserved space for,
267 modify the iov_len pointer of the appropriate extent to a smaller
268 value. Note that you may have received more space than you
269 requested if it was available!
270
271 @param buf the evbuffer in which to reserve space.
272 @param vec one or two extents returned by evbuffer_reserve_space.
273 @param n_vecs the number of extents.
274 @return 0 on success, -1 on error
275 @see evbuffer_reserve_space()
276 */
277 int evbuffer_commit_space(struct evbuffer *buf,
278 struct evbuffer_iovec *vec, int n_vecs);
279
280 /**
281 Append data to the end of an evbuffer.
282
283 @param buf the evbuffer to be appended to
284 @param data pointer to the beginning of the data buffer
285 @param datlen the number of bytes to be copied from the data buffer
286 @return 0 on success, -1 on failure.
287 */
288 int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen);
289
290
291 /**
292 Read data from an evbuffer and drain the bytes read.
293
294 If more bytes are requested than are available in the evbuffer, we
295 only extract as many bytes as were available.
296
297 @param buf the evbuffer to be read from
298 @param data the destination buffer to store the result
299 @param datlen the maximum size of the destination buffer
300 @return the number of bytes read, or -1 if we can't drain the buffer.
301 */
302 int evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen);
303
304 /**
305 Read data from an evbuffer, and leave the buffer unchanged.
306
307 If more bytes are requested than are available in the evbuffer, we
308 only extract as many bytes as were available.
309
310 @param buf the evbuffer to be read from
311 @param data_out the destination buffer to store the result
312 @param datlen the maximum size of the destination buffer
313 @return the number of bytes read, or -1 if we can't drain the buffer.
314 */
315 ev_ssize_t evbuffer_copyout(struct evbuffer *buf, void *data_out, size_t datlen);
316
317 /**
318 Read data from an evbuffer into another evbuffer, draining
319 the bytes from the source buffer. This function avoids copy
320 operations to the extent possible.
321
322 If more bytes are requested than are available in src, the src
323 buffer is drained completely.
324
325 @param src the evbuffer to be read from
326 @param dst the destination evbuffer to store the result into
327 @param datlen the maximum numbers of bytes to transfer
328 @return the number of bytes read
329 */
330 int evbuffer_remove_buffer(struct evbuffer *src, struct evbuffer *dst,
331 size_t datlen);
332
333 /** Used to tell evbuffer_readln what kind of line-ending to look for.
334 */
335 enum evbuffer_eol_style {
336 /** Any sequence of CR and LF characters is acceptable as an
337 * EOL.
338 *
339 * Note that this style can produce ambiguous results: the
340 * sequence "CRLF" will be treated as a single EOL if it is
341 * all in the buffer at once, but if you first read a CR from
342 * the network and later read an LF from the network, it will
343 * be treated as two EOLs.
344 */
345 EVBUFFER_EOL_ANY,
346 /** An EOL is an LF, optionally preceded by a CR. This style is
347 * most useful for implementing text-based internet protocols. */
348 EVBUFFER_EOL_CRLF,
349 /** An EOL is a CR followed by an LF. */
350 EVBUFFER_EOL_CRLF_STRICT,
351 /** An EOL is a LF. */
352 EVBUFFER_EOL_LF
353 };
354
355 /**
356 * Read a single line from an evbuffer.
357 *
358 * Reads a line terminated by an EOL as determined by the evbuffer_eol_style
359 * argument. Returns a newly allocated nul-terminated string; the caller must
360 * free the returned value. The EOL is not included in the returned string.
361 *
362 * @param buffer the evbuffer to read from
363 * @param n_read_out if non-NULL, points to a size_t that is set to the
364 * number of characters in the returned string. This is useful for
365 * strings that can contain NUL characters.
366 * @param eol_style the style of line-ending to use.
367 * @return pointer to a single line, or NULL if an error occurred
368 */
369 char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out,
370 enum evbuffer_eol_style eol_style);
371
372 /**
373 Move all data from one evbuffer into another evbuffer.
374
375 This is a destructive add. The data from one buffer moves into
376 the other buffer. However, no unnecessary memory copies occur.
377
378 @param outbuf the output buffer
379 @param inbuf the input buffer
380 @return 0 if successful, or -1 if an error occurred
381
382 @see evbuffer_remove_buffer()
383 */
384 int evbuffer_add_buffer(struct evbuffer *outbuf, struct evbuffer *inbuf);
385
386 /**
387 A cleanup function for a piece of memory added to an evbuffer by
388 reference.
389
390 @see evbuffer_add_reference()
391 */
392 typedef void (*evbuffer_ref_cleanup_cb)(const void *data,
393 size_t datalen, void *extra);
394
395 /**
396 Reference memory into an evbuffer without copying.
397
398 The memory needs to remain valid until all the added data has been
399 read. This function keeps just a reference to the memory without
400 actually incurring the overhead of a copy.
401
402 @param outbuf the output buffer
403 @param data the memory to reference
404 @param datlen how memory to reference
405 @param cleanupfn callback to be invoked when the memory is no longer
406 referenced by this evbuffer.
407 @param cleanupfn_arg optional argument to the cleanup callback
408 @return 0 if successful, or -1 if an error occurred
409 */
410 int evbuffer_add_reference(struct evbuffer *outbuf,
411 const void *data, size_t datlen,
412 evbuffer_ref_cleanup_cb cleanupfn, void *cleanupfn_arg);
413
414 /**
415 Copy data from a file into the evbuffer for writing to a socket.
416
417 This function avoids unnecessary data copies between userland and
418 kernel. Where available, it uses sendfile or splice; failing those,
419 it tries to use mmap.
420
421 The function owns the resulting file descriptor and will close it
422 when finished transferring data.
423
424 The results of using evbuffer_remove() or evbuffer_pullup() on
425 evbuffers whose data was added using this function are undefined.
426
427 @param outbuf the output buffer
428 @param fd the file descriptor
429 @param offset the offset from which to read data
430 @param length how much data to read
431 @return 0 if successful, or -1 if an error occurred
432 */
433
434 int evbuffer_add_file(struct evbuffer *outbuf, int fd, ev_off_t offset,
435 ev_off_t length);
436
437 /**
438 Append a formatted string to the end of an evbuffer.
439
440 The string is formated as printf.
441
442 @param buf the evbuffer that will be appended to
443 @param fmt a format string
444 @param ... arguments that will be passed to printf(3)
445 @return The number of bytes added if successful, or -1 if an error occurred.
446
447 @see evutil_printf(), evbuffer_add_vprintf()
448 */
449 int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...)
450 #ifdef __GNUC__
451 __attribute__((format(printf, 2, 3)))
452 #endif
453 ;
454
455 /**
456 Append a va_list formatted string to the end of an evbuffer.
457
458 @param buf the evbuffer that will be appended to
459 @param fmt a format string
460 @param ap a varargs va_list argument array that will be passed to vprintf(3)
461 @return The number of bytes added if successful, or -1 if an error occurred.
462 */
463 int evbuffer_add_vprintf(struct evbuffer *buf, const char *fmt, va_list ap);
464
465
466 /**
467 Remove a specified number of bytes data from the beginning of an evbuffer.
468
469 @param buf the evbuffer to be drained
470 @param len the number of bytes to drain from the beginning of the buffer
471 @return 0 on success, -1 on failure.
472 */
473 int evbuffer_drain(struct evbuffer *buf, size_t len);
474
475
476 /**
477 Write the contents of an evbuffer to a file descriptor.
478
479 The evbuffer will be drained after the bytes have been successfully written.
480
481 @param buffer the evbuffer to be written and drained
482 @param fd the file descriptor to be written to
483 @return the number of bytes written, or -1 if an error occurred
484 @see evbuffer_read()
485 */
486 int evbuffer_write(struct evbuffer *buffer, evutil_socket_t fd);
487
488 /**
489 Write some of the contents of an evbuffer to a file descriptor.
490
491 The evbuffer will be drained after the bytes have been successfully written.
492
493 @param buffer the evbuffer to be written and drained
494 @param fd the file descriptor to be written to
495 @param howmuch the largest allowable number of bytes to write, or -1
496 to write as many bytes as we can.
497 @return the number of bytes written, or -1 if an error occurred
498 @see evbuffer_read()
499 */
500 int evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd,
501 ev_ssize_t howmuch);
502
503 /**
504 Read from a file descriptor and store the result in an evbuffer.
505
506 @param buffer the evbuffer to store the result
507 @param fd the file descriptor to read from
508 @param howmuch the number of bytes to be read
509 @return the number of bytes read, or -1 if an error occurred
510 @see evbuffer_write()
511 */
512 int evbuffer_read(struct evbuffer *buffer, evutil_socket_t fd, int howmuch);
513
514 /**
515 Search for a string within an evbuffer.
516
517 @param buffer the evbuffer to be searched
518 @param what the string to be searched for
519 @param len the length of the search string
520 @param start NULL or a pointer to a valid struct evbuffer_ptr.
521 @return a struct evbuffer_ptr whose 'pos' field has the offset of the
522 first occurrence of the string in the buffer after 'start'. The 'pos'
523 field of the result is -1 if the string was not found.
524 */
525 struct evbuffer_ptr evbuffer_search(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start);
526
527 /**
528 Search for a string within part of an evbuffer.
529
530 @param buffer the evbuffer to be searched
531 @param what the string to be searched for
532 @param len the length of the search string
533 @param start NULL or a pointer to a valid struct evbuffer_ptr that
534 indicates where we should start searching.
535 @param end NULL or a pointer to a valid struct evbuffer_ptr that
536 indicates where we should stop searching.
537 @return a struct evbuffer_ptr whose 'pos' field has the offset of the
538 first occurrence of the string in the buffer after 'start'. The 'pos'
539 field of the result is -1 if the string was not found.
540 */
541 struct evbuffer_ptr evbuffer_search_range(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start, const struct evbuffer_ptr *end);
542
543 /**
544 Defines how to adjust an evbuffer_ptr by evbuffer_ptr_set()
545
546 @see evbuffer_ptr_set() */
547 enum evbuffer_ptr_how {
548 /** Sets the pointer to the position; can be called on with an
549 uninitialized evbuffer_ptr. */
550 EVBUFFER_PTR_SET,
551 /** Advances the pointer by adding to the current position. */
552 EVBUFFER_PTR_ADD
553 };
554
555 /**
556 Sets the search pointer in the buffer to position.
557
558 If evbuffer_ptr is not initialized. This function can only be called
559 with EVBUFFER_PTR_SET.
560
561 @param buffer the evbuffer to be search
562 @param ptr a pointer to a struct evbuffer_ptr
563 @param position the position at which to start the next search
564 @param how determines how the pointer should be manipulated.
565 @returns 0 on success or -1 otherwise
566 */
567 int
568 evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *ptr,
569 size_t position, enum evbuffer_ptr_how how);
570
571 /**
572 Search for an end-of-line string within an evbuffer.
573
574 @param buffer the evbuffer to be searched
575 @param start NULL or a pointer to a valid struct evbuffer_ptr to start
576 searching at.
577 @param eol_len_out If non-NULL, the pointed-to value will be set to
578 the length of the end-of-line string.
579 @param eol_style The kind of EOL to look for; see evbuffer_readln() for
580 more information
581 @return a struct evbuffer_ptr whose 'pos' field has the offset of the
582 first occurrence EOL in the buffer after 'start'. The 'pos'
583 field of the result is -1 if the string was not found.
584 */
585 struct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer,
586 struct evbuffer_ptr *start, size_t *eol_len_out,
587 enum evbuffer_eol_style eol_style);
588
589 /** Function to peek at data inside an evbuffer without removing it or
590 copying it out.
591
592 Pointers to the data are returned by filling the 'vec_out' array
593 with pointers to one or more extents of data inside the buffer.
594
595 The total data in the extents that you get back may be more than
596 you requested (if there is more data last extent than you asked
597 for), or less (if you do not provide enough evbuffer_iovecs, or if
598 the buffer does not have as much data as you asked to see).
599
600 @param buffer the evbuffer to peek into,
601 @param len the number of bytes to try to peek. If negative, we
602 will try to fill as much of vec_out as we can.
603 @param start_at an evbuffer_ptr indicating the point at which we
604 should start looking for data. NULL means, "At the start of the
605 buffer."
606 @param vec_out an array of evbuffer_iovec
607 @param n_vec the length of vec_out. If 0, we only count how many
608 extents would be necessary to point to the requested amount of
609 data.
610 @return The number of extents needed. This may be less than n_vec
611 if we didn't need all the evbuffer_iovecs we were given, or more
612 than n_vec if we would need more to return all the data that was
613 requested.
614 */
615 int evbuffer_peek(struct evbuffer *buffer, ev_ssize_t len,
616 struct evbuffer_ptr *start_at,
617 struct evbuffer_iovec *vec_out, int n_vec);
618
619
620 /** Structure passed to an evbuffer_cb_func evbuffer callback
621
622 @see evbuffer_cb_func, evbuffer_add_cb()
623 */
624 struct evbuffer_cb_info {
625 /** The number of bytes in this evbuffer when callbacks were last
626 * invoked. */
627 size_t orig_size;
628 /** The number of bytes added since callbacks were last invoked. */
629 size_t n_added;
630 /** The number of bytes removed since callbacks were last invoked. */
631 size_t n_deleted;
632 };
633
634 /** Type definition for a callback that is invoked whenever data is added or
635 removed from an evbuffer.
636
637 An evbuffer may have one or more callbacks set at a time. The order
638 in which they are executed is undefined.
639
640 A callback function may add more callbacks, or remove itself from the
641 list of callbacks, or add or remove data from the buffer. It may not
642 remove another callback from the list.
643
644 If a callback adds or removes data from the buffer or from another
645 buffer, this can cause a recursive invocation of your callback or
646 other callbacks. If you ask for an infinite loop, you might just get
647 one: watch out!
648
649 @param buffer the buffer whose size has changed
650 @param info a structure describing how the buffer changed.
651 @param arg a pointer to user data
652 */
653 typedef void (*evbuffer_cb_func)(struct evbuffer *buffer, const struct evbuffer_cb_info *info, void *arg);
654
655 struct evbuffer_cb_entry;
656 /** Add a new callback to an evbuffer.
657
658 Subsequent calls to evbuffer_add_cb() add new callbacks. To remove this
659 callback, call evbuffer_remove_cb or evbuffer_remove_cb_entry.
660
661 @param buffer the evbuffer to be monitored
662 @param cb the callback function to invoke when the evbuffer is modified,
663 or NULL to remove all callbacks.
664 @param cbarg an argument to be provided to the callback function
665 @return a handle to the callback on success, or NULL on failure.
666 */
667 struct evbuffer_cb_entry *evbuffer_add_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);
668
669 /** Remove a callback from an evbuffer, given a handle returned from
670 evbuffer_add_cb.
671
672 Calling this function invalidates the handle.
673
674 @return 0 if a callback was removed, or -1 if no matching callback was
675 found.
676 */
677 int evbuffer_remove_cb_entry(struct evbuffer *buffer,
678 struct evbuffer_cb_entry *ent);
679
680 /** Remove a callback from an evbuffer, given the function and argument
681 used to add it.
682
683 @return 0 if a callback was removed, or -1 if no matching callback was
684 found.
685 */
686 int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);
687
688 /** If this flag is not set, then a callback is temporarily disabled, and
689 * should not be invoked.
690 *
691 * @see evbuffer_cb_set_flags(), evbuffer_cb_clear_flags()
692 */
693 #define EVBUFFER_CB_ENABLED 1
694
695 /** Change the flags that are set for a callback on a buffer by adding more.
696
697 @param buffer the evbuffer that the callback is watching.
698 @param cb the callback whose status we want to change.
699 @param flags EVBUFFER_CB_ENABLED to re-enable the callback.
700 @return 0 on success, -1 on failure.
701 */
702 int evbuffer_cb_set_flags(struct evbuffer *buffer,
703 struct evbuffer_cb_entry *cb, ev_uint32_t flags);
704
705 /** Change the flags that are set for a callback on a buffer by removing some
706
707 @param buffer the evbuffer that the callback is watching.
708 @param cb the callback whose status we want to change.
709 @param flags EVBUFFER_CB_ENABLED to disable the callback.
710 @return 0 on success, -1 on failure.
711 */
712 int evbuffer_cb_clear_flags(struct evbuffer *buffer,
713 struct evbuffer_cb_entry *cb, ev_uint32_t flags);
714
715 #if 0
716 /** Postpone calling a given callback until unsuspend is called later.
717
718 This is different from disabling the callback, since the callback will get
719 invoked later if the buffer size changes between now and when we unsuspend
720 it.
721
722 @param the buffer that the callback is watching.
723 @param cb the callback we want to suspend.
724 */
725 void evbuffer_cb_suspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb);
726 /** Stop postponing a callback that we postponed with evbuffer_cb_suspend.
727
728 If data was added to or removed from the buffer while the callback was
729 suspended, the callback will get called once now.
730
731 @param the buffer that the callback is watching.
732 @param cb the callback we want to stop suspending.
733 */
734 void evbuffer_cb_unsuspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb);
735 #endif
736
737 /**
738 Makes the data at the begging of an evbuffer contiguous.
739
740 @param buf the evbuffer to make contiguous
741 @param size the number of bytes to make contiguous, or -1 to make the
742 entire buffer contiguous.
743 @return a pointer to the contiguous memory array
744 */
745
746 unsigned char *evbuffer_pullup(struct evbuffer *buf, ev_ssize_t size);
747
748 /**
749 Prepends data to the beginning of the evbuffer
750
751 @param buf the evbuffer to which to prepend data
752 @param data a pointer to the memory to prepend
753 @param size the number of bytes to prepend
754 @return 0 if successful, or -1 otherwise
755 */
756
757 int evbuffer_prepend(struct evbuffer *buf, const void *data, size_t size);
758
759 /**
760 Prepends all data from the src evbuffer to the beginning of the dst
761 evbuffer.
762
763 @param dst the evbuffer to which to prepend data
764 @param src the evbuffer to prepend; it will be emptied as a result
765 @return 0 if successful, or -1 otherwise
766 */
767 int evbuffer_prepend_buffer(struct evbuffer *dst, struct evbuffer* src);
768
769 /**
770 Prevent calls that modify an evbuffer from succeeding. A buffer may
771 frozen at the front, at the back, or at both the front and the back.
772
773 If the front of a buffer is frozen, operations that drain data from
774 the front of the buffer, or that prepend data to the buffer, will
775 fail until it is unfrozen. If the back a buffer is frozen, operations
776 that append data from the buffer will fail until it is unfrozen.
777
778 @param buf The buffer to freeze
779 @param at_front If true, we freeze the front of the buffer. If false,
780 we freeze the back.
781 @return 0 on success, -1 on failure.
782 */
783 int evbuffer_freeze(struct evbuffer *buf, int at_front);
784 /**
785 Re-enable calls that modify an evbuffer.
786
787 @param buf The buffer to un-freeze
788 @param at_front If true, we unfreeze the front of the buffer. If false,
789 we unfreeze the back.
790 @return 0 on success, -1 on failure.
791 */
792 int evbuffer_unfreeze(struct evbuffer *buf, int at_front);
793
794 struct event_base;
795 /**
796 Force all the callbacks on an evbuffer to be run, not immediately after
797 the evbuffer is altered, but instead from inside the event loop.
798
799 This can be used to serialize all the callbacks to a single thread
800 of execution.
801 */
802 int evbuffer_defer_callbacks(struct evbuffer *buffer, struct event_base *base);
803
804 #ifdef __cplusplus
805 }
806 #endif
807
808 #endif /* _EVENT2_BUFFER_H_ */
evbuffer_new
struct evbuffer * evbuffer_new(void)
Allocate storage for a new evbuffer.
Definition: buffer.c:315
evbuffer_copyout
ev_ssize_t evbuffer_copyout(struct evbuffer *buf, void *data_out, size_t datlen)
Read data from an evbuffer, and leave the buffer unchanged.
Definition: buffer.c:992
evbuffer_read
int evbuffer_read(struct evbuffer *buffer, evutil_socket_t fd, int howmuch)
Read from a file descriptor and store the result in an evbuffer.
Definition: buffer.c:2008
evbuffer_iovec::iov_len
size_t iov_len
The length of the extent of memory.
Definition: buffer.h:132
evbuffer_remove_cb
int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg)
Remove a callback from an evbuffer, given the function and argument used to add it.
Definition: buffer.c:2854
evbuffer_cb_clear_flags
int evbuffer_cb_clear_flags(struct evbuffer *buffer, struct evbuffer_cb_entry *cb, ev_uint32_t flags)
Change the flags that are set for a callback on a buffer by removing some.
Definition: buffer.c:2883
EVBUFFER_EOL_CRLF
An EOL is an LF, optionally preceded by a CR.
Definition: buffer.h:344
evbuffer_prepend_buffer
int evbuffer_prepend_buffer(struct evbuffer *dst, struct evbuffer *src)
Prepends all data from the src evbuffer to the beginning of the dst evbuffer.
Definition: buffer.c:862
evbuffer_cb_entry
A single evbuffer callback for an evbuffer.
Definition: evbuffer-internal.h:60
evbuffer_ptr
Pointer to a position within an evbuffer.
Definition: buffer.h:105
evbuffer::lock
void * lock
A lock used to mediate access to this buffer.
Definition: evbuffer-internal.h:111
evbuffer_add_vprintf
int evbuffer_add_vprintf(struct evbuffer *buf, const char *fmt, va_list ap)
Append a va_list formatted string to the end of an evbuffer.
Definition: buffer.c:2549
evbuffer_add_reference
int evbuffer_add_reference(struct evbuffer *outbuf, const void *data, size_t datlen, evbuffer_ref_cleanup_cb cleanupfn, void *cleanupfn_arg)
Reference memory into an evbuffer without copying.
Definition: buffer.c:2623
evbuffer_defer_callbacks
int evbuffer_defer_callbacks(struct evbuffer *buffer, struct event_base *base)
Force all the callbacks on an evbuffer to be run, not immediately after the evbuffer is altered...
Definition: buffer.c:346
EVBUFFER_PTR_SET
Sets the pointer to the position; can be called on with an uninitialized evbuffer_ptr.
Definition: buffer.h:546
evbuffer_cb_info::n_added
size_t n_added
The number of bytes added since callbacks were last invoked.
Definition: buffer.h:625
evbuffer_cb_entry::cb
union evbuffer_cb_entry::@9 cb
The callback function to invoke when this callback is called.
evbuffer_search_range
struct evbuffer_ptr evbuffer_search_range(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start, const struct evbuffer_ptr *end)
Search for a string within part of an evbuffer.
Definition: buffer.c:2439
evbuffer_iovec::iov_base
void * iov_base
The start of the extent of memory.
Definition: buffer.h:130
evbuffer_free
void evbuffer_free(struct evbuffer *buf)
Deallocate storage for an evbuffer.
Definition: buffer.c:523
evbuffer_get_length
size_t evbuffer_get_length(const struct evbuffer *buf)
Returns the total number of bytes stored in the evbuffer.
Definition: buffer.c:542
evbuffer_peek
int evbuffer_peek(struct evbuffer *buffer, ev_ssize_t len, struct evbuffer_ptr *start_at, struct evbuffer_iovec *vec_out, int n_vec)
Function to peek at data inside an evbuffer without removing it or copying it out.
Definition: buffer.c:2504
evbuffer_add_buffer
int evbuffer_add_buffer(struct evbuffer *outbuf, struct evbuffer *inbuf)
Move all data from one evbuffer into another evbuffer.
Definition: buffer.c:816
evbuffer_commit_space
int evbuffer_commit_space(struct evbuffer *buf, struct evbuffer_iovec *vec, int n_vecs)
Commits previously reserved space.
Definition: buffer.c:619
EVBUFFER_PTR_ADD
Advances the pointer by adding to the current position.
Definition: buffer.h:548
evbuffer_reserve_space
int evbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size, struct evbuffer_iovec *vec, int n_vec)
Reserves space in the last chain or chains of an evbuffer.
Definition: buffer.c:570
evbuffer_ptr_how
evbuffer_ptr_how
Defines how to adjust an evbuffer_ptr by evbuffer_ptr_set()
Definition: buffer.h:543
evbuffer_cb_info
Structure passed to an evbuffer_cb_func evbuffer callback.
Definition: buffer.h:620
evutil_socket_t
#define evutil_socket_t
A type wide enough to hold the output of "socket()" or "accept()".
Definition: util.h:278
evbuffer_remove_buffer
int evbuffer_remove_buffer(struct evbuffer *src, struct evbuffer *dst, size_t datlen)
Read data from an evbuffer into another evbuffer, draining the bytes from the source buffer...
Definition: buffer.c:1041
evbuffer_cb_info::n_deleted
size_t n_deleted
The number of bytes removed since callbacks were last invoked.
Definition: buffer.h:627
EVBUFFER_EOL_ANY
Any sequence of CR and LF characters is acceptable as an EOL.
Definition: buffer.h:341
evbuffer_cb_set_flags
int evbuffer_cb_set_flags(struct evbuffer *buffer, struct evbuffer_cb_entry *cb, ev_uint32_t flags)
Change the flags that are set for a callback on a buffer by adding more.
Definition: buffer.c:2871
evbuffer_add_cb
struct evbuffer_cb_entry * evbuffer_add_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg)
Add a new callback to an evbuffer.
Definition: buffer.c:2828
evbuffer
Definition: evbuffer-internal.h:78
evbuffer_lock
void evbuffer_lock(struct evbuffer *buf)
Acquire the lock on an evbuffer.
Definition: buffer.c:530
evbuffer_add_file
int evbuffer_add_file(struct evbuffer *outbuf, int fd, ev_off_t offset, ev_off_t length)
Copy data from a file into the evbuffer for writing to a socket.
Definition: buffer.c:2670
evbuffer_eol_style
evbuffer_eol_style
Used to tell evbuffer_readln what kind of line-ending to look for.
Definition: buffer.h:331
EVBUFFER_EOL_LF
An EOL is a LF.
Definition: buffer.h:348
evbuffer_freeze
int evbuffer_freeze(struct evbuffer *buf, int at_front)
Prevent calls that modify an evbuffer from succeeding.
Definition: buffer.c:2895
evbuffer_search_eol
struct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer, struct evbuffer_ptr *start, size_t *eol_len_out, enum evbuffer_eol_style eol_style)
Search for an end-of-line string within an evbuffer.
Definition: buffer.c:1367
evbuffer_get_contiguous_space
size_t evbuffer_get_contiguous_space(const struct evbuffer *buf)
Returns the number of contiguous available bytes in the first buffer chain.
Definition: buffer.c:556
evbuffer_drain
int evbuffer_drain(struct evbuffer *buf, size_t len)
Remove a specified number of bytes data from the beginning of an evbuffer.
Definition: buffer.c:908
util.h
Common convenience functions for cross-platform portability and related socket manipulations.
evbuffer_add_printf
int evbuffer_add_printf(struct evbuffer *buf, const char *fmt,...)
Append a formatted string to the end of an evbuffer.
Definition: buffer.c:2610
evbuffer_cb_entry::cbarg
void * cbarg
Argument to pass to cb.
Definition: evbuffer-internal.h:71
evbuffer_prepend
int evbuffer_prepend(struct evbuffer *buf, const void *data, size_t size)
Prepends data to the beginning of the evbuffer.
Definition: buffer.c:1570
evbuffer_ptr_set
int evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *ptr, size_t position, enum evbuffer_ptr_how how)
Sets the search pointer in the buffer to position.
Definition: buffer.c:2353
evbuffer_readln
char * evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out, enum evbuffer_eol_style eol_style)
Read a single line from an evbuffer.
Definition: buffer.c:1442
evbuffer_remove_cb_entry
int evbuffer_remove_cb_entry(struct evbuffer *buffer, struct evbuffer_cb_entry *ent)
Remove a callback from an evbuffer, given a handle returned from evbuffer_add_cb. ...
Definition: buffer.c:2843
evbuffer_add
int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen)
Append data to the end of an evbuffer.
Definition: buffer.c:1485
evbuffer_cb_entry::flags
ev_uint32_t flags
Currently set flags on this callback.
Definition: evbuffer-internal.h:73
EVBUFFER_EOL_CRLF_STRICT
An EOL is a CR followed by an LF.
Definition: buffer.h:346
evbuffer_unfreeze
int evbuffer_unfreeze(struct evbuffer *buf, int at_front)
Re-enable calls that modify an evbuffer.
Definition: buffer.c:2907
evbuffer_cb_info::orig_size
size_t orig_size
The number of bytes in this evbuffer when callbacks were last invoked.
Definition: buffer.h:623
evbuffer_ref_cleanup_cb
void(* evbuffer_ref_cleanup_cb)(const void *data, size_t datalen, void *extra)
A cleanup function for a piece of memory added to an evbuffer by reference.
Definition: buffer.h:388
evbuffer_write_atmost
int evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd, ev_ssize_t howmuch)
Write some of the contents of an evbuffer to a file descriptor.
Definition: buffer.c:2281
evbuffer_write
int evbuffer_write(struct evbuffer *buffer, evutil_socket_t fd)
Write the contents of an evbuffer to a file descriptor.
Definition: buffer.c:2327
evbuffer_pullup
unsigned char * evbuffer_pullup(struct evbuffer *buf, ev_ssize_t size)
Makes the data at the begging of an evbuffer contiguous.
Definition: buffer.c:1125
evbuffer_iovec
Describes a single extent of memory inside an evbuffer.
Definition: buffer.h:125
evbuffer_enable_locking
int evbuffer_enable_locking(struct evbuffer *buf, void *lock)
Enable locking on an evbuffer so that it can safely be used by multiple threads at the same time...
Definition: buffer.c:358
evbuffer_cb_func
void(* evbuffer_cb_func)(struct evbuffer *buffer, const struct evbuffer_cb_info *info, void *arg)
Type definition for a callback that is invoked whenever data is added or removed from an evbuffer...
Definition: buffer.h:649
evbuffer_remove
int evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen)
Read data from an evbuffer and drain the bytes read.
Definition: buffer.c:978
event_base
Definition: event-internal.h:167
evbuffer_search
struct evbuffer_ptr evbuffer_search(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start)
Search for a string within an evbuffer.
Definition: buffer.c:2433
evbuffer_expand
int evbuffer_expand(struct evbuffer *buf, size_t datlen)
Expands the available space in an evbuffer.
Definition: buffer.c:1888
evbuffer_unlock
void evbuffer_unlock(struct evbuffer *buf)
Release the lock on an evbuffer.
Definition: buffer.c:536