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., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 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     (void)status;
 140 #if defined( sgi )
 141     if ( !status && !cpu )
 142         pthread_setrunon_np( cpu );
 143 #endif
 144     return status;
 145 }
 146
 147 inline void
 148 SGThread::join()
 149 {
 150     int status = pthread_join( tid, 0 );
 151     assert( status == 0 );
 152     (void)status;
 153 }
 154
 155 inline void
 156 SGThread::cancel()
 157 {
 158     int status = pthread_cancel( tid );
 159     assert( status == 0 );
 160     (void)status;
 161 }
 162
 163 /**
 164  * A mutex is used to protect a section of code such that at any time
 165  * only a single thread can execute the code.
 166  */
 167 class SGMutex
 168 {
 169     friend class SGPthreadCond;
 170
 171 public:
 172
 173     /**
 174      * Create a new mutex.
 175      * Under Linux this is a 'fast' mutex.
 176      */
 177     SGMutex();
 178
 179     /**
 180      * Destroy a mutex object.
 181      * Note: it is the responsibility of the caller to ensure the mutex is
 182      * unlocked before destruction occurs.
 183      */
 184     ~SGMutex();
 185
 186     /**
 187      * Lock this mutex.
 188      * If the mutex is currently unlocked, it becomes locked and owned by
 189      * the calling thread.  If the mutex is already locked by another thread,
 190      * the calling thread is suspended until the mutex is unlocked.  If the
 191      * mutex is already locked and owned by the calling thread, the calling
 192      * thread is suspended until the mutex is unlocked, effectively causing
 193      * the calling thread to deadlock.
 194      *
 195      * @see SGMutex::trylock
 196      */
 197     void lock();
 198
 199     /**
 200      * Try to lock the mutex for the current thread.  Behaves like lock except
 201      * that it doesn't block the calling thread.
 202      * @return true if mutex was successfully locked, otherwise false.
 203      * @see SGMutex::lock
 204      */
 205     bool trylock();
 206
 207     /**
 208      * Unlock this mutex.
 209      * It is assumed that the mutex is locked and owned by the calling thread.
 210      */
 211     void unlock();
 212
 213 protected:
 214
 215     /**
 216      * Pthread mutex.
 217      */
 218     pthread_mutex_t mutex;
 219 };
 220
 221 inline SGMutex::SGMutex()
 222 {
 223     int status = pthread_mutex_init( &mutex, 0 );
 224     assert( status == 0 );
 225     (void)status;
 226 }
 227
 228 inline SGMutex::~SGMutex()
 229 {
 230     int status = pthread_mutex_destroy( &mutex );
 231     assert( status == 0 );
 232     (void)status;
 233 }
 234
 235 inline void SGMutex::lock()
 236 {
 237     int status = pthread_mutex_lock( &mutex );
 238     assert( status == 0 );
 239     (void)status;
 240 }
 241
 242 inline void SGMutex::unlock()
 243 {
 244     int status = pthread_mutex_unlock( &mutex );
 245     assert( status == 0 );
 246     (void)status;
 247 }
 248
 249 /**
 250  * A condition variable is a synchronization device that allows threads to
 251  * suspend execution until some predicate on shared data is satisfied.
 252  * A condition variable is always associated with a mutex to avoid race
 253  * conditions.
 254  */
 255 class SGPthreadCond
 256 {
 257 public:
 258     /**
 259      * Create a new condition variable.
 260      */
 261     SGPthreadCond();
 262
 263     /**
 264      * Destroy the condition object.
 265      */
 266     ~SGPthreadCond();
 267
 268     /**
 269      * Wait for this condition variable to be signaled.
 270      *
 271      * @param SGMutex& reference to a locked mutex.
 272      */
 273     void wait( SGMutex& );
 274
 275     /**
 276      * Wait for this condition variable to be signaled for at most
 277      * 'ms' milliseconds.
 278      *
 279      * @param mutex reference to a locked mutex.
 280      * @param ms milliseconds to wait for a signal.
 281      *
 282      * @return
 283      */
 284     bool wait( SGMutex& mutex, unsigned long ms );
 285
 286     /**
 287      * Wake one thread waiting on this condition variable.
 288      * Nothing happens if no threads are waiting.
 289      * If several threads are waiting exactly one thread is restarted.  It
 290      * is not specified which.
 291      */
 292     void signal();
 293
 294     /**
 295      * Wake all threads waiting on this condition variable.
 296      * Nothing happens if no threads are waiting.
 297      */
 298     void broadcast();
 299
 300 private:
 301     // Disable copying.
 302     SGPthreadCond(const SGPthreadCond& );
 303     SGPthreadCond& operator=(const SGPthreadCond& );
 304
 305 private:
 306
 307     /**
 308      * The Pthread conditon variable.
 309      */
 310     pthread_cond_t cond;
 311 };
 312
 313 inline SGPthreadCond::SGPthreadCond()
 314 {
 315     int status = pthread_cond_init( &cond, 0 );
 316     assert( status == 0 );
 317     (void)status;
 318 }
 319
 320 inline SGPthreadCond::~SGPthreadCond()
 321 {
 322     int status = pthread_cond_destroy( &cond );
 323     assert( status == 0 );
 324     (void)status;
 325 }
 326
 327 inline void SGPthreadCond::signal()
 328 {
 329     int status = pthread_cond_signal( &cond );
 330     assert( status == 0 );
 331     (void)status;
 332 }
 333
 334 inline void SGPthreadCond::broadcast()
 335 {
 336     int status = pthread_cond_broadcast( &cond );
 337     assert( status == 0 );
 338     (void)status;
 339 }
 340
 341 inline void SGPthreadCond::wait( SGMutex& mutex )
 342 {
 343     int status = pthread_cond_wait( &cond, &mutex.mutex );
 344     assert( status == 0 );
 345     (void)status;
 346 }
 347
 348 #endif /* SGTHREAD_HXX_INCLUDED */