libevent/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_
  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         /** 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. */
 157 struct 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  */
 201 struct 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. */
 207 struct 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. */
 238 void _evbuffer_incref(struct evbuffer *buf);
 239 /** Increase the reference count of buf by one and acquire the lock. */
 240 void _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. */
 243 void _evbuffer_chain_pin(struct evbuffer_chain *chain, unsigned flag);
 244 /** Unpin a single buffer chain using a given flag. */
 245 void _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. */
 248 void _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. */
 252 int _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  */
 260 int _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 */
 273 void evbuffer_set_parent(struct evbuffer *buf, struct bufferevent *bev);
 274
 275 void evbuffer_invoke_callbacks(struct evbuffer *buf);
 276
 277 #ifdef __cplusplus
 278 }
 279 #endif
 280
 281 #endif /* _EVBUFFER_INTERNAL_H_ */