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_