1/* 2 * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> 3 * Copyright (c) 2007-2012 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 31extern "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. */ 60struct evbuffer_cb_entry { 61 /** Structures to implement a doubly-linked queue of callbacks */ 62 TAILQ_ENTRY(evbuffer_cb_entry) next; 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 76struct bufferevent; 77struct evbuffer_chain; 78struct evbuffer { 79 /** The first chain in this buffer's linked list of chains. */ 80 struct evbuffer_chain *first; 81 /** The last chain in this buffer's linked list of chains. */ 82 struct evbuffer_chain *last; 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 */ 97 struct evbuffer_chain **last_with_datap; 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 /** Zero or more EVBUFFER_FLAG_* bits */ 133 ev_uint32_t flags; 134 135 /** Used to implement deferred callbacks. */ 136 struct deferred_cb_queue *cb_queue; 137 138 /** A reference count on this evbuffer. When the reference count 139 * reaches 0, the buffer is destroyed. Manipulated with 140 * evbuffer_incref and evbuffer_decref_and_unlock and 141 * evbuffer_free. */ 142 int refcnt; 143 144 /** A deferred_cb handle to make all of this buffer's callbacks 145 * invoked from the event loop. */ 146 struct deferred_cb deferred; 147 148 /** A doubly-linked-list of callback functions */ 149 TAILQ_HEAD(evbuffer_cb_queue, evbuffer_cb_entry) callbacks; 150 151 /** The parent bufferevent object this evbuffer belongs to. 152 * NULL if the evbuffer stands alone. */ 153 struct bufferevent *parent; 154}; 155 156/** A single item in an evbuffer. */ 157struct evbuffer_chain { 158 /** points to next buffer in the chain */ 159 struct evbuffer_chain *next; 160 161 /** total allocation available in the buffer field. */ 162 size_t buffer_len; 163 164 /** unused space at the beginning of buffer or an offset into a 165 * file for sendfile buffers. */ 166 ev_off_t misalign; 167 168 /** Offset into buffer + misalign at which to start writing. 169 * In other words, the total number of bytes actually stored 170 * in buffer. */ 171 size_t off; 172 173 /** Set if special handling is required for this chain */ 174 unsigned flags; 175#define EVBUFFER_MMAP 0x0001 /**< memory in buffer is mmaped */ 176#define EVBUFFER_SENDFILE 0x0002 /**< a chain used for sendfile */ 177#define EVBUFFER_REFERENCE 0x0004 /**< a chain with a mem reference */ 178#define EVBUFFER_IMMUTABLE 0x0008 /**< read-only chain */ 179 /** a chain that mustn't be reallocated or freed, or have its contents 180 * memmoved, until the chain is un-pinned. */ 181#define EVBUFFER_MEM_PINNED_R 0x0010 182#define EVBUFFER_MEM_PINNED_W 0x0020 183#define EVBUFFER_MEM_PINNED_ANY (EVBUFFER_MEM_PINNED_R|EVBUFFER_MEM_PINNED_W) 184 /** a chain that should be freed, but can't be freed until it is 185 * un-pinned. */ 186#define EVBUFFER_DANGLING 0x0040 187 188 /** Usually points to the read-write memory belonging to this 189 * buffer allocated as part of the evbuffer_chain allocation. 190 * For mmap, this can be a read-only buffer and 191 * EVBUFFER_IMMUTABLE will be set in flags. For sendfile, it 192 * may point to NULL. 193 */ 194 unsigned char *buffer; 195}; 196 197/* this is currently used by both mmap and sendfile */ 198/* TODO(niels): something strange needs to happen for Windows here, I am not 199 * sure what that is, but it needs to get looked into. 200 */ 201struct evbuffer_chain_fd { 202 int fd; /**< the fd associated with this chain */ 203}; 204 205/** callback for a reference buffer; lets us know what to do with it when 206 * we're done with it. */ 207struct evbuffer_chain_reference { 208 evbuffer_ref_cleanup_cb cleanupfn; 209 void *extra; 210}; 211 212#define EVBUFFER_CHAIN_SIZE sizeof(struct evbuffer_chain) 213/** Return a pointer to extra data allocated along with an evbuffer. */ 214#define EVBUFFER_CHAIN_EXTRA(t, c) (t *)((struct evbuffer_chain *)(c) + 1) 215 216/** Assert that we are holding the lock on an evbuffer */ 217#define ASSERT_EVBUFFER_LOCKED(buffer) \ 218 EVLOCK_ASSERT_LOCKED((buffer)->lock) 219 220#define EVBUFFER_LOCK(buffer) \ 221 do { \ 222 EVLOCK_LOCK((buffer)->lock, 0); \ 223 } while (0) 224#define EVBUFFER_UNLOCK(buffer) \ 225 do { \ 226 EVLOCK_UNLOCK((buffer)->lock, 0); \ 227 } while (0) 228#define EVBUFFER_LOCK2(buffer1, buffer2) \ 229 do { \ 230 EVLOCK_LOCK2((buffer1)->lock, (buffer2)->lock, 0, 0); \ 231 } while (0) 232#define EVBUFFER_UNLOCK2(buffer1, buffer2) \ 233 do { \ 234 EVLOCK_UNLOCK2((buffer1)->lock, (buffer2)->lock, 0, 0); \ 235 } while (0) 236 237/** Increase the reference count of buf by one. */ 238void _evbuffer_incref(struct evbuffer *buf); 239/** Increase the reference count of buf by one and acquire the lock. */ 240void _evbuffer_incref_and_lock(struct evbuffer *buf); 241/** Pin a single buffer chain using a given flag. A pinned chunk may not be 242 * moved or freed until it is unpinned. */ 243void _evbuffer_chain_pin(struct evbuffer_chain *chain, unsigned flag); 244/** Unpin a single buffer chain using a given flag. */ 245void _evbuffer_chain_unpin(struct evbuffer_chain *chain, unsigned flag); 246/** As evbuffer_free, but requires that we hold a lock on the buffer, and 247 * releases the lock before freeing it and the buffer. */ 248void _evbuffer_decref_and_unlock(struct evbuffer *buffer); 249 250/** As evbuffer_expand, but does not guarantee that the newly allocated memory 251 * is contiguous. Instead, it may be split across two or more chunks. */ 252int _evbuffer_expand_fast(struct evbuffer *, size_t, int); 253 254/** Helper: prepares for a readv/WSARecv call by expanding the buffer to 255 * hold enough memory to read 'howmuch' bytes in possibly noncontiguous memory. 256 * Sets up the one or two iovecs in 'vecs' to point to the free memory and its 257 * extent, and *chainp to point to the first chain that we'll try to read into. 258 * Returns the number of vecs used. 259 */ 260int _evbuffer_read_setup_vecs(struct evbuffer *buf, ev_ssize_t howmuch, 261 struct evbuffer_iovec *vecs, int n_vecs, struct evbuffer_chain ***chainp, 262 int exact); 263 264/* Helper macro: copies an evbuffer_iovec in ei to a win32 WSABUF in i. */ 265#define WSABUF_FROM_EVBUFFER_IOV(i,ei) do { \ 266 (i)->buf = (ei)->iov_base; \ 267 (i)->len = (unsigned long)(ei)->iov_len; \ 268 } while (0) 269/* XXXX the cast above is safe for now, but not if we allow mmaps on win64. 270 * See note in buffer_iocp's launch_write function */ 271 272/** Set the parent bufferevent object for buf to bev */ 273void evbuffer_set_parent(struct evbuffer *buf, struct bufferevent *bev); 274 275void evbuffer_invoke_callbacks(struct evbuffer *buf); 276 277#ifdef __cplusplus 278} 279#endif 280 281#endif /* _EVBUFFER_INTERNAL_H_ */ 282