Lely core libraries  2.3.4
threads-pthread.c File Reference

This file is part of the C11 and POSIX compatibility library. More...

#include "libc.h"
#include <lely/libc/threads.h>
#include <errno.h>
#include <stdint.h>
#include <sched.h>
Include dependency graph for threads-pthread.c:

Go to the source code of this file.

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. More...
 
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. More...
 
void cnd_destroy (cnd_t *cond)
 Releases all resources used by the condition variable at cond. More...
 
int cnd_init (cnd_t *cond)
 Creates a condition variable. More...
 
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. More...
 
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. More...
 
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(). More...
 
void mtx_destroy (mtx_t *mtx)
 Releases any resources used by the mutex at mtx. More...
 
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: More...
 
int mtx_lock (mtx_t *mtx)
 Blocks until it locks the mutex at mtx. More...
 
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. More...
 
int mtx_trylock (mtx_t *mtx)
 Endeavors to lock the mutex at mtx. More...
 
int mtx_unlock (mtx_t *mtx)
 Unlocks the mutex at mtx. More...
 
int thrd_create (thrd_t *thr, thrd_start_t func, void *arg)
 Creates a new thread executing func(arg). More...
 
thrd_t thrd_current (void)
 Identifies the thread that called it. More...
 
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. More...
 
int thrd_equal (thrd_t thr0, thrd_t thr1)
 Determines whether the thread identified by thr0 refers to the thread identified by thr1. More...
 
_Noreturn void thrd_exit (int res)
 Terminates execution of the calling thread and sets its result code to res. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

Detailed Description

This file is part of the C11 and POSIX compatibility library.

See also
lely/libc/threads.h
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-pthread.c.

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.

Definition at line 46 of file threads-pthread.c.

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

Definition at line 52 of file threads-pthread.c.

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

Definition at line 63 of file threads-pthread.c.

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

Definition at line 69 of file threads-pthread.c.

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

Definition at line 80 of file threads-pthread.c.

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

Definition at line 91 of file threads-pthread.c.

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

Definition at line 102 of file threads-pthread.c.

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

Definition at line 113 of file threads-pthread.c.

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

Definition at line 119 of file threads-pthread.c.

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

Definition at line 150 of file threads-pthread.c.

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

Definition at line 161 of file threads-pthread.c.

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

Definition at line 172 of file threads-pthread.c.

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

Definition at line 183 of file threads-pthread.c.

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

Definition at line 194 of file threads-pthread.c.

◆ thrd_current()

thrd_t thrd_current ( void  )

Identifies the thread that called it.

Returns
the identifier of the thread that called it.

Definition at line 212 of file threads-pthread.c.

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

Definition at line 218 of file threads-pthread.c.

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

Definition at line 229 of file threads-pthread.c.

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

Definition at line 235 of file threads-pthread.c.

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

Definition at line 244 of file threads-pthread.c.

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

Definition at line 258 of file threads-pthread.c.

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

Definition at line 284 of file threads-pthread.c.

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

Definition at line 301 of file threads-pthread.c.

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

Definition at line 307 of file threads-pthread.c.