evbuffer-internal.h revision 275970
1250323Sdteske/* 2252980Sdteske * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> 3250323Sdteske * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 4250323Sdteske * 5250323Sdteske * Redistribution and use in source and binary forms, with or without 6250323Sdteske * modification, are permitted provided that the following conditions 7250323Sdteske * are met: 8250323Sdteske * 1. Redistributions of source code must retain the above copyright 9250323Sdteske * notice, this list of conditions and the following disclaimer. 10250323Sdteske * 2. Redistributions in binary form must reproduce the above copyright 11250323Sdteske * notice, this list of conditions and the following disclaimer in the 12250323Sdteske * documentation and/or other materials provided with the distribution. 13250323Sdteske * 3. The name of the author may not be used to endorse or promote products 14252987Sdteske * derived from this software without specific prior written permission. 15250323Sdteske * 16250323Sdteske * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17250323Sdteske * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18252987Sdteske * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19250323Sdteske * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20250323Sdteske * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21250323Sdteske * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22250323Sdteske * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23250323Sdteske * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24250323Sdteske * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25250323Sdteske * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26250323Sdteske */ 27250323Sdteske#ifndef EVBUFFER_INTERNAL_H_INCLUDED_ 28250323Sdteske#define EVBUFFER_INTERNAL_H_INCLUDED_ 29250323Sdteske 30250323Sdteske#ifdef __cplusplus 31250323Sdteskeextern "C" { 32250323Sdteske#endif 33250323Sdteske 34250323Sdteske#include "event2/event-config.h" 35250323Sdteske#include "evconfig-private.h" 36250323Sdteske#include "event2/util.h" 37250323Sdteske#include "event2/event_struct.h" 38#include "util-internal.h" 39#include "defer-internal.h" 40 41/* Experimental cb flag: "never deferred." Implementation note: 42 * these callbacks may get an inaccurate view of n_del/n_added in their 43 * arguments. */ 44#define EVBUFFER_CB_NODEFER 2 45 46#ifdef _WIN32 47#include <winsock2.h> 48#endif 49#include <sys/queue.h> 50 51/* Minimum allocation for a chain. We define this so that we're burning no 52 * more than 5% of each allocation on overhead. It would be nice to lose even 53 * less space, though. */ 54#if EVENT__SIZEOF_VOID_P < 8 55#define MIN_BUFFER_SIZE 512 56#else 57#define MIN_BUFFER_SIZE 1024 58#endif 59 60/** A single evbuffer callback for an evbuffer. This function will be invoked 61 * when bytes are added to or removed from the evbuffer. */ 62struct evbuffer_cb_entry { 63 /** Structures to implement a doubly-linked queue of callbacks */ 64 LIST_ENTRY(evbuffer_cb_entry) next; 65 /** The callback function to invoke when this callback is called. 66 If EVBUFFER_CB_OBSOLETE is set in flags, the cb_obsolete field is 67 valid; otherwise, cb_func is valid. */ 68 union { 69 evbuffer_cb_func cb_func; 70 evbuffer_cb cb_obsolete; 71 } cb; 72 /** Argument to pass to cb. */ 73 void *cbarg; 74 /** Currently set flags on this callback. */ 75 ev_uint32_t flags; 76}; 77 78struct bufferevent; 79struct evbuffer_chain; 80struct evbuffer { 81 /** The first chain in this buffer's linked list of chains. */ 82 struct evbuffer_chain *first; 83 /** The last chain in this buffer's linked list of chains. */ 84 struct evbuffer_chain *last; 85 86 /** Pointer to the next pointer pointing at the 'last_with_data' chain. 87 * 88 * To unpack: 89 * 90 * The last_with_data chain is the last chain that has any data in it. 91 * If all chains in the buffer are empty, it is the first chain. 92 * If the buffer has no chains, it is NULL. 93 * 94 * The last_with_datap pointer points at _whatever 'next' pointer_ 95 * points at the last_with_datap chain. If the last_with_data chain 96 * is the first chain, or it is NULL, then the last_with_datap pointer 97 * is &buf->first. 98 */ 99 struct evbuffer_chain **last_with_datap; 100 101 /** Total amount of bytes stored in all chains.*/ 102 size_t total_len; 103 104 /** Number of bytes we have added to the buffer since we last tried to 105 * invoke callbacks. */ 106 size_t n_add_for_cb; 107 /** Number of bytes we have removed from the buffer since we last 108 * tried to invoke callbacks. */ 109 size_t n_del_for_cb; 110 111#ifndef EVENT__DISABLE_THREAD_SUPPORT 112 /** A lock used to mediate access to this buffer. */ 113 void *lock; 114#endif 115 /** True iff we should free the lock field when we free this 116 * evbuffer. */ 117 unsigned own_lock : 1; 118 /** True iff we should not allow changes to the front of the buffer 119 * (drains or prepends). */ 120 unsigned freeze_start : 1; 121 /** True iff we should not allow changes to the end of the buffer 122 * (appends) */ 123 unsigned freeze_end : 1; 124 /** True iff this evbuffer's callbacks are not invoked immediately 125 * upon a change in the buffer, but instead are deferred to be invoked 126 * from the event_base's loop. Useful for preventing enormous stack 127 * overflows when we have mutually recursive callbacks, and for 128 * serializing callbacks in a single thread. */ 129 unsigned deferred_cbs : 1; 130#ifdef _WIN32 131 /** True iff this buffer is set up for overlapped IO. */ 132 unsigned is_overlapped : 1; 133#endif 134 /** Zero or more EVBUFFER_FLAG_* bits */ 135 ev_uint32_t flags; 136 137 /** Used to implement deferred callbacks. */ 138 struct event_base *cb_queue; 139 140 /** A reference count on this evbuffer. When the reference count 141 * reaches 0, the buffer is destroyed. Manipulated with 142 * evbuffer_incref and evbuffer_decref_and_unlock and 143 * evbuffer_free. */ 144 int refcnt; 145 146 /** A struct event_callback handle to make all of this buffer's callbacks 147 * invoked from the event loop. */ 148 struct event_callback deferred; 149 150 /** A doubly-linked-list of callback functions */ 151 LIST_HEAD(evbuffer_cb_queue, evbuffer_cb_entry) callbacks; 152 153 /** The parent bufferevent object this evbuffer belongs to. 154 * NULL if the evbuffer stands alone. */ 155 struct bufferevent *parent; 156}; 157 158/** A single item in an evbuffer. */ 159struct evbuffer_chain { 160 /** points to next buffer in the chain */ 161 struct evbuffer_chain *next; 162 163 /** total allocation available in the buffer field. */ 164 size_t buffer_len; 165 166 /** unused space at the beginning of buffer or an offset into a 167 * file for sendfile buffers. */ 168 ev_off_t misalign; 169 170 /** Offset into buffer + misalign at which to start writing. 171 * In other words, the total number of bytes actually stored 172 * in buffer. */ 173 size_t off; 174 175 /** Set if special handling is required for this chain */ 176 unsigned flags; 177#define EVBUFFER_FILESEGMENT 0x0001 /**< A chain used for a file segment */ 178#define EVBUFFER_SENDFILE 0x0002 /**< a chain used with sendfile */ 179#define EVBUFFER_REFERENCE 0x0004 /**< a chain with a mem reference */ 180#define EVBUFFER_IMMUTABLE 0x0008 /**< read-only chain */ 181 /** a chain that mustn't be reallocated or freed, or have its contents 182 * memmoved, until the chain is un-pinned. */ 183#define EVBUFFER_MEM_PINNED_R 0x0010 184#define EVBUFFER_MEM_PINNED_W 0x0020 185#define EVBUFFER_MEM_PINNED_ANY (EVBUFFER_MEM_PINNED_R|EVBUFFER_MEM_PINNED_W) 186 /** a chain that should be freed, but can't be freed until it is 187 * un-pinned. */ 188#define EVBUFFER_DANGLING 0x0040 189 /** a chain that is a referenced copy of another chain */ 190#define EVBUFFER_MULTICAST 0x0080 191 192 /** number of references to this chain */ 193 int refcnt; 194 195 /** Usually points to the read-write memory belonging to this 196 * buffer allocated as part of the evbuffer_chain allocation. 197 * For mmap, this can be a read-only buffer and 198 * EVBUFFER_IMMUTABLE will be set in flags. For sendfile, it 199 * may point to NULL. 200 */ 201 unsigned char *buffer; 202}; 203 204/** callback for a reference chain; lets us know what to do with it when 205 * we're done with it. Lives at the end of an evbuffer_chain with the 206 * EVBUFFER_REFERENCE flag set */ 207struct evbuffer_chain_reference { 208 evbuffer_ref_cleanup_cb cleanupfn; 209 void *extra; 210}; 211 212/** File segment for a file-segment chain. Lives at the end of an 213 * evbuffer_chain with the EVBUFFER_FILESEGMENT flag set. */ 214struct evbuffer_chain_file_segment { 215 struct evbuffer_file_segment *segment; 216#ifdef _WIN32 217 /** If we're using CreateFileMapping, this is the handle to the view. */ 218 HANDLE view_handle; 219#endif 220}; 221 222/* Declared in event2/buffer.h; defined here. */ 223struct evbuffer_file_segment { 224 void *lock; /**< lock prevent concurrent access to refcnt */ 225 int refcnt; /**< Reference count for this file segment */ 226 unsigned flags; /**< combination of EVBUF_FS_* flags */ 227 228 /** What kind of file segment is this? */ 229 unsigned can_sendfile : 1; 230 unsigned is_mapping : 1; 231 232 /** The fd that we read the data from. */ 233 int fd; 234 /** If we're using mmap, this is the raw mapped memory. */ 235 void *mapping; 236#ifdef _WIN32 237 /** If we're using CreateFileMapping, this is the mapping */ 238 HANDLE mapping_handle; 239#endif 240 /** If we're using mmap or IO, this is the content of the file 241 * segment. */ 242 char *contents; 243 /** Position of this segment within the file. */ 244 ev_off_t file_offset; 245 /** If we're using mmap, this is the offset within 'mapping' where 246 * this data segment begins. */ 247 ev_off_t mmap_offset; 248 /** The length of this segment. */ 249 ev_off_t length; 250 /** Cleanup callback function */ 251 evbuffer_file_segment_cleanup_cb cleanup_cb; 252 /** Argument to be pass to cleanup callback function */ 253 void *cleanup_cb_arg; 254}; 255 256/** Information about the multicast parent of a chain. Lives at the 257 * end of an evbuffer_chain with the EVBUFFER_MULTICAST flag set. */ 258struct evbuffer_multicast_parent { 259 /** source buffer the multicast parent belongs to */ 260 struct evbuffer *source; 261 /** multicast parent for this chain */ 262 struct evbuffer_chain *parent; 263}; 264 265#define EVBUFFER_CHAIN_SIZE sizeof(struct evbuffer_chain) 266/** Return a pointer to extra data allocated along with an evbuffer. */ 267#define EVBUFFER_CHAIN_EXTRA(t, c) (t *)((struct evbuffer_chain *)(c) + 1) 268 269/** Assert that we are holding the lock on an evbuffer */ 270#define ASSERT_EVBUFFER_LOCKED(buffer) \ 271 EVLOCK_ASSERT_LOCKED((buffer)->lock) 272 273#define EVBUFFER_LOCK(buffer) \ 274 do { \ 275 EVLOCK_LOCK((buffer)->lock, 0); \ 276 } while (0) 277#define EVBUFFER_UNLOCK(buffer) \ 278 do { \ 279 EVLOCK_UNLOCK((buffer)->lock, 0); \ 280 } while (0) 281#define EVBUFFER_LOCK2(buffer1, buffer2) \ 282 do { \ 283 EVLOCK_LOCK2((buffer1)->lock, (buffer2)->lock, 0, 0); \ 284 } while (0) 285#define EVBUFFER_UNLOCK2(buffer1, buffer2) \ 286 do { \ 287 EVLOCK_UNLOCK2((buffer1)->lock, (buffer2)->lock, 0, 0); \ 288 } while (0) 289 290/** Increase the reference count of buf by one. */ 291void evbuffer_incref_(struct evbuffer *buf); 292/** Increase the reference count of buf by one and acquire the lock. */ 293void evbuffer_incref_and_lock_(struct evbuffer *buf); 294/** Pin a single buffer chain using a given flag. A pinned chunk may not be 295 * moved or freed until it is unpinned. */ 296void evbuffer_chain_pin_(struct evbuffer_chain *chain, unsigned flag); 297/** Unpin a single buffer chain using a given flag. */ 298void evbuffer_chain_unpin_(struct evbuffer_chain *chain, unsigned flag); 299/** As evbuffer_free, but requires that we hold a lock on the buffer, and 300 * releases the lock before freeing it and the buffer. */ 301void evbuffer_decref_and_unlock_(struct evbuffer *buffer); 302 303/** As evbuffer_expand, but does not guarantee that the newly allocated memory 304 * is contiguous. Instead, it may be split across two or more chunks. */ 305int evbuffer_expand_fast_(struct evbuffer *, size_t, int); 306 307/** Helper: prepares for a readv/WSARecv call by expanding the buffer to 308 * hold enough memory to read 'howmuch' bytes in possibly noncontiguous memory. 309 * Sets up the one or two iovecs in 'vecs' to point to the free memory and its 310 * extent, and *chainp to point to the first chain that we'll try to read into. 311 * Returns the number of vecs used. 312 */ 313int evbuffer_read_setup_vecs_(struct evbuffer *buf, ev_ssize_t howmuch, 314 struct evbuffer_iovec *vecs, int n_vecs, struct evbuffer_chain ***chainp, 315 int exact); 316 317/* Helper macro: copies an evbuffer_iovec in ei to a win32 WSABUF in i. */ 318#define WSABUF_FROM_EVBUFFER_IOV(i,ei) do { \ 319 (i)->buf = (ei)->iov_base; \ 320 (i)->len = (unsigned long)(ei)->iov_len; \ 321 } while (0) 322/* XXXX the cast above is safe for now, but not if we allow mmaps on win64. 323 * See note in buffer_iocp's launch_write function */ 324 325/** Set the parent bufferevent object for buf to bev */ 326void evbuffer_set_parent_(struct evbuffer *buf, struct bufferevent *bev); 327 328void evbuffer_invoke_callbacks_(struct evbuffer *buf); 329 330 331int evbuffer_get_callbacks_(struct evbuffer *buffer, 332 struct event_callback **cbs, 333 int max_cbs); 334 335#ifdef __cplusplus 336} 337#endif 338 339#endif /* EVBUFFER_INTERNAL_H_INCLUDED_ */ 340