simgear/threads/SGThread.hxx

   1 // SGThread - Simple pthread class wrappers.
   2 //
   3 // Written by Bernie Bright, started April 2001.
   4 //
   5 // Copyright (C) 2001  Bernard Bright - bbright@bigpond.net.au
   6 //
   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.
  11 //
  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.
  16 //
  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.
  20 //
  21 // $Id$
  22
  23 #ifndef SGTHREAD_HXX_INCLUDED
  24 #define SGTHREAD_HXX_INCLUDED 1
  25
  26 #include <simgear/compiler.h>
  27
  28 #include <pthread.h>
  29 #if defined ( SG_HAVE_STD_INCLUDES )
  30 #  include <cassert>
  31 #  include <cerrno>
  32 #else
  33 #  include <assert.h>
  34 #  include <sys/errno.h>
  35 #endif
  36
  37 class SGThread;
  38
  39 extern "C" {
  40     void* start_handler( void* );
  41 };
  42
  43 /**
  44  * Encapsulate generic threading methods.
  45  * Users derive a class from SGThread and implement the run() member function.
  46  */
  47 class SGThread
  48 {
  49 public:
  50     /**
  51      * SGThread cancelation modes.
  52      */
  53     enum cancel_t
  54     {
  55         CANCEL_DISABLE = 0,
  56         CANCEL_DEFERRED,
  57         CANCEL_IMMEDIATE
  58     };
  59 public:
  60
  61     /**
  62      * Create a new thread object.
  63      * When a SGThread object is created it does not begin execution
  64      * immediately.  It is started by calling the start() member function.
  65      */
  66     SGThread();
  67
  68     /**
  69      * Start the underlying thread of execution.
  70      * @param cpu An optional parameter to specify on which CPU to run this
  71      * thread (only supported on IRIX at this time).
  72      * @return Pthread error code if execution fails, otherwise returns 0.
  73      */
  74     int start( unsigned cpu = 0 );
  75
  76     /**
  77      * Sends a cancellation request to the underlying thread.  The target
  78      * thread will either ignore the request, honor it immediately or defer
  79      * it until it reaches a cancellation point.
  80      */
  81     void cancel();
  82
  83     /**
  84      * Suspends the exection of the calling thread until this thread
  85      * terminates.
  86      */
  87     void join();
  88
  89 protected:
  90     /**
  91      * Destroy a thread object.
  92      * This is protected so that its illegal to simply delete a thread
  93      * - it must return from its run() function.
  94      */
  95     virtual ~SGThread();
  96
  97     /**
  98      * Set the threads cancellation mode.
  99      * @param mode The required cancellation mode.
 100      */
 101     void set_cancel( cancel_t mode );
 102
 103     /**
 104      * All threads execute by deriving the run() method of SGThread.
 105      * If this function terminates then the thread also terminates.
 106      */
 107     virtual void run() = 0;
 108
 109 private:
 110
 111     /**
 112      * Pthread thread identifier.
 113      */
 114     pthread_t tid;
 115
 116     friend void* start_handler( void* );
 117
 118 private:
 119     // Disable copying.
 120     SGThread( const SGThread& );
 121     SGThread& operator=( const SGThread& );
 122 };
 123
 124 inline
 125 SGThread::SGThread()
 126 {
 127 }
 128
 129 inline
 130 SGThread::~SGThread()
 131 {
 132 }
 133
 134 inline int
 135 SGThread::start( unsigned cpu )
 136 {
 137     int status = pthread_create( &tid, 0, start_handler, this );
 138     assert( status == 0 );
 139 #if defined( sgi )
 140     if ( !status && !cpu )
 141         pthread_setrunon_np( cpu );
 142 #endif
 143     return status;
 144 }
 145
 146 inline void
 147 SGThread::join()
 148 {
 149     int status = pthread_join( tid, 0 );
 150     assert( status == 0 );
 151 }
 152
 153 inline void
 154 SGThread::cancel()
 155 {
 156     int status = pthread_cancel( tid );
 157     assert( status == 0 );
 158 }
 159
 160 /**
 161  * A mutex is used to protect a section of code such that at any time
 162  * only a single thread can execute the code.
 163  */
 164 class SGMutex
 165 {
 166     friend class SGPthreadCond;
 167
 168 public:
 169
 170     /**
 171      * Create a new mutex.
 172      * Under Linux this is a 'fast' mutex.
 173      */
 174     SGMutex();
 175
 176     /**
 177      * Destroy a mutex object.
 178      * Note: it is the responsibility of the caller to ensure the mutex is
 179      * unlocked before destruction occurs.
 180      */
 181     ~SGMutex();
 182
 183     /**
 184      * Lock this mutex.
 185      * If the mutex is currently unlocked, it becomes locked and owned by
 186      * the calling thread.  If the mutex is already locked by another thread,
 187      * the calling thread is suspended until the mutex is unlocked.  If the
 188      * mutex is already locked and owned by the calling thread, the calling
 189      * thread is suspended until the mutex is unlocked, effectively causing
 190      * the calling thread to deadlock.
 191      *
 192      * @see SGMutex::trylock
 193      */
 194     void lock();
 195
 196     /**
 197      * Try to lock the mutex for the current thread.  Behaves like lock except
 198      * that it doesn't block the calling thread.
 199      * @return true if mutex was successfully locked, otherwise false.
 200      * @see SGMutex::lock
 201      */
 202     bool trylock();
 203
 204     /**
 205      * Unlock this mutex.
 206      * It is assumed that the mutex is locked and owned by the calling thread.
 207      */
 208     void unlock();
 209
 210 protected:
 211
 212     /**
 213      * Pthread mutex.
 214      */
 215     pthread_mutex_t mutex;
 216 };
 217
 218 inline SGMutex::SGMutex()
 219 {
 220     int status = pthread_mutex_init( &mutex, 0 );
 221     assert( status == 0 );
 222 }
 223
 224 inline SGMutex::~SGMutex()
 225 {
 226     int status = pthread_mutex_destroy( &mutex );
 227     assert( status == 0 );
 228 }
 229
 230 inline void SGMutex::lock()
 231 {
 232     int status = pthread_mutex_lock( &mutex );
 233     assert( status == 0 );
 234 }
 235
 236 inline void SGMutex::unlock()
 237 {
 238     int status = pthread_mutex_unlock( &mutex );
 239     assert( status == 0 );
 240 }
 241
 242 /**
 243  * A condition variable is a synchronization device that allows threads to
 244  * suspend execution until some predicate on shared data is satisfied.
 245  * A condition variable is always associated with a mutex to avoid race
 246  * conditions.
 247  */
 248 class SGPthreadCond
 249 {
 250 public:
 251     /**
 252      * Create a new condition variable.
 253      */
 254     SGPthreadCond();
 255
 256     /**
 257      * Destroy the condition object.
 258      */
 259     ~SGPthreadCond();
 260
 261     /**
 262      * Wait for this condition variable to be signaled.
 263      *
 264      * @param SGMutex& reference to a locked mutex.
 265      */
 266     void wait( SGMutex& );
 267
 268     /**
 269      * Wait for this condition variable to be signaled for at most
 270      * 'ms' milliseconds.
 271      *
 272      * @param mutex reference to a locked mutex.
 273      * @param ms milliseconds to wait for a signal.
 274      *
 275      * @return
 276      */
 277     bool wait( SGMutex& mutex, unsigned long ms );
 278
 279     /**
 280      * Wake one thread waiting on this condition variable.
 281      * Nothing happens if no threads are waiting.
 282      * If several threads are waiting exactly one thread is restarted.  It
 283      * is not specified which.
 284      */
 285     void signal();
 286
 287     /**
 288      * Wake all threads waiting on this condition variable.
 289      * Nothing happens if no threads are waiting.
 290      */
 291     void broadcast();
 292
 293 private:
 294     // Disable copying.
 295     SGPthreadCond(const SGPthreadCond& );
 296     SGPthreadCond& operator=(const SGPthreadCond& );
 297
 298 private:
 299
 300     /**
 301      * The Pthread conditon variable.
 302      */
 303     pthread_cond_t cond;
 304 };
 305
 306 inline SGPthreadCond::SGPthreadCond()
 307 {
 308     int status = pthread_cond_init( &cond, 0 );
 309     assert( status == 0 );
 310 }
 311
 312 inline SGPthreadCond::~SGPthreadCond()
 313 {
 314     int status = pthread_cond_destroy( &cond );
 315     assert( status == 0 );
 316 }
 317
 318 inline void SGPthreadCond::signal()
 319 {
 320     int status = pthread_cond_signal( &cond );
 321     assert( status == 0 );
 322 }
 323
 324 inline void SGPthreadCond::broadcast()
 325 {
 326     int status = pthread_cond_broadcast( &cond );
 327     assert( status == 0 );
 328 }
 329
 330 inline void SGPthreadCond::wait( SGMutex& mutex )
 331 {
 332     int status = pthread_cond_wait( &cond, &mutex.mutex );
 333     assert( status == 0 );
 334 }
 335
 336 #endif /* SGTHREAD_HXX_INCLUDED */