oculus1

annotate libovr/Src/Kernel/OVR_Threads.h @ 3:b069a5c27388

find changesets by author, revision, files, or words in the commit message
added a couple more stuff, fixed all the LibOVR line endings
author John Tsiombikas <nuclear@member.fsf.org>
date Sun, 15 Sep 2013 04:10:05 +0300
parents e2f9e4603129
children
rev   line source
nuclear@3 1 /************************************************************************************
nuclear@3 2
nuclear@3 3 PublicHeader: None
nuclear@3 4 Filename : OVR_Threads.h
nuclear@3 5 Content : Contains thread-related (safe) functionality
nuclear@3 6 Created : September 19, 2012
nuclear@3 7 Notes :
nuclear@3 8
nuclear@3 9 Copyright : Copyright 2012 Oculus VR, Inc. All Rights reserved.
nuclear@3 10
nuclear@3 11 Use of this software is subject to the terms of the Oculus license
nuclear@3 12 agreement provided at the time of installation or download, or which
nuclear@3 13 otherwise accompanies this software in either electronic or hard copy form.
nuclear@3 14
nuclear@3 15 ************************************************************************************/
nuclear@3 16 #ifndef OVR_Threads_h
nuclear@3 17 #define OVR_Threads_h
nuclear@3 18
nuclear@3 19 #include "OVR_Types.h"
nuclear@3 20 #include "OVR_Atomic.h"
nuclear@3 21 #include "OVR_RefCount.h"
nuclear@3 22 #include "OVR_Array.h"
nuclear@3 23
nuclear@3 24 // Defines the infinite wait delay timeout
nuclear@3 25 #define OVR_WAIT_INFINITE 0xFFFFFFFF
nuclear@3 26
nuclear@3 27 // To be defined in the project configuration options
nuclear@3 28 #ifdef OVR_ENABLE_THREADS
nuclear@3 29
nuclear@3 30
nuclear@3 31 namespace OVR {
nuclear@3 32
nuclear@3 33 //-----------------------------------------------------------------------------------
nuclear@3 34 // ****** Declared classes
nuclear@3 35
nuclear@3 36 // Declared with thread support only
nuclear@3 37 class Mutex;
nuclear@3 38 class WaitCondition;
nuclear@3 39 class Event;
nuclear@3 40 // Implementation forward declarations
nuclear@3 41 class MutexImpl;
nuclear@3 42 class WaitConditionImpl;
nuclear@3 43
nuclear@3 44
nuclear@3 45
nuclear@3 46 //-----------------------------------------------------------------------------------
nuclear@3 47 // ***** Mutex
nuclear@3 48
nuclear@3 49 // Mutex class represents a system Mutex synchronization object that provides access
nuclear@3 50 // serialization between different threads, allowing one thread mutually exclusive access
nuclear@3 51 // to a resource. Mutex is more heavy-weight then Lock, but supports WaitCondition.
nuclear@3 52
nuclear@3 53 class Mutex
nuclear@3 54 {
nuclear@3 55 friend class WaitConditionImpl;
nuclear@3 56 friend class MutexImpl;
nuclear@3 57
nuclear@3 58 MutexImpl *pImpl;
nuclear@3 59
nuclear@3 60 public:
nuclear@3 61 // Constructor/destructor
nuclear@3 62 Mutex(bool recursive = 1);
nuclear@3 63 ~Mutex();
nuclear@3 64
nuclear@3 65 // Locking functions
nuclear@3 66 void DoLock();
nuclear@3 67 bool TryLock();
nuclear@3 68 void Unlock();
nuclear@3 69
nuclear@3 70 // Returns 1 if the mutes is currently locked by another thread
nuclear@3 71 // Returns 0 if the mutex is not locked by another thread, and can therefore be acquired.
nuclear@3 72 bool IsLockedByAnotherThread();
nuclear@3 73
nuclear@3 74 // Locker class; Used for automatic locking of a mutex withing scope
nuclear@3 75 class Locker
nuclear@3 76 {
nuclear@3 77 public:
nuclear@3 78 Mutex *pMutex;
nuclear@3 79 Locker(Mutex *pmutex)
nuclear@3 80 { pMutex = pmutex; pMutex->DoLock(); }
nuclear@3 81 ~Locker()
nuclear@3 82 { pMutex->Unlock(); }
nuclear@3 83 };
nuclear@3 84 };
nuclear@3 85
nuclear@3 86
nuclear@3 87 //-----------------------------------------------------------------------------------
nuclear@3 88 // ***** WaitCondition
nuclear@3 89
nuclear@3 90 /*
nuclear@3 91 WaitCondition is a synchronization primitive that can be used to implement what is known as a monitor.
nuclear@3 92 Dependent threads wait on a wait condition by calling Wait(), and get woken up by other threads that
nuclear@3 93 call Notify() or NotifyAll().
nuclear@3 94
nuclear@3 95 The unique feature of this class is that it provides an atomic way of first releasing a Mutex, and then
nuclear@3 96 starting a wait on a wait condition. If both the mutex and the wait condition are associated with the same
nuclear@3 97 resource, this ensures that any condition checked for while the mutex was locked does not change before
nuclear@3 98 the wait on the condition is actually initiated.
nuclear@3 99 */
nuclear@3 100
nuclear@3 101 class WaitCondition
nuclear@3 102 {
nuclear@3 103 friend class WaitConditionImpl;
nuclear@3 104 // Internal implementation structure
nuclear@3 105 WaitConditionImpl *pImpl;
nuclear@3 106
nuclear@3 107 public:
nuclear@3 108 // Constructor/destructor
nuclear@3 109 WaitCondition();
nuclear@3 110 ~WaitCondition();
nuclear@3 111
nuclear@3 112 // Release mutex and wait for condition. The mutex is re-aquired after the wait.
nuclear@3 113 // Delay is specified in milliseconds (1/1000 of a second).
nuclear@3 114 bool Wait(Mutex *pmutex, unsigned delay = OVR_WAIT_INFINITE);
nuclear@3 115
nuclear@3 116 // Notify a condition, releasing at one object waiting
nuclear@3 117 void Notify();
nuclear@3 118 // Notify a condition, releasing all objects waiting
nuclear@3 119 void NotifyAll();
nuclear@3 120 };
nuclear@3 121
nuclear@3 122
nuclear@3 123 //-----------------------------------------------------------------------------------
nuclear@3 124 // ***** Event
nuclear@3 125
nuclear@3 126 // Event is a wait-able synchronization object similar to Windows event.
nuclear@3 127 // Event can be waited on until it's signaled by another thread calling
nuclear@3 128 // either SetEvent or PulseEvent.
nuclear@3 129
nuclear@3 130 class Event
nuclear@3 131 {
nuclear@3 132 // Event state, its mutex and the wait condition
nuclear@3 133 volatile bool State;
nuclear@3 134 volatile bool Temporary;
nuclear@3 135 mutable Mutex StateMutex;
nuclear@3 136 WaitCondition StateWaitCondition;
nuclear@3 137
nuclear@3 138 void updateState(bool newState, bool newTemp, bool mustNotify);
nuclear@3 139
nuclear@3 140 public:
nuclear@3 141 Event(bool setInitially = 0) : State(setInitially), Temporary(false) { }
nuclear@3 142 ~Event() { }
nuclear@3 143
nuclear@3 144 // Wait on an event condition until it is set
nuclear@3 145 // Delay is specified in milliseconds (1/1000 of a second).
nuclear@3 146 bool Wait(unsigned delay = OVR_WAIT_INFINITE);
nuclear@3 147
nuclear@3 148 // Set an event, releasing objects waiting on it
nuclear@3 149 void SetEvent()
nuclear@3 150 { updateState(true, false, true); }
nuclear@3 151
nuclear@3 152 // Reset an event, un-signaling it
nuclear@3 153 void ResetEvent()
nuclear@3 154 { updateState(false, false, false); }
nuclear@3 155
nuclear@3 156 // Set and then reset an event once a waiter is released.
nuclear@3 157 // If threads are already waiting, they will be notified and released
nuclear@3 158 // If threads are not waiting, the event is set until the first thread comes in
nuclear@3 159 void PulseEvent()
nuclear@3 160 { updateState(true, true, true); }
nuclear@3 161 };
nuclear@3 162
nuclear@3 163
nuclear@3 164 //-----------------------------------------------------------------------------------
nuclear@3 165 // ***** Thread class
nuclear@3 166
nuclear@3 167 // ThreadId uniquely identifies a thread; returned by GetCurrentThreadId() and
nuclear@3 168 // Thread::GetThreadId.
nuclear@3 169 typedef void* ThreadId;
nuclear@3 170
nuclear@3 171
nuclear@3 172 // *** Thread flags
nuclear@3 173
nuclear@3 174 // Indicates that the thread is has been started, i.e. Start method has been called, and threads
nuclear@3 175 // OnExit() method has not yet been called/returned.
nuclear@3 176 #define OVR_THREAD_STARTED 0x01
nuclear@3 177 // This flag is set once the thread has ran, and finished.
nuclear@3 178 #define OVR_THREAD_FINISHED 0x02
nuclear@3 179 // This flag is set temporarily if this thread was started suspended. It is used internally.
nuclear@3 180 #define OVR_THREAD_START_SUSPENDED 0x08
nuclear@3 181 // This flag is used to ask a thread to exit. Message driven threads will usually check this flag
nuclear@3 182 // and finish once it is set.
nuclear@3 183 #define OVR_THREAD_EXIT 0x10
nuclear@3 184
nuclear@3 185
nuclear@3 186 class Thread : public RefCountBase<Thread>
nuclear@3 187 { // NOTE: Waitable must be the first base since it implements RefCountImpl.
nuclear@3 188
nuclear@3 189 public:
nuclear@3 190
nuclear@3 191 // *** Callback functions, can be used instead of overriding Run
nuclear@3 192
nuclear@3 193 // Run function prototypes.
nuclear@3 194 // Thread function and user handle passed to it, executed by the default
nuclear@3 195 // Thread::Run implementation if not null.
nuclear@3 196 typedef int (*ThreadFn)(Thread *pthread, void* h);
nuclear@3 197
nuclear@3 198 // Thread ThreadFunction1 is executed if not 0, otherwise ThreadFunction2 is tried
nuclear@3 199 ThreadFn ThreadFunction;
nuclear@3 200 // User handle passes to a thread
nuclear@3 201 void* UserHandle;
nuclear@3 202
nuclear@3 203 // Thread state to start a thread with
nuclear@3 204 enum ThreadState
nuclear@3 205 {
nuclear@3 206 NotRunning = 0,
nuclear@3 207 Running = 1,
nuclear@3 208 Suspended = 2
nuclear@3 209 };
nuclear@3 210
nuclear@3 211 // Thread priority
nuclear@3 212 enum ThreadPriority
nuclear@3 213 {
nuclear@3 214 CriticalPriority,
nuclear@3 215 HighestPriority,
nuclear@3 216 AboveNormalPriority,
nuclear@3 217 NormalPriority,
nuclear@3 218 BelowNormalPriority,
nuclear@3 219 LowestPriority,
nuclear@3 220 IdlePriority,
nuclear@3 221 };
nuclear@3 222
nuclear@3 223 // Thread constructor parameters
nuclear@3 224 struct CreateParams
nuclear@3 225 {
nuclear@3 226 CreateParams(ThreadFn func = 0, void* hand = 0, UPInt ssize = 128 * 1024,
nuclear@3 227 int proc = -1, ThreadState state = NotRunning, ThreadPriority prior = NormalPriority)
nuclear@3 228 : threadFunction(func), userHandle(hand), stackSize(ssize),
nuclear@3 229 processor(proc), initialState(state), priority(prior) {}
nuclear@3 230 ThreadFn threadFunction; // Thread function
nuclear@3 231 void* userHandle; // User handle passes to a thread
nuclear@3 232 UPInt stackSize; // Thread stack size
nuclear@3 233 int processor; // Thread hardware processor
nuclear@3 234 ThreadState initialState; //
nuclear@3 235 ThreadPriority priority; // Thread priority
nuclear@3 236 };
nuclear@3 237
nuclear@3 238 // *** Constructors
nuclear@3 239
nuclear@3 240 // A default constructor always creates a thread in NotRunning state, because
nuclear@3 241 // the derived class has not yet been initialized. The derived class can call Start explicitly.
nuclear@3 242 // "processor" parameter specifies which hardware processor this thread will be run on.
nuclear@3 243 // -1 means OS decides this. Implemented only on Win32
nuclear@3 244 Thread(UPInt stackSize = 128 * 1024, int processor = -1);
nuclear@3 245 // Constructors that initialize the thread with a pointer to function.
nuclear@3 246 // An option to start a thread is available, but it should not be used if classes are derived from Thread.
nuclear@3 247 // "processor" parameter specifies which hardware processor this thread will be run on.
nuclear@3 248 // -1 means OS decides this. Implemented only on Win32
nuclear@3 249 Thread(ThreadFn threadFunction, void* userHandle = 0, UPInt stackSize = 128 * 1024,
nuclear@3 250 int processor = -1, ThreadState initialState = NotRunning);
nuclear@3 251 // Constructors that initialize the thread with a create parameters structure.
nuclear@3 252 explicit Thread(const CreateParams& params);
nuclear@3 253
nuclear@3 254 // Destructor.
nuclear@3 255 virtual ~Thread();
nuclear@3 256
nuclear@3 257 // Waits for all Threads to finish; should be called only from the root
nuclear@3 258 // application thread. Once this function returns, we know that all other
nuclear@3 259 // thread's references to Thread object have been released.
nuclear@3 260 static void OVR_CDECL FinishAllThreads();
nuclear@3 261
nuclear@3 262
nuclear@3 263 // *** Overridable Run function for thread processing
nuclear@3 264
nuclear@3 265 // - returning from this method will end the execution of the thread
nuclear@3 266 // - return value is usually 0 for success
nuclear@3 267 virtual int Run();
nuclear@3 268 // Called after return/exit function
nuclear@3 269 virtual void OnExit();
nuclear@3 270
nuclear@3 271
nuclear@3 272 // *** Thread management
nuclear@3 273
nuclear@3 274 // Starts the thread if its not already running
nuclear@3 275 // - internally sets up the threading and calls Run()
nuclear@3 276 // - initial state can either be Running or Suspended, NotRunning will just fail and do nothing
nuclear@3 277 // - returns the exit code
nuclear@3 278 virtual bool Start(ThreadState initialState = Running);
nuclear@3 279
nuclear@3 280 // Quits with an exit code
nuclear@3 281 virtual void Exit(int exitCode=0);
nuclear@3 282
nuclear@3 283 // Suspend the thread until resumed
nuclear@3 284 // Returns 1 for success, 0 for failure.
nuclear@3 285 bool Suspend();
nuclear@3 286 // Resumes currently suspended thread
nuclear@3 287 // Returns 1 for success, 0 for failure.
nuclear@3 288 bool Resume();
nuclear@3 289
nuclear@3 290 // Static function to return a pointer to the current thread
nuclear@3 291 //static Thread* GetThread();
nuclear@3 292
nuclear@3 293
nuclear@3 294 // *** Thread status query functions
nuclear@3 295
nuclear@3 296 bool GetExitFlag() const;
nuclear@3 297 void SetExitFlag(bool exitFlag);
nuclear@3 298
nuclear@3 299 // Determines whether the thread was running and is now finished
nuclear@3 300 bool IsFinished() const;
nuclear@3 301 // Determines if the thread is currently suspended
nuclear@3 302 bool IsSuspended() const;
nuclear@3 303 // Returns current thread state
nuclear@3 304 ThreadState GetThreadState() const;
nuclear@3 305
nuclear@3 306 // Returns the number of available CPUs on the system
nuclear@3 307 static int GetCPUCount();
nuclear@3 308
nuclear@3 309 // Returns the thread exit code. Exit code is initialized to 0,
nuclear@3 310 // and set to the return value if Run function after the thread is finished.
nuclear@3 311 inline int GetExitCode() const { return ExitCode; }
nuclear@3 312 // Returns an OS handle
nuclear@3 313 #if defined(OVR_OS_WIN32)
nuclear@3 314 void* GetOSHandle() const { return ThreadHandle; }
nuclear@3 315 #else
nuclear@3 316 pthread_t GetOSHandle() const { return ThreadHandle; }
nuclear@3 317 #endif
nuclear@3 318
nuclear@3 319 #if defined(OVR_OS_WIN32)
nuclear@3 320 ThreadId GetThreadId() const { return IdValue; }
nuclear@3 321 #else
nuclear@3 322 ThreadId GetThreadId() const { return (ThreadId)GetOSHandle(); }
nuclear@3 323 #endif
nuclear@3 324
nuclear@3 325 static int GetOSPriority(ThreadPriority);
nuclear@3 326 // *** Sleep
nuclear@3 327
nuclear@3 328 // Sleep secs seconds
nuclear@3 329 static bool Sleep(unsigned secs);
nuclear@3 330 // Sleep msecs milliseconds
nuclear@3 331 static bool MSleep(unsigned msecs);
nuclear@3 332
nuclear@3 333
nuclear@3 334 // *** Debugging functionality
nuclear@3 335 #if defined(OVR_OS_WIN32)
nuclear@3 336 virtual void SetThreadName( const char* name );
nuclear@3 337 #else
nuclear@3 338 virtual void SetThreadName( const char* name ) { OVR_UNUSED(name); }
nuclear@3 339 #endif
nuclear@3 340
nuclear@3 341 private:
nuclear@3 342 #if defined(OVR_OS_WIN32)
nuclear@3 343 friend unsigned WINAPI Thread_Win32StartFn(void *pthread);
nuclear@3 344
nuclear@3 345 #else
nuclear@3 346 friend void *Thread_PthreadStartFn(void * phandle);
nuclear@3 347
nuclear@3 348 static int InitAttr;
nuclear@3 349 static pthread_attr_t Attr;
nuclear@3 350 #endif
nuclear@3 351
nuclear@3 352 protected:
nuclear@3 353 // Thread state flags
nuclear@3 354 AtomicInt<UInt32> ThreadFlags;
nuclear@3 355 AtomicInt<SInt32> SuspendCount;
nuclear@3 356 UPInt StackSize;
nuclear@3 357
nuclear@3 358 // Hardware processor which this thread is running on.
nuclear@3 359 int Processor;
nuclear@3 360 ThreadPriority Priority;
nuclear@3 361
nuclear@3 362 #if defined(OVR_OS_WIN32)
nuclear@3 363 void* ThreadHandle;
nuclear@3 364 volatile ThreadId IdValue;
nuclear@3 365
nuclear@3 366 // System-specific cleanup function called from destructor
nuclear@3 367 void CleanupSystemThread();
nuclear@3 368
nuclear@3 369 #else
nuclear@3 370 pthread_t ThreadHandle;
nuclear@3 371 #endif
nuclear@3 372
nuclear@3 373 // Exit code of the thread, as returned by Run.
nuclear@3 374 int ExitCode;
nuclear@3 375
nuclear@3 376 // Internal run function.
nuclear@3 377 int PRun();
nuclear@3 378 // Finishes the thread and releases internal reference to it.
nuclear@3 379 void FinishAndRelease();
nuclear@3 380
nuclear@3 381 void Init(const CreateParams& params);
nuclear@3 382
nuclear@3 383 // Protected copy constructor
nuclear@3 384 Thread(const Thread &source) { OVR_UNUSED(source); }
nuclear@3 385
nuclear@3 386 };
nuclear@3 387
nuclear@3 388 // Returns the unique Id of a thread it is called on, intended for
nuclear@3 389 // comparison purposes.
nuclear@3 390 ThreadId GetCurrentThreadId();
nuclear@3 391
nuclear@3 392
nuclear@3 393 } // OVR
nuclear@3 394
nuclear@3 395 #endif // OVR_ENABLE_THREADS
nuclear@3 396 #endif // OVR_Threads_h