granicus.if.org Git - libevent/blob - evbuffer-internal.h

   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_INCLUDED_
  28 #define EVBUFFER_INTERNAL_H_INCLUDED_
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 #include "event2/event-config.h"
  35 #include "evconfig-private.h"
  36 #include "event2/util.h"
  37 #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. */
  62 struct 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
  78 struct bufferevent;
  79 struct evbuffer_chain;
  80 struct 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          * pointing at the last_with_data 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         /** Maximum bytes per one read */
 104         size_t max_read;
 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_ */