1 // SGThread - Simple pthread class wrappers.
3 // Written by Bernie Bright, started April 2001.
5 // Copyright (C) 2001 Bernard Bright - bbright@bigpond.net.au
7 // This program is free software; you can redistribute it and/or
8 // modify it under the terms of the GNU General Public License as
9 // published by the Free Software Foundation; either version 2 of the
10 // License, or (at your option) any later version.
12 // This program is distributed in the hope that it will be useful, but
13 // WITHOUT ANY WARRANTY; without even the implied warranty of
14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 // General Public License for more details.
17 // You should have received a copy of the GNU General Public License
18 // along with this program; if not, write to the Free Software
19 // Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
23 #ifndef SGTHREAD_HXX_INCLUDED
24 #define SGTHREAD_HXX_INCLUDED 1
33 void* start_handler( void* );
37 * Encapsulate generic threading methods.
38 * Users derive a class from SGThread and implement the run() member function.
44 * SGThread cancelation modes.
55 * Create a new thread object.
56 * When a SGThread object is created it does not begin execution
57 * immediately. It is started by calling the start() member function.
62 * Start the underlying thread of execution.
63 * @return Pthread error code if execution fails, otherwise returns 0.
68 * Sends a cancellation request to the underlying thread. The target
69 * thread will either ignore the request, honor it immediately or defer
70 * it until it reaches a cancellation point.
75 * Suspends the exection of the calling thread until this thread
82 * Destroy a thread object.
83 * This is protected so that its illegal to simply delete a thread
84 * - it must return from its run() function.
89 * Set the threads cancellation mode.
90 * @param mode The required cancellation mode.
92 void set_cancel( cancel_t mode );
95 * All threads execute by deriving the run() method of SGThread.
96 * If this function terminates then the thread also terminates.
98 virtual void run() = 0;
103 * Pthread thread identifier.
107 friend void* start_handler( void* );
111 SGThread( const SGThread& );
112 SGThread& operator=( const SGThread& );
121 SGThread::~SGThread()
128 int status = pthread_create( &tid, 0, start_handler, this );
129 assert( status == 0 );
136 int status = pthread_join( tid, 0 );
137 assert( status == 0 );
143 int status = pthread_cancel( tid );
144 assert( status == 0 );
148 * A mutex is used to protect a section of code such that at any time
149 * only a single thread can execute the code.
153 friend class SGCondition;
158 * Create a new mutex.
159 * Under Linux this is a 'fast' mutex.
164 * Destroy a mutex object.
165 * Note: it is the responsibility of the caller to ensure the mutex is
166 * unlocked before destruction occurs.
172 * If the mutex is currently unlocked, it becomes locked and owned by
173 * the calling thread. If the mutex is already locked by another thread,
174 * the calling thread is suspended until the mutex is unlocked. If the
175 * mutex is already locked and owned by the calling thread, the calling
176 * thread is suspended until the mutex is unlocked, effectively causing
177 * the calling thread to deadlock.
179 * @see SGMutex::trylock
184 * Try to lock the mutex for the current thread. Behaves like lock except
185 * that it doesn't block the calling thread.
186 * @return true if mutex was successfully locked, otherwise false.
193 * It is assumed that the mutex is locked and owned by the calling thread.
202 pthread_mutex_t mutex;
205 inline SGMutex::SGMutex()
207 int status = pthread_mutex_init( &mutex, 0 );
208 assert( status == 0 );
211 inline SGMutex::~SGMutex()
213 int status = pthread_mutex_destroy( &mutex );
214 assert( status == 0 );
217 inline void SGMutex::lock()
219 int status = pthread_mutex_lock( &mutex );
220 assert( status == 0 );
223 inline void SGMutex::unlock()
225 int status = pthread_mutex_unlock( &mutex );
226 assert( status == 0 );
230 * A condition variable is a synchronization device that allows threads to
231 * suspend execution until some predicate on shared data is satisfied.
232 * A condition variable is always associated with a mutex to avoid race
239 * Create a new condition variable.
244 * Destroy the condition object.
249 * Wait for this condition variable to be signaled.
251 * @param SGMutex& reference to a locked mutex.
253 void wait( SGMutex& );
256 * Wait for this condition variable to be signaled for at most
259 * @param mutex reference to a locked mutex.
260 * @param ms milliseconds to wait for a signal.
264 bool wait( SGMutex& mutex, unsigned long ms );
267 * Wake one thread waiting on this condition variable.
268 * Nothing happens if no threads are waiting.
269 * If several threads are waiting exactly one thread is restarted. It
270 * is not specified which.
275 * Wake all threads waiting on this condition variable.
276 * Nothing happens if no threads are waiting.
282 SGCondition(const SGCondition& );
283 SGCondition& operator=(const SGCondition& );
288 * The Pthread conditon variable.
293 inline SGCondition::SGCondition()
295 int status = pthread_cond_init( &cond, 0 );
296 assert( status == 0 );
299 inline SGCondition::~SGCondition()
301 int status = pthread_cond_destroy( &cond );
302 assert( status == 0 );
305 inline void SGCondition::signal()
307 int status = pthread_cond_signal( &cond );
308 assert( status == 0 );
311 inline void SGCondition::broadcast()
313 int status = pthread_cond_broadcast( &cond );
314 assert( status == 0 );
317 inline void SGCondition::wait( SGMutex& mutex )
319 int status = pthread_cond_wait( &cond, &mutex.mutex );
320 assert( status == 0 );
323 #endif /* SGTHREAD_HXX_INCLUDED */