1 /* 2 * Copyright (c) 2008-2011 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 27 /** @file event2/thread.h 28 29 Functions for multi-threaded applications using Libevent. 30 31 When using a multi-threaded application in which multiple threads 32 add and delete events from a single event base, Libevent needs to 33 lock its data structures. 34 35 Like the memory-management function hooks, all of the threading functions 36 _must_ be set up before an event_base is created if you want the base to 37 use them. 38 39 Most programs will either be using Windows threads or Posix threads. You 40 can configure Libevent to use one of these event_use_windows_threads() or 41 event_use_pthreads() respectively. If you're using another threading 42 library, you'll need to configure threading functions manually using 43 evthread_set_lock_callbacks() and evthread_set_condition_callbacks(). 44 45 */ 46 module deimos.event2.thread; 47 48 extern (C): 49 nothrow: 50 51 import deimos.event2._d_util; 52 import deimos.event2.event_struct; 53 54 /** 55 @name Flags passed to lock functions 56 57 @{ 58 */ 59 /** A flag passed to a locking callback when the lock was allocated as a 60 * read-write lock, and we want to acquire or release the lock for writing. */ 61 enum EVTHREAD_WRITE = 0x04; 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 reading. */ 64 enum EVTHREAD_READ = 0x08; 65 /** A flag passed to a locking callback when we don't want to block waiting 66 * for the lock; if we can't get the lock immediately, we will instead 67 * return nonzero from the locking callback. */ 68 enum EVTHREAD_TRY = 0x10; 69 /**@}*/ 70 71 72 enum EVTHREAD_LOCK_API_VERSION = 1; 73 74 /** 75 @name Types of locks 76 77 @{*/ 78 /** A recursive lock is one that can be acquired multiple times at once by the 79 * same thread. No other process can allocate the lock until the thread that 80 * has been holding it has unlocked it as many times as it locked it. */ 81 enum EVTHREAD_LOCKTYPE_RECURSIVE = 1; 82 /* A read-write lock is one that allows multiple simultaneous readers, but 83 * where any one writer excludes all other writers and readers. */ 84 enum EVTHREAD_LOCKTYPE_READWRITE = 2; 85 /**@}*/ 86 87 /** This structure describes the interface a threading library uses for 88 * locking. It's used to tell evthread_set_lock_callbacks() how to use 89 * locking on this platform. 90 */ 91 struct evthread_lock_callbacks { 92 /** The current version of the locking API. Set this to 93 * EVTHREAD_LOCK_API_VERSION */ 94 int lock_api_version; 95 /** Which kinds of locks does this version of the locking API 96 * support? A bitfield of EVTHREAD_LOCKTYPE_RECURSIVE and 97 * EVTHREAD_LOCKTYPE_READWRITE. 98 * 99 * (Note that RECURSIVE locks are currently mandatory, and 100 * READWRITE locks are not currently used.) 101 **/ 102 uint supported_locktypes; 103 /** Function to allocate and initialize new lock of type 'locktype'. 104 * Returns NULL on failure. */ 105 ExternC!(void* function(uint locktype)) alloc; 106 /** Funtion to release all storage held in 'lock', which was created 107 * with type 'locktype'. */ 108 ExternC!(void function(void* lock, uint locktype)) free; 109 /** Acquire an already-allocated lock at 'lock' with mode 'mode'. 110 * Returns 0 on success, and nonzero on failure. */ 111 ExternC!(int function(uint mode, void* lock)) lock; 112 /** Release a lock at 'lock' using mode 'mode'. Returns 0 on success, 113 * and nonzero on failure. */ 114 ExternC!(int function(uint mode, void* lock)) unlock; 115 }; 116 117 /** Sets a group of functions that Libevent should use for locking. 118 * For full information on the required callback API, see the 119 * documentation for the individual members of evthread_lock_callbacks. 120 * 121 * Note that if you're using Windows or the Pthreads threading library, you 122 * probably shouldn't call this function; instead, use 123 * evthread_use_windows_threads() or evthread_use_posix_threads() if you can. 124 */ 125 int evthread_set_lock_callbacks(const(evthread_lock_callbacks)*); 126 127 enum EVTHREAD_CONDITION_API_VERSION = 1; 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 ExternC!(void* function(uint condtype)) alloc_condition; 142 /** Function to free a condition variable. */ 143 ExternC!(void function(void* cond)) free_condition; 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 ExternC!(int function(void* cond, int broadcast)) signal_condition; 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 ExternC!(int function(void* cond, void* lock, 162 const(timeval)* timeout)) wait_condition; 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_pthreads() if you can. 172 */ 173 int evthread_set_condition_callbacks( 174 const(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 ExternC!(c_ulong function()) id_fn); 185 186 version (Win32) { 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(); 192 /** 193 Defined if Libevent was built with support for evthread_use_windows_threads() 194 */ 195 enum EVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED = 1; 196 } 197 198 version (Posix) { 199 /** Sets up Libevent for use with Pthreads locking and thread ID functions. 200 Unavailable if Libevent is not build for use with pthreads. Requires 201 libraries to link against Libevent_pthreads as well as Libevent. 202 203 @return 0 on success, -1 on failure. */ 204 int evthread_use_pthreads(); 205 /** Defined if Libevent was built with support for evthread_use_pthreads() */ 206 enum EVTHREAD_USE_PTHREADS_IMPLEMENTED = 1; 207 } 208 209 /** Enable debugging wrappers around the current lock callbacks. If Libevent 210 * makes one of several common locking errors, exit with an assertion failure. 211 * 212 * If you're going to call this function, you must do so before any locks are 213 * allocated. 214 **/ 215 void evthread_enable_lock_debuging(); 216 217 /** Make sure it's safe to tell an event base to wake up from another thread 218 or a signal handler. 219 220 @return 0 on success, -1 on failure. 221 */ 222 int evthread_make_base_notifiable(event_base* base);