Lely core libraries 2.3.4
threads.h File Reference

This header file is part of the C11 and POSIX compatibility library; it includes <threads.h>, if it exists, and defines any missing functionality. More...

#include <lely/features.h>
#include <lely/libc/time.h>
Include dependency graph for threads.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define TSS_DTOR_ITERATIONS   1
 The static initializer for an object of type #once_flag.
 

Typedefs

typedef int(* thrd_start_t) (void *)
 A complete object type that holds a flag for use by call_once().
 

Enumerations

enum  { mtx_plain = 0 , mtx_recursive = 2 , mtx_timed = 1 }
 A complete object type that holds an identifier for a condition variable. More...
 
enum  {
  thrd_success , thrd_error , thrd_timedout , thrd_busy ,
  thrd_nomem
}
 

Functions

void call_once (once_flag *flag, void(*func)(void))
 Uses the #once_flag at flag to ensure that func is called exactly once, the first time the call_once() functions is called with that value of flag.
 
int cnd_broadcast (cnd_t *cond)
 Unblocks all of the threads that are blocked on the condition variable at cond at the time of the call.
 
void cnd_destroy (cnd_t *cond)
 Releases all resources used by the condition variable at cond.
 
int cnd_init (cnd_t *cond)
 Creates a condition variable.
 
int cnd_signal (cnd_t *cond)
 Unblocks one of the threads that are blocked on the condition variable at cond at the time of the call.
 
int cnd_timedwait (cnd_t *cond, mtx_t *mtx, const struct timespec *ts)
 Atomically unlocks the mutex at mtx and endeavors to block until the condition variable at cond is signaled by a call to cnd_signal() or to cnd_broadcast(), or until after the TIME_UTC-based calendar time at ts.
 
int cnd_wait (cnd_t *cond, mtx_t *mtx)
 Atomically unlocks the mutex at mtx and endeavors to block until the condition variable at cond is signaled by a call to cnd_signal() or to cnd_broadcast().
 
void mtx_destroy (mtx_t *mtx)
 Releases any resources used by the mutex at mtx.
 
int mtx_init (mtx_t *mtx, int type)
 Creates a mutex object with properties indicated by type, which must have one of the four values:
 
int mtx_lock (mtx_t *mtx)
 Blocks until it locks the mutex at mtx.
 
int mtx_timedlock (mtx_t *mtx, const struct timespec *ts)
 Endeavors to block until it locks the mutex at mtx or until after the TIME_UTC-based calendar time at ts.
 
int mtx_trylock (mtx_t *mtx)
 Endeavors to lock the mutex at mtx.
 
int mtx_unlock (mtx_t *mtx)
 Unlocks the mutex at mtx.
 
int thrd_create (thrd_t *thr, thrd_start_t func, void *arg)
 Creates a new thread executing func(arg).
 
thrd_t thrd_current (void)
 Identifies the thread that called it.
 
int thrd_detach (thrd_t thr)
 Tells the operating system to dispose of any resources allocated to the thread identified by thr when that thread terminates.
 
int thrd_equal (thrd_t thr0, thrd_t thr1)
 Determines whether the thread identified by thr0 refers to the thread identified by thr1.
 
_Noreturn void thrd_exit (int res)
 Terminates execution of the calling thread and sets its result code to res.
 
int thrd_join (thrd_t thr, int *res)
 Joins the thread identified by thr with the current thread by blocking until the other thread has terminated.
 
int thrd_sleep (const struct timespec *duration, struct timespec *remaining)
 Suspends execution of the calling thread until either the interval specified by duration has elapsed or a signal which is not being ignored is received.
 
void thrd_yield (void)
 Endeavors to permit other threads to run, even if the current thread would ordinarily continue to run.
 
int tss_create (tss_t *key, tss_dtor_t dtor)
 Creates a thread-specific storage pointer with destructor dtor, which may be NULL.
 
void tss_delete (tss_t key)
 Releases any resources used by the thread-specific storage identified by key.
 
void * tss_get (tss_t key)
 Returns the value for the current thread held in the thread-specific storage identified by key.
 
int tss_set (tss_t key, void *val)
 Sets the value for the current thread held in the thread-specific storage identified by key to val.
 

Detailed Description

This header file is part of the C11 and POSIX compatibility library; it includes <threads.h>, if it exists, and defines any missing functionality.

Author
J. S. Seldenthuis jseld.nosp@m.enth.nosp@m.uis@l.nosp@m.ely..nosp@m.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Definition in file threads.h.

Macro Definition Documentation

◆ TSS_DTOR_ITERATIONS

#define TSS_DTOR_ITERATIONS   1

The static initializer for an object of type #once_flag.

The maximum number of times that destructors will be called when a thread terminates.

Definition at line 74 of file threads.h.

Typedef Documentation

◆ thrd_start_t

typedef int(* thrd_start_t) (void *)

A complete object type that holds a flag for use by call_once().

The function pointer type used for a destructor for a thread-specific storage pointer. The function pointer type that is passed to thrd_create() to create a new thread.

Definition at line 168 of file threads.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

A complete object type that holds an identifier for a condition variable.

A complete object type that holds an identifier for a thread. A complete object type that holds an identifier for a thread-specific storage pointer. A complete object type that holds an identifier for a mutex.

Enumerator
mtx_plain 

A mutex type that supports neither timeout nor test and return.

mtx_recursive 

A mutex type that supports recursive locking.

mtx_timed 

A mutex type that supports timeout (not available with the native Windows API).

Definition at line 107 of file threads.h.

◆ anonymous enum

anonymous enum
Enumerator
thrd_success 

Indicates that the requested operation succeeded.

thrd_error 

Indicates that the requested operation failed.

thrd_timedout 

Indicates that the time specified in the call was reached without acquiring the requested resource.

thrd_busy 

Indicates that the requested operation failed because a resource requested by a test and return function is already in use.

thrd_nomem 

Indicates that the requested operation failed because it was unable to allocate memory.

Definition at line 119 of file threads.h.

Function Documentation

◆ call_once()

void call_once ( once_flag *  flag,
void(*)(void)  func 
)

Uses the #once_flag at flag to ensure that func is called exactly once, the first time the call_once() functions is called with that value of flag.

Completion of an effective call to the call_once() function synchronizes with all subsequent calls to the call_once() function with the same value of flag.

◆ cnd_broadcast()

int cnd_broadcast ( cnd_t *  cond)

Unblocks all of the threads that are blocked on the condition variable at cond at the time of the call.

If no threads are blocked on the condition variable at cond at the time of the call, the function does nothing.

Returns
thrd_success on success, or thrd_error if the request could not be honored.

◆ cnd_destroy()

void cnd_destroy ( cnd_t *  cond)

Releases all resources used by the condition variable at cond.

This function requires that no threads be blocked waiting for the condition variable at cond.

◆ cnd_init()

int cnd_init ( cnd_t *  cond)

Creates a condition variable.

If it succeeds it sets the variable at cond to a value that uniquely identifies the newly created condition variable. A thread that calls cnd_wait() on a newly created condition variable will block.

Returns
thrd_success on success, or thrd_nomem if no memory could be allocated for the newly created condition, or thrd_error if the request could not be honored.

◆ cnd_signal()

int cnd_signal ( cnd_t *  cond)

Unblocks one of the threads that are blocked on the condition variable at cond at the time of the call.

If no threads are blocked on the condition variable at the time of the call, the function does nothing and return success.

Returns
thrd_success on success or thrd_error if the request could not be honored.

◆ cnd_timedwait()

int cnd_timedwait ( cnd_t *  cond,
mtx_t *  mtx,
const struct timespec ts 
)

Atomically unlocks the mutex at mtx and endeavors to block until the condition variable at cond is signaled by a call to cnd_signal() or to cnd_broadcast(), or until after the TIME_UTC-based calendar time at ts.

When the calling thread becomes unblocked it locks the variable at mtx before it returns. This function requires that the mutex at mtx be locked by the calling thread.

Returns
thrd_success upon success, or thrd_timedout if the time specified in the call was reached without acquiring the requested resource, or thrd_error if the request could not be honored.

◆ cnd_wait()

int cnd_wait ( cnd_t *  cond,
mtx_t *  mtx 
)

Atomically unlocks the mutex at mtx and endeavors to block until the condition variable at cond is signaled by a call to cnd_signal() or to cnd_broadcast().

When the calling thread becomes unblocked it locks the mutex at mtx before it returns. This function requires that the mutex at mtx be locked by the calling thread.

Returns
thrd_success on success or thrd_error if the request could not be honored.

◆ mtx_destroy()

void mtx_destroy ( mtx_t *  mtx)

Releases any resources used by the mutex at mtx.

No threads can be blocked waiting for the mutex at mtx.

◆ mtx_init()

int mtx_init ( mtx_t *  mtx,
int  type 
)

Creates a mutex object with properties indicated by type, which must have one of the four values:

  • #mtx_plain for a simple non-recursive mutex,
  • #mtx_timed for a non-recursive mutex that supports timeout,
  • #mtx_plain | #mtx_recursive for a simple recursive mutex, or
  • #mtx_timed | #mtx_recursive for a recursive mutex that supports timeout.

If this function succeeds, it sets the mutex at mtx to a value that uniquely identifies the newly created mutex.

Returns
thrd_success on success, or thrd_error if the request could not be honored.

◆ mtx_lock()

int mtx_lock ( mtx_t *  mtx)

Blocks until it locks the mutex at mtx.

If the mutex is non-recursive, it SHALL not be locked by the calling thread. Prior calls to mtx_unlock() on the same mutex shall synchronize with this operation.

Returns
thrd_success on success, or thrd_error if the request could not be honored.

◆ mtx_timedlock()

int mtx_timedlock ( mtx_t *  mtx,
const struct timespec ts 
)

Endeavors to block until it locks the mutex at mtx or until after the TIME_UTC-based calendar time at ts.

The specified mutex SHALL support timeout. If the operation succeeds, prior calls to mtx_unlock() on the same mutex shall synchronize with this operation.

Returns
thrd_success on success, or thrd_timedout if the time specified was reached without acquiring the requested resource, or thrd_error if the request could not be honored.

◆ mtx_trylock()

int mtx_trylock ( mtx_t *  mtx)

Endeavors to lock the mutex at mtx.

If the mutex is already locked, the function returns without blocking. If the operation succeeds, prior calls to mtx_unlock() on the same mutex shall synchronize with this operation.

Returns
thrd_success on success, or thrd_busy if the resource requested is already in use, or thrd_error if the request could not be honored.

◆ mtx_unlock()

int mtx_unlock ( mtx_t *  mtx)

Unlocks the mutex at mtx.

The mutex at mtx SHALL be locked by the calling thread.

Returns
thrd_success on success, or thrd_error if the request could not be honored.

◆ thrd_create()

int thrd_create ( thrd_t *  thr,
thrd_start_t  func,
void *  arg 
)

Creates a new thread executing func(arg).

If this function succeeds, it sets the object at thr to the identifier of the newly created thread. (A thread's identifier may be reused for a different thread once the original thread has exited and either been detached or joined to another thread.) The completion of this function synchronizes with the beginning of the execution of the new thread.

Returns
thrd_success on success, or thrd_nomem if no memory could be allocated for the thread requested, or thrd_error if the request could not be honored.

◆ thrd_current()

thrd_t thrd_current ( void  )

Identifies the thread that called it.

Returns
the identifier of the thread that called it.

◆ thrd_detach()

int thrd_detach ( thrd_t  thr)

Tells the operating system to dispose of any resources allocated to the thread identified by thr when that thread terminates.

The thread identified by thr SHALL not have been previously detached or joined with another thread.

Returns
thrd_success on success or thrd_error if the request could not be honored.

◆ thrd_equal()

int thrd_equal ( thrd_t  thr0,
thrd_t  thr1 
)

Determines whether the thread identified by thr0 refers to the thread identified by thr1.

Returns
zero if the thread thr0 and the thread thr1 refer to different threads. Otherwise this function returns a nonzero value.

◆ thrd_exit()

_Noreturn void thrd_exit ( int  res)

Terminates execution of the calling thread and sets its result code to res.

The program shall terminate normally after the last thread has been terminated. The behavior shall be as if the program called the exit() function with the status EXIT_SUCCESS at thread termination time.

◆ thrd_join()

int thrd_join ( thrd_t  thr,
int *  res 
)

Joins the thread identified by thr with the current thread by blocking until the other thread has terminated.

If the parameter res is not a NULL pointer, it stores the thread's result code in the integer at res. The termination of the other thread synchronizes with the completion of this function. The thread identified by thr SHALL not have been previously detached or joined with another thread.

Returns
thrd_success on success or thrd_error if the request could not be honored.

◆ thrd_sleep()

int thrd_sleep ( const struct timespec duration,
struct timespec remaining 
)

Suspends execution of the calling thread until either the interval specified by duration has elapsed or a signal which is not being ignored is received.

If interrupted by a signal and the remaining argument is not NULL, the amount of time remaining (the requested interval minus the time actually slept) is stored in the interval it points to. The duration and remaining arguments may point to the same object.

The suspension time may be longer than requested because the interval is rounded up to an integer multiple of the sleep resolution or because of the scheduling of other activity by the system. But, except for the case of being interrupted by a signal, the suspension time shall not be less than that specified, as measured by the system clock TIME_UTC.

Returns
zero if the requested time has elapsed, -1 if it has been interrupted by a signal, or a negative value if it fails.

◆ tss_create()

int tss_create ( tss_t *  key,
tss_dtor_t  dtor 
)

Creates a thread-specific storage pointer with destructor dtor, which may be NULL.

If this function is successful, it sets the thread-specific storage at key to a value that uniquely identifies the newly created pointer; otherwise, the thread-specific storage at key is set to an undefined value.

Returns
thrd_success on success or thrd_error if the request could not be honored.

◆ tss_get()

void * tss_get ( tss_t  key)

Returns the value for the current thread held in the thread-specific storage identified by key.

Returns
the value for the current thread if successful, or zero if unsuccessful.

◆ tss_set()

int tss_set ( tss_t  key,
void *  val 
)

Sets the value for the current thread held in the thread-specific storage identified by key to val.

Returns
thrd_success on success or thrd_error if the request could not be honored.