Threading

Libobs provides a number of helper functions/types specifically for threading. The threading header will additionally provide access to pthread functions even on Windows.

#include <util/threading.h>

Threading Types

type os_event_t
type os_sem_t

General Thread Functions

void os_set_thread_name(const char *name)

Sets the name of the current thread.


Event Functions

int os_event_init(os_event_t **event, enum os_event_type type)

Creates an event object.

Parameters:
  • event – Pointer that receives a pointer to a new event object

  • type

    Can be one of the following values:

    • OS_EVENT_TYPE_AUTO - Automatically resets when signaled

    • OS_EVENT_TYPE_MANUAL - Stays signaled until the os_event_reset() function is called

Returns:

0 if successful, negative otherwise


void os_event_destroy(os_event_t *event)

Destroys an event.

Parameters:
  • event – An event object


int os_event_wait(os_event_t *event)

Waits for an event to signal.

Parameters:
  • event – An event object

Returns:

0 if successful, negative otherwise


int os_event_timedwait(os_event_t *event, unsigned long milliseconds)

Waits a specific duration for an event to signal.

Parameters:
  • event – An event object

  • milliseconds – Milliseconds to wait

Returns:

Can be one of the following values:

  • 0 - successful

  • ETIMEDOUT - Timed out

  • EINVAL - An unexpected error occurred


int os_event_try(os_event_t *event)

Checks for a signaled state without waiting.

Parameters:
  • event – An event object

Returns:

Can be one of the following values:

  • 0 - successful

  • EAGAIN - The event is not signaled

  • EINVAL - An unexpected error occurred


int os_event_signal(os_event_t *event)

Signals the event.

Parameters:
  • event – An event object

Returns:

0 if successful, negative otherwise


void os_event_reset(os_event_t *event)

Resets the signaled state of the event.

Parameters:
  • event – An event object


Semaphore Functions

int os_sem_init(os_sem_t **sem, int value)

Creates a semaphore object.

Parameters:
  • sem – Pointer that receives a pointer to the semaphore object

  • value – Initial value of the semaphore

Returns:

0 if successful, negative otherwise


void os_sem_destroy(os_sem_t *sem)

Destroys a semaphore object.

Parameters:
  • sem – Semaphore object


int os_sem_post(os_sem_t *sem)

Increments the semaphore.

Parameters:
  • sem – Semaphore object

Returns:

0 if successful, negative otherwise


int os_sem_wait(os_sem_t *sem)

Decrements the semaphore or waits until the semaphore has been incremented.

Parameters:
  • sem – Semaphore object

Returns:

0 if successful, negative otherwise


Atomic Inline Functions

long os_atomic_inc_long(volatile long *val)

Increments a long variable atomically.


long os_atomic_dec_long(volatile long *val)

Decrements a long variable atomically.


void os_atomic_store_long(volatile long *ptr, long val)

Stores the value of a long variable atomically.


long os_atomic_set_long(volatile long *ptr, long val)

Exchanges the value of a long variable atomically. Badly named.


long os_atomic_exchange_long(volatile long *ptr, long val)

Exchanges the value of a long variable atomically. Properly named.


long os_atomic_load_long(volatile const long *ptr)

Gets the value of a long variable atomically.


bool os_atomic_compare_swap_long(volatile long *val, long old_val, long new_val)

Swaps the value of a long variable atomically if its value matches.


void os_atomic_store_bool(volatile bool *ptr, bool val)

Stores the value of a boolean variable atomically.


bool os_atomic_set_bool(volatile bool *ptr, bool val)

Exchanges the value of a boolean variable atomically. Badly named.


bool os_atomic_exchange_bool(volatile bool *ptr, bool val)

Exchanges the value of a boolean variable atomically. Properly named.


bool os_atomic_load_bool(volatile const bool *ptr)

Gets the value of a boolean variable atomically.