| // Copyright 2015 Google Inc. All Rights Reserved. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| // Thread creation and cleanup. |
| |
| #ifndef STARBOARD_THREAD_H_ |
| #define STARBOARD_THREAD_H_ |
| |
| #include "starboard/export.h" |
| #include "starboard/thread_types.h" |
| #include "starboard/time.h" |
| #include "starboard/types.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| // A spectrum of thread priorities. Platforms map them appropriately to their |
| // own priority system. Note that scheduling is platform-specific, and what |
| // these priorities mean, if they mean anything at all, is also |
| // platform-specific. |
| // |
| // In particular, several of these priority values can map to the same priority |
| // on a given platform. The only guarantee is that each lower priority should be |
| // treated less-than-or-equal-to a higher priority. |
| typedef enum SbThreadPriority { |
| // The lowest thread priority available on the current platform. |
| kSbThreadPriorityLowest, |
| |
| // A lower-than-normal thread priority, if available on the current platform. |
| kSbThreadPriorityLow, |
| |
| // Really, what is normal? You should spend time pondering that question more |
| // than you consider less-important things, but less than you think about |
| // more-important things. |
| kSbThreadPriorityNormal, |
| |
| // A higher-than-normal thread priority, if available on the current platform. |
| kSbThreadPriorityHigh, |
| |
| // The highest thread priority available on the current platform that isn't |
| // considered "real-time" or "time-critical," if those terms have any meaning |
| // on the current platform. |
| kSbThreadPriorityHighest, |
| |
| // If the platform provides any kind of real-time or time-critical scheduling, |
| // this priority will request that treatment. Real-time scheduling generally |
| // means that the thread will have more consistency in scheduling than |
| // non-real-time scheduled threads, often by being more deterministic in how |
| // threads run in relation to each other. But exactly how being real-time |
| // affects the thread scheduling is platform-specific. |
| // |
| // For platforms where that is not offered, or otherwise not meaningful, this |
| // will just be the highest priority available in the platform's scheme, which |
| // may be the same as kThreadPriority_Highest. |
| kSbThreadPriorityRealTime, |
| |
| // Well-defined constant value to mean "no priority." This means to use the |
| // default priority assignment method of that platform. This may mean to |
| // inherit the priority of the spawning thread, or it may mean a specific |
| // default priority, or it may mean something else, depending on the platform. |
| kSbThreadNoPriority = kSbInvalidInt, |
| } SbThreadPriority; |
| |
| // An ID type that is unique per thread. |
| typedef int32_t SbThreadId; |
| |
| // Function pointer type for SbThreadCreate. |context| is a pointer-sized bit |
| // of data passed in from the calling thread. |
| typedef void* (*SbThreadEntryPoint)(void* context); |
| |
| // Function pointer type for Thread-Local destructors. |
| typedef void (*SbThreadLocalDestructor)(void* value); |
| |
| // Type for thread core affinity. This generally will be a single cpu (or core |
| // or hyperthread) identifier. Some platforms may not support affinity, and some |
| // may have specific rules about how it must be used. |
| typedef int32_t SbThreadAffinity; |
| |
| // Private structure representing a thread-local key. |
| typedef struct SbThreadLocalKeyPrivate SbThreadLocalKeyPrivate; |
| |
| // A handle to a thread-local key. |
| typedef SbThreadLocalKeyPrivate* SbThreadLocalKey; |
| |
| // Well-defined constant value to mean "no thread ID." |
| #define kSbThreadInvalidId (SbThreadId)0 |
| |
| // Well-defined constant value to mean "no affinity." |
| #define kSbThreadNoAffinity (SbThreadAffinity) kSbInvalidInt |
| |
| // Well-defined constant value to mean "no thread local key." |
| #define kSbThreadLocalKeyInvalid (SbThreadLocalKey) NULL |
| |
| // Returns whether the given thread handle is valid. |
| static SB_C_INLINE bool SbThreadIsValid(SbThread thread) { |
| return thread != kSbThreadInvalid; |
| } |
| |
| // Returns whether the given thread ID is valid. |
| static SB_C_INLINE bool SbThreadIsValidId(SbThreadId id) { |
| return id != kSbThreadInvalidId; |
| } |
| |
| // Returns whether the given thread priority is valid. |
| static SB_C_INLINE bool SbThreadIsValidPriority(SbThreadPriority priority) { |
| return priority != kSbThreadNoPriority; |
| } |
| |
| // Returns whether the given thread affinity is valid. |
| static SB_C_INLINE bool SbThreadIsValidAffinity(SbThreadAffinity affinity) { |
| return affinity != kSbThreadNoAffinity; |
| } |
| |
| // Returns whether the given thread local variable key is valid. |
| static SB_C_INLINE bool SbThreadIsValidLocalKey(SbThreadLocalKey key) { |
| return key != kSbThreadLocalKeyInvalid; |
| } |
| |
| // Creates a new thread, which starts immediately. The |stack_size| parameter |
| // can be 0 to indicate that the default stack size should be used. |priority| |
| // can be set to kSbThreadNoPriority to use the default priority for the |
| // platform (e.g. possibly a fixed, standard priority, or possibly a priority |
| // inherited from the thread that is calling SbThreadCreate()). |affinity| can |
| // be set to kSbThreadNoAffinity to use the default affinity for the platform. |
| // |joinable| sets whether the thread can be joined, or should start out |
| // "detached." |name| is mainly used for debugging, may be NULL, and may not |
| // even be used in production builds. Returns a handle to the newly created |
| // thread upon success, and returns kSbThreadInvalid if not. |entry_point| will |
| // be executed on the newly created thread, and passed |context|. |
| // |
| // NOTE: For joinable threads, when you are done with the thread handle, you |
| // must call SbThreadJoin to release system resources associated with the |
| // thread. This is not necessary for detached threads, but a detached thread |
| // cannot be joined. |
| SB_EXPORT SbThread SbThreadCreate(int64_t stack_size, |
| SbThreadPriority priority, |
| SbThreadAffinity affinity, |
| bool joinable, |
| const char* name, |
| SbThreadEntryPoint entry_point, |
| void* context); |
| |
| // Joins with joinable |thread|, created with SbThreadCreate. This function |
| // blocks the caller until the designated thread exits, and then cleans up that |
| // thread's resources. Returns true on success, false if |thread| is invalid or |
| // detached. This will essentially detach |thread|. Each joinable thread must be |
| // joined to be fully cleaned up. If |out_return| is not NULL, the return value |
| // of the thread's main function is placed there. |
| // |
| // Each joinable thread can only be joined once. Once SbThreadJoin is called, |
| // the thread behaves as if it was detached to all threads other than the |
| // joining thread. |
| SB_EXPORT bool SbThreadJoin(SbThread thread, void** out_return); |
| |
| // Detaches |thread|, which prevents it from being joined. This is sort of like |
| // a non-blocking join. Does nothing if the thread is already detached, or is |
| // already being joined by another thread. |
| SB_EXPORT void SbThreadDetach(SbThread thread); |
| |
| // Yields the currently executing thread, so another thread has a chance to run. |
| SB_EXPORT void SbThreadYield(); |
| |
| // Sleeps the currently executing thread for at least the given |duration| in |
| // microseconds. A negative duration does nothing. |
| SB_EXPORT void SbThreadSleep(SbTime duration); |
| |
| // Gets the handle of the currently executing thread. |
| SB_EXPORT SbThread SbThreadGetCurrent(); |
| |
| // Gets the Thread ID of the currently executing thread. |
| SB_EXPORT SbThreadId SbThreadGetId(); |
| |
| // Returns whether |thread1| and |thread2| refer to the same thread. |
| SB_EXPORT bool SbThreadIsEqual(SbThread thread1, SbThread thread2); |
| |
| // Gets the debug name of the currently executing thread. |
| SB_EXPORT void SbThreadGetName(char* buffer, int buffer_size); |
| |
| // Sets the debug name of the currently executing thread. Will copy the |
| // specified name string. |
| SB_EXPORT void SbThreadSetName(const char* name); |
| |
| // Creates a new, unique key for thread local data with given optional |
| // |destructor|. |destructor| may be NULL if there is no clean up |
| // needed. Returns kSbThreadLocalKeyInvalid if creation was unsuccessful. |
| // |
| // When does |destructor| get called? It can only be called in the owning |
| // thread, and let's just say thread interruption isn't viable. The destructor, |
| // if specified, is called on every thread's local values when the thread exits, |
| // if and only if the value in the key is non-NULL. |
| SB_EXPORT SbThreadLocalKey |
| SbThreadCreateLocalKey(SbThreadLocalDestructor destructor); |
| |
| // Destroys thread local data |key|. Does nothing if key is |
| // kSbThreadLocalKeyInvalid or has already been destroyed. This does NOT call |
| // the destructor on any stored values. |
| SB_EXPORT void SbThreadDestroyLocalKey(SbThreadLocalKey key); |
| |
| // Gets the pointer-sized value for |key| in the currently executing thread's |
| // local storage. Returns NULL if key is kSbThreadLocalKeyInvalid or has already |
| // been destroyed. |
| SB_EXPORT void* SbThreadGetLocalValue(SbThreadLocalKey key); |
| |
| // Sets the pointer-sized value for |key| in the currently executing thread's |
| // local storage. Returns whether |key| is valid and has not already been |
| // destroyed. |
| SB_EXPORT bool SbThreadSetLocalValue(SbThreadLocalKey key, void* value); |
| |
| // Returns whether |thread| is the current thread. |
| SB_C_INLINE bool SbThreadIsCurrent(SbThread thread) { |
| return SbThreadGetCurrent() == thread; |
| } |
| |
| #ifdef __cplusplus |
| } // extern "C" |
| #endif |
| |
| #endif // STARBOARD_THREAD_H_ |