obs-studio/docs/sphinx/reference-libobs-util-threa...

194 lines
4.4 KiB
ReStructuredText

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.
.. code:: cpp
#include <util/threading.h>
Threading Types
---------------
.. type:: os_event_t
.. type:: os_sem_t
General Thread Functions
------------------------
.. function:: void os_set_thread_name(const char *name)
Sets the name of the current thread.
----------------------
Event Functions
---------------
.. function:: int os_event_init(os_event_t **event, enum os_event_type type)
Creates an event object.
:param event: Pointer that receives a pointer to a new event object
:param type: Can be one of the following values:
- OS_EVENT_TYPE_AUTO - Automatically resets when
signaled
- OS_EVENT_TYPE_MANUAL - Stays signaled until the
:c:func:`os_event_reset()` function is called
:return: 0 if successful, negative otherwise
----------------------
.. function:: void os_event_destroy(os_event_t *event)
Destroys an event.
:param event: An event object
----------------------
.. function:: int os_event_wait(os_event_t *event)
Waits for an event to signal.
:param event: An event object
:return: 0 if successful, negative otherwise
----------------------
.. function:: int os_event_timedwait(os_event_t *event, unsigned long milliseconds)
Waits a specific duration for an event to signal.
:param event: An event object
:param milliseconds: Milliseconds to wait
:return: Can be one of the following values:
- 0 - successful
- ETIMEDOUT - Timed out
- EINVAL - An unexpected error occurred
----------------------
.. function:: int os_event_try(os_event_t *event)
Checks for a signaled state without waiting.
:param event: An event object
:return: Can be one of the following values:
- 0 - successful
- EAGAIN - The event is not signaled
- EINVAL - An unexpected error occurred
----------------------
.. function:: int os_event_signal(os_event_t *event)
Signals the event.
:param event: An event object
:return: 0 if successful, negative otherwise
----------------------
.. function:: void os_event_reset(os_event_t *event)
Resets the signaled state of the event.
:param event: An event object
----------------------
Semaphore Functions
-------------------
.. function:: int os_sem_init(os_sem_t **sem, int value)
Creates a semaphore object.
:param sem: Pointer that receives a pointer to the semaphore object
:param value: Initial value of the semaphore
:return: 0 if successful, negative otherwise
----------------------
.. function:: void os_sem_destroy(os_sem_t *sem)
Destroys a semaphore object.
:param sem: Semaphore object
----------------------
.. function:: int os_sem_post(os_sem_t *sem)
Increments the semaphore.
:param sem: Semaphore object
:return: 0 if successful, negative otherwise
----------------------
.. function:: int os_sem_wait(os_sem_t *sem)
Decrements the semaphore or waits until the semaphore has been
incremented.
:param sem: Semaphore object
:return: 0 if successful, negative otherwise
---------------------
Atomic Inline Functions
-----------------------
.. function:: long os_atomic_inc_long(volatile long *val)
Increments a long variable atomically.
---------------------
.. function:: long os_atomic_dec_long(volatile long *val)
Decrements a long variable atomically.
---------------------
.. function:: long os_atomic_set_long(volatile long *ptr, long val)
Sets the value of a long variable atomically.
---------------------
.. function:: long os_atomic_load_long(const volatile long *ptr)
Gets the value of a long variable atomically.
---------------------
.. function:: 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.
---------------------
.. function:: bool os_atomic_set_bool(volatile bool *ptr, bool val)
Sets the value of a boolean variable atomically.
---------------------
.. function:: bool os_atomic_load_bool(const volatile bool *ptr)
Gets the value of a boolean variable atomically.