---
layout: doc
title: "Starboard Module Reference: thread.h"
---

Defines functionality related to thread creation and cleanup.

## Macros ##

### kSbThreadInvalidId ###

Well-defined constant value to mean "no thread ID."

### kSbThreadLocalKeyInvalid ###

Well-defined constant value to mean "no thread local key."

### kSbThreadNoAffinity ###

Well-defined constant value to mean "no affinity."

## 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 more
    than you consider less-important things, but less than you think about more-
    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't
    considered "real-time" or "time-critical," if those terms have any meaning
    on 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 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 kSbThreadPriorityHighest.
*   `kSbThreadNoPriority`

    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.

## Typedefs ##

### SbThreadAffinity ###

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.

#### Definition ####

```
typedef int32_t SbThreadAffinity
```

### SbThreadEntryPoint ###

Function pointer type for SbThreadCreate. `context` is a pointer-sized bit of
data passed in from the calling thread.

#### Definition ####

```
typedef void*(* SbThreadEntryPoint) (void *context)
```

### SbThreadId ###

An ID type that is unique per thread.

#### Definition ####

```
typedef int32_t SbThreadId
```

### SbThreadLocalDestructor ###

Function pointer type for Thread-Local destructors.

#### Definition ####

```
typedef void(* SbThreadLocalDestructor) (void *value)
```

### SbThreadLocalKey ###

A handle to a thread-local key.

#### Definition ####

```
typedef SbThreadLocalKeyPrivate* SbThreadLocalKey
```

## Functions ##

### SbThreadCreate ###

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`.

`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. `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. `affinity`: The thread's affinity. This value can be set to
`kSbThreadNoAffinity` to use the platform's default affinity. `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. `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. `entry_point`: A pointer to a function that will be
executed on the newly created thread. `context`: This value will be passed to
the `entry_point` function.

#### Declaration ####

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

### SbThreadCreateLocalKey ###

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.

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

#### Declaration ####

```
SbThreadLocalKey SbThreadCreateLocalKey(SbThreadLocalDestructor destructor)
```

### SbThreadDestroyLocalKey ###

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.

`key`: The key for which to destroy thread local data.

#### Declaration ####

```
void SbThreadDestroyLocalKey(SbThreadLocalKey key)
```

### SbThreadDetach ###

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.

`thread`: The thread to be detached.

#### Declaration ####

```
void SbThreadDetach(SbThread thread)
```

### SbThreadGetCurrent ###

Returns the handle of the currently executing thread.

#### Declaration ####

```
SbThread SbThreadGetCurrent()
```

### SbThreadGetId ###

Returns the Thread ID of the currently executing thread.

#### Declaration ####

```
SbThreadId SbThreadGetId()
```

### SbThreadGetLocalValue ###

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.

`key`: The key for which to return the value.

#### Declaration ####

```
void* SbThreadGetLocalValue(SbThreadLocalKey key)
```

### SbThreadGetName ###

Returns the debug name of the currently executing thread.

#### Declaration ####

```
void SbThreadGetName(char *buffer, int buffer_size)
```

### SbThreadIsCurrent ###

Returns whether `thread` is the current thread.

`thread`: The thread to check.

#### Declaration ####

```
static bool SbThreadIsCurrent(SbThread thread)
```

### SbThreadIsEqual ###

Indicates whether `thread1` and `thread2` refer to the same thread.

`thread1`: The first thread to compare. `thread2`: The second thread to compare.

#### Declaration ####

```
bool SbThreadIsEqual(SbThread thread1, SbThread thread2)
```

### SbThreadIsValid ###

Returns whether the given thread handle is valid.

#### Declaration ####

```
static bool SbThreadIsValid(SbThread thread)
```

### SbThreadIsValidAffinity ###

Returns whether the given thread affinity is valid.

#### Declaration ####

```
static bool SbThreadIsValidAffinity(SbThreadAffinity affinity)
```

### SbThreadIsValidId ###

Returns whether the given thread ID is valid.

#### Declaration ####

```
static bool SbThreadIsValidId(SbThreadId id)
```

### SbThreadIsValidLocalKey ###

Returns whether the given thread local variable key is valid.

#### Declaration ####

```
static bool SbThreadIsValidLocalKey(SbThreadLocalKey key)
```

### SbThreadIsValidPriority ###

Returns whether the given thread priority is valid.

#### Declaration ####

```
static bool SbThreadIsValidPriority(SbThreadPriority priority)
```

### SbThreadJoin ###

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.

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

#### Declaration ####

```
bool SbThreadJoin(SbThread thread, void **out_return)
```

### SbThreadSetLocalValue ###

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.

`key`: The key for which to set the key value. `value`: The new pointer-sized
key value.

#### Declaration ####

```
bool SbThreadSetLocalValue(SbThreadLocalKey key, void *value)
```

### SbThreadSetName ###

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

`name`: The name to assign to the thread.

#### Declaration ####

```
void SbThreadSetName(const char *name)
```

### SbThreadSleep ###

Sleeps the currently executing thread.

`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`.

#### Declaration ####

```
void SbThreadSleep(SbTime duration)
```

### SbThreadYield ###

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

#### Declaration ####

```
void SbThreadYield()
```