external/bsd/libevent/dist/evbuffer-internal.h

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