Starboard Module Reference: thread.h

Defines functionality related to thread creation and cleanup.

Enums

SbThreadPriority

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.
    For platforms where that is not offered, or otherwise not meaningful, thiswill just be the highest priority available in the platform's scheme, whichmay be the same as kThreadPriority_Highest.
  • 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.

Structs

SbThreadLocalKeyPrivate

Private structure representing a thread-local key.

Functions

SbThreadCreate

Description

Creates a new thread, which starts immediately.

  • If the function succeeds, the return value is a handle to the newly created thread.
  • If the function fails, the return value is kSbThreadInvalid.

Declaration and definitions

SB_EXPORT SbThread SbThreadCreate(int64_t stack_size,
                                  SbThreadPriority priority,
                                  SbThreadAffinity affinity,
                                  bool joinable,
                                  const char* name,
                                  SbThreadEntryPoint entry_point,
                                  void* context);

#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

Parameters
int64_t
stack_size
The amount of memory reserved for the thread. Set the value to 0 to indicate that the default stack size should be used.
SbThreadPriority
priority
The thread's priority. This value can be set to kSbThreadNoPriority to use the platform's default priority. As examples, it could be set to a fixed, standard priority or to a priority inherited from the thread that is calling SbThreadCreate(), or to something else.
SbThreadAffinity
affinity
The thread's affinity. This value can be set to kSbThreadNoAffinity to use the platform's default affinity.
bool
joinable
Indicates whether the thread can be joined (true) or should start out "detached" (false). Note that 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 detached threads cannot be joined.
const char*
name
A name used to identify the thread. This value is used mainly for debugging, it can be NULL, and it might not be used in production builds.
SbThreadEntryPoint
entry_point
A pointer to a function that will be executed on the newly created thread.
void*
context
This value will be passed to the entry_point function.

SbThreadCreateLocalKey

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

SB_EXPORT SbThreadLocalKey
SbThreadCreateLocalKey(SbThreadLocalDestructor destructor);

#include "starboard/thread.h"

SbThreadLocalKey SbThreadCreateLocalKey(
    SbThreadLocalDestructor /*destructor*/) {
  return kSbThreadLocalKeyInvalid;
}

Parameters

Parameters
SbThreadLocalDestructor
destructor
A pointer to a function. The value may be NULL if no clean up is needed.

SbThreadDestroyLocalKey

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

SB_EXPORT void SbThreadDestroyLocalKey(SbThreadLocalKey key);

#include "starboard/thread.h"

void SbThreadDestroyLocalKey(SbThreadLocalKey /*key*/) {
}

Parameters

Parameters
SbThreadLocalKey
key
The key for which to destroy thread local data.

SbThreadDetach

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

SB_EXPORT void SbThreadDetach(SbThread thread);

#include "starboard/thread.h"

void SbThreadDetach(SbThread /*thread*/) {
}

Parameters

Parameters
SbThread
thread
The thread to be detached.

SbThreadGetCurrent

Description

Returns the handle of the currently executing thread.

Declaration and definitions

SB_EXPORT SbThread SbThreadGetCurrent();

#include "starboard/thread.h"

SbThread SbThreadGetCurrent() {
  return kSbThreadInvalid;
}

SbThreadGetId

Description

Returns the Thread ID of the currently executing thread.

Declaration and definitions

SB_EXPORT SbThreadId SbThreadGetId();

#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));
}

SbThreadGetLocalValue

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

SB_EXPORT void* SbThreadGetLocalValue(SbThreadLocalKey key);

#include "starboard/thread.h"

void* SbThreadGetLocalValue(SbThreadLocalKey /*key*/) {
  return NULL;
}

Parameters

Parameters
SbThreadLocalKey
key
The key for which to return the value.

SbThreadGetName

Description

Returns the debug name of the currently executing thread.

Declaration and definitions

SB_EXPORT void SbThreadGetName(char* buffer, int buffer_size);

#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

Parameters
char*
buffer
int
buffer_size

SbThreadIsCurrent

Description

Returns whether thread is the current thread.

Declaration

static SB_C_INLINE bool SbThreadIsCurrent(SbThread thread) {
  return SbThreadGetCurrent() == thread;
}

Parameters

Parameters
SbThread
thread
The thread to check.

SbThreadIsEqual

Description

Indicates whether thread1 and thread2 refer to the same thread.

Declaration and definitions

SB_EXPORT bool SbThreadIsEqual(SbThread thread1, SbThread thread2);

#include "starboard/thread.h"

bool SbThreadIsEqual(SbThread /*thread1*/, SbThread /*thread2*/) {
  return false;
}

Parameters

Parameters
SbThread
thread1
The first thread to compare.
SbThread
thread2
The second thread to compare.

SbThreadIsValid

Description

Returns whether the given thread handle is valid.

Declaration

static SB_C_INLINE bool SbThreadIsValid(SbThread thread) {
  return thread != kSbThreadInvalid;
}

Parameters

Parameters
SbThread
thread

SbThreadIsValidAffinity

Description

Returns whether the given thread affinity is valid.

Declaration

static SB_C_INLINE bool SbThreadIsValidAffinity(SbThreadAffinity affinity) {
  return affinity != kSbThreadNoAffinity;
}

Parameters

Parameters
SbThreadAffinity
affinity

SbThreadIsValidId

Description

Returns whether the given thread ID is valid.

Declaration

static SB_C_INLINE bool SbThreadIsValidId(SbThreadId id) {
  return id != kSbThreadInvalidId;
}

Parameters

Parameters
SbThreadId
id

SbThreadIsValidLocalKey

Description

Returns whether the given thread local variable key is valid.

Declaration

static SB_C_INLINE bool SbThreadIsValidLocalKey(SbThreadLocalKey key) {
  return key != kSbThreadLocalKeyInvalid;
}

Parameters

Parameters
SbThreadLocalKey
key

SbThreadIsValidPriority

Description

Returns whether the given thread priority is valid.

Declaration

static SB_C_INLINE bool SbThreadIsValidPriority(SbThreadPriority priority) {
  return priority != kSbThreadNoPriority;
}

Parameters

Parameters
SbThreadPriority
priority

SbThreadJoin

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

SB_EXPORT bool SbThreadJoin(SbThread thread, void** out_return);

#include "starboard/thread.h"

bool SbThreadJoin(SbThread /*thread*/, void** /*out_return*/) {
  return false;
}

Parameters

Parameters
SbThread
thread
The thread to which the current thread will be joined. The thread must have been created with SbThreadCreate.
void**
out_return
If this is not NULL, then the SbThreadJoin function populates it with the return value of the thread's main function.

SbThreadSetLocalValue

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

SB_EXPORT bool SbThreadSetLocalValue(SbThreadLocalKey key, void* value);

#include "starboard/thread.h"

bool SbThreadSetLocalValue(SbThreadLocalKey /*key*/, void* /*value*/) {
  return false;
}

Parameters

Parameters
SbThreadLocalKey
key
The key for which to set the key value.
void*
value
The new pointer-sized key value.

SbThreadSetName

Description

Sets the debug name of the currently executing thread by copying the specified name string.

Declaration and definitions

SB_EXPORT void SbThreadSetName(const char* name);

#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

Parameters
const char*
name
The name to assign to the thread.

SbThreadSleep

Description

Sleeps the currently executing thread.

Declaration and definitions

SB_EXPORT void SbThreadSleep(SbTime duration);

#include "starboard/thread.h"

void SbThreadSleep(SbTime /*duration*/) {
}

Parameters

Parameters
SbTime
duration
The minimum amount of time, in microseconds, that the currently executing thread should sleep. The function is a no-op if this value is negative or 0.

SbThreadYield

Description

Yields the currently executing thread, so another thread has a chance to run.

Declaration and definitions

SB_EXPORT void SbThreadYield();

#include "starboard/thread.h"

void SbThreadYield() {
}