/////////////////////////////////////////////////////////////////////////////// // Copyright (c) Electronic Arts Inc. All rights reserved. /////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////// // eathread.h // // Created by Paul Pedriana, Maxis // // Provides some base global definitions for the EA::Thread library. // // Design // Many of the design criteria for EA::Thread is based on the design of the // Posix threading standard. The Posix threading standard is designed to // work portably on a wide range of operating systems and hardware, including // embedded systems and realtime environments. As such, Posix threads generally // represent a competent model to follow where possible. Windows and various // other platforms have independent multi-threading systems which are taken // into account here as well. If something exists in Windows but doesn't // exist here (e.g. Thread suspend/resume), there is a decent chance that it // is by design and for some good reason. // // C++ // There are a number of C++ libraries devoted to multithreading. Usually the // goal of these libraries is provide a platform independent interface which // simplifies the most common usage patterns and helps prevent common errors. // Some of these libraries are basic wrappers around existing C APIs while // others provide a new and different paradigm. We take the former approach // here, as it is provides more or less the same functionality but provides // it in a straightforward way that is easily approached by those familiar // with platform-specific APIs. This approach has been referred to as the // "Wrapper Facade Pattern". // // Condition Variables // Posix condition variables are implemented via the Condition class. Condition // is essentially the Java and C# name for Posix' condition variables. For some // people, a condition variable may seem similar to a Win32 Signal. In actuality // they are similar but there is one critical difference: a Signal does not // atomically unlock a mutex as part of the signaling process. This results in // problematic race conditions that make reliable producer/consumer systems // impossible to implement. // // Signals // As of this writing, there isn't a Win32-like Signal class. The reason for this // is that Semaphore does most or all the duty that Signal does and is a little // more portable, given that Signals exist only on Win32 and not elsewhere. // // Timeouts // Timeouts are specified as absolute times and not relative times. This may // not be how Win32 threading works but it is what's proper and is how Posix // threading works. From the OpenGroup online pthread documentation on this: // An absolute time measure was chosen for specifying the // timeout parameter for two reasons. First, a relative time // measure can be easily implemented on top of a function // that specifies absolute time, but there is a race // condition associated with specifying an absolute timeout // on top of a function that specifies relative timeouts. // For example, assume that clock_gettime() returns the // current time and cond_relative_timed_wait() uses relative // timeouts: // clock_gettime(CLOCK_REALTIME, &now); // reltime = sleep_til_this_absolute_time - now; // cond_relative_timed_wait(c, m, &reltime); // If the thread is preempted between the first statement and // the last statement, the thread blocks for too long. Blocking, // however, is irrelevant if an absolute timeout is used. // An absolute timeout also need not be recomputed if it is used // multiple times in a loop, such as that enclosing a condition wait. // For cases when the system clock is advanced discontinuously by // an operator, it is expected that implementations process any // timed wait expiring at an intervening time as if that time had // actually occurred. // // General Threads // For detailed information about threads, it is recommended that you read // various competent sources of information about multithreading and // multiprocessing. // Programming with POSIX(R) Threads, by David R. Butenhof // http://www.opengroup.org/onlinepubs/007904975/basedefs/pthread.h.html // usenet: comp.programming.threads // http://www.openmp.org/index.cgi?faq // http://www.lambdacs.com/cpt/MFAQ.html // http://www.lambdacs.com/cpt/FAQ.html // http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/processes_and_threads.asp // ///////////////////////////////////////////////////////////////////////////// #ifndef EATHREAD_EATHREAD_H #define EATHREAD_EATHREAD_H #include #if !EA_THREADS_AVAILABLE // Do nothing #elif EA_USE_CPP11_CONCURRENCY EA_DISABLE_VC_WARNING(4265 4365 4836 4571 4625 4626 4628 4193 4127 4548 4574 4946 4350) #include #include EA_RESTORE_VC_WARNING() #elif defined(EA_PLATFORM_UNIX) || EA_POSIX_THREADS_AVAILABLE #include #if defined(EA_HAVE_DINKUMWARE_CPP_LIBRARY) // Dinkumware doesn't usually provide gettimeofday or #include // clock_gettime #elif defined(EA_PLATFORM_UNIX) #include // gettimeofday #endif #endif #if defined(EA_PLATFORM_APPLE) #include #endif #if defined(EA_PLATFORM_SONY) #include "sdk_version.h" #include #endif #include #include #if defined(EA_PRAGMA_ONCE_SUPPORTED) #pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result. #endif /////////////////////////////////////////////////////////////////////////////// // EA_THREAD_PREEMPTIVE / EA_THREAD_COOPERATIVE // // Defined or not defined. // // EA_THREAD_COOPERATIVE means that threads are not time-sliced by the // operating system. If there exist multiple threads of the same priority // then they will need to wait, sleep, or yield in order for the others // to get time. See enum Scheduling and EATHREAD_SCHED for more info. // // EA_THREAD_PREEMPTIVE means that threads are time-sliced by the operating // system at runtime. If there exist multiple threads of the same priority // then the operating system will split execution time between them. // See enum Scheduling and EATHREAD_SCHED for more info. // #if !EA_THREADS_AVAILABLE #define EA_THREAD_COOPERATIVE #else #define EA_THREAD_PREEMPTIVE #endif /// namespace EA /// /// This is the standard Electronic Arts C++ namespace. /// namespace EA { namespace Allocator { class ICoreAllocator; } /// namespace Thread /// /// This is the standard Electronic Arts Thread C++ namespace. /// namespace Thread { /// Scheduling /// Defines scheduling types supported by the given platform. /// These are defined in detail by the Posix standard, with the /// exception of Coop, which is added here. FIFO scheduling /// is the most classic for game development, as it allows for /// thread priorities and well-behaved synchronization primitives, /// but it doesn't do time-slicing. The problem with time slicing /// is that threads are pre-empted in the middle of work and this /// hurts execution performance and cache performance. /// enum Scheduling { kSchedulingFIFO = 1, /// There is no automatic time-slicing; thread priorities control execution and context switches. kSchedulingRR = 2, /// Same as FIFO but is periodic time-slicing. kSchedulingSporadic = 4, /// Complex scheduling control. See the Posix standard. kSchedulingTS = 8, /// a.k.a. SCHED_OTHER. Usually same as FIFO or RR except that thread priorities and execution can be temporarily modified. kSchedulingCoop = 16 /// The user must control thread scheduling beyond the use of synchronization primitives. }; #if defined(EA_PLATFORM_UNIX) #define EATHREAD_SCHED kSchedulingFIFO #elif defined(EA_PLATFORM_MICROSOFT) #define EATHREAD_SCHED kSchedulingRR #else #define EATHREAD_SCHED kSchedulingFIFO #endif // EATHREAD_MULTIPROCESSING_OS // // Defined as 0 or 1. // Indicates whether the OS supports multiple concurrent processes, which may be in // addition to supporting multiple threads within a process. // Some platforms support multiple concurrently loaded processes but don't support // running these processes concurrently. We don't currently count this as a // multiprocessing OS. #ifndef EATHREAD_MULTIPROCESSING_OS #if defined(EA_PLATFORM_WINDOWS) || defined(EA_PLATFORM_UNIX) #define EATHREAD_MULTIPROCESSING_OS 1 #else #define EATHREAD_MULTIPROCESSING_OS 0 #endif #endif // EATHREAD_OTHER_THREAD_NAMING_SUPPORTED // // Defined as 0 or 1. // Indicates whether the OS supports setting the thread name from a different // thread (set to 1) or if the name can be set only from the curren thread (set to 0) #ifndef EATHREAD_OTHER_THREAD_NAMING_SUPPORTED #if defined(EA_PLATFORM_LINUX) || defined(EA_PLATFORM_APPLE) #define EATHREAD_OTHER_THREAD_NAMING_SUPPORTED 0 #else #define EATHREAD_OTHER_THREAD_NAMING_SUPPORTED 1 #endif #endif // Uint / Int // Defines a machine-word sized integer, useful for operations that are as efficient // as possible on the given machine. Note that the C99 intfastNN_t types aren't sufficient, // as they are defined by compilers in an undesirable way for the processors we work with. #if !defined(EA_PLATFORM_WORD_SIZE) || (EA_PLATFORM_WORD_SIZE == 4) typedef uint32_t Uint; typedef int32_t Int; #else typedef uint64_t Uint; typedef int64_t Int; #endif /// ThreadId /// Uniquely identifies a thread throughout the system and is used by the EAThread API /// to identify threads in a way equal to system provided thread ids. A ThreadId is the /// same as a system thread id and can be used in direct system threading API calls. #if !EA_THREADS_AVAILABLE typedef int ThreadId; #elif EA_USE_CPP11_CONCURRENCY typedef std::thread::id ThreadId; #elif defined(EA_PLATFORM_SONY) typedef uint64_t ThreadId; #elif defined(EA_PLATFORM_UNIX) || EA_POSIX_THREADS_AVAILABLE typedef pthread_t ThreadId; #elif defined(EA_PLATFORM_MICROSOFT) && !EA_POSIX_THREADS_AVAILABLE typedef void* ThreadId; // This is really HANDLE, but HANDLE is the same as void* and we can avoid an expensive #include here. #else typedef int ThreadId; #endif // ThreadId constants #if EA_USE_CPP11_CONCURRENCY const ThreadId kThreadIdInvalid = ThreadId(); /// Special ThreadId indicating an invalid thread identifier. #else const ThreadId kThreadIdInvalid = ThreadId(0); /// Special ThreadId indicating an invalid thread identifier. const ThreadId kThreadIdCurrent = ThreadId(INT_MAX); /// Special ThreadId indicating the current thread. const ThreadId kThreadIdAny = ThreadId(INT_MAX - 1); /// Special ThreadId indicating no thread in particular. #endif /// SysThreadId /// It turns out that Microsoft operating systems (Windows, XBox, XBox 360) /// have two different ways to identify a thread: HANDLE and DWORD. Some API /// functions take thread HANDLES, while others take what Microsoft calls /// thread ids (DWORDs). EAThread ThreadId is a HANDLE, as that is used for /// more of the core threading APIs. However, some OS-level APIs accept instead /// the DWORD thread id. #if defined(EA_PLATFORM_MICROSOFT) && !EA_POSIX_THREADS_AVAILABLE && !EA_USE_CPP11_CONCURRENCY typedef uint32_t SysThreadId; const SysThreadId kSysThreadIdInvalid = SysThreadId(0); /// Special SysThreadId indicating an invalid thread identifier. #elif defined(EA_PLATFORM_SONY) typedef ScePthread SysThreadId; const SysThreadId kSysThreadIdInvalid = { 0 }; /// Special SysThreadId indicating an invalid thread identifier. #elif defined(EA_PLATFORM_APPLE) typedef thread_act_t SysThreadId; // thread_act_t is useful for calling mach APIs such as thread_policy_set() with. const SysThreadId kSysThreadIdInvalid = SysThreadId(0); /// Special SysThreadId indicating an invalid thread identifier. #elif EA_USE_CPP11_CONCURRENCY typedef std::thread::native_handle_type SysThreadId; const SysThreadId kSysThreadIdInvalid = { 0 }; /// Special SysThreadId indicating an invalid thread identifier. // For MSVC, native_handle_type is not a primitive type so we define operator== and operator!= for convenience. // We use an auto converting proxy type for comparisons to avoid errors when native_handle_type is a built in type. bool Equals(const SysThreadId& a, const SysThreadId& b); struct SysThreadIdProxy { SysThreadIdProxy(const SysThreadId& id_) : id(id_) {} SysThreadId id; }; inline bool operator==(const SysThreadId& lhs, const SysThreadIdProxy& rhs) { return Equals(lhs, rhs.id); } inline bool operator!=(const SysThreadId& lhs, const SysThreadIdProxy& rhs) { return !Equals(lhs, rhs.id); } #else typedef ThreadId SysThreadId; const SysThreadId kSysThreadIdInvalid = SysThreadId(0); /// Special SysThreadId indicating an invalid thread identifier. #endif /// ThreadUniqueId /// Uniquely identifies a thread throughout the system, but in a way that is not /// necessarily compatible with system thread id identification. Sometimes it is /// costly to work with system thread ids whereas all you want is some integer /// that is unique between threads and you don't need to use it for system calls. /// See the EAThreadGetUniqueId macro/function for usage. typedef Uint ThreadUniqueId; // ThreadUniqueId constants const ThreadUniqueId kThreadUniqueIdInvalid = 0; /// Special ThreadUniqueId indicating an invalid thread identifier. // Time constants // Milliseconds are the units of time in EAThread. While every generation of computers // results in faster computers and thus milliseconds become an increasingly large number // compared to the computer speed, computer multithreading is still largely done at the // millisecond level, due to it still being a small value relative to human perception. // We may reconsider this some time in the future and provide an option to have ThreadTime // be specified in finer units, such as microseconds. #if EA_USE_CPP11_CONCURRENCY typedef std::chrono::milliseconds::rep ThreadTime; /// Current storage mechanism for time used by thread timeout functions. Units are milliseconds. const ThreadTime kTimeoutImmediate = std::chrono::milliseconds::zero().count();/// Used to specify to functions to return immediately if the operation could not be done. const ThreadTime kTimeoutNone = std::chrono::milliseconds::max().count(); /// Used to specify to functions to block without a timeout (i.e. block forever). const ThreadTime kTimeoutYield = std::chrono::milliseconds::zero().count(); /// This is used with ThreadSleep to minimally yield to threads of equivalent priority. #define EA_THREADTIME_AS_INT64(t) ((int64_t)(t)) #define EA_THREADTIME_AS_DOUBLE(t) ((double)(t)) #elif defined(EA_PLATFORM_SONY) && EA_THREADS_AVAILABLE typedef double ThreadTime; // SceKernelUseconds maps to unsigned int static_assert(sizeof(ThreadTime) >= sizeof(unsigned int), "ThreadTime not large enough for uint32_t representation of milliseconds for platform portablity"); const ThreadTime kTimeoutImmediate = 0; const ThreadTime kTimeoutNone = DBL_MAX; const ThreadTime kTimeoutYield = 0.000001; // 1 nanosecond in terms of a millisecond #define EA_THREADTIME_AS_UINT_MICROSECONDS(t) ((unsigned int)((t) * 1000.0)) /// Returns the milliseconds time as uint in microseconds. #define EA_THREADTIME_AS_INT64(t) ((int64_t)(t)) /// Returns the unconverted milliseconds time as a int64_t. #define EA_THREADTIME_AS_DOUBLE(t) (t) /// Returns the time as double milliseconds. May include a fraction component. #define EA_TIMESPEC_AS_UINT(t) ((unsigned int)(((t).tv_sec * 1000) + ((t).tv_nsec / 1000000))) /// Returns the time as uint in milliseconds. #define EA_TIMESPEC_AS_DOUBLE_IN_MS(t) ( (((t).tv_sec * 1000000000ull) + ((t).tv_nsec))/1000000.0) /// Returns the time as uint in milliseconds. #elif (defined(EA_PLATFORM_UNIX) || EA_POSIX_THREADS_AVAILABLE) && EA_THREADS_AVAILABLE struct ThreadTime : public timespec { typedef int seconds_t; // To consider: change to uint64_t or maybe long. typedef int nseconds_t; ThreadTime() { tv_sec = 0; tv_nsec = 0; } ThreadTime(const timespec& ts) { tv_sec = ts.tv_sec; tv_nsec = ts.tv_nsec; } ThreadTime(seconds_t nSeconds, nseconds_t nNanoseconds) { tv_sec = (long)nSeconds; tv_nsec = (long)nNanoseconds; } ThreadTime(const int64_t& nMilliseconds) { tv_sec = (long)(nMilliseconds / 1000); tv_nsec = (long)((nMilliseconds - (tv_sec * 1000)) * 1000000); } ThreadTime& operator+=(const int64_t& nMilliseconds) { long lTemp((long)nMilliseconds / 1000); tv_sec += lTemp; tv_nsec += (long)((nMilliseconds - (lTemp * 1000)) * 1000000); if(tv_nsec >= 1000000000){ tv_sec++; tv_nsec -= 1000000000; } return *this; } ThreadTime& operator-=(const int64_t& nMilliseconds) { long lTemp((long)nMilliseconds / 1000); tv_sec -= lTemp; tv_nsec -= (long)((nMilliseconds - (lTemp * 1000)) * 1000000); if(tv_nsec < 0) { tv_sec--; tv_nsec += 1000000000; } return *this; } ThreadTime& operator+=(const ThreadTime& tt) { tv_sec += tt.tv_sec; tv_nsec += tt.tv_nsec; if(tv_nsec >= 1000000000){ tv_sec++; tv_nsec -= 1000000000; } return *this; } ThreadTime& operator-=(const ThreadTime& tt) { tv_sec -= tt.tv_sec; tv_nsec -= tt.tv_nsec; if(tv_nsec < 0) { tv_sec--; tv_nsec += 1000000000; } return *this; } }; inline ThreadTime operator+ (const ThreadTime& tt1, const ThreadTime& tt2) { ThreadTime ttR(tt1); ttR += tt2; return ttR; } inline ThreadTime operator+ (const ThreadTime& tt, const int64_t& nMilliseconds){ ThreadTime ttR(tt); ttR += nMilliseconds; return ttR; } inline ThreadTime operator- (const ThreadTime& tt1, const ThreadTime& tt2) { ThreadTime ttR(tt1); ttR -= tt2; return ttR; } inline ThreadTime operator- (const ThreadTime& tt, const int64_t& nMilliseconds){ ThreadTime ttR(tt); ttR -= nMilliseconds; return ttR; } inline bool operator==(const ThreadTime& tt1, const ThreadTime& tt2) { return (tt1.tv_nsec == tt2.tv_nsec) && (tt1.tv_sec == tt2.tv_sec); } // These comparisons assume that the nsec value is normalized (always between 0 && 1000000000). inline bool operator!=(const ThreadTime& tt1, const ThreadTime& tt2) { return (tt1.tv_nsec != tt2.tv_nsec) || (tt1.tv_sec != tt2.tv_sec); } inline bool operator< (const ThreadTime& tt1, const ThreadTime& tt2) { return (tt1.tv_sec == tt2.tv_sec) ? (tt1.tv_nsec < tt2.tv_nsec) : (tt1.tv_sec < tt2.tv_sec); } inline bool operator> (const ThreadTime& tt1, const ThreadTime& tt2) { return (tt1.tv_sec == tt2.tv_sec) ? (tt1.tv_nsec > tt2.tv_nsec) : (tt1.tv_sec > tt2.tv_sec); } inline bool operator<=(const ThreadTime& tt1, const ThreadTime& tt2) { return (tt1.tv_sec == tt2.tv_sec) ? (tt1.tv_nsec <= tt2.tv_nsec) : (tt1.tv_sec <= tt2.tv_sec); } inline bool operator>=(const ThreadTime& tt1, const ThreadTime& tt2) { return (tt1.tv_sec == tt2.tv_sec) ? (tt1.tv_nsec >= tt2.tv_nsec) : (tt1.tv_sec >= tt2.tv_sec); } const ThreadTime kTimeoutImmediate(0, 0); /// Used to specify to functions to return immediately if the operation could not be done. const ThreadTime kTimeoutNone(INT_MAX, INT_MAX); /// Used to specify to functions to block without a timeout (i.e. block forever). const ThreadTime kTimeoutYield(0, 0); /// Used to specify to ThreadSleep to yield to threads of equivalent priority. #define EA_THREADTIME_AS_INT64(t) ((int64_t)(((t).tv_sec * 1000) + ((t).tv_nsec / 1000000))) /// Returns the time as int64_t milliseconds. #define EA_THREADTIME_AS_INT64_MICROSECONDS(t) ((int64_t)(((t).tv_sec * 1000000) + (((t).tv_nsec / 1000)))) /// Returns the time as int64_t microseconds. #define EA_THREADTIME_AS_DOUBLE(t) (((t).tv_sec * 1000.0) + ((t).tv_nsec / 1000000.0)) /// Returns the time as double milliseconds. #elif defined(EA_PLATFORM_MICROSOFT) && defined(EA_PROCESSOR_X86_64) typedef uint64_t ThreadTime; /// Current storage mechanism for time used by thread timeout functions. Units are milliseconds. const ThreadTime kTimeoutImmediate = 0; /// Used to specify to functions to return immediately if the operation could not be done. const ThreadTime kTimeoutNone = UINT64_MAX; /// Used to specify to functions to block without a timeout (i.e. block forever). const ThreadTime kTimeoutYield = 0; /// This is used with ThreadSleep to minimally yield to threads of equivalent priority. #define EA_THREADTIME_AS_INT64(t) ((int64_t)(t)) #define EA_THREADTIME_AS_DOUBLE(t) ((double)(t)) #else typedef unsigned ThreadTime; /// Current storage mechanism for time used by thread timeout functions. Units are milliseconds. const ThreadTime kTimeoutImmediate = 0; /// Used to specify to functions to return immediately if the operation could not be done. const ThreadTime kTimeoutNone = UINT_MAX; /// Used to specify to functions to block without a timeout (i.e. block forever). const ThreadTime kTimeoutYield = 0; /// This is used with ThreadSleep to minimally yield to threads of equivalent priority. #define EA_THREADTIME_AS_INT64(t) ((int64_t)(t)) #define EA_THREADTIME_AS_DOUBLE(t) ((double)(t)) #endif #if defined(EA_PLATFORM_MICROSOFT) /// Can be removed from C++11 Concurrency builds once full C++11 implementation is completed uint32_t RelativeTimeoutFromAbsoluteTimeout(ThreadTime absoluteTimeout); #endif // Thread priority constants // There is a standardized mechanism to convert system-specific thread // priorities to these platform-independent priorities and back without // loss of precision or behaviour. The convention is that kThreadPriorityDefault // equates to the system-specific normal thread priority. Thus for Microsoft // APIs a thread with priority kThreadPriorityDefault will be of Microsoft // priority THREAD_PRIORITY_NORMAL. A thread with an EAThread priority // of kThreadPriorityDefault + 1 will have a Microsoft priority of THREAD_PRIORITY_NORMAL + 1. // The only difference is that with EAThread all platforms are standardized on // kThreadPriorityDefault as the normal value and that higher EAThread priority // integral values mean higher thread priorities for running threads. This last // item is of significance because Sony platforms natively define lower integers // to mean higher thread priorities. With EAThread you get consistent behaviour // across platforms and thus kThreadPriorityDefault + 1 always results in a // thread that runs at priority of one level higher. On Sony platforms, this + 1 // gets translated to a - 1 when calling the Sony native thread priority API. // EAThread priorities have no mandated integral bounds, though // kThreadPriorityMin and kThreadPriorityMax are defined as convenient practical // endpoints for users. Users should not generally use hard-coded constants to // refer to EAThread priorities much like it's best not to use hard-coded // constants to refer to platform-specific native thread priorities. Also, users // generally want to avoid manipulating thread priorities to the extent possible // and use conventional synchronization primitives to control execution. // Similarly, wildly varying thread priorities such as +100 are not likely to // achieve much and are not likely to be very portable. // const int kThreadPriorityUnknown = INT_MIN; /// Invalid or unknown priority. const int kThreadPriorityMin = -128; /// Minimum thread priority enumerated by EAThread. In practice, a valid thread priority can be anything other than kThreadPriorityUnknown. const int kThreadPriorityDefault = 0; /// Default (a.k.a. normal) thread priority. const int kThreadPriorityMax = 127; /// Maximum thread priority enumerated by EAThread. In practice, a valid thread priority can be anything other than kThreadPriorityUnknown. /// kSysThreadPriorityDefault /// Defines the platform-specific default thread priority. #if defined(EA_PLATFORM_SONY) const int kSysThreadPriorityDefault = 700; #elif defined(EA_PLATFORM_UNIX) || EA_POSIX_THREADS_AVAILABLE const int kSysThreadPriorityDefault = 0; // Some Unix variants use values other than zero, but these are not relevant. #elif defined(EA_PLATFORM_MICROSOFT) const int kSysThreadPriorityDefault = 0; // Same as THREAD_PRIORITY_NORMAL #else const int kSysThreadPriorityDefault = 0; #endif // The following functions are standalone and not static members of the thread class // because they are potentially used by multiple threading primitives and we don't // want to create a dependency of threading primitives on class Thread. /// GetThreadId /// Gets the thread ID for the current thread. This thread ID should /// be unique throughout the system. EATHREADLIB_API ThreadId GetThreadId(); /// GetSysThreadId /// Gets the operating system thread id associated with the given ThreadId. /// It turns out that Microsoft operating systems (Windows, XBox, XBox 360) /// have two different ways to identify a thread: HANDLE and DWORD. Some API /// functions take thread HANDLES, while others take what Microsoft calls /// thread ids (DWORDs). EAThread ThreadId is a HANDLE, as that is used for /// more of the core threading APIs. However, some OS-level APIs accept instead /// the DWORD thread id. This function returns the OS thread id for a given /// EAThread ThreadId. In the case of Microsoft OSs, this returns a DWORD from /// a HANDLE and with other OSs this function simply returns the ThreadId. /// Returns a valid SysThreadId or kSysThreadIdInvalid if the input id is invalid. EATHREADLIB_API SysThreadId GetSysThreadId(ThreadId id); /// GetThreadId /// /// This is a portable function to convert between ThreadId's and SysThreadId's. /// For platforms that do not differentiate between these two types no conversion is attempted. EATHREADLIB_API ThreadId GetThreadId(SysThreadId id); /// GetSysThreadId /// Gets the SysThreadId for the current thread. This thread ID should /// be unique throughout the system. EATHREADLIB_API SysThreadId GetSysThreadId(); /// GetThreadPriority /// Gets the priority of the current thread. /// This function can return any int except for kThreadPriorityUnknown, as the /// current thread's priority will always be knowable. A return value of kThreadPriorityDefault /// means that this thread is of normal (a.k.a. default) priority. /// See the documentation for thread priority constants (e.g. kThreadPriorityDefault) /// for more information about thread priority values and behaviour. EATHREADLIB_API int GetThreadPriority(); /// SetThreadPriority /// Sets the priority of the current thread. /// Accepts any integer priority value except kThreadPriorityUnknown. /// On some platforms, this function will automatically convert any invalid /// priority for that particular platform to a valid one. A normal (a.k.a. default) thread /// priority is identified by kThreadPriorityDefault. /// See the documentation for thread priority constants (e.g. kThreadPriorityDefault) /// for more information about thread priority values and behaviour. EATHREADLIB_API bool SetThreadPriority(int nPriority); /// GetThreadStackBase /// Returns the base address of the current thread's stack. /// Recall that on all supported platforms that the stack grows downward /// and thus that the stack base address is of a higher value than the /// stack's contents. EATHREADLIB_API void* GetThreadStackBase(); // Thread processor constants const int kProcessorDefault = -1; /// Use the default processor for the platform. On many platforms, the default is to not be tied to any specific processor, but other threads can only ever be bound to a single processor. const int kProcessorAny = -2; /// Run the thread on any processor. Many platforms will switch threads between processors dynamically. /// SetThreadProcessor /// Sets the processor the current thread should run on. Valid values /// are kThreadProcessorDefault, kThreadProcessorAny, or a processor /// index in the range of [0, processor count). If the input value /// is >= the processor count, it will be reduced to be a modulo of /// the processor count. Any other invalid value will cause the processor /// to be set to zero. /// This function isn't guaranteed to restrict the thread from executing /// on the given processor for all platforms. Some platforms don't support /// assigning thread processor affinity, while with others (e.g. Windows using /// SetThreadIdealProcessor) the OS tries to comply but will use a different /// processor when the assigned one is unavailable. EATHREADLIB_API void SetThreadProcessor(int nProcessor); /// GetThreadProcessor /// Returns the (possibly virtual) CPU index that the thread is currently /// running on. Different systems may have differing definitions of what /// a unique processor is. Some CPUs have multiple sub-CPUs (e.g. "cores") /// which are treated as unique processors by the system. /// Many systems switch threads between processors dynamically; thus it's /// possible that the thread may be on a different CPU by the time this /// function returns. /// Lastly, some systems don't provide the ability to detect what processor /// the current thread is running on; in these cases this function returns 0. EATHREADLIB_API int GetThreadProcessor(); /// GetProcessorCount /// Returns the (possibly virtual) CPU count that the current system has. /// Some systems (e.g. Posix, Unix) don't expose an ability to tell how /// many processors there are; in these cases this function returns 1. /// This function returns the number of currently active processors. /// Some systems can modify the number of active processors dynamically. EATHREADLIB_API int GetProcessorCount(); /// kThreadAffinityMaskAny /// Defines the thread affinity mask that enables the thread /// to float on all available processors. typedef uint64_t ThreadAffinityMask; const ThreadAffinityMask kThreadAffinityMaskAny = ~0ULL; /// GetAvailableCpuAffinityMask /// Returns the thread affinity mask with only the available /// processors. /// If a theoretical platform reserves core 7 (counting from 0) in an /// 8 core system, the affinity mask would be 0x7f. EATHREADLIB_API ThreadAffinityMask GetAvailableCpuAffinityMask(); /// SetThreadAffinityMask /// /// The nAffinityMask is a bit field where each bit designates a processor. /// /// This function isn't guaranteed to restrict the thread from executing /// on the given processor for all platforms. Some platforms don't support /// assigning thread processor affinity, while with others (e.g. Windows using /// SetThreadIdealProcessor) the OS tries to comply but will use a different /// processor when the assigned one is unavailable. EATHREADLIB_API void SetThreadAffinityMask(ThreadAffinityMask nAffinityMask); EATHREADLIB_API void SetThreadAffinityMask(const EA::Thread::ThreadId& id, ThreadAffinityMask nAffinityMask); /// GetThreadAffinityMask /// /// Returns the current thread affinity mask specified by the user. EATHREADLIB_API ThreadAffinityMask GetThreadAffinityMask(); EATHREADLIB_API ThreadAffinityMask GetThreadAffinityMask(const EA::Thread::ThreadId& id); /// GetName /// Returns the name of the thread assigned by the SetName function. /// If the thread was not named by the SetName function, then the name is empty (""). EATHREADLIB_API const char* GetThreadName(); EATHREADLIB_API const char* GetThreadName(const EA::Thread::ThreadId& id); /// SetThreadName /// /// Sets a descriptive name or the thread. On some platforms this name is passed on /// to the debugging tools so they can see this name. The name length, including a /// terminating 0 char, is limited to EATHREAD_NAME_SIZE characters. Any characters /// beyond that are ignored. /// /// You can set the name of a Thread object only if it has already begun. You can /// also set the name with the Begin function via the ThreadParameters argument to /// Begin. This design is in order to simplify the implementation, but being able /// to set ThreadParameters before Begin is something that can be considered in the /// future. /// /// Some platforms (e.g. Linux) have the restriction that this function works /// properly only when called by the same thread that you want to name. Given this /// situation, the most portable way to use this SetName function is to either /// always call it from the thread to be named or to use the ThreadParameters to /// give the thread a name before it is started and let the started thread name /// itself. // // // EATHREADLIB_API void SetThreadName(const char* pName); EATHREADLIB_API void SetThreadName(const EA::Thread::ThreadId& id, const char* pName); /// ThreadSleep /// Puts the current thread to sleep for an amount of time hinted at /// by the time argument. The timeout is merely a hint and the system /// thread scheduler might return well before the sleep time has elapsed. /// The input 'timeRelative' refers to a relative time and not an /// absolute time such as used by EAThread mutexes, semaphores, etc. /// This is for consistency with other threading systems such as Posix and Win32. /// A sleep time of zero has the same effect as simply yielding to other /// available threads. /// EATHREADLIB_API void ThreadSleep(const ThreadTime& timeRelative = kTimeoutImmediate); /// ThreadCooperativeYield /// On platforms that use cooperative multithreading instead of /// pre-emptive multithreading, this function maps to ThreadSleep(0). /// On pre-emptive platforms, this function is a no-op. The intention /// is to allow cooperative multithreaded systems to yield manually /// in order for other threads to run, but also not to penalize /// pre-emptive systems that don't need such manual yielding. If you /// want to forcefully yield on a pre-emptive system, call ThreadSleep(0). #ifdef EA_THREAD_COOPERATIVE #define ThreadCooperativeYield() EA::Thread::ThreadSleep(EA::Thread::kTimeoutYield) #else #define ThreadCooperativeYield() #endif /// End /// This function provides a way for a thread to end itself. EATHREADLIB_API void ThreadEnd(intptr_t threadReturnValue); /// GetThreadTime /// Gets the current absolute time in milliseconds. /// This is required for working with absolute timeouts, for example. /// To specify a timeout that is relative to the current time, simply /// add time (in milliseconds) to the return value of GetThreadTime. /// Alternatively, you can use ConvertRelativeTime to calculate an absolute time. EATHREADLIB_API ThreadTime GetThreadTime(); /// ConvertRelativeTime /// Given a relative time (in milliseconds), this function returns an /// absolute time (in milliseconds). /// Example usage: /// mutex.Lock(ConvertRelativeTime(1000)); EATHREADLIB_API inline ThreadTime ConvertRelativeTime(const ThreadTime& timeRelative) { return GetThreadTime() + timeRelative; } /// SetAssertionFailureFunction /// Allows the user to specify a callback function to trap assertion failures. /// You can use this to glue your own assertion system into this system. typedef void (*AssertionFailureFunction)(const char* pExpression, void* pContext); EATHREADLIB_API void SetAssertionFailureFunction(AssertionFailureFunction pAssertionFailureFunction, void* pContext); /// AssertionFailure /// Triggers an assertion failure. This function is generally intended for internal /// use but is available so that related code can use the same system. EATHREADLIB_API void AssertionFailure(const char* pExpression); EATHREADLIB_API void AssertionFailureV(const char* pFormat, ...); /// Allocator /// This is the same as (the first four functions of) ICoreAllocator. /// If the allocator is set via SetAllocator, then it must be done before /// any other thread operations which might allocate memory are done. /// Typically this includes creating objects via factory functions and /// creating threads whereby you specify that thread resources be allocated for you.. class Allocator { public: virtual ~Allocator() {} virtual void* Alloc(size_t size, const char* name = 0, unsigned int flags = 0) = 0; virtual void* Alloc(size_t size, const char* name, unsigned int flags, unsigned int align, unsigned int alignOffset = 0) = 0; virtual void Free(void* block, size_t size=0) = 0; }; EATHREADLIB_API void SetAllocator(Allocator* pAllocator); EATHREADLIB_API Allocator* GetAllocator(); EATHREADLIB_API void SetAllocator(EA::Allocator::ICoreAllocator* pAllocator); } // namespace Thread } // namespace EA /// EAThreadGetUniqueId /// /// Gets a value that is unique per thread but isn't necessarily the system-recognized /// thread id. This function is at least as fast as GetThreadId, and on some platforms /// is potentially significantly faster due to being implemented in inline asm which /// avoids a system function call which may cause an instruction cache miss penalty. /// This function is useful for creating very fast implementations of some kinds of /// threading constructs. It's implemented as a macro instead of a function in order /// to optimizing inlining success across all platforms and compilers. /// /// This function is guaranteed to yield a valid value; there are no error conditions. /// /// This macro acts as if it were declared as a function like this: /// void EAThreadGetUniqueId(ThreadUniqueId& result); /// /// Example usage: /// ThreadUniqueId x; /// EAThreadGetUniqueId(x); /// #if EA_USE_CPP11_CONCURRENCY #define EAThreadGetUniqueId(dest) (dest = static_cast(std::hash()(std::this_thread::get_id()))) #elif defined(EA_PLATFORM_WINDOWS) && defined(EA_COMPILER_MSVC) && !defined(EA_PLATFORM_WIN64) // Reference implementation: //extern "C" __declspec(dllimport) unsigned long __stdcall GetCurrentThreadId(); //#define EAThreadGetUniqueId(dest) dest = (ThreadUniqueId)(uintptr_t)GetCurrentThreadId() // Fast implementation: extern "C" unsigned long __readfsdword(unsigned long offset); #pragma intrinsic(__readfsdword) #define EAThreadGetUniqueId(dest) dest = (EA::Thread::ThreadUniqueId)(uintptr_t)__readfsdword(0x18) #elif defined(EA_COMPILER_MSVC) && defined(EA_PROCESSOR_X86_64) EA_DISABLE_ALL_VC_WARNINGS() #include EA_RESTORE_ALL_VC_WARNINGS() #define EAThreadGetUniqueId(dest) dest = (EA::Thread::ThreadUniqueId)(uintptr_t)__readgsqword(0x30) // Could also use dest = (EA::Thread::ThreadUniqueId)NtCurrentTeb(), but that would require #including , which is very heavy. #else // Reference implementation: #define EAThreadGetUniqueId(dest) dest = (EA::Thread::ThreadUniqueId)(uintptr_t)EA::Thread::GetThreadId() #endif // EAThreadIdToString // Convert a thread id to a string suitable for use with printf like functions, e.g.: // printf("%s", EAThreadIdToString(myThreadId)); // This macro is intended for debugging purposes and makes no guarantees about performance // or how a thread id is mapped to a string. namespace EA { namespace Thread { namespace detail { struct EATHREADLIB_API ThreadIdToStringBuffer { public: enum { BufSize = 32 }; explicit ThreadIdToStringBuffer(EA::Thread::ThreadId threadId); const char* c_str() const { return mBuf; } private: char mBuf[BufSize]; }; struct EATHREADLIB_API SysThreadIdToStringBuffer { public: enum { BufSize = 32 }; explicit SysThreadIdToStringBuffer(EA::Thread::SysThreadId sysThreadId); const char* c_str() const { return mBuf; } private: char mBuf[BufSize]; }; } } } #if !defined(EAThreadThreadIdToString) #define EAThreadThreadIdToString(threadId) (EA::Thread::detail::ThreadIdToStringBuffer(threadId).c_str()) #endif #if !defined(EAThreadSysThreadIdToString) #define EAThreadSysThreadIdToString(sysThreadId) (EA::Thread::detail::SysThreadIdToStringBuffer(sysThreadId).c_str()) #endif /////////////////////////////////////////////////////////////////////////////// // Inline functions /////////////////////////////////////////////////////////////////////////////// #if defined(EA_PLATFORM_MICROSOFT) && !EA_POSIX_THREADS_AVAILABLE // We implement GetSysThreadId in our associated .cpp file. #elif defined(EA_PLATFORM_SONY) // We implement GetSysThreadId in our associated .cpp file. #elif defined(EA_PLATFORM_APPLE) // We implement GetSysThreadId in our associated .cpp file. #elif EA_USE_CPP11_CONCURRENCY // We implement GetSysThreadId in our associated .cpp file. #else inline EA::Thread::SysThreadId EA::Thread::GetSysThreadId(ThreadId id) { return id; } inline EA::Thread::SysThreadId EA::Thread::GetSysThreadId() { return GetThreadId(); // ThreadId == SysThreadId in this case } #endif #endif // EATHREAD_EATHREAD_H