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 // Copyright (C) 2011  Mathias Froehlich
   7 //
   8 // This program is free software; you can redistribute it and/or
   9 // modify it under the terms of the GNU General Public License as
  10 // published by the Free Software Foundation; either version 2 of the
  11 // License, or (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful, but
  14 // WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16 // General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the Free Software
  20 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  21 //
  22
  23 #ifndef SGTHREAD_HXX_INCLUDED
  24 #define SGTHREAD_HXX_INCLUDED 1
  25
  26 #include <simgear/compiler.h>
  27
  28 /**
  29  * Encapsulate generic threading methods.
  30  * Users derive a class from SGThread and implement the run() member function.
  31  */
  32 class SGThread {
  33 public:
  34     /**
  35      * Create a new thread object.
  36      * When a SGThread object is created it does not begin execution
  37      * immediately.  It is started by calling the start() member function.
  38      */
  39     SGThread();
  40
  41     /**
  42      * Start the underlying thread of execution.
  43      * @return Pthread error code if execution fails, otherwise returns 0.
  44      */
  45     bool start();
  46
  47     /**
  48      * Suspends the exection of the calling thread until this thread
  49      * terminates.
  50      */
  51     void join();
  52
  53     /**
  54      *Retreive the current thread id.
  55      */
  56     static long current( void );
  57
  58 protected:
  59     /**
  60      * Destroy a thread object.
  61      * This is protected so that its illegal to simply delete a thread
  62      * - it must return from its run() function.
  63      */
  64     virtual ~SGThread();
  65
  66     /**
  67      * All threads execute by deriving the run() method of SGThread.
  68      * If this function terminates then the thread also terminates.
  69      */
  70     virtual void run() = 0;
  71
  72 private:
  73     // Disable copying.
  74     SGThread(const SGThread&);
  75     SGThread& operator=(const SGThread&);
  76
  77     struct PrivateData;
  78     PrivateData* _privateData;
  79
  80     friend struct PrivateData;
  81 };
  82
  83 class SGWaitCondition;
  84
  85 /**
  86  * A mutex is used to protect a section of code such that at any time
  87  * only a single thread can execute the code.
  88  */
  89 class SGMutex {
  90 public:
  91     /**
  92      * Create a new mutex.
  93      * Under Linux this is a 'fast' mutex.
  94      */
  95     SGMutex();
  96
  97     /**
  98      * Destroy a mutex object.
  99      * Note: it is the responsibility of the caller to ensure the mutex is
 100      * unlocked before destruction occurs.
 101      */
 102     ~SGMutex();
 103
 104     /**
 105      * Lock this mutex.
 106      * If the mutex is currently unlocked, it becomes locked and owned by
 107      * the calling thread.  If the mutex is already locked by another thread,
 108      * the calling thread is suspended until the mutex is unlocked.  If the
 109      * mutex is already locked and owned by the calling thread, the calling
 110      * thread is suspended until the mutex is unlocked, effectively causing
 111      * the calling thread to deadlock.
 112      */
 113     void lock();
 114
 115     /**
 116      * Unlock this mutex.
 117      * It is assumed that the mutex is locked and owned by the calling thread.
 118      */
 119     void unlock();
 120
 121 private:
 122     struct PrivateData;
 123     PrivateData* _privateData;
 124
 125     friend class SGWaitCondition;
 126 };
 127
 128 /**
 129  * A condition variable is a synchronization device that allows threads to
 130  * suspend execution until some predicate on shared data is satisfied.
 131  * A condition variable is always associated with a mutex to avoid race
 132  * conditions.
 133  */
 134 class SGWaitCondition {
 135 public:
 136     /**
 137      * Create a new condition variable.
 138      */
 139     SGWaitCondition();
 140
 141     /**
 142      * Destroy the condition object.
 143      */
 144     ~SGWaitCondition();
 145
 146     /**
 147      * Wait for this condition variable to be signaled.
 148      *
 149      * @param SGMutex& reference to a locked mutex.
 150      */
 151     void wait(SGMutex&);
 152
 153     /**
 154      * Wait for this condition variable to be signaled for at most
 155      * 'ms' milliseconds.
 156      *
 157      * @param mutex reference to a locked mutex.
 158      * @param ms milliseconds to wait for a signal.
 159      *
 160      * @return
 161      */
 162     bool wait(SGMutex& mutex, unsigned msec);
 163
 164     /**
 165      * Wake one thread waiting on this condition variable.
 166      * Nothing happens if no threads are waiting.
 167      * If several threads are waiting exactly one thread is restarted.  It
 168      * is not specified which.
 169      */
 170     void signal();
 171
 172     /**
 173      * Wake all threads waiting on this condition variable.
 174      * Nothing happens if no threads are waiting.
 175      */
 176     void broadcast();
 177
 178 private:
 179     // Disable copying.
 180     SGWaitCondition(const SGWaitCondition&);
 181     SGWaitCondition& operator=(const SGWaitCondition&);
 182
 183     struct PrivateData;
 184     PrivateData* _privateData;
 185 };
 186
 187 #endif /* SGTHREAD_HXX_INCLUDED */