libevent/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. */
  60 struct 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
  76 struct bufferevent;
  77 struct evbuffer_chain;
  78 struct 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
 133         /** Used to implement deferred callbacks. */
 134         struct deferred_cb_queue *cb_queue;
 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. */
 144         struct deferred_cb deferred;
 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. */
 151         struct bufferevent *parent;
 152 };
 153
 154 /** A single item in an evbuffer. */
 155 struct evbuffer_chain {
 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  */
 199 struct evbuffer_chain_fd {
 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. */
 205 struct evbuffer_chain_reference {
 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_ */