libevent/include/event2/thread.h

   1 /*
   2  * Copyright (c) 2008-2010 Niels Provos and Nick Mathewson
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  * 1. Redistributions of source code must retain the above copyright
   8  *    notice, this list of conditions and the following disclaimer.
   9  * 2. Redistributions in binary form must reproduce the above copyright
  10  *    notice, this list of conditions and the following disclaimer in the
  11  *    documentation and/or other materials provided with the distribution.
  12  * 3. The name of the author may not be used to endorse or promote products
  13  *    derived from this software without specific prior written permission.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25  */
  26 #ifndef _EVENT2_THREAD_H_
  27 #define _EVENT2_THREAD_H_
  28
  29 /** @file thread.h
  30
  31   Functions for multi-threaded applications using Libevent.
  32
  33   When using a multi-threaded application in which multiple threads
  34   add and delete events from a single event base, Libevent needs to
  35   lock its data structures.
  36
  37   Like the memory-management function hooks, all of the threading functions
  38   _must_ be set up before an event_base is created if you want the base to
  39   use them.
  40
  41   A multi-threaded application must provide locking functions to
  42   Libevent via evthread_set_locking_callback().  Libevent will invoke
  43   this callback whenever a lock needs to be acquired or released.
  44
  45   The total number of locks employed by Libevent can be determined
  46   via the evthread_num_locks() function.  An application must provision
  47   that many locks.
  48
  49   If the owner of an event base is waiting for events to happen,
  50   Libevent may signal the thread via a special file descriptor to wake
  51   up.   To enable this feature, an application needs to provide a
  52   thread identity function via evthread_set_id_callback().
  53
  54  */
  55
  56 #ifdef __cplusplus
  57 extern "C" {
  58 #endif
  59
  60 #include <event2/event-config.h>
  61
  62 /** A flag passed to a locking callback when the lock was allocated as a
  63  * read-write lock, and we want to acquire or release the lock for writing. */
  64 #define EVTHREAD_WRITE  0x04
  65 /** A flag passed to a locking callback when the lock was allocated as a
  66  * read-write lock, and we want to acquire or release the lock for reading. */
  67 #define EVTHREAD_READ   0x08
  68 /** A flag passed to a locking callback when we don't want to block waiting
  69  * for the lock; if we can't get the lock immediately, we will instead
  70  * return nonzero from the locking callback. */
  71 #define EVTHREAD_TRY    0x10
  72
  73 #ifndef _EVENT_DISABLE_THREAD_SUPPORT
  74
  75 #define EVTHREAD_LOCK_API_VERSION 1
  76
  77 /** A recursive lock is one that can be acquired multiple times at once by the
  78  * same thread.  No other process can allocate the lock until the thread that
  79  * has been holding it has unlocked it as many times as it locked it. */
  80 #define EVTHREAD_LOCKTYPE_RECURSIVE 1
  81 /* A read-write lock is one that allows multiple simultaneous readers, but
  82  * where any one writer excludes all other writers and readers. */
  83 #define EVTHREAD_LOCKTYPE_READWRITE 2
  84
  85 /** This structure describes the interface a threading library uses for
  86  * locking.   It's used to tell evthread_set_lock_callbacks how to use
  87  * locking on this platform.
  88  */
  89 struct evthread_lock_callbacks {
  90         /** The current version of the locking API.  Set this to
  91          * EVTHREAD_LOCK_API_VERSION */
  92         int lock_api_version;
  93         /** Which kinds of locks does this version of the locking API
  94          * support?  A bitfield of EVTHREAD_LOCKTYPE_RECURSIVE and
  95          * EVTHREAD_LOCKTYPE_READWRITE.
  96          *
  97          * (Note that RECURSIVE locks are currently mandatory, and
  98          * READWRITE locks are not currently used.)
  99          **/
 100         unsigned supported_locktypes;
 101         /** Function to allocate and initialize new lock of type 'locktype'.
 102          * Returns NULL on failure. */
 103         void *(*alloc)(unsigned locktype);
 104         /** Funtion to release all storage held in 'lock', which was created
 105          * with type 'locktype'. */
 106         void (*free)(void *lock, unsigned locktype);
 107         /** Acquire an already-allocated lock at 'lock' with mode 'mode'.
 108          * Returns 0 on success, and nonzero on failure. */
 109         int (*lock)(unsigned mode, void *lock);
 110         /** Release a lock at 'lock' using mode 'mode'.  Returns 0 on success,
 111          * and nonzero on failure. */
 112         int (*unlock)(unsigned mode, void *lock);
 113 };
 114
 115 /** Sets a group of functions that Libevent should use for locking.
 116  * For full information on the required callback API, see the
 117  * documentation for the individual members of evthread_lock_callbacks.
 118  *
 119  * Note that if you're using Windows or the Pthreads threading library, you
 120  * probably shouldn't call this function; instead, use
 121  * evthread_use_windows_threads() or evthread_use_posix_threads() if you can.
 122  */
 123 int evthread_set_lock_callbacks(const struct evthread_lock_callbacks *);
 124
 125 #define EVTHREAD_CONDITION_API_VERSION 1
 126
 127 struct timeval;
 128
 129 /** This structure describes the interface a threading library uses for
 130  * condition variables.  It's used to tell evthread_set_condition_callbacks
 131  * how to use locking on this platform.
 132  */
 133 struct evthread_condition_callbacks {
 134         /** The current version of the conditions API.  Set this to
 135          * EVTHREAD_CONDITION_API_VERSION */
 136         int condition_api_version;
 137         /** Function to allocate and initialize a new condition variable.
 138          * Returns the condition variable on success, and NULL on failure.
 139          * The 'condtype' argument will be 0 with this API version.
 140          */
 141         void *(*alloc_condition)(unsigned condtype);
 142         /** Function to free a condition variable. */
 143         void (*free_condition)(void *cond);
 144         /** Function to signal a condition variable.  If 'broadcast' is 1, all
 145          * threads waiting on 'cond' should be woken; otherwise, only on one
 146          * thread is worken.  Should return 0 on success, -1 on failure.
 147          * This function will only be called while holding the associated
 148          * lock for the condition.
 149          */
 150         int (*signal_condition)(void *cond, int broadcast);
 151         /** Function to wait for a condition variable.  The lock 'lock'
 152          * will be held when this function is called; should be released
 153          * while waiting for the condition to be come signalled, and
 154          * should be held again when this function returns.
 155          * If timeout is provided, it is interval of seconds to wait for
 156          * the event to become signalled; if it is NULL, the function
 157          * should wait indefinitely.
 158          *
 159          * The function should return -1 on error; 0 if the condition
 160          * was signalled, or 1 on a timeout. */
 161         int (*wait_condition)(void *cond, void *lock,
 162             const struct timeval *timeout);
 163 };
 164
 165 /** Sets a group of functions that Libevent should use for condition variables.
 166  * For full information on the required callback API, see the
 167  * documentation for the individual members of evthread_condition_callbacks.
 168  *
 169  * Note that if you're using Windows or the Pthreads threading library, you
 170  * probably shouldn't call this function; instead, use
 171  * evthread_use_windows_threads() or evthread_use_posix_threads() if you can.
 172  */
 173 int evthread_set_condition_callbacks(
 174         const struct evthread_condition_callbacks *);
 175
 176 /**
 177    Sets the function for determining the thread id.
 178
 179    @param base the event base for which to set the id function
 180    @param id_fn the identify function Libevent should invoke to
 181      determine the identity of a thread.
 182 */
 183 void evthread_set_id_callback(
 184     unsigned long (*id_fn)(void));
 185
 186 #if defined(WIN32) && !defined(_EVENT_DISABLE_THREAD_SUPPORT)
 187 /** Sets up Libevent for use with Windows builtin locking and thread ID
 188         functions.  Unavailable if Libevent is not built for Windows.
 189
 190         @return 0 on success, -1 on failure. */
 191 int evthread_use_windows_threads(void);
 192 #define EVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED 1
 193 #endif
 194
 195 #if defined(_EVENT_HAVE_PTHREADS)
 196 /** Sets up Libevent for use with Pthreads locking and thread ID functions.
 197         Unavailable if Libevent is not build for use with pthreads.  Requires
 198         libraries to link against Libevent_pthreads as well as Libevent.
 199
 200         @return 0 on success, -1 on failure. */
 201 int evthread_use_pthreads(void);
 202 #define EVTHREAD_USE_PTHREADS_IMPLEMENTED 1
 203
 204 #endif
 205
 206 /** Enable debugging wrappers around the current lock callbacks.  If Libevent
 207  * makes one of several common locking errors, exit with an assertion failure.
 208  **/
 209 void evthread_enable_lock_debuging(void);
 210
 211 #endif /* _EVENT_DISABLE_THREAD_SUPPORT */
 212
 213 struct event_base;
 214 /** Make sure it's safe to tell an event base to wake up from another thread.
 215     or a signal handler.
 216
 217         @return 0 on success, -1 on failure.
 218  */
 219 int evthread_make_base_notifiable(struct event_base *base);
 220
 221 #ifdef __cplusplus
 222 }
 223 #endif
 224
 225 #endif /* _EVENT2_THREAD_H_ */