include/am-thread-utils.h
changeset 0 ba3d4abaf3f1
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/include/am-thread-utils.h	Fri Aug 23 20:34:17 2013 -0700
     1.3 @@ -0,0 +1,265 @@
     1.4 +// vim: set sts=8 ts=2 sw=2 tw=99 et:
     1.5 +//
     1.6 +// Copyright (C) 2013, David Anderson and AlliedModders LLC
     1.7 +// All rights reserved.
     1.8 +// 
     1.9 +// Redistribution and use in source and binary forms, with or without
    1.10 +// modification, are permitted provided that the following conditions are met:
    1.11 +// 
    1.12 +//  * Redistributions of source code must retain the above copyright notice, this
    1.13 +//    list of conditions and the following disclaimer.
    1.14 +//  * Redistributions in binary form must reproduce the above copyright notice,
    1.15 +//    this list of conditions and the following disclaimer in the documentation
    1.16 +//    and/or other materials provided with the distribution.
    1.17 +//  * Neither the name of AlliedModders LLC nor the names of its contributors
    1.18 +//    may be used to endorse or promote products derived from this software
    1.19 +//    without specific prior written permission.
    1.20 +//
    1.21 +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    1.22 +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    1.23 +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    1.24 +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
    1.25 +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
    1.26 +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
    1.27 +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    1.28 +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
    1.29 +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    1.30 +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    1.31 +// POSSIBILITY OF SUCH DAMAGE.
    1.32 +
    1.33 +#ifndef _include_amtl_threads_
    1.34 +#define _include_amtl_threads_
    1.35 +
    1.36 +#include <assert.h>
    1.37 +#if defined(_MSC_VER)
    1.38 +# include <windows.h>
    1.39 +# include <WinBase.h>
    1.40 +#else
    1.41 +# include <pthread.h>
    1.42 +#endif
    1.43 +#include <am-utility.h>
    1.44 +
    1.45 +// Thread primitives for SourcePawn.
    1.46 +//
    1.47 +// Linking Requirements:
    1.48 +// 
    1.49 +// OS X: None (-lpthread and -ldl are optional)
    1.50 +// Windows: None
    1.51 +// Linux: -lpthread -lrt required
    1.52 +//
    1.53 +// -- Mutexes --
    1.54 +//
    1.55 +// A Lockable is a mutual exclusion primitive. It can be owned by at most one
    1.56 +// thread at a time, and ownership blocks any other thread from taking taking
    1.57 +// ownership. Ownership must be acquired and released on the same thread.
    1.58 +// Lockables are not re-entrant.
    1.59 +//
    1.60 +// While a few classes support the Lockable interface, the simplest Lockable
    1.61 +// object that can be instantiated is a Mutex.
    1.62 +//
    1.63 +// -- Condition Variables --
    1.64 +//
    1.65 +// A ConditionVariable provides mutually exclusive access based on a
    1.66 +// condition ocurring. CVs provide two capabilities: Wait(), which will block
    1.67 +// until the condition is triggered, and Notify(), which signals any blocking
    1.68 +// thread that the condition has occurred.
    1.69 +//
    1.70 +// Condition variables have an underlying mutex lock. This lock must be
    1.71 +// acquired before calling Wait() or Notify(). It is automatically released
    1.72 +// once Wait begins blocking. This operation is atomic with respect to other
    1.73 +// threads and the mutex. For example, it is not possible for the lock to be
    1.74 +// acquired by another thread in between unlocking and blocking. Since Notify
    1.75 +// also requires the lock to be acquired, there is no risk of an event
    1.76 +// accidentally dissipating into thin air because it was sent before the other
    1.77 +// thread began blocking.
    1.78 +//
    1.79 +// When Wait() returns, the lock is automatically re-acquired. This operation
    1.80 +// is NOT atomic. In between waking up and re-acquiring the lock, another
    1.81 +// thread may steal the lock and issue another event. Applications must
    1.82 +// account for this. For example, a message pump should check that there are
    1.83 +// no messages left to process before blocking again.
    1.84 +//
    1.85 +// Likewise, it is also not defined whether a Signal() will have any effect
    1.86 +// while a thread is not waiting on the monitor. This is yet another reason
    1.87 +// the above paragraph is so important - applications should, under a lock of
    1.88 +// the condition variable - check for state changes before waiting.
    1.89 +//
    1.90 +// -- Threads --
    1.91 +//
    1.92 +// A Thread object, when created, spawns a new thread with the given callback
    1.93 +// (the callbacks must implement IRunnable). Threads have one method of
    1.94 +// interest, Join(), which will block until the thread's execution finishes.
    1.95 +// Deleting a thread object will free any operating system resources associated
    1.96 +// with that thread, if the thread has finished executing.
    1.97 +//
    1.98 +// Threads can fail to spawn; make sure to check Succeeded().
    1.99 +//
   1.100 +
   1.101 +namespace ke {
   1.102 +
   1.103 +// Abstraction for getting a unique thread identifier. Debug-only.
   1.104 +#if defined(_MSC_VER)
   1.105 +typedef DWORD ThreadId;
   1.106 +
   1.107 +static inline ThreadId GetCurrentThreadId()
   1.108 +{
   1.109 +  return ::GetCurrentThreadId();
   1.110 +}
   1.111 +#else
   1.112 +typedef pthread_t ThreadId;
   1.113 +
   1.114 +static inline ThreadId GetCurrentThreadId()
   1.115 +{
   1.116 +  return pthread_self();
   1.117 +}
   1.118 +#endif
   1.119 +
   1.120 +// Classes which use non-reentrant, same-thread lock/unlock semantics should
   1.121 +// inherit from this and implement DoLock/DoUnlock.
   1.122 +class Lockable
   1.123 +{
   1.124 + public:
   1.125 +  Lockable()
   1.126 +  {
   1.127 +#if !defined(NDEBUG)
   1.128 +    owner_ = 0;
   1.129 +#endif
   1.130 +  }
   1.131 +  virtual ~Lockable() {
   1.132 +  }
   1.133 +
   1.134 +  bool TryLock() {
   1.135 +    if (DoTryLock()) {
   1.136 +      DebugSetLocked();
   1.137 +      return true;
   1.138 +    }
   1.139 +    return false;
   1.140 +  }
   1.141 +
   1.142 +  void Lock() {
   1.143 +    assert(Owner() != GetCurrentThreadId());
   1.144 +    DoLock();
   1.145 +    DebugSetLocked();
   1.146 +  }
   1.147 +
   1.148 +  void Unlock() {
   1.149 +    assert(Owner() == GetCurrentThreadId());
   1.150 +    DebugSetUnlocked();
   1.151 +    DoUnlock();
   1.152 +  }
   1.153 +
   1.154 +  void AssertCurrentThreadOwns() const {
   1.155 +    assert(Owner() == GetCurrentThreadId());
   1.156 +  }
   1.157 +#if !defined(NDEBUG)
   1.158 +  bool Locked() const {
   1.159 +    return owner_ != 0;
   1.160 +  }
   1.161 +  ThreadId Owner() const {
   1.162 +    return owner_;
   1.163 +  }
   1.164 +#endif
   1.165 +
   1.166 +  virtual bool DoTryLock() = 0;
   1.167 +  virtual void DoLock() = 0;
   1.168 +  virtual void DoUnlock() = 0;
   1.169 +
   1.170 + protected:
   1.171 +  void DebugSetUnlocked() {
   1.172 +#if !defined(NDEBUG)
   1.173 +    owner_ = 0;
   1.174 +#endif
   1.175 +  }
   1.176 +  void DebugSetLocked() {
   1.177 +#if !defined(NDEBUG)
   1.178 +    owner_ = GetCurrentThreadId();
   1.179 +#endif
   1.180 +  }
   1.181 +
   1.182 + protected:
   1.183 +#if !defined(NDEBUG)
   1.184 +  ThreadId owner_;
   1.185 +#endif
   1.186 +};
   1.187 +
   1.188 +// RAII for automatically locking and unlocking an object.
   1.189 +class AutoLock
   1.190 +{
   1.191 + public:
   1.192 +  AutoLock(Lockable *lock)
   1.193 +   : lock_(lock)
   1.194 +  {
   1.195 +    lock_->Lock();
   1.196 +  }
   1.197 +  ~AutoLock() {
   1.198 +    lock_->Unlock();
   1.199 +  }
   1.200 +
   1.201 + private:
   1.202 +  Lockable *lock_;
   1.203 +};
   1.204 +
   1.205 +class AutoTryLock
   1.206 +{
   1.207 + public:
   1.208 +  AutoTryLock(Lockable *lock)
   1.209 +  {
   1.210 +    lock_ = lock->TryLock() ? lock : NULL;
   1.211 +  }
   1.212 +  ~AutoTryLock() {
   1.213 +    if (lock_)
   1.214 +      lock_->Unlock();
   1.215 +  }
   1.216 +
   1.217 + private:
   1.218 +  Lockable *lock_;
   1.219 +};
   1.220 +
   1.221 +// RAII for automatically unlocking and relocking an object.
   1.222 +class AutoUnlock
   1.223 +{
   1.224 + public:
   1.225 +  AutoUnlock(Lockable *lock)
   1.226 +   : lock_(lock)
   1.227 +  {
   1.228 +    lock_->Unlock();
   1.229 +  }
   1.230 +  ~AutoUnlock() {
   1.231 +    lock_->Lock();
   1.232 +  }
   1.233 +
   1.234 + private:
   1.235 +  Lockable *lock_;
   1.236 +};
   1.237 +
   1.238 +enum WaitResult {
   1.239 +  // Woke up because something happened.
   1.240 +  Wait_Signaled,
   1.241 +
   1.242 +  // Woke up because nothing happened and a timeout was specified.
   1.243 +  Wait_Timeout,
   1.244 +
   1.245 +  // Woke up, but because of an error.
   1.246 +  Wait_Error
   1.247 +};
   1.248 +
   1.249 +// This must be implemented in order to spawn a new thread.
   1.250 +class IRunnable
   1.251 +{
   1.252 + public:
   1.253 +  virtual ~IRunnable() {
   1.254 +  }
   1.255 +
   1.256 +  virtual void Run() = 0;
   1.257 +};
   1.258 +
   1.259 +} // namespace ke
   1.260 +
   1.261 +// Include the actual thread implementations.
   1.262 +#if defined(_MSC_VER)
   1.263 +# include "am-thread-windows.h"
   1.264 +#else
   1.265 +# include "am-thread-posix.h"
   1.266 +#endif
   1.267 +
   1.268 +#endif // _include_amtl_threads_