threads.ch
Declarations
Public Only
Publicstruct mtx_t
struct mtx_t
Publicstruct thrd_t
struct thrd_t
TODO thrd_t is implementation defined
See Also
- https:en.cppreference.com/w/c/thread
Publicstruct cnd_t
struct cnd_t
TODO cnd_t is implementation defined
See Also
- https:en.cppreference.com/w/c/thread
Publicstruct tss_t
struct tss_t
TODO tss_t is implementation defined
See Also
- https:en.cppreference.com/w/c/thread
Publicstruct tss_dtor_t
struct tss_dtor_t
TODO tss_dtor_t is implementation defined
See Also
- https:en.cppreference.com/w/c/thread
Publicstruct once_flag
struct once_flag
TODO once_flag is implementation defined
See Also
- https:en.cppreference.com/w/c/thread
Publicenum thrd_result
enum thrd_result {
thrd_success,
thrd_nomem,
thrd_timedout,
thrd_busy,
thrd_error
}
TODO the values for enum members are implementation defined
See Also
- https:en.cppreference.com/w/c/thread/thrd_errors
Publicfunction thrd_equal
Checks whether lhs and rhs refer to the same thread.
Parameters
- lhs, rhs - threads to compare @return Non-zero value if lhs and rhs refer to the same value, 0 otherwise. @see https:en.cppreference.com/w/c/thread/thrd_equal
Returns
Non-zero value if lhs and rhs refer to the same value, 0 otherwise. @see https:en.cppreference.com/w/c/thread/thrd_equal
See Also
- https:en.cppreference.com/w/c/thread/thrd_equal
Publicfunction thrd_current
func thrd_current() : thrd_t
Returns the identifier of the calling thread.
Returns
The identifier of the calling thread. @see https:en.cppreference.com/w/c/thread/thrd_current
See Also
- https:en.cppreference.com/w/c/thread/thrd_current
Publicfunction thrd_sleep
Blocks the execution of the current thread for at least until the TIME_UTC based duration pointed to by duration has elapsed.
The sleep may resume earlier if a signal that is not ignored is received. In such case, if remaining is not NULL, the remaining time duration is stored into the object pointed to by remaining.
Parameters
- duration - pointer to the duration to sleep for @param remaining - pointer to the object to put the remaining time on interruption. May be NULL, in which case it is ignored @return 0 on successful sleep, -1 if a signal occurred, other negative value if an error occurred. @see https:en.cppreference.com/w/c/thread/thrd_sleep
- remaining - pointer to the object to put the remaining time on interruption. May be NULL, in which case it is ignored @return 0 on successful sleep, -1 if a signal occurred, other negative value if an error occurred. @see https:en.cppreference.com/w/c/thread/thrd_sleep
Returns
0 on successful sleep, -1 if a signal occurred, other negative value if an error occurred. @see https:en.cppreference.com/w/c/thread/thrd_sleep
See Also
- https:en.cppreference.com/w/c/thread/thrd_sleep
Publicfunction thrd_yield
func thrd_yield() : void
Provides a hint to the implementation to reschedule the execution of threads, allowing other threads to run.
See Also
- https:en.cppreference.com/w/c/thread/thrd_yield
Publicfunction thrd_exit
func thrd_exit(res : int) : void
First, for every thread-specific storage key which was created with a non-null destructor and for which the associated value is non-null (see tss_create), thrd_exit sets the value associated with the key to NULL and then invokes the destructor with the previous value of the key. The order in which the destructors are invoked is unspecified.
If, after this, there remain keys with both non-null destructors and values (e.g. if a destructor executed tss_set), the process is repeated up to TSS_DTOR_ITERATIONS times.
Finally, the thrd_exit function terminates execution of the calling thread and sets its result code to res.
If the last thread in the program is terminated with thrd_exit, the entire program terminates as if by calling exit with EXIT_SUCCESS as the argument (so the functions registered by atexit are executed in the context of that last thread)
Parameters
- res - the result value to return @see https:en.cppreference.com/w/c/thread/thrd_exit
See Also
- https:en.cppreference.com/w/c/thread/thrd_exit
Publicfunction thrd_detach
Detaches the thread identified by thr from the current environment. The resources held by the thread will be freed automatically once the thread exits.
Parameters
- thr - identifier of the thread to detach @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/thrd_detach
Returns
thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/thrd_detach
See Also
- https:en.cppreference.com/w/c/thread/thrd_detach
Publicfunction thrd_join
Blocks the current thread until the thread identified by thr finishes execution.
If res is not a null pointer, the result code of the thread is put to the location pointed to by res.
The termination of the thread synchronizes-with the completion of this function.
The behavior is undefined if the thread was previously detached or joined by another thread.
Parameters
- thr - identifier of the thread to join @param res - location to put the result code to @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/thrd_join
- res - location to put the result code to @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/thrd_join
Returns
thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/thrd_join
See Also
- https:en.cppreference.com/w/c/thread/thrd_join
Publicfunction mtx_init
Creates a new mutex object with type. The object pointed to by mutex is set to an identifier of the newly created mutex.
type must have one of the following values:
mtx_plain - a simple, non-recursive mutex is created.
mtx_timed - a non-recursive mutex, that supports timeout, is created.
mtx_plain | mtx_recursive - a recursive mutex is created.
mtx_timed | mtx_recursive - a recursive mutex, that supports timeout, is created.
Parameters
- mutex - pointer to the mutex to initialize @param type - the type of the mutex @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/mtx_init
- type - the type of the mutex @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/mtx_init
Returns
thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/mtx_init
See Also
- https:en.cppreference.com/w/c/thread/mtx_init
Publicfunction mtx_lock
Blocks the current thread until the mutex pointed to by mutex is locked.
The behavior is undefined if the current thread has already locked the mutex and the mutex is not recursive.
Prior calls to mtx_unlock on the same mutex synchronize-with this operation, and all lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic)
Parameters
- mutex - pointer to the mutex to lock @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/mtx_lock
Returns
thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/mtx_lock
See Also
- https:en.cppreference.com/w/c/thread/mtx_lock
Publicfunction mtx_timedlock
Blocks the current thread until the mutex pointed to by mutex is locked or until the TIME_UTC based absolute calendar time point pointed to by time_point has been reached.
Since this function takes an absolute time, if a duration is required, the calendar time point must be calculated manually.
The behavior is undefined if the current thread has already locked the mutex and the mutex is not recursive.
The behavior is undefined if the mutex does not support timeout.
Prior calls to mtx_unlock on the same mutex synchronize-with this operation (if this operation succeeds), and all lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic)
Parameters
- mutex (restricted) - pointer to the mutex to lock @param time_point (restricted) - pointer to the absolute calendar time until which to wait for the timeout @return thrd_success if successful, thrd_timedout if the timeout time has been reached before the mutex is locked, thrd_error if an error occurs. @see https:en.cppreference.com/w/c/thread/mtx_timedlock
- time_point (restricted) - pointer to the absolute calendar time until which to wait for the timeout @return thrd_success if successful, thrd_timedout if the timeout time has been reached before the mutex is locked, thrd_error if an error occurs. @see https:en.cppreference.com/w/c/thread/mtx_timedlock
Returns
thrd_success if successful, thrd_timedout if the timeout time has been reached before the mutex is locked, thrd_error if an error occurs. @see https:en.cppreference.com/w/c/thread/mtx_timedlock
See Also
- https:en.cppreference.com/w/c/thread/mtx_timedlock
Publicfunction mtx_trylock
Tries to lock the mutex pointed to by mutex without blocking. Returns immediately if the mutex is already locked.
Prior calls to mtx_unlock on the same mutex synchronize-with this operation (if this operation succeeds), and all lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic)
Parameters
- mutex - pointer to the mutex to lock @return thrd_success if successful, thrd_busy if the mutex has already been locked or due to a spurious failure to acquire an available mutex, thrd_error if an error occurs. @see https:en.cppreference.com/w/c/thread/mtx_trylock
Returns
thrd_success if successful, thrd_busy if the mutex has already been locked or due to a spurious failure to acquire an available mutex, thrd_error if an error occurs. @see https:en.cppreference.com/w/c/thread/mtx_trylock
See Also
- https:en.cppreference.com/w/c/thread/mtx_trylock
Publicfunction mtx_unlock
Unlocks the mutex pointed to by mutex.
The behavior is undefined if the mutex is not locked by the calling thread.
This function synchronizes-with subsequent mtx_lock, mtx_trylock, or mtx_timedlock on the same mutex. All lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic).
Parameters
- mutex - pointer to the mutex to unlock @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/mtx_unlock
Returns
thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/mtx_unlock
See Also
- https:en.cppreference.com/w/c/thread/mtx_unlock
Publicfunction mtx_destroy
func mtx_destroy(mutex : *mtx_t) : void
Destroys the mutex pointed to by mutex.
If there are threads waiting on mutex, the behavior is undefined.
Parameters
- mutex - pointer to the mutex to destroy @see https:en.cppreference.com/w/c/thread/mtx_destroy
See Also
- https:en.cppreference.com/w/c/thread/mtx_destroy
enum mtx_type
enum mtx_type {
recursive,
plain,
timed
}
When passed to mtx_init, identifies the type of a mutex to create.
See Also
- https:en.cppreference.com/w/c/thread/mtx_types
Publicfunction call_once
func call_once(flag : *once_flag, func : func() : void) : void
Calls function func exactly once, even if invoked from several threads. The completion of the function func synchronizes with all previous or subsequent calls to call_once with the same flag variable.
Parameters
- flag - pointer to an object of type call_once that is used to ensure func is called only once @param func - the function to execute only once @see https:en.cppreference.com/w/c/thread/call_once
- func - the function to execute only once @see https:en.cppreference.com/w/c/thread/call_once
See Also
- https:en.cppreference.com/w/c/thread/call_once
Publicfunction cnd_init
Initializes new condition variable. The object pointed to by cond will be set to value that identifies the condition variable.
Parameters
- cond - pointer to a variable to store identifier of the condition variable to @return thrd_success if the condition variable was successfully created. Otherwise returns thrd_nomem if there was insufficient amount of memory or thrd_error if another error occurred.
Returns
thrd_success if the condition variable was successfully created. Otherwise returns thrd_nomem if there was insufficient amount of memory or thrd_error if another error occurred.
Publicfunction cnd_signal
Unblocks one thread that currently waits on condition variable pointed to by cond. If no threads are blocked, does nothing and returns thrd_success.
Parameters
- cond - pointer to a condition variable @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/cnd_signal
Returns
thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/cnd_signal
See Also
- https:en.cppreference.com/w/c/thread/cnd_signal
Publicfunction cnd_broadcast
Unblocks all threads that are blocked on condition variable cond at the time of the call. If no threads are blocked on cond, the function does nothing and returns thrd_success.
Parameters
- cond - pointer to a condition variable @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/cnd_broadcast
Returns
thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/cnd_broadcast
See Also
- https:en.cppreference.com/w/c/thread/cnd_broadcast
Publicfunction cnd_wait
Atomically unlocks the mutex pointed to by mutex and blocks on the condition variable pointed to by cond until the thread is signalled by cnd_signal or cnd_broadcast, or until a spurious wake-up occurs. The mutex is locked again before the function returns.
The behavior is undefined if the mutex is not already locked by the calling thread.
Parameters
- cond - pointer to the condition variable to block on @param mutex - pointer to the mutex to unlock for the duration of the block @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/cnd_wait
- mutex - pointer to the mutex to unlock for the duration of the block @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/cnd_wait
Returns
thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/cnd_wait
See Also
- https:en.cppreference.com/w/c/thread/cnd_wait
Publicfunction cnd_timedwait
Atomically unlocks the mutex pointed to by mutex and blocks on the condition variable pointed to by cond until the thread is signalled by cnd_signal or cnd_broadcast, or until the TIME_UTC based time point pointed to by time_point has been reached, or until a spurious wake-up occurs. The mutex is locked again before the function returns.
The behavior is undefined if the mutex is not already locked by the calling thread.
Parameters
- cond - pointer to the condition variable to block on @param mutex - pointer to the mutex to unlock for the duration of the block @param time_point - pointer to an object specifying timeout time to wait until @return thrd_success if successful, thrd_timedout if the timeout time has been reached before the mutex is locked, or thrd_error if an error occurred. @see https:en.cppreference.com/w/c/thread/cnd_timedwait
- mutex - pointer to the mutex to unlock for the duration of the block @param time_point - pointer to an object specifying timeout time to wait until @return thrd_success if successful, thrd_timedout if the timeout time has been reached before the mutex is locked, or thrd_error if an error occurred. @see https:en.cppreference.com/w/c/thread/cnd_timedwait
- time_point - pointer to an object specifying timeout time to wait until @return thrd_success if successful, thrd_timedout if the timeout time has been reached before the mutex is locked, or thrd_error if an error occurred. @see https:en.cppreference.com/w/c/thread/cnd_timedwait
Returns
thrd_success if successful, thrd_timedout if the timeout time has been reached before the mutex is locked, or thrd_error if an error occurred. @see https:en.cppreference.com/w/c/thread/cnd_timedwait
See Also
- https:en.cppreference.com/w/c/thread/cnd_timedwait
Publicfunction cnd_destroy
func cnd_destroy(cond : *cnd_t) : void
Destroys the condition variable pointed to by cond.
If there are threads waiting on cond, the behavior is undefined.
Parameters
- cond - pointer to the condition variable to destroy @see https:en.cppreference.com/w/c/thread/cnd_destroy
See Also
- https:en.cppreference.com/w/c/thread/cnd_destroy
Publicfunction tss_create
Creates new thread-specific storage key and stores it in the object pointed to by tss_key. Although the same key value may be used by different threads, the values bound to the key by tss_set are maintained on a per-thread basis and persist for the life of the calling thread.
The value NULL is associated with the newly created key in all existing threads, and upon thread creation, the values associated with all TSS keys is initialized to NULL.
If destructor is not a null pointer, then also associates the destructor which is called when the storage is released by thrd_exit (but not by tss_delete and not at program termination by exit).
A call to tss_create from within a thread-specific storage destructor results in undefined behavior.
Parameters
- tss_key - pointer to memory location to store the new thread-specific storage key @param destructor - pointer to a function to call at thread exit @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/tss_create
- destructor - pointer to a function to call at thread exit @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/tss_create
Returns
thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/tss_create
See Also
- https:en.cppreference.com/w/c/thread/tss_create
Publicfunction tss_get
func tss_get(tss_key : tss_t) : *void
Returns the value held in thread-specific storage for the current thread identified by tss_key. Different threads may get different values identified by the same key.
On thread startup (see thrd_create), the values associated with all TSS keys are NULL. Different value may be placed in the thread-specific storage with tss_set.
Parameters
- tss_key - thread-specific storage key, obtained from tss_create and not deleted by tss_delete @return The value on success, NULL on failure. @see https:en.cppreference.com/w/c/thread/tss_get
Returns
The value on success, NULL on failure. @see https:en.cppreference.com/w/c/thread/tss_get
See Also
- https:en.cppreference.com/w/c/thread/tss_get
Publicfunction tss_set
Sets the value of the thread-specific storage identified by tss_id for the current thread to val. Different threads may set different values to the same key.
The destructor, if available, is not invoked.
Parameters
- tss_id - thread-specific storage key, obtained from tss_create and not deleted by tss_delete @param val - value to set thread-specific storage to @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/tss_set
- val - value to set thread-specific storage to @return thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/tss_set
Returns
thrd_success if successful, thrd_error otherwise. @see https:en.cppreference.com/w/c/thread/tss_set
See Also
- https:en.cppreference.com/w/c/thread/tss_set
Publicfunction tss_delete
func tss_delete(tss_id : tss_t) : void
Destroys the thread-specific storage identified by tss_id.
The destructor, if one was registered by tss_create, is not called (they are only called at thread exit, either by thrd_exit or by returning from the thread function), it is the responsibility of the programmer to ensure that every thread that is aware of tss_id performed all necessary cleanup, before the call to tss_delete is made.
If tss_delete is called while another thread is executing destructors for tss_id, it's unspecified whether this changes the number of invocations to the associated destructor.
If tss_delete is called while the calling thread is executing destructors, then the destructor associated with tss_id will not be executed again on this thread.
Parameters
- tss_id - thread-specific storage key previously returned by tss_create and not yet deleted by tss_delete @see https:en.cppreference.com/w/c/thread/tss_delete
See Also
- https:en.cppreference.com/w/c/thread/tss_delete
See Also