OpenMPI  0.1.1
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  */
346  /** An EOL is an LF, optionally preceded by a CR. This style is
347  * most useful for implementing text-based internet protocols. */
349  /** An EOL is a CR followed by an LF. */
351  /** An EOL is a 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. */
551  /** Advances the pointer by adding to the current position. */
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_ */
struct evbuffer * evbuffer_new(void)
Allocate storage for a new evbuffer.
Definition: buffer.c:315
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
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
size_t iov_len
The length of the extent of memory.
Definition: buffer.h:132
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
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
An EOL is an LF, optionally preceded by a CR.
Definition: buffer.h:344
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
A single evbuffer callback for an evbuffer.
Definition: evbuffer-internal.h:60
Pointer to a position within an evbuffer.
Definition: buffer.h:105
void * lock
A lock used to mediate access to this buffer.
Definition: evbuffer-internal.h:111
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
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
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
Sets the pointer to the position; can be called on with an uninitialized evbuffer_ptr.
Definition: buffer.h:546
size_t n_added
The number of bytes added since callbacks were last invoked.
Definition: buffer.h:625
union evbuffer_cb_entry::@9 cb
The callback function to invoke when this callback is called.
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
void * iov_base
The start of the extent of memory.
Definition: buffer.h:130
void evbuffer_free(struct evbuffer *buf)
Deallocate storage for an evbuffer.
Definition: buffer.c:523
size_t evbuffer_get_length(const struct evbuffer *buf)
Returns the total number of bytes stored in the evbuffer.
Definition: buffer.c:542
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
int evbuffer_add_buffer(struct evbuffer *outbuf, struct evbuffer *inbuf)
Move all data from one evbuffer into another evbuffer.
Definition: buffer.c:816
int evbuffer_commit_space(struct evbuffer *buf, struct evbuffer_iovec *vec, int n_vecs)
Commits previously reserved space.
Definition: buffer.c:619
Advances the pointer by adding to the current position.
Definition: buffer.h:548
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
Defines how to adjust an evbuffer_ptr by evbuffer_ptr_set()
Definition: buffer.h:543
Structure passed to an evbuffer_cb_func evbuffer callback.
Definition: buffer.h:620
#define evutil_socket_t
A type wide enough to hold the output of "socket()" or "accept()".
Definition: util.h:278
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
size_t n_deleted
The number of bytes removed since callbacks were last invoked.
Definition: buffer.h:627
Any sequence of CR and LF characters is acceptable as an EOL.
Definition: buffer.h:341
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
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
Definition: evbuffer-internal.h:78
void evbuffer_lock(struct evbuffer *buf)
Acquire the lock on an evbuffer.
Definition: buffer.c:530
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
Used to tell evbuffer_readln what kind of line-ending to look for.
Definition: buffer.h:331
An EOL is a LF.
Definition: buffer.h:348
int evbuffer_freeze(struct evbuffer *buf, int at_front)
Prevent calls that modify an evbuffer from succeeding.
Definition: buffer.c:2895
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
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
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
Common convenience functions for cross-platform portability and related socket manipulations.
int evbuffer_add_printf(struct evbuffer *buf, const char *fmt,...)
Append a formatted string to the end of an evbuffer.
Definition: buffer.c:2610
void * cbarg
Argument to pass to cb.
Definition: evbuffer-internal.h:71
int evbuffer_prepend(struct evbuffer *buf, const void *data, size_t size)
Prepends data to the beginning of the evbuffer.
Definition: buffer.c:1570
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
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
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
int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen)
Append data to the end of an evbuffer.
Definition: buffer.c:1485
ev_uint32_t flags
Currently set flags on this callback.
Definition: evbuffer-internal.h:73
An EOL is a CR followed by an LF.
Definition: buffer.h:346
int evbuffer_unfreeze(struct evbuffer *buf, int at_front)
Re-enable calls that modify an evbuffer.
Definition: buffer.c:2907
size_t orig_size
The number of bytes in this evbuffer when callbacks were last invoked.
Definition: buffer.h:623
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
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
int evbuffer_write(struct evbuffer *buffer, evutil_socket_t fd)
Write the contents of an evbuffer to a file descriptor.
Definition: buffer.c:2327
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
Describes a single extent of memory inside an evbuffer.
Definition: buffer.h:125
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
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
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
Definition: event-internal.h:167
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
int evbuffer_expand(struct evbuffer *buf, size_t datlen)
Expands the available space in an evbuffer.
Definition: buffer.c:1888
void evbuffer_unlock(struct evbuffer *buf)
Release the lock on an evbuffer.
Definition: buffer.c:536