contrib/ntp/sntp/libevent/include/event2/thread.h

   1 /*
   2  * Copyright (c) 2008-2012 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_INCLUDED_
  27 #define EVENT2_THREAD_H_INCLUDED_
  28
  29 /** @file event2/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   Most programs will either be using Windows threads or Posix threads.  You
  42   can configure Libevent to use one of these event_use_windows_threads() or
  43   event_use_pthreads() respectively.  If you're using another threading
  44   library, you'll need to configure threading functions manually using
  45   evthread_set_lock_callbacks() and evthread_set_condition_callbacks().
  46
  47  */
  48
  49 #include <event2/visibility.h>
  50
  51 #ifdef __cplusplus
  52 extern "C" {
  53 #endif
  54
  55 #include <event2/event-config.h>
  56
  57 /**
  58    @name Flags passed to lock functions
  59
  60    @{
  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
  74 #if !defined(EVENT__DISABLE_THREAD_SUPPORT) || defined(EVENT_IN_DOXYGEN_)
  75
  76 #define EVTHREAD_LOCK_API_VERSION 1
  77
  78 /**
  79    @name Types of locks
  80
  81    @{*/
  82 /** A recursive lock is one that can be acquired multiple times at once by the
  83  * same thread.  No other process can allocate the lock until the thread that
  84  * has been holding it has unlocked it as many times as it locked it. */
  85 #define EVTHREAD_LOCKTYPE_RECURSIVE 1
  86 /* A read-write lock is one that allows multiple simultaneous readers, but
  87  * where any one writer excludes all other writers and readers. */
  88 #define EVTHREAD_LOCKTYPE_READWRITE 2
  89 /**@}*/
  90
  91 /** This structure describes the interface a threading library uses for
  92  * locking.   It's used to tell evthread_set_lock_callbacks() how to use
  93  * locking on this platform.
  94  */
  95 struct evthread_lock_callbacks {
  96         /** The current version of the locking API.  Set this to
  97          * EVTHREAD_LOCK_API_VERSION */
  98         int lock_api_version;
  99         /** Which kinds of locks does this version of the locking API
 100          * support?  A bitfield of EVTHREAD_LOCKTYPE_RECURSIVE and
 101          * EVTHREAD_LOCKTYPE_READWRITE.
 102          *
 103          * (Note that RECURSIVE locks are currently mandatory, and
 104          * READWRITE locks are not currently used.)
 105          **/
 106         unsigned supported_locktypes;
 107         /** Function to allocate and initialize new lock of type 'locktype'.
 108          * Returns NULL on failure. */
 109         void *(*alloc)(unsigned locktype);
 110         /** Funtion to release all storage held in 'lock', which was created
 111          * with type 'locktype'. */
 112         void (*free)(void *lock, unsigned locktype);
 113         /** Acquire an already-allocated lock at 'lock' with mode 'mode'.
 114          * Returns 0 on success, and nonzero on failure. */
 115         int (*lock)(unsigned mode, void *lock);
 116         /** Release a lock at 'lock' using mode 'mode'.  Returns 0 on success,
 117          * and nonzero on failure. */
 118         int (*unlock)(unsigned mode, void *lock);
 119 };
 120
 121 /** Sets a group of functions that Libevent should use for locking.
 122  * For full information on the required callback API, see the
 123  * documentation for the individual members of evthread_lock_callbacks.
 124  *
 125  * Note that if you're using Windows or the Pthreads threading library, you
 126  * probably shouldn't call this function; instead, use
 127  * evthread_use_windows_threads() or evthread_use_posix_threads() if you can.
 128  */
 129 EVENT2_EXPORT_SYMBOL
 130 int evthread_set_lock_callbacks(const struct evthread_lock_callbacks *);
 131
 132 #define EVTHREAD_CONDITION_API_VERSION 1
 133
 134 struct timeval;
 135
 136 /** This structure describes the interface a threading library uses for
 137  * condition variables.  It's used to tell evthread_set_condition_callbacks
 138  * how to use locking on this platform.
 139  */
 140 struct evthread_condition_callbacks {
 141         /** The current version of the conditions API.  Set this to
 142          * EVTHREAD_CONDITION_API_VERSION */
 143         int condition_api_version;
 144         /** Function to allocate and initialize a new condition variable.
 145          * Returns the condition variable on success, and NULL on failure.
 146          * The 'condtype' argument will be 0 with this API version.
 147          */
 148         void *(*alloc_condition)(unsigned condtype);
 149         /** Function to free a condition variable. */
 150         void (*free_condition)(void *cond);
 151         /** Function to signal a condition variable.  If 'broadcast' is 1, all
 152          * threads waiting on 'cond' should be woken; otherwise, only on one
 153          * thread is worken.  Should return 0 on success, -1 on failure.
 154          * This function will only be called while holding the associated
 155          * lock for the condition.
 156          */
 157         int (*signal_condition)(void *cond, int broadcast);
 158         /** Function to wait for a condition variable.  The lock 'lock'
 159          * will be held when this function is called; should be released
 160          * while waiting for the condition to be come signalled, and
 161          * should be held again when this function returns.
 162          * If timeout is provided, it is interval of seconds to wait for
 163          * the event to become signalled; if it is NULL, the function
 164          * should wait indefinitely.
 165          *
 166          * The function should return -1 on error; 0 if the condition
 167          * was signalled, or 1 on a timeout. */
 168         int (*wait_condition)(void *cond, void *lock,
 169             const struct timeval *timeout);
 170 };
 171
 172 /** Sets a group of functions that Libevent should use for condition variables.
 173  * For full information on the required callback API, see the
 174  * documentation for the individual members of evthread_condition_callbacks.
 175  *
 176  * Note that if you're using Windows or the Pthreads threading library, you
 177  * probably shouldn't call this function; instead, use
 178  * evthread_use_windows_threads() or evthread_use_pthreads() if you can.
 179  */
 180 EVENT2_EXPORT_SYMBOL
 181 int evthread_set_condition_callbacks(
 182         const struct evthread_condition_callbacks *);
 183
 184 /**
 185    Sets the function for determining the thread id.
 186
 187    @param base the event base for which to set the id function
 188    @param id_fn the identify function Libevent should invoke to
 189      determine the identity of a thread.
 190 */
 191 EVENT2_EXPORT_SYMBOL
 192 void evthread_set_id_callback(
 193     unsigned long (*id_fn)(void));
 194
 195 #if (defined(_WIN32) && !defined(EVENT__DISABLE_THREAD_SUPPORT)) || defined(EVENT_IN_DOXYGEN_)
 196 /** Sets up Libevent for use with Windows builtin locking and thread ID
 197     functions.  Unavailable if Libevent is not built for Windows.
 198
 199     @return 0 on success, -1 on failure. */
 200 EVENT2_EXPORT_SYMBOL
 201 int evthread_use_windows_threads(void);
 202 /**
 203    Defined if Libevent was built with support for evthread_use_windows_threads()
 204 */
 205 #define EVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED 1
 206 #endif
 207
 208 #if defined(EVENT__HAVE_PTHREADS) || defined(EVENT_IN_DOXYGEN_)
 209 /** Sets up Libevent for use with Pthreads locking and thread ID functions.
 210     Unavailable if Libevent is not build for use with pthreads.  Requires
 211     libraries to link against Libevent_pthreads as well as Libevent.
 212
 213     @return 0 on success, -1 on failure. */
 214 EVENT2_EXPORT_SYMBOL
 215 int evthread_use_pthreads(void);
 216 /** Defined if Libevent was built with support for evthread_use_pthreads() */
 217 #define EVTHREAD_USE_PTHREADS_IMPLEMENTED 1
 218
 219 #endif
 220
 221 /** Enable debugging wrappers around the current lock callbacks.  If Libevent
 222  * makes one of several common locking errors, exit with an assertion failure.
 223  *
 224  * If you're going to call this function, you must do so before any locks are
 225  * allocated.
 226  **/
 227 EVENT2_EXPORT_SYMBOL
 228 void evthread_enable_lock_debugging(void);
 229
 230 /* Old (misspelled) version: This is deprecated; use
 231  * evthread_enable_log_debugging instead. */
 232 EVENT2_EXPORT_SYMBOL
 233 void evthread_enable_lock_debuging(void);
 234
 235 #endif /* EVENT__DISABLE_THREAD_SUPPORT */
 236
 237 struct event_base;
 238 /** Make sure it's safe to tell an event base to wake up from another thread
 239     or a signal handler.
 240
 241     You shouldn't need to call this by hand; configuring the base with thread
 242     support should be necessary and sufficient.
 243
 244     @return 0 on success, -1 on failure.
 245  */
 246 EVENT2_EXPORT_SYMBOL
 247 int evthread_make_base_notifiable(struct event_base *base);
 248
 249 #ifdef __cplusplus
 250 }
 251 #endif
 252
 253 #endif /* EVENT2_THREAD_H_INCLUDED_ */