OpenMPI  0.1.1
evbuffer-internal.h
1 /*
2  * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu>
3  * Copyright (c) 2007-2010 Niels Provos and Nick Mathewson
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. The name of the author may not be used to endorse or promote products
14  * derived from this software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  */
27 #ifndef _EVBUFFER_INTERNAL_H_
28 #define _EVBUFFER_INTERNAL_H_
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 #include "event2/event-config.h"
35 #include "event2/util.h"
36 #include "util-internal.h"
37 #include "defer-internal.h"
38 
39 /* Experimental cb flag: "never deferred." Implementation note:
40  * these callbacks may get an inaccurate view of n_del/n_added in their
41  * arguments. */
42 #define EVBUFFER_CB_NODEFER 2
43 
44 #ifdef WIN32
45 #include <winsock2.h>
46 #endif
47 #include <sys/queue.h>
48 
49 /* Minimum allocation for a chain. We define this so that we're burning no
50  * more than 5% of each allocation on overhead. It would be nice to lose even
51  * less space, though. */
52 #if _EVENT_SIZEOF_VOID_P < 8
53 #define MIN_BUFFER_SIZE 512
54 #else
55 #define MIN_BUFFER_SIZE 1024
56 #endif
57 
58 /** A single evbuffer callback for an evbuffer. This function will be invoked
59  * when bytes are added to or removed from the evbuffer. */
61  /** Structures to implement a doubly-linked queue of callbacks */
63  /** The callback function to invoke when this callback is called.
64  If EVBUFFER_CB_OBSOLETE is set in flags, the cb_obsolete field is
65  valid; otherwise, cb_func is valid. */
66  union {
67  evbuffer_cb_func cb_func;
68  evbuffer_cb cb_obsolete;
69  } cb;
70  /** Argument to pass to cb. */
71  void *cbarg;
72  /** Currently set flags on this callback. */
73  ev_uint32_t flags;
74 };
75 
76 struct bufferevent;
77 struct evbuffer_chain;
78 struct evbuffer {
79  /** The first chain in this buffer's linked list of chains. */
81  /** The last chain in this buffer's linked list of chains. */
83 
84  /** Pointer to the next pointer pointing at the 'last_with_data' chain.
85  *
86  * To unpack:
87  *
88  * The last_with_data chain is the last chain that has any data in it.
89  * If all chains in the buffer are empty, it is the first chain.
90  * If the buffer has no chains, it is NULL.
91  *
92  * The last_with_datap pointer points at _whatever 'next' pointer_
93  * points at the last_with_datap chain. If the last_with_data chain
94  * is the first chain, or it is NULL, then the last_with_datap pointer
95  * is &buf->first.
96  */
98 
99  /** Total amount of bytes stored in all chains.*/
100  size_t total_len;
101 
102  /** Number of bytes we have added to the buffer since we last tried to
103  * invoke callbacks. */
104  size_t n_add_for_cb;
105  /** Number of bytes we have removed from the buffer since we last
106  * tried to invoke callbacks. */
107  size_t n_del_for_cb;
108 
109 #ifndef _EVENT_DISABLE_THREAD_SUPPORT
110  /** A lock used to mediate access to this buffer. */
111  void *lock;
112 #endif
113  /** True iff we should free the lock field when we free this
114  * evbuffer. */
115  unsigned own_lock : 1;
116  /** True iff we should not allow changes to the front of the buffer
117  * (drains or prepends). */
118  unsigned freeze_start : 1;
119  /** True iff we should not allow changes to the end of the buffer
120  * (appends) */
121  unsigned freeze_end : 1;
122  /** True iff this evbuffer's callbacks are not invoked immediately
123  * upon a change in the buffer, but instead are deferred to be invoked
124  * from the event_base's loop. Useful for preventing enormous stack
125  * overflows when we have mutually recursive callbacks, and for
126  * serializing callbacks in a single thread. */
127  unsigned deferred_cbs : 1;
128 #ifdef WIN32
129  /** True iff this buffer is set up for overlapped IO. */
130  unsigned is_overlapped : 1;
131 #endif
132 
133  /** Used to implement deferred callbacks. */
135 
136  /** A reference count on this evbuffer. When the reference count
137  * reaches 0, the buffer is destroyed. Manipulated with
138  * evbuffer_incref and evbuffer_decref_and_unlock and
139  * evbuffer_free. */
140  int refcnt;
141 
142  /** A deferred_cb handle to make all of this buffer's callbacks
143  * invoked from the event loop. */
145 
146  /** A doubly-linked-list of callback functions */
147  TAILQ_HEAD(evbuffer_cb_queue, evbuffer_cb_entry) callbacks;
148 
149  /** The parent bufferevent object this evbuffer belongs to.
150  * NULL if the evbuffer stands alone. */
152 };
153 
154 /** A single item in an evbuffer. */
156  /** points to next buffer in the chain */
157  struct evbuffer_chain *next;
158 
159  /** total allocation available in the buffer field. */
160  size_t buffer_len;
161 
162  /** unused space at the beginning of buffer or an offset into a
163  * file for sendfile buffers. */
164  ev_off_t misalign;
165 
166  /** Offset into buffer + misalign at which to start writing.
167  * In other words, the total number of bytes actually stored
168  * in buffer. */
169  size_t off;
170 
171  /** Set if special handling is required for this chain */
172  unsigned flags;
173 #define EVBUFFER_MMAP 0x0001 /**< memory in buffer is mmaped */
174 #define EVBUFFER_SENDFILE 0x0002 /**< a chain used for sendfile */
175 #define EVBUFFER_REFERENCE 0x0004 /**< a chain with a mem reference */
176 #define EVBUFFER_IMMUTABLE 0x0008 /**< read-only chain */
177  /** a chain that mustn't be reallocated or freed, or have its contents
178  * memmoved, until the chain is un-pinned. */
179 #define EVBUFFER_MEM_PINNED_R 0x0010
180 #define EVBUFFER_MEM_PINNED_W 0x0020
181 #define EVBUFFER_MEM_PINNED_ANY (EVBUFFER_MEM_PINNED_R|EVBUFFER_MEM_PINNED_W)
182  /** a chain that should be freed, but can't be freed until it is
183  * un-pinned. */
184 #define EVBUFFER_DANGLING 0x0040
185 
186  /** Usually points to the read-write memory belonging to this
187  * buffer allocated as part of the evbuffer_chain allocation.
188  * For mmap, this can be a read-only buffer and
189  * EVBUFFER_IMMUTABLE will be set in flags. For sendfile, it
190  * may point to NULL.
191  */
192  unsigned char *buffer;
193 };
194 
195 /* this is currently used by both mmap and sendfile */
196 /* TODO(niels): something strange needs to happen for Windows here, I am not
197  * sure what that is, but it needs to get looked into.
198  */
200  int fd; /**< the fd associated with this chain */
201 };
202 
203 /** callback for a reference buffer; lets us know what to do with it when
204  * we're done with it. */
206  evbuffer_ref_cleanup_cb cleanupfn;
207  void *extra;
208 };
209 
210 #define EVBUFFER_CHAIN_SIZE sizeof(struct evbuffer_chain)
211 /** Return a pointer to extra data allocated along with an evbuffer. */
212 #define EVBUFFER_CHAIN_EXTRA(t, c) (t *)((struct evbuffer_chain *)(c) + 1)
213 
214 /** Assert that we are holding the lock on an evbuffer */
215 #define ASSERT_EVBUFFER_LOCKED(buffer) \
216  EVLOCK_ASSERT_LOCKED((buffer)->lock)
217 
218 #define EVBUFFER_LOCK(buffer) \
219  do { \
220  EVLOCK_LOCK((buffer)->lock, 0); \
221  } while (0)
222 #define EVBUFFER_UNLOCK(buffer) \
223  do { \
224  EVLOCK_UNLOCK((buffer)->lock, 0); \
225  } while (0)
226 #define EVBUFFER_LOCK2(buffer1, buffer2) \
227  do { \
228  EVLOCK_LOCK2((buffer1)->lock, (buffer2)->lock, 0, 0); \
229  } while (0)
230 #define EVBUFFER_UNLOCK2(buffer1, buffer2) \
231  do { \
232  EVLOCK_UNLOCK2((buffer1)->lock, (buffer2)->lock, 0, 0); \
233  } while (0)
234 
235 /** Increase the reference count of buf by one. */
236 void _evbuffer_incref(struct evbuffer *buf);
237 /** Increase the reference count of buf by one and acquire the lock. */
238 void _evbuffer_incref_and_lock(struct evbuffer *buf);
239 /** Pin a single buffer chain using a given flag. A pinned chunk may not be
240  * moved or freed until it is unpinned. */
241 void _evbuffer_chain_pin(struct evbuffer_chain *chain, unsigned flag);
242 /** Unpin a single buffer chain using a given flag. */
243 void _evbuffer_chain_unpin(struct evbuffer_chain *chain, unsigned flag);
244 /** As evbuffer_free, but requires that we hold a lock on the buffer, and
245  * releases the lock before freeing it and the buffer. */
246 void _evbuffer_decref_and_unlock(struct evbuffer *buffer);
247 
248 /** As evbuffer_expand, but does not guarantee that the newly allocated memory
249  * is contiguous. Instead, it may be split across two or more chunks. */
250 int _evbuffer_expand_fast(struct evbuffer *, size_t, int);
251 
252 /** Helper: prepares for a readv/WSARecv call by expanding the buffer to
253  * hold enough memory to read 'howmuch' bytes in possibly noncontiguous memory.
254  * Sets up the one or two iovecs in 'vecs' to point to the free memory and its
255  * extent, and *chainp to point to the first chain that we'll try to read into.
256  * Returns the number of vecs used.
257  */
258 int _evbuffer_read_setup_vecs(struct evbuffer *buf, ev_ssize_t howmuch,
259  struct evbuffer_iovec *vecs, int n_vecs, struct evbuffer_chain ***chainp,
260  int exact);
261 
262 /* Helper macro: copies an evbuffer_iovec in ei to a win32 WSABUF in i. */
263 #define WSABUF_FROM_EVBUFFER_IOV(i,ei) do { \
264  (i)->buf = (ei)->iov_base; \
265  (i)->len = (unsigned long)(ei)->iov_len; \
266  } while (0)
267 /* XXXX the cast above is safe for now, but not if we allow mmaps on win64.
268  * See note in buffer_iocp's launch_write function */
269 
270 /** Set the parent bufferevent object for buf to bev */
271 void evbuffer_set_parent(struct evbuffer *buf, struct bufferevent *bev);
272 
273 #ifdef __cplusplus
274 }
275 #endif
276 
277 #endif /* _EVBUFFER_INTERNAL_H_ */
struct evbuffer_chain * first
The first chain in this buffer's linked list of chains.
Definition: evbuffer-internal.h:80
struct evbuffer_chain * last
The last chain in this buffer's linked list of chains.
Definition: evbuffer-internal.h:82
callback for a reference buffer; lets us know what to do with it when we're done with it...
Definition: evbuffer-internal.h:205
A single evbuffer callback for an evbuffer.
Definition: evbuffer-internal.h:60
unsigned flags
Set if special handling is required for this chain.
Definition: evbuffer-internal.h:172
void * lock
A lock used to mediate access to this buffer.
Definition: evbuffer-internal.h:111
union evbuffer_cb_entry::@9 cb
The callback function to invoke when this callback is called.
unsigned char * buffer
Usually points to the read-write memory belonging to this buffer allocated as part of the evbuffer_ch...
Definition: evbuffer-internal.h:192
struct deferred_cb_queue * cb_queue
Used to implement deferred callbacks.
Definition: evbuffer-internal.h:134
size_t total_len
Total amount of bytes stored in all chains.
Definition: evbuffer-internal.h:100
TAILQ_ENTRY(evbuffer_cb_entry) next
Structures to implement a doubly-linked queue of callbacks.
struct bufferevent * parent
The parent bufferevent object this evbuffer belongs to.
Definition: evbuffer-internal.h:151
TAILQ_HEAD(evbuffer_cb_queue, evbuffer_cb_entry) callbacks
A doubly-linked-list of callback functions.
size_t n_add_for_cb
Number of bytes we have added to the buffer since we last tried to invoke callbacks.
Definition: evbuffer-internal.h:104
Definition: evbuffer-internal.h:78
size_t off
Offset into buffer + misalign at which to start writing.
Definition: evbuffer-internal.h:169
void(* evbuffer_cb)(struct evbuffer *buffer, size_t old_len, size_t new_len, void *arg)
Type definition for a callback that is invoked whenever data is added or removed from an evbuffer...
Definition: buffer_compat.h:70
unsigned freeze_end
True iff we should not allow changes to the end of the buffer (appends)
Definition: evbuffer-internal.h:121
Definition: evbuffer-internal.h:199
size_t n_del_for_cb
Number of bytes we have removed from the buffer since we last tried to invoke callbacks.
Definition: evbuffer-internal.h:107
Common convenience functions for cross-platform portability and related socket manipulations.
struct deferred_cb deferred
A deferred_cb handle to make all of this buffer's callbacks invoked from the event loop...
Definition: evbuffer-internal.h:144
void * cbarg
Argument to pass to cb.
Definition: evbuffer-internal.h:71
unsigned deferred_cbs
True iff this evbuffer's callbacks are not invoked immediately upon a change in the buffer...
Definition: evbuffer-internal.h:127
int refcnt
A reference count on this evbuffer.
Definition: evbuffer-internal.h:140
ev_off_t misalign
unused space at the beginning of buffer or an offset into a file for sendfile buffers.
Definition: evbuffer-internal.h:164
unsigned own_lock
True iff we should free the lock field when we free this evbuffer.
Definition: evbuffer-internal.h:115
int fd
the fd associated with this chain
Definition: evbuffer-internal.h:200
unsigned freeze_start
True iff we should not allow changes to the front of the buffer (drains or prepends).
Definition: evbuffer-internal.h:118
ev_uint32_t flags
Currently set flags on this callback.
Definition: evbuffer-internal.h:73
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
A deferred_cb is a callback that can be scheduled to run as part of an event_base's event_loop...
Definition: defer-internal.h:42
struct evbuffer_chain ** last_with_datap
Pointer to the next pointer pointing at the 'last_with_data' chain.
Definition: evbuffer-internal.h:97
struct evbuffer_chain * next
points to next buffer in the chain
Definition: evbuffer-internal.h:157
Shared implementation of a bufferevent.
Definition: bufferevent_struct.h:70
size_t buffer_len
total allocation available in the buffer field.
Definition: evbuffer-internal.h:160
Describes a single extent of memory inside an evbuffer.
Definition: buffer.h:125
A single item in an evbuffer.
Definition: evbuffer-internal.h:155
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
A deferred_cb_queue is a list of deferred_cb that we can add to and run.
Definition: defer-internal.h:54