Defines functionality related to thread creation and cleanup.
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.
Values
kSbThreadPriorityLowest - The lowest thread priority available on the current platform.kSbThreadPriorityLow - A lower-than-normal thread priority, if available on the current platform.kSbThreadPriorityNormal - Really, what is normal? You should spend time pondering that question morethan you consider less-important things, but less than you think aboutmore-important things.kSbThreadPriorityHigh - A higher-than-normal thread priority, if available on the current platform.kSbThreadPriorityHighest - The highest thread priority available on the current platform that isn'tconsidered “real-time” or “time-critical,” if those terms have any meaningon the current platform.kSbThreadPriorityRealTime - If the platform provides any kind of real-time or time-critical scheduling,this priority will request that treatment. Real-time scheduling generallymeans that the thread will have more consistency in scheduling thannon-real-time scheduled threads, often by being more deterministic in howthreads run in relation to each other. But exactly how being real-timeaffects the thread scheduling is platform-specific.kSbThreadNoPriority - Well-defined constant value to mean “no priority.” This means to use thedefault priority assignment method of that platform. This may mean toinherit the priority of the spawning thread, or it may mean a specificdefault priority, or it may mean something else, depending on the platform.Private structure representing a thread-local key.
Description
Creates a new thread, which starts immediately.
Declaration and definitions
#include "starboard/thread.h"
SbThread SbThreadCreate(int64_t /*stack_size*/,
SbThreadPriority /*priority*/,
SbThreadAffinity /*affinity*/,
bool /*joinable*/,
const char* /*name*/,
SbThreadEntryPoint /*entry_point*/,
void* /*context*/) {
return kSbThreadInvalid;
}
Parameters
Description
Creates and returns a new, unique key for thread local data. If the function does not succeed, the function returns kSbThreadLocalKeyInvalid.
If destructor is specified, it will be called in the owning thread, and only in the owning thread, when the thread exits. In that case, it is called on the local value associated with the key in the current thread as long as the local value is not NULL.
Declaration and definitions
#include "starboard/thread.h"
SbThreadLocalKey SbThreadCreateLocalKey(
SbThreadLocalDestructor /*destructor*/) {
return kSbThreadLocalKeyInvalid;
}
Parameters
Description
Destroys thread local data for the specified key. The function is a no-op if the key is invalid (kSbThreadLocalKeyInvalid`) or has already been destroyed. This function does NOT call the destructor on any stored values.
Declaration and definitions
#include "starboard/thread.h"
void SbThreadDestroyLocalKey(SbThreadLocalKey /*key*/) {
}
Parameters
Description
Detaches thread, which prevents it from being joined. This is sort of like a non-blocking join. This function is a no-op if the thread is already detached or if the thread is already being joined by another thread.
Declaration and definitions
#include "starboard/thread.h"
void SbThreadDetach(SbThread /*thread*/) {
}
Parameters
Description
Returns the handle of the currently executing thread.
Declaration and definitions
#include "starboard/thread.h"
SbThread SbThreadGetCurrent() {
return kSbThreadInvalid;
}
Description
Returns the Thread ID of the currently executing thread.
Declaration and definitions
#include "starboard/thread.h"
SbThreadId SbThreadGetId() {
return 0;
}
#include "starboard/thread.h"
#include <sys/syscall.h>
#include <sys/types.h>
#include <unistd.h>
SbThreadId SbThreadGetId() {
// This is not portable outside of Linux.
return static_cast<SbThreadId>(syscall(SYS_gettid));
}
Description
Returns the pointer-sized value for key in the currently executing thread's local storage. Returns NULL if key is kSbThreadLocalKeyInvalid or if the key has already been destroyed.
Declaration and definitions
#include "starboard/thread.h"
void* SbThreadGetLocalValue(SbThreadLocalKey /*key*/) {
return NULL;
}
Parameters
Description
Returns the debug name of the currently executing thread.
Declaration and definitions
#include "starboard/thread.h"
void SbThreadGetName(char* /*buffer*/, int /*buffer_size*/) {
}
#include "starboard/thread.h"
#include <pthread.h>
void SbThreadGetName(char* buffer, int buffer_size) {
pthread_getname_np(pthread_self(), buffer, static_cast<size_t>(buffer_size));
}
Parameters
Description
Returns whether thread is the current thread.
Declaration
static SB_C_INLINE bool SbThreadIsCurrent(SbThread thread) {
return SbThreadGetCurrent() == thread;
}
Parameters
Description
Indicates whether thread1 and thread2 refer to the same thread.
Declaration and definitions
#include "starboard/thread.h"
bool SbThreadIsEqual(SbThread /*thread1*/, SbThread /*thread2*/) {
return false;
}
Parameters
Description
Returns whether the given thread handle is valid.
Declaration
static SB_C_INLINE bool SbThreadIsValid(SbThread thread) {
return thread != kSbThreadInvalid;
}
Parameters
Description
Returns whether the given thread affinity is valid.
Declaration
static SB_C_INLINE bool SbThreadIsValidAffinity(SbThreadAffinity affinity) {
return affinity != kSbThreadNoAffinity;
}
Parameters
Description
Returns whether the given thread ID is valid.
Declaration
static SB_C_INLINE bool SbThreadIsValidId(SbThreadId id) {
return id != kSbThreadInvalidId;
}
Parameters
Description
Returns whether the given thread local variable key is valid.
Declaration
static SB_C_INLINE bool SbThreadIsValidLocalKey(SbThreadLocalKey key) {
return key != kSbThreadLocalKeyInvalid;
}
Parameters
Description
Returns whether the given thread priority is valid.
Declaration
static SB_C_INLINE bool SbThreadIsValidPriority(SbThreadPriority priority) {
return priority != kSbThreadNoPriority;
}
Parameters
Description
Joins the thread on which this function is called with joinable thread. This function blocks the caller until the designated thread exits, and then cleans up that thread's resources. The cleanup process essentially detaches thread.
The return value is true if the function is successful and false if thread is invalid or detached.
Each joinable thread can only be joined once and must be joined to be fully cleaned up. Once SbThreadJoin is called, the thread behaves as if it were detached to all threads other than the joining thread.
Declaration and definitions
#include "starboard/thread.h"
bool SbThreadJoin(SbThread /*thread*/, void** /*out_return*/) {
return false;
}
Parameters
Description
Sets the pointer-sized value for key in the currently executing thread's local storage. The return value indicates whether key is valid and has not already been destroyed.
Declaration and definitions
#include "starboard/thread.h"
bool SbThreadSetLocalValue(SbThreadLocalKey /*key*/, void* /*value*/) {
return false;
}
Parameters
Description
Sets the debug name of the currently executing thread by copying the specified name string.
Declaration and definitions
#include "starboard/thread.h"
void SbThreadSetName(const char* /*name*/) {
}
#include "starboard/thread.h"
#include <errno.h>
#include <pthread.h>
#include <sys/types.h>
#include <unistd.h>
#include "starboard/log.h"
#include "starboard/string.h"
void SbThreadSetName(const char* name) {
// We don't want to rename the main thread.
if (SbThreadGetId() == getpid()) {
return;
}
const int kMaxThreadNameLength = 16;
char buffer[kMaxThreadNameLength];
if (SbStringGetLength(name) >= SB_ARRAY_SIZE_INT(buffer)) {
SbStringCopy(buffer, name, SB_ARRAY_SIZE_INT(buffer));
SB_DLOG(WARNING) << "Thread name \"" << name << "\" was truncated to \""
<< buffer << "\"";
name = buffer;
}
if (pthread_setname_np(pthread_self(), name) != 0) {
SB_DLOG(ERROR) << "Failed to set thread name to " << name;
}
}
Parameters
Description
Sleeps the currently executing thread.
Declaration and definitions
#include "starboard/thread.h"
void SbThreadSleep(SbTime /*duration*/) {
}
Parameters
Description
Yields the currently executing thread, so another thread has a chance to run.
Declaration and definitions
#include "starboard/thread.h"
void SbThreadYield() {
}