OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

thread.h
Go to the documentation of this file.
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 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 #ifdef __cplusplus
50 extern "C" {
51 #endif
52
53 #include <event2/event-config.h>
54
55 /**** OMPI CHANGE ****/
56 #include "opal_rename.h"
57 /**** END OMPI CHANGE ****/
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 int evthread_set_lock_callbacks(const struct evthread_lock_callbacks *);
132
133 #define EVTHREAD_CONDITION_API_VERSION 1
134
135 struct timeval;
136
137 /** This structure describes the interface a threading library uses for
138 * condition variables. It's used to tell evthread_set_condition_callbacks
139 * how to use locking on this platform.
140 */
141 struct evthread_condition_callbacks {
142 /** The current version of the conditions API. Set this to
143 * EVTHREAD_CONDITION_API_VERSION */
144 int condition_api_version;
145 /** Function to allocate and initialize a new condition variable.
146 * Returns the condition variable on success, and NULL on failure.
147 * The 'condtype' argument will be 0 with this API version.
148 */
149 void *(*alloc_condition)(unsigned condtype);
150 /** Function to free a condition variable. */
151 void (*free_condition)(void *cond);
152 /** Function to signal a condition variable. If 'broadcast' is 1, all
153 * threads waiting on 'cond' should be woken; otherwise, only on one
154 * thread is worken. Should return 0 on success, -1 on failure.
155 * This function will only be called while holding the associated
156 * lock for the condition.
157 */
158 int (*signal_condition)(void *cond, int broadcast);
159 /** Function to wait for a condition variable. The lock 'lock'
160 * will be held when this function is called; should be released
161 * while waiting for the condition to be come signalled, and
162 * should be held again when this function returns.
163 * If timeout is provided, it is interval of seconds to wait for
164 * the event to become signalled; if it is NULL, the function
165 * should wait indefinitely.
166 *
167 * The function should return -1 on error; 0 if the condition
168 * was signalled, or 1 on a timeout. */
169 int (*wait_condition)(void *cond, void *lock,
170 const struct timeval *timeout);
171 };
172
173 /** Sets a group of functions that Libevent should use for condition variables.
174 * For full information on the required callback API, see the
175 * documentation for the individual members of evthread_condition_callbacks.
176 *
177 * Note that if you're using Windows or the Pthreads threading library, you
178 * probably shouldn't call this function; instead, use
179 * evthread_use_windows_threads() or evthread_use_pthreads() if you can.
180 */
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 void evthread_set_id_callback(
192 unsigned long (*id_fn)(void));
193
194 #if (defined(WIN32) && !defined(_EVENT_DISABLE_THREAD_SUPPORT)) || defined(_EVENT_IN_DOXYGEN)
195 /** Sets up Libevent for use with Windows builtin locking and thread ID
196 functions. Unavailable if Libevent is not built for Windows.
197
198 @return 0 on success, -1 on failure. */
199 int evthread_use_windows_threads(void);
200 /**
201 Defined if Libevent was built with support for evthread_use_windows_threads()
202 */
203 #define EVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED 1
204 #endif
205
206 #if defined(_EVENT_HAVE_PTHREADS) || defined(_EVENT_IN_DOXYGEN)
207 /** Sets up Libevent for use with Pthreads locking and thread ID functions.
208 Unavailable if Libevent is not build for use with pthreads. Requires
209 libraries to link against Libevent_pthreads as well as Libevent.
210
211 @return 0 on success, -1 on failure. */
212 int evthread_use_pthreads(void);
213 /** Defined if Libevent was built with support for evthread_use_pthreads() */
214 #define EVTHREAD_USE_PTHREADS_IMPLEMENTED 1
215
216 #endif
217
218 /** Enable debugging wrappers around the current lock callbacks. If Libevent
219 * makes one of several common locking errors, exit with an assertion failure.
220 *
221 * If you're going to call this function, you must do so before any locks are
222 * allocated.
223 **/
224 void evthread_enable_lock_debuging(void);
225
226 #endif /* _EVENT_DISABLE_THREAD_SUPPORT */
227
228 struct event_base;
229 /** Make sure it's safe to tell an event base to wake up from another thread
230 or a signal handler.
231
232 @return 0 on success, -1 on failure.
233 */
234 int evthread_make_base_notifiable(struct event_base *base);
235
236 #ifdef __cplusplus
237 }
238 #endif
239
240 #endif /* _EVENT2_THREAD_H_ */
evthread_set_lock_callbacks
int evthread_set_lock_callbacks(const struct evthread_lock_callbacks *)
Sets a group of functions that Libevent should use for locking.
Definition: evthread.c:72
evthread_condition_callbacks
This structure describes the interface a threading library uses for condition variables.
Definition: thread.h:141
evthread_set_condition_callbacks
int evthread_set_condition_callbacks(const struct evthread_condition_callbacks *)
Sets a group of functions that Libevent should use for condition variables.
Definition: evthread.c:104
evthread_lock_callbacks::unlock
int(* unlock)(unsigned mode, void *lock)
Release a lock at 'lock' using mode 'mode'.
Definition: thread.h:120
evthread_set_id_callback
void evthread_set_id_callback(unsigned long(*id_fn)(void))
Sets the function for determining the thread id.
Definition: evthread.c:66
evthread_condition_callbacks::free_condition
void(* free_condition)(void *cond)
Function to free a condition variable.
Definition: thread.h:151
evthread_lock_callbacks::lock_api_version
int lock_api_version
The current version of the locking API.
Definition: thread.h:100
evthread_condition_callbacks::condition_api_version
int condition_api_version
The current version of the conditions API.
Definition: thread.h:144
evthread_lock_callbacks::free
void(* free)(void *lock, unsigned locktype)
Funtion to release all storage held in 'lock', which was created with type 'locktype'.
Definition: thread.h:114
evthread_lock_callbacks::lock
int(* lock)(unsigned mode, void *lock)
Acquire an already-allocated lock at 'lock' with mode 'mode'.
Definition: thread.h:117
evthread_make_base_notifiable
int evthread_make_base_notifiable(struct event_base *base)
Make sure it's safe to tell an event base to wake up from another thread or a signal handler...
Definition: event.c:2730
evthread_lock_callbacks
This structure describes the interface a threading library uses for locking.
Definition: thread.h:97
evthread_enable_lock_debuging
void evthread_enable_lock_debuging(void)
Enable debugging wrappers around the current lock callbacks.
Definition: evthread.c:258
evthread_condition_callbacks::wait_condition
int(* wait_condition)(void *cond, void *lock, const struct timeval *timeout)
Function to wait for a condition variable.
Definition: thread.h:169
evthread_lock_callbacks::supported_locktypes
unsigned supported_locktypes
Which kinds of locks does this version of the locking API support? A bitfield of EVTHREAD_LOCKTYPE_RE...
Definition: thread.h:108
evthread_condition_callbacks::signal_condition
int(* signal_condition)(void *cond, int broadcast)
Function to signal a condition variable.
Definition: thread.h:158
event_base
Definition: event-internal.h:167