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