2 * Copyright 2001-2010 Internet2
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 * @file xmltooling/util/Threads.h
20 * Thread and locking wrappers
23 #ifndef _xmltooling_threads_h
24 #define _xmltooling_threads_h
26 #include <xmltooling/exceptions.h>
32 DECL_XMLTOOLING_EXCEPTION(ThreadingException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions during threading/locking operations);
35 * A class for manual thread creation and synchronization.
37 class XMLTOOL_API Thread
39 MAKE_NONCOPYABLE(Thread);
46 * Disassociate from the thread.
48 * @return 0 for success, non-zero for failure
50 virtual int detach()=0;
53 * Join with the thread and wait for its completion.
55 * @param thread_return holds the return value of the thread routine
56 * @return 0 for success, non-zero for failure
58 virtual int join(void** thread_return)=0;
63 * @param signo the signal to send to the thread
64 * @return 0 for success, non-zero for failure
66 virtual int kill(int signo)=0;
69 * Creates a new thread object to run the supplied start routine.
71 * @param start_routine the function to execute on the thread
72 * @param arg a parameter for the start routine
73 * @param stacksize size of stack to use, or 0 for default
74 * @return the created and running thread object
76 static Thread* create(void* (*start_routine)(void*), void* arg, size_t stacksize=0);
79 * Exits a thread gracefully.
81 * @param return_val the return value for the thread
83 static void exit(void* return_val);
86 * Sleeps the current thread for the specified amount of time.
88 * @param seconds time to sleep
90 static void sleep(int seconds);
93 * Masks all signals from a thread.
95 static void mask_all_signals(void);
98 * Masks specific signals from a thread.
101 * @param newmask the new signal mask
102 * @param oldmask the old signal mask
103 * @return 0 for success, non-zero for failure
105 static int mask_signals(int how, const sigset_t *newmask, sigset_t *oldmask);
110 * A class for managing Thread Local Storage values.
112 class XMLTOOL_API ThreadKey
114 MAKE_NONCOPYABLE(ThreadKey);
118 virtual ~ThreadKey() {}
121 * Sets the value for a TLS key.
123 * @param data the value to set
124 * @return 0 for success, non-zero for failure
126 virtual int setData(void* data)=0;
129 * Returns the value for a TLS key.
131 * @return the value or NULL
133 virtual void* getData() const=0;
136 * Creates a new TLS key.
138 * @param destroy_fn a functon to cleanup key values
139 * @return the new key
141 static ThreadKey* create(void (*destroy_fn)(void*));
145 * Allows system to notify TLS implementation when a thread completes.
147 * <p>Windows doesn't support TLS destructors, so only the DllMain detach
148 * notification can be used to trigger per-thread cleanup.
150 static void onDetach();
155 * A class for managing exclusive access to resources.
157 class XMLTOOL_API Mutex
159 MAKE_NONCOPYABLE(Mutex);
166 * Locks the mutex for exclusive access.
168 * @return 0 for success, non-zero for failure
170 virtual int lock()=0;
173 * Unlocks the mutex for exclusive access.
175 * @return 0 for success, non-zero for failure
177 virtual int unlock()=0;
180 * Creates a new mutex object.
182 * @return the new mutex
184 static Mutex* create();
188 * A class for managing shared and exclusive access to resources.
190 class XMLTOOL_API RWLock
192 MAKE_NONCOPYABLE(RWLock);
199 * Obtains a shared lock.
201 * @return 0 for success, non-zero for failure
203 virtual int rdlock()=0;
206 * Obtains an exclusive lock.
208 * @return 0 for success, non-zero for failure
210 virtual int wrlock()=0;
215 * @return 0 for success, non-zero for failure
217 virtual int unlock()=0;
220 * Creates a new read/write lock.
222 * @return the new lock
224 static RWLock* create();
228 * A class for establishing queues on a mutex based on a periodic condition.
230 class XMLTOOL_API CondWait
232 MAKE_NONCOPYABLE(CondWait);
236 virtual ~CondWait() {}
239 * Waits for a condition variable using the supplied mutex as a queue.
241 * @param lock mutex to queue on
242 * @return 0 for success, non-zero for failure
244 virtual int wait(Mutex* lock)=0;
247 * Waits for a condition variable using the supplied mutex as a queue,
248 * but only for a certain time limit.
250 * @param lock mutex to queue on
251 * @param delay_seconds maximum time to wait before waking up
252 * @return 0 for success, non-zero for failure
254 virtual int timedwait(Mutex* lock, int delay_seconds)=0;
257 * Signal a single thread to wake up if a condition changes.
259 * @return 0 for success, non-zero for failure
261 virtual int signal()=0;
264 * Signal all threads to wake up if a condition changes.
266 * @return 0 for success, non-zero for failure
268 virtual int broadcast()=0;
271 * Creates a new condition variable.
273 * @return the new condition variable
275 static CondWait* create();
279 * RAII wrapper for a mutex lock.
281 class XMLTOOL_API Lock {
282 MAKE_NONCOPYABLE(Lock);
285 * Locks and wraps the designated mutex.
287 * @param mtx mutex to lock
289 Lock(Mutex* mtx) : mutex(mtx) {
294 * Unlocks the wrapped mutex.
305 * RAII wrapper for a shared lock.
307 class XMLTOOL_API SharedLock {
308 MAKE_NONCOPYABLE(SharedLock);
311 * Locks and wraps the designated shared lock.
313 * @param lock lock to acquire
314 * @param lockit true if the lock should be acquired here, false if already acquired
316 SharedLock(RWLock* lock, bool lockit=true) : rwlock(lock) {
322 * Unlocks the wrapped shared lock.
334 #endif /* _xmltooling_threads_h */