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 protected:
  54     /**
  55      * Destroy a thread object.
  56      * This is protected so that its illegal to simply delete a thread
  57      * - it must return from its run() function.
  58      */
  59     virtual ~SGThread();
  60
  61     /**
  62      * All threads execute by deriving the run() method of SGThread.
  63      * If this function terminates then the thread also terminates.
  64      */
  65     virtual void run() = 0;
  66
  67 private:
  68     // Disable copying.
  69     SGThread(const SGThread&);
  70     SGThread& operator=(const SGThread&);
  71
  72     struct PrivateData;
  73     PrivateData* _privateData;
  74
  75     friend struct PrivateData;
  76 };
  77
  78 class SGWaitCondition;
  79
  80 /**
  81  * A mutex is used to protect a section of code such that at any time
  82  * only a single thread can execute the code.
  83  */
  84 class SGMutex {
  85 public:
  86     /**
  87      * Create a new mutex.
  88      * Under Linux this is a 'fast' mutex.
  89      */
  90     SGMutex();
  91
  92     /**
  93      * Destroy a mutex object.
  94      * Note: it is the responsibility of the caller to ensure the mutex is
  95      * unlocked before destruction occurs.
  96      */
  97     ~SGMutex();
  98
  99     /**
 100      * Lock this mutex.
 101      * If the mutex is currently unlocked, it becomes locked and owned by
 102      * the calling thread.  If the mutex is already locked by another thread,
 103      * the calling thread is suspended until the mutex is unlocked.  If the
 104      * mutex is already locked and owned by the calling thread, the calling
 105      * thread is suspended until the mutex is unlocked, effectively causing
 106      * the calling thread to deadlock.
 107      */
 108     void lock();
 109
 110     /**
 111      * Unlock this mutex.
 112      * It is assumed that the mutex is locked and owned by the calling thread.
 113      */
 114     void unlock();
 115
 116 private:
 117     struct PrivateData;
 118     PrivateData* _privateData;
 119
 120     friend class SGWaitCondition;
 121 };
 122
 123 /**
 124  * A condition variable is a synchronization device that allows threads to
 125  * suspend execution until some predicate on shared data is satisfied.
 126  * A condition variable is always associated with a mutex to avoid race
 127  * conditions.
 128  */
 129 class SGWaitCondition {
 130 public:
 131     /**
 132      * Create a new condition variable.
 133      */
 134     SGWaitCondition();
 135
 136     /**
 137      * Destroy the condition object.
 138      */
 139     ~SGWaitCondition();
 140
 141     /**
 142      * Wait for this condition variable to be signaled.
 143      *
 144      * @param SGMutex& reference to a locked mutex.
 145      */
 146     void wait(SGMutex&);
 147
 148     /**
 149      * Wait for this condition variable to be signaled for at most
 150      * 'ms' milliseconds.
 151      *
 152      * @param mutex reference to a locked mutex.
 153      * @param ms milliseconds to wait for a signal.
 154      *
 155      * @return
 156      */
 157     bool wait(SGMutex& mutex, unsigned msec);
 158
 159     /**
 160      * Wake one thread waiting on this condition variable.
 161      * Nothing happens if no threads are waiting.
 162      * If several threads are waiting exactly one thread is restarted.  It
 163      * is not specified which.
 164      */
 165     void signal();
 166
 167     /**
 168      * Wake all threads waiting on this condition variable.
 169      * Nothing happens if no threads are waiting.
 170      */
 171     void broadcast();
 172
 173 private:
 174     // Disable copying.
 175     SGWaitCondition(const SGWaitCondition&);
 176     SGWaitCondition& operator=(const SGWaitCondition&);
 177
 178     struct PrivateData;
 179     PrivateData* _privateData;
 180 };
 181
 182 #endif /* SGTHREAD_HXX_INCLUDED */