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