Minimal POSIX-threads-style interface for SuperTinyKernel RTOS. More...

Classes
struct	pthread_attr_t
	Thread creation attributes. More...
struct	pthread_mutexattr_t
	Mutex attributes. More...
struct	pthread_mutex_t
	A pthread mutex. More...
struct	pthread_condattr_t
	Condition variable attributes (currently no settable properties). More...
struct	pthread_cond_t
	A pthread condition variable. More...
struct	pthread_rwlockattr_t
	Read-write lock attributes (currently no settable properties). More...
struct	pthread_rwlock_t
	A pthread read-write lock. More...
struct	pthread_spinlock_t
	A pthread spinlock. More...
struct	pthread_barrierattr_t
	Barrier attributes (currently no settable properties). More...
struct	pthread_barrier_t
	A pthread barrier. More...
struct	pthread_once_t
	A pthread_once() control object. More...

Macros
#define	STK_C_PTHREAD_MAX_THREADS (8U)
	Maximum number of concurrently-alive pthread_t's (default: 8).
#define	STK_C_PTHREAD_DEFAULT_STACK_WORDS (1024U)
	Default per-thread stack size in stk_word_t units, used when pthread_attr_t does not specify a stack size or an external stack (default: 1024 words).
#define	STK_C_PTHREAD_REAPER_STACK_WORDS (256U)
	Stack size (in stk_word_t units) for the internal reaper task that reclaims detached-thread resources (default: 256 words).
#define	STK_C_PTHREAD_KEYS_MAX (8U)
	Maximum number of concurrently-alive pthread_key_t's (default: 8).
#define	PTHREAD_CREATE_JOINABLE (0)
#define	PTHREAD_CREATE_DETACHED (1)
#define	PTHREAD_MUTEX_NORMAL (0)
#define	PTHREAD_MUTEX_DEFAULT (PTHREAD_MUTEX_NORMAL)
#define	PTHREAD_MUTEX_ERRORCHECK (1)
#define	PTHREAD_MUTEX_RECURSIVE (2)
#define	PTHREAD_MUTEX_INITIALIZER {0}
#define	PTHREAD_COND_INITIALIZER {0}
#define	PTHREAD_RWLOCK_INITIALIZER {0}
#define	PTHREAD_PROCESS_PRIVATE (0)
#define	PTHREAD_PROCESS_SHARED (1)
#define	PTHREAD_BARRIER_SERIAL_THREAD (-1)
	Returned by pthread_barrier_wait() to exactly one arbitrary caller per round; all others receive 0. See "pthread_barrier_wait() note" in the file-level docs.
#define	PTHREAD_ONCE_INIT {0}
#define	PTHREAD_KEYS_MAX (STK_C_PTHREAD_KEYS_MAX)
	POSIX-standard name for STK_C_PTHREAD_KEYS_MAX (this file).
#define	PTHREAD_DESTRUCTOR_ITERATIONS (4)
	Maximum number of passes over a finishing thread's keys made while destructors keep setting new non-NULL values for their own key. See "pthread_key_t / thread-specific data limitation" in the file-level docs.

Typedefs
typedef struct pthread_stk_ctrl_t *	pthread_t
	Opaque thread handle.
typedef struct pthread_attr_t	pthread_attr_t
	Thread creation attributes.
typedef struct pthread_mutexattr_t	pthread_mutexattr_t
	Mutex attributes.
typedef struct pthread_mutex_t	pthread_mutex_t
	A pthread mutex.
typedef struct pthread_condattr_t	pthread_condattr_t
	Condition variable attributes (currently no settable properties).
typedef struct pthread_cond_t	pthread_cond_t
	A pthread condition variable.
typedef struct pthread_rwlockattr_t	pthread_rwlockattr_t
	Read-write lock attributes (currently no settable properties).
typedef struct pthread_rwlock_t	pthread_rwlock_t
	A pthread read-write lock.
typedef struct pthread_spinlock_t	pthread_spinlock_t
	A pthread spinlock.
typedef struct pthread_barrierattr_t	pthread_barrierattr_t
	Barrier attributes (currently no settable properties).
typedef struct pthread_barrier_t	pthread_barrier_t
	A pthread barrier.
typedef struct pthread_once_t	pthread_once_t
	A pthread_once() control object.
typedef unsigned int	pthread_key_t
	A thread-specific data key.

Functions
void	stk_pthread_bind_kernel (stk_kernel_t *kernel)
	Bind the STK kernel instance that pthread_create() will add new threads to.
int	pthread_attr_init (pthread_attr_t *attr)
	Initialize a thread attributes object with default values (default stack size, no external stack, joinable).
int	pthread_attr_destroy (pthread_attr_t *attr)
	Destroy a thread attributes object (no-op; no owned resources).
int	pthread_attr_setstacksize (pthread_attr_t *attr, size_t stacksize)
	Set the requested stack size in bytes.
int	pthread_attr_getstacksize (const pthread_attr_t attr, size_t stacksize)
	Get the currently requested stack size in bytes (0 = default).
int	pthread_attr_setstack (pthread_attr_t attr, void stackaddr, size_t stacksize)
	Supply an external, caller-owned stack buffer for the thread.
int	pthread_attr_getstack (const pthread_attr_t attr, void stackaddr, size_t stacksize)
	Get the previously-set external stack (NULL/0 if none set).
int	pthread_attr_setdetachstate (pthread_attr_t *attr, int detachstate)
	Set PTHREAD_CREATE_JOINABLE or PTHREAD_CREATE_DETACHED.
int	pthread_attr_getdetachstate (const pthread_attr_t attr, int detachstate)
	Get the current detach-state setting.
int	pthread_create (pthread_t thread, const pthread_attr_t attr, void (start_routine)(void ), void arg)
	Create and start a new thread.
int	pthread_join (pthread_t thread, void **retval)
	Block until the given joinable thread finishes, then reclaim its resources.
int	pthread_detach (pthread_t thread)
	Mark a thread as detached.
void	pthread_exit (void *retval)
	Terminate the calling thread.
pthread_t	pthread_self (void)
	Return the calling thread's own handle.
int	pthread_equal (pthread_t t1, pthread_t t2)
	Compare two thread handles for equality.
int	pthread_yield (void)
	Voluntarily give up the CPU to another ready task (cooperative yield), then resume once rescheduled.
int	pthread_mutexattr_init (pthread_mutexattr_t *attr)
int	pthread_mutexattr_destroy (pthread_mutexattr_t *attr)
int	pthread_mutexattr_settype (pthread_mutexattr_t *attr, int type)
	Set the mutex type.
int	pthread_mutexattr_gettype (const pthread_mutexattr_t attr, int type)
int	pthread_mutex_init (pthread_mutex_t mutex, const pthread_mutexattr_t attr)
	Initialize a mutex.
int	pthread_mutex_destroy (pthread_mutex_t *mutex)
int	pthread_mutex_lock (pthread_mutex_t *mutex)
int	pthread_mutex_trylock (pthread_mutex_t *mutex)
int	pthread_mutex_unlock (pthread_mutex_t *mutex)
int	pthread_mutex_timedlock (pthread_mutex_t mutex, const struct timespec abstime)
	Lock with an absolute deadline.
int	pthread_condattr_init (pthread_condattr_t *attr)
int	pthread_condattr_destroy (pthread_condattr_t *attr)
int	pthread_cond_init (pthread_cond_t cond, const pthread_condattr_t attr)
int	pthread_cond_destroy (pthread_cond_t *cond)
int	pthread_cond_wait (pthread_cond_t cond, pthread_mutex_t mutex)
	Atomically unlock mutex and wait for a signal; re-locks mutex before returning.
int	pthread_cond_timedwait (pthread_cond_t cond, pthread_mutex_t mutex, const struct timespec *abstime)
	As pthread_cond_wait(), with an absolute deadline.
int	pthread_cond_signal (pthread_cond_t *cond)
int	pthread_cond_broadcast (pthread_cond_t *cond)
int	pthread_rwlockattr_init (pthread_rwlockattr_t *attr)
int	pthread_rwlockattr_destroy (pthread_rwlockattr_t *attr)
int	pthread_rwlock_init (pthread_rwlock_t rwlock, const pthread_rwlockattr_t attr)
	Initialize a read-write lock.
int	pthread_rwlock_destroy (pthread_rwlock_t *rwlock)
int	pthread_rwlock_rdlock (pthread_rwlock_t *rwlock)
	Acquire the lock for shared reading. Blocks until available.
int	pthread_rwlock_tryrdlock (pthread_rwlock_t *rwlock)
	Try to acquire the read lock without blocking.
int	pthread_rwlock_timedrdlock (pthread_rwlock_t rwlock, const struct timespec abstime)
	Acquire the read lock with an absolute deadline.
int	pthread_rwlock_wrlock (pthread_rwlock_t *rwlock)
	Acquire the lock for exclusive writing. Blocks until available.
int	pthread_rwlock_trywrlock (pthread_rwlock_t *rwlock)
	Try to acquire the write lock without blocking.
int	pthread_rwlock_timedwrlock (pthread_rwlock_t rwlock, const struct timespec abstime)
	Acquire the write lock with an absolute deadline.
int	pthread_rwlock_unlock (pthread_rwlock_t *rwlock)
	Release a read or write hold, whichever the calling thread holds.
int	pthread_spin_init (pthread_spinlock_t *lock, int pshared)
	Initialize a spinlock.
int	pthread_spin_destroy (pthread_spinlock_t *lock)
int	pthread_spin_lock (pthread_spinlock_t *lock)
	Acquire the spinlock, spinning until available.
int	pthread_spin_trylock (pthread_spinlock_t *lock)
	Try to acquire the spinlock without blocking.
int	pthread_spin_unlock (pthread_spinlock_t *lock)
int	pthread_barrierattr_init (pthread_barrierattr_t *attr)
int	pthread_barrierattr_destroy (pthread_barrierattr_t *attr)
int	pthread_barrier_init (pthread_barrier_t barrier, const pthread_barrierattr_t attr, unsigned int count)
	Initialize a barrier for count participating threads.
int	pthread_barrier_destroy (pthread_barrier_t *barrier)
int	pthread_barrier_wait (pthread_barrier_t *barrier)
	Block until count threads have called this function, then release them all together; the barrier resets for reuse.
int	pthread_once (pthread_once_t once_control, void(init_routine)(void))
	Call init_routine exactly once for a given once_control, no matter how many threads call pthread_once() on it concurrently.
int	pthread_key_create (pthread_key_t key, void(destructor)(void *))
	Allocate a new thread-specific data key.
int	pthread_key_delete (pthread_key_t key)
	Free a thread-specific data key.
int	pthread_setspecific (pthread_key_t key, const void *value)
	Set the calling thread's value for key.
void *	pthread_getspecific (pthread_key_t key)
	Get the calling thread's value for key.

Detailed Description

Minimal POSIX-threads-style interface for SuperTinyKernel RTOS.

Macro Definition Documentation

◆ PTHREAD_BARRIER_SERIAL_THREAD

#define PTHREAD_BARRIER_SERIAL_THREAD (-1)

Returned by pthread_barrier_wait() to exactly one arbitrary caller per round; all others receive 0. See "pthread_barrier_wait() note" in the file-level docs.

Definition at line 339 of file stk_c_pthread.h.

Referenced by pthread_barrier_wait().

◆ PTHREAD_COND_INITIALIZER

#define PTHREAD_COND_INITIALIZER {0}

Definition at line 273 of file stk_c_pthread.h.

◆ PTHREAD_CREATE_DETACHED

#define PTHREAD_CREATE_DETACHED (1)

Definition at line 227 of file stk_c_pthread.h.

Referenced by pthread_attr_setdetachstate(), and pthread_create().

◆ PTHREAD_CREATE_JOINABLE

#define PTHREAD_CREATE_JOINABLE (0)

Definition at line 226 of file stk_c_pthread.h.

Referenced by pthread_attr_init(), and pthread_attr_setdetachstate().

◆ PTHREAD_DESTRUCTOR_ITERATIONS

#define PTHREAD_DESTRUCTOR_ITERATIONS (4)

Maximum number of passes over a finishing thread's keys made while destructors keep setting new non-NULL values for their own key. See "pthread_key_t / thread-specific data limitation" in the file-level docs.

Definition at line 373 of file stk_c_pthread.h.

Referenced by anonymous_namespace{stk_c_pthread.cpp}::RunKeyDestructors().

◆ PTHREAD_KEYS_MAX

#define PTHREAD_KEYS_MAX (STK_C_PTHREAD_KEYS_MAX)

POSIX-standard name for STK_C_PTHREAD_KEYS_MAX (this file).

Definition at line 365 of file stk_c_pthread.h.

◆ PTHREAD_MUTEX_DEFAULT

#define PTHREAD_MUTEX_DEFAULT (PTHREAD_MUTEX_NORMAL)

Definition at line 238 of file stk_c_pthread.h.

Referenced by pthread_mutexattr_init().

◆ PTHREAD_MUTEX_ERRORCHECK

#define PTHREAD_MUTEX_ERRORCHECK (1)

Definition at line 239 of file stk_c_pthread.h.

◆ PTHREAD_MUTEX_INITIALIZER

#define PTHREAD_MUTEX_INITIALIZER {0}

Definition at line 253 of file stk_c_pthread.h.

◆ PTHREAD_MUTEX_NORMAL

#define PTHREAD_MUTEX_NORMAL (0)

Definition at line 237 of file stk_c_pthread.h.

Referenced by pthread_mutex_init(), and pthread_mutexattr_settype().

◆ PTHREAD_MUTEX_RECURSIVE

#define PTHREAD_MUTEX_RECURSIVE (2)

Definition at line 240 of file stk_c_pthread.h.

◆ PTHREAD_ONCE_INIT

#define PTHREAD_ONCE_INIT {0}

Definition at line 354 of file stk_c_pthread.h.

◆ PTHREAD_PROCESS_PRIVATE

#define PTHREAD_PROCESS_PRIVATE (0)

Definition at line 301 of file stk_c_pthread.h.

Referenced by pthread_spin_init().

◆ PTHREAD_PROCESS_SHARED

#define PTHREAD_PROCESS_SHARED (1)

Definition at line 302 of file stk_c_pthread.h.

◆ PTHREAD_RWLOCK_INITIALIZER

#define PTHREAD_RWLOCK_INITIALIZER {0}

Definition at line 299 of file stk_c_pthread.h.

◆ STK_C_PTHREAD_DEFAULT_STACK_WORDS

#define STK_C_PTHREAD_DEFAULT_STACK_WORDS (1024U)

Default per-thread stack size in stk_word_t units, used when pthread_attr_t does not specify a stack size or an external stack (default: 1024 words).

Note: Threads created with this exact size are served from a static BlockMemoryPool (STK_C_PTHREAD_MAX_THREADS blocks, zero heap use). Any other requested size falls back to malloc().

Definition at line 173 of file stk_c_pthread.h.

◆ STK_C_PTHREAD_KEYS_MAX

#define STK_C_PTHREAD_KEYS_MAX (8U)

Maximum number of concurrently-alive pthread_key_t's (default: 8).

Note: Also exposed under the POSIX-standard name PTHREAD_KEYS_MAX.

Definition at line 189 of file stk_c_pthread.h.

Referenced by pthread_getspecific(), pthread_key_create(), pthread_key_delete(), pthread_setspecific(), and anonymous_namespace{stk_c_pthread.cpp}::RunKeyDestructors().

◆ STK_C_PTHREAD_MAX_THREADS

#define STK_C_PTHREAD_MAX_THREADS (8U)

Maximum number of concurrently-alive pthread_t's (default: 8).

Note: A thread stays "alive" from pthread_create() until its resources are reclaimed (by pthread_join(), or by the internal reaper for detached threads once they finish).

Definition at line 161 of file stk_c_pthread.h.

Referenced by anonymous_namespace{stk_c_pthread.cpp}::AcquireThreadSlot(), anonymous_namespace{stk_c_pthread.cpp}::DequeueReap(), anonymous_namespace{stk_c_pthread.cpp}::EnqueueReap(), anonymous_namespace{stk_c_pthread.cpp}::EnsureStackPool(), and anonymous_namespace{stk_c_pthread.cpp}::STK_BLOCKPOOL_STORAGE_DECL().

◆ STK_C_PTHREAD_REAPER_STACK_WORDS

#define STK_C_PTHREAD_REAPER_STACK_WORDS (256U)

Stack size (in stk_word_t units) for the internal reaper task that reclaims detached-thread resources (default: 256 words).

Definition at line 181 of file stk_c_pthread.h.

Referenced by anonymous_namespace{stk_c_pthread.cpp}::EnsureReaper().

Typedef Documentation

◆ pthread_attr_t

typedef struct pthread_attr_t pthread_attr_t

Thread creation attributes.

Note: Fields are considered private; use the pthread_attr_* accessors.

◆ pthread_barrier_t

typedef struct pthread_barrier_t pthread_barrier_t

A pthread barrier.

Note: Fields are considered private. No static-initializer macro (matching real POSIX) - pthread_barrier_init() must be called before use, since it is where the trip count is supplied.

◆ pthread_barrierattr_t

typedef struct pthread_barrierattr_t pthread_barrierattr_t

Barrier attributes (currently no settable properties).

◆ pthread_cond_t

typedef struct pthread_cond_t pthread_cond_t

A pthread condition variable.

Note: Fields are considered private. May be statically initialized with PTHREAD_COND_INITIALIZER, in which case the underlying STK condition variable is created lazily on first use.

◆ pthread_condattr_t

typedef struct pthread_condattr_t pthread_condattr_t

Condition variable attributes (currently no settable properties).

◆ pthread_key_t

typedef unsigned int pthread_key_t

A thread-specific data key.

Note: An index into an internal key table; there is no analogue to a NULL handle, so use pthread_key_create()'s return value to check success.

Definition at line 360 of file stk_c_pthread.h.

◆ pthread_mutex_t

typedef struct pthread_mutex_t pthread_mutex_t

A pthread mutex.

Note: Fields are considered private. May be statically initialized with PTHREAD_MUTEX_INITIALIZER, in which case the underlying STK mutex is created lazily on first use.

◆ pthread_mutexattr_t

typedef struct pthread_mutexattr_t pthread_mutexattr_t

Mutex attributes.

Note: Only PTHREAD_MUTEX_NORMAL / PTHREAD_MUTEX_DEFAULT are supported.

◆ pthread_once_t

typedef struct pthread_once_t pthread_once_t

A pthread_once() control object.

Note: Fields are considered private. Statically initialized with PTHREAD_ONCE_INIT; the guard mutex used to block concurrent callers is created lazily on first use. See "pthread_once() note" in the file-level docs.

◆ pthread_rwlock_t

typedef struct pthread_rwlock_t pthread_rwlock_t

A pthread read-write lock.

Note: Fields are considered private. May be statically initialized with PTHREAD_RWLOCK_INITIALIZER, in which case the underlying STK rwmutex is created lazily on first use.

See also: "pthread_rwlock_unlock() disambiguation" in the file-level docs regarding the __wrlocked field.

◆ pthread_rwlockattr_t

typedef struct pthread_rwlockattr_t pthread_rwlockattr_t

Read-write lock attributes (currently no settable properties).

Note: In particular there is no reader/writer preference setting; the underlying stk_rwmutex_t always applies a writer-preference policy (see stk_rwmutex_read_lock() in stk_c.h).

◆ pthread_spinlock_t

typedef struct pthread_spinlock_t pthread_spinlock_t

A pthread spinlock.

Note: Fields are considered private. Unlike the other pthread objects in this shim, spinlocks have no static-initializer macro (matching real POSIX) - pthread_spin_init() must be called before use.

See also: "pthread_spin_* recursion note" in the file-level docs.

◆ pthread_t

typedef struct pthread_stk_ctrl_t* pthread_t

Opaque thread handle.

Definition at line 214 of file stk_c_pthread.h.

Function Documentation

◆ pthread_attr_destroy()

int pthread_attr_destroy ( pthread_attr_t * attr )

Destroy a thread attributes object (no-op; no owned resources).

Definition at line 473 of file stk_c_pthread.cpp.

{
    if (attr == nullptr) { return EINVAL; }
    return 0;
}

◆ pthread_attr_getdetachstate()

int pthread_attr_getdetachstate	(	const pthread_attr_t *	attr,
		int *	detachstate )

Get the current detach-state setting.

Definition at line 526 of file stk_c_pthread.cpp.

{
    if ((attr == nullptr) || (detachstate == nullptr)) { return EINVAL; }
 
    *detachstate = attr->__detachstate;
    return 0;
}

References pthread_attr_t::__detachstate.

◆ pthread_attr_getstack()

int pthread_attr_getstack	(	const pthread_attr_t *	attr,
		void **	stackaddr,
		size_t *	stacksize )

Get the previously-set external stack (NULL/0 if none set).

Definition at line 505 of file stk_c_pthread.cpp.

{
    if ((attr == nullptr) || (stackaddr == nullptr) || (stacksize == nullptr)) { return EINVAL; }
 
    *stackaddr = attr->__ext_stack;
    *stacksize = attr->__stack_bytes;
    return 0;
}

References pthread_attr_t::__ext_stack, and pthread_attr_t::__stack_bytes.

◆ pthread_attr_getstacksize()

int pthread_attr_getstacksize	(	const pthread_attr_t *	attr,
		size_t *	stacksize )

Get the currently requested stack size in bytes (0 = default).

Definition at line 487 of file stk_c_pthread.cpp.

{
    if ((attr == nullptr) || (stacksize == nullptr)) { return EINVAL; }
 
    *stacksize = (attr->__stack_bytes != 0U) ? attr->__stack_bytes : kDefaultStackBytes;
    return 0;
}

References pthread_attr_t::__stack_bytes, and anonymous_namespace{stk_c_pthread.cpp}::kDefaultStackBytes.

◆ pthread_attr_init()

int pthread_attr_init ( pthread_attr_t * attr )

Initialize a thread attributes object with default values (default stack size, no external stack, joinable).

Definition at line 463 of file stk_c_pthread.cpp.

{
    if (attr == nullptr) { return EINVAL; }
 
    attr->__stack_bytes = 0U;
    attr->__ext_stack   = nullptr;
    attr->__detachstate = PTHREAD_CREATE_JOINABLE;
    return 0;
}

References pthread_attr_t::__detachstate, pthread_attr_t::__ext_stack, pthread_attr_t::__stack_bytes, and PTHREAD_CREATE_JOINABLE.

◆ pthread_attr_setdetachstate()

int pthread_attr_setdetachstate	(	pthread_attr_t *	attr,
		int	detachstate )

Set PTHREAD_CREATE_JOINABLE or PTHREAD_CREATE_DETACHED.

Definition at line 514 of file stk_c_pthread.cpp.

{
    if ((attr == nullptr) ||
        ((detachstate != PTHREAD_CREATE_JOINABLE) && (detachstate != PTHREAD_CREATE_DETACHED)))
    {
        return EINVAL;
    }
 
    attr->__detachstate = detachstate;
    return 0;
}

References pthread_attr_t::__detachstate, PTHREAD_CREATE_DETACHED, and PTHREAD_CREATE_JOINABLE.

◆ pthread_attr_setstack()

int pthread_attr_setstack	(	pthread_attr_t *	attr,
		void *	stackaddr,
		size_t	stacksize )

Supply an external, caller-owned stack buffer for the thread.

The buffer is never freed by this shim; the caller must keep it valid for the entire lifetime of the thread.

Parameters

[in]	stackaddr	Pointer to a stk_word_t-aligned buffer.
[in]	stacksize	Size of the buffer in bytes.

Definition at line 495 of file stk_c_pthread.cpp.

{
    if ((attr == nullptr) || (stackaddr == nullptr) || (stacksize < sizeof(stk_word_t))) { return EINVAL; }
    if ((reinterpret_cast<uintptr_t>(stackaddr) & STK_ALIGN_MASK) != 0U) { return EINVAL; }
 
    attr->__ext_stack   = static_cast<stk_word_t *>(stackaddr);
    attr->__stack_bytes = stacksize;
    return 0;
}

References pthread_attr_t::__ext_stack, pthread_attr_t::__stack_bytes, and STK_ALIGN_MASK.

◆ pthread_attr_setstacksize()

int pthread_attr_setstacksize	(	pthread_attr_t *	attr,
		size_t	stacksize )

Set the requested stack size in bytes.

Note: Only exactly STK_C_PTHREAD_DEFAULT_STACK_WORDS * sizeof(stk_word_t) bytes is served from the static pool; any other value falls back to malloc() at pthread_create() time.

Definition at line 479 of file stk_c_pthread.cpp.

{
    if ((attr == nullptr) || (stacksize == 0U)) { return EINVAL; }
 
    attr->__stack_bytes = stacksize;
    return 0;
}

References pthread_attr_t::__stack_bytes.

◆ pthread_barrier_destroy()

int pthread_barrier_destroy ( pthread_barrier_t * barrier )

Definition at line 1068 of file stk_c_pthread.cpp.

{
    if (barrier == nullptr) { return EINVAL; }
 
    if (barrier->__handle != nullptr)
    {
        stk_barrier_destroy(barrier->__handle);
        barrier->__handle = nullptr;
    }
    return 0;
}

References pthread_barrier_t::__handle, and stk_barrier_destroy().

Here is the call graph for this function:

◆ pthread_barrier_init()

int pthread_barrier_init	(	pthread_barrier_t *	barrier,
		const pthread_barrierattr_t *	attr,
		unsigned int	count )

Initialize a barrier for count participating threads.

Parameters

[in]	attr	Optional, or NULL for defaults (no settable properties).
[in]	count	Number of threads that must call pthread_barrier_wait() before any of them is released. Must not be 0.

Returns: 0 on success, EINVAL if count is 0, EAGAIN if the underlying STK barrier could not be created.

Definition at line 1057 of file stk_c_pthread.cpp.

{
    if (barrier == nullptr) { return EINVAL; }
    if (count == 0U) { return EINVAL; }
 
    barrier->__handle = stk_barrier_create(&barrier->__mem, sizeof(barrier->__mem),
                                            static_cast<uint32_t>(count));
    return (barrier->__handle != nullptr) ? 0 : EAGAIN;
}

References pthread_barrier_t::__handle, pthread_barrier_t::__mem, and stk_barrier_create().

Here is the call graph for this function:

◆ pthread_barrier_wait()

int pthread_barrier_wait ( pthread_barrier_t * barrier )

Block until count threads have called this function, then release them all together; the barrier resets for reuse.

Returns: PTHREAD_BARRIER_SERIAL_THREAD to exactly one arbitrary caller, 0 to the rest.

See also: "pthread_barrier_wait() note" in the file-level docs (ISR-unsafe).

Definition at line 1080 of file stk_c_pthread.cpp.

{
    if ((barrier == nullptr) || (barrier->__handle == nullptr)) { return EINVAL; }
 
    return stk_barrier_wait(barrier->__handle) ? PTHREAD_BARRIER_SERIAL_THREAD : 0;
}

References pthread_barrier_t::__handle, PTHREAD_BARRIER_SERIAL_THREAD, and stk_barrier_wait().

Here is the call graph for this function:

◆ pthread_barrierattr_destroy()

int pthread_barrierattr_destroy ( pthread_barrierattr_t * attr )

Definition at line 1051 of file stk_c_pthread.cpp.

{
    if (attr == nullptr) { return EINVAL; }
    return 0;
}

◆ pthread_barrierattr_init()

int pthread_barrierattr_init ( pthread_barrierattr_t * attr )

Definition at line 1043 of file stk_c_pthread.cpp.

{
    if (attr == nullptr) { return EINVAL; }
 
    attr->__reserved = 0;
    return 0;
}

References pthread_barrierattr_t::__reserved.

◆ pthread_cond_broadcast()

int pthread_cond_broadcast ( pthread_cond_t * cond )

Definition at line 874 of file stk_c_pthread.cpp.

{
    if (cond == nullptr) { return EINVAL; }
 
    stk_cv_notify_all(EnsureCond(cond));
    return 0;
}

References anonymous_namespace{stk_c_pthread.cpp}::EnsureCond(), and stk_cv_notify_all().

Here is the call graph for this function:

◆ pthread_cond_destroy()

int pthread_cond_destroy ( pthread_cond_t * cond )

Definition at line 835 of file stk_c_pthread.cpp.

{
    if (cond == nullptr) { return EINVAL; }
 
    if (cond->__handle != nullptr)
    {
        stk_cv_destroy(cond->__handle);
        cond->__handle = nullptr;
    }
    return 0;
}

References pthread_cond_t::__handle, and stk_cv_destroy().

Here is the call graph for this function:

◆ pthread_cond_init()

int pthread_cond_init	(	pthread_cond_t *	cond,
		const pthread_condattr_t *	attr )

Definition at line 827 of file stk_c_pthread.cpp.

{
    if (cond == nullptr) { return EINVAL; }
 
    cond->__handle = stk_cv_create(&cond->__mem, sizeof(cond->__mem));
    return (cond->__handle != nullptr) ? 0 : EAGAIN;
}

References pthread_cond_t::__handle, pthread_cond_t::__mem, and stk_cv_create().

Here is the call graph for this function:

◆ pthread_cond_signal()

int pthread_cond_signal ( pthread_cond_t * cond )

Definition at line 866 of file stk_c_pthread.cpp.

{
    if (cond == nullptr) { return EINVAL; }
 
    stk_cv_notify_one(EnsureCond(cond));
    return 0;
}

References anonymous_namespace{stk_c_pthread.cpp}::EnsureCond(), and stk_cv_notify_one().

Here is the call graph for this function:

◆ pthread_cond_timedwait()

int pthread_cond_timedwait	(	pthread_cond_t *	cond,
		pthread_mutex_t *	mutex,
		const struct timespec *	abstime )

As pthread_cond_wait(), with an absolute deadline.

Returns: 0 on success, ETIMEDOUT if the deadline passed first.

See also: "pthread_cond_timedwait() / pthread_mutex_timedlock() limitation" in the file-level docs regarding the meaning of abstime.

Definition at line 855 of file stk_c_pthread.cpp.

{
    if ((cond == nullptr) || (mutex == nullptr) || (mutex->__handle == nullptr) || (abstime == nullptr))
    {
        return EINVAL;
    }
 
    const bool signaled = stk_cv_wait(EnsureCond(cond), mutex->__handle, TimespecToRelativeTimeout(abstime));
    return signaled ? 0 : ETIMEDOUT;
}

References pthread_mutex_t::__handle, anonymous_namespace{stk_c_pthread.cpp}::EnsureCond(), stk_cv_wait(), and anonymous_namespace{stk_c_pthread.cpp}::TimespecToRelativeTimeout().

Here is the call graph for this function:

◆ pthread_cond_wait()

int pthread_cond_wait	(	pthread_cond_t *	cond,
		pthread_mutex_t *	mutex )

Atomically unlock mutex and wait for a signal; re-locks mutex before returning.

Definition at line 847 of file stk_c_pthread.cpp.

{
    if ((cond == nullptr) || (mutex == nullptr) || (mutex->__handle == nullptr)) { return EINVAL; }
 
    (void)stk_cv_wait(EnsureCond(cond), mutex->__handle, STK_WAIT_INFINITE);
    return 0;
}

References pthread_mutex_t::__handle, anonymous_namespace{stk_c_pthread.cpp}::EnsureCond(), stk_cv_wait(), and STK_WAIT_INFINITE.

Here is the call graph for this function:

◆ pthread_condattr_destroy()

int pthread_condattr_destroy ( pthread_condattr_t * attr )

Definition at line 821 of file stk_c_pthread.cpp.

{
    if (attr == nullptr) { return EINVAL; }
    return 0;
}

◆ pthread_condattr_init()

int pthread_condattr_init ( pthread_condattr_t * attr )

Definition at line 813 of file stk_c_pthread.cpp.

{
    if (attr == nullptr) { return EINVAL; }
 
    attr->__reserved = 0;
    return 0;
}

References pthread_condattr_t::__reserved.

◆ pthread_create()

int pthread_create	(	pthread_t *	thread,
		const pthread_attr_t *	attr,
		void (	start_routine )(void *),
		void *	arg )

Create and start a new thread.

Parameters

[out]	thread	Receives the new thread's handle on success.
[in]	attr	Optional attributes, or NULL for defaults.
[in]	start_routine	Thread entry function.
[in]	arg	Argument passed to start_routine.

Returns: 0 on success, or an errno-style error code: EINVAL - no kernel bound (see stk_pthread_bind_kernel()). EAGAIN - STK_C_PTHREAD_MAX_THREADS slots exhausted, stack allocation failed, or the underlying STK task could not be created.

Note: Requires the bound kernel to be KERNEL_DYNAMIC.

Definition at line 537 of file stk_c_pthread.cpp.

{
    STK_C_ASSERT(s_BoundKernel != nullptr);
    STK_C_ASSERT(thread != nullptr);
    STK_C_ASSERT(start_routine != nullptr);
 
    if ((s_BoundKernel == nullptr) || (thread == nullptr) || (start_routine == nullptr))
    {
        return EINVAL;
    }
 
    pthread_stk_ctrl_t *const ctrl = AcquireThreadSlot();
    if (ctrl == nullptr)
    {
        return EAGAIN;
    }
 
    const size_t stack_bytes = ((attr != nullptr) && (attr->__stack_bytes != 0U)) ?
        attr->__stack_bytes : kDefaultStackBytes;
    const uint32_t stack_words =
        static_cast<uint32_t>((stack_bytes + sizeof(stk_word_t) - 1U) / sizeof(stk_word_t));
 
    if ((attr != nullptr) && (attr->__ext_stack != nullptr))
    {
        ctrl->stack           = attr->__ext_stack;
        ctrl->stack_owned      = false;
        ctrl->stack_from_pool  = false;
    }
    else if (stack_bytes == kDefaultStackBytes)
    {
        stk_blockpool_t *const pool = EnsureStackPool();
        void *const blk = (pool != nullptr) ? stk_blockpool_try_alloc(pool) : nullptr;
        if (blk != nullptr)
        {
            ctrl->stack          = static_cast<stk_word_t *>(blk);
            ctrl->stack_owned     = true;
            ctrl->stack_from_pool = true;
        }
        else
        {
            ctrl->stack          = static_cast<stk_word_t *>(malloc(stack_bytes));
            ctrl->stack_owned     = true;
            ctrl->stack_from_pool = false;
        }
    }
    else
    {
        ctrl->stack          = static_cast<stk_word_t *>(malloc(stack_bytes));
        ctrl->stack_owned     = true;
        ctrl->stack_from_pool = false;
    }
 
    if (ctrl->stack == nullptr)
    {
        stk_critical_section_enter();
        ctrl->busy = false;
        stk_critical_section_exit();
        return EAGAIN;
    }
 
    ctrl->start_routine = start_routine;
    ctrl->arg            = arg;
    ctrl->retval          = nullptr;
    ctrl->detached        = ((attr != nullptr) && (attr->__detachstate == PTHREAD_CREATE_DETACHED));
 
    ctrl->done_event = stk_event_create(&ctrl->done_event_mem, sizeof(ctrl->done_event_mem),
                                        true /* manual_reset */);
 
    ctrl->task = stk_task_create_user(PthreadTrampoline, ctrl, ctrl->stack, stack_words);
    if (ctrl->task == nullptr)
    {
        if (ctrl->done_event != nullptr) { stk_event_destroy(ctrl->done_event); }
        if (ctrl->stack_owned)
        {
            if (ctrl->stack_from_pool) { (void)stk_blockpool_free(s_StackPool, ctrl->stack); }
            else                       { free(ctrl->stack); }
        }
        stk_critical_section_enter();
        ctrl->busy = false;
        stk_critical_section_exit();
        return EAGAIN;
    }
 
    EnsureReaper();
 
    stk_kernel_add_task(s_BoundKernel, ctrl->task);
 
    *thread = ctrl;
    return 0;
}

Here is the call graph for this function:

◆ pthread_detach()

int pthread_detach ( pthread_t thread )

Mark a thread as detached.

A detached thread's resources are reclaimed automatically (by an internal reaper task) once it finishes; it must not be joined.

Returns: 0 on success, EINVAL if thread is NULL, already joined, or already detached.

Definition at line 657 of file stk_c_pthread.cpp.

{
    pthread_stk_ctrl_t *const ctrl = thread;
    if (ctrl == nullptr) { return EINVAL; }
 
    bool ok = false;
    stk_critical_section_enter();
    if (!ctrl->joined && !ctrl->detached)
    {
        ctrl->detached = true;
        ok = true;
    }
    stk_critical_section_exit();
 
    if (!ok) { return EINVAL; }
 
    MaybeReap(ctrl);
    return 0;
}

References pthread_stk_ctrl_t::detached, pthread_stk_ctrl_t::joined, anonymous_namespace{stk_c_pthread.cpp}::MaybeReap(), stk_critical_section_enter(), and stk_critical_section_exit().

Here is the call graph for this function:

◆ pthread_equal()

int pthread_equal	(	pthread_t	t1,
		pthread_t	t2 )

Compare two thread handles for equality.

Definition at line 712 of file stk_c_pthread.cpp.

{
    return (t1 == t2) ? 1 : 0;
}

◆ pthread_exit()

void pthread_exit ( void * retval )

Terminate the calling thread.

Parameters

[in] retval Value made available to a joiner via pthread_join(), or discarded if the thread is detached.

Note: Does not return.

Definition at line 677 of file stk_c_pthread.cpp.

{
    pthread_stk_ctrl_t *const ctrl = static_cast<pthread_stk_ctrl_t *>(stk_tls_get());
 
    if (ctrl != nullptr)
    {
        RunKeyDestructors(ctrl);
 
        stk_critical_section_enter();
        ctrl->retval   = retval;
        ctrl->finished = true;
        stk_critical_section_exit();
 
        stk_event_set(ctrl->done_event);
        MaybeReap(ctrl);
 
        STK_C_ASSERT(s_BoundKernel != nullptr);
        stk_kernel_schedule_task_removal(s_BoundKernel, ctrl->task);
    }
 
    // Safety net: if the task is somehow still running past the removal request
    // (or ctrl was NULL, i.e. this wasn't called from a pthread_create()'d thread),
    // park here instead of falling back into caller code that isn't expecting to
    // regain control.
    for (;;)
    {
        stk_sleep(STK_WAIT_INFINITE);
    }
}

References pthread_stk_ctrl_t::done_event, pthread_stk_ctrl_t::finished, anonymous_namespace{stk_c_pthread.cpp}::MaybeReap(), pthread_stk_ctrl_t::retval, anonymous_namespace{stk_c_pthread.cpp}::RunKeyDestructors(), anonymous_namespace{stk_c_pthread.cpp}::s_BoundKernel, STK_C_ASSERT, stk_critical_section_enter(), stk_critical_section_exit(), stk_event_set(), stk_kernel_schedule_task_removal(), stk_sleep(), stk_tls_get(), STK_WAIT_INFINITE, and pthread_stk_ctrl_t::task.

Here is the call graph for this function:

◆ pthread_getspecific()

void * pthread_getspecific ( pthread_key_t key )

Get the calling thread's value for key.

Returns: The stored value, or NULL if key is invalid, no value has been set, or the calling task was not created via pthread_create().

Definition at line 1168 of file stk_c_pthread.cpp.

{
    if ((key >= STK_C_PTHREAD_KEYS_MAX) || !s_Keys[key].used) { return nullptr; }
 
    ThreadCtrl *const ctrl = static_cast<ThreadCtrl *>(stk_tls_get());
    if (ctrl == nullptr) { return nullptr; } // not a pthread_create()'d task; see file docs
 
    return ctrl->tsd[key];
}

References anonymous_namespace{stk_c_pthread.cpp}::s_Keys, STK_C_PTHREAD_KEYS_MAX, stk_tls_get(), and pthread_stk_ctrl_t::tsd.

Here is the call graph for this function:

◆ pthread_join()

int pthread_join	(	pthread_t	thread,
		void **	retval )

Block until the given joinable thread finishes, then reclaim its resources.

Parameters

[in]	thread	Thread to join.
[out]	retval	Optional; receives the thread's return value / the value passed to pthread_exit().

Returns: 0 on success, EINVAL if thread is NULL, already joined, or detached.

Definition at line 629 of file stk_c_pthread.cpp.

{
    pthread_stk_ctrl_t *const ctrl = thread;
    if (ctrl == nullptr) { return EINVAL; }
 
    bool ok = false;
    stk_critical_section_enter();
    if (!ctrl->detached && !ctrl->joined)
    {
        ctrl->joined = true;
        ok = true;
    }
    stk_critical_section_exit();
 
    if (!ok) { return EINVAL; }
 
    stk_event_wait(ctrl->done_event, STK_WAIT_INFINITE);
 
    if (retval != nullptr)
    {
        *retval = ctrl->retval;
    }
 
    WaitForTaskGone(ctrl->task);
    ReleaseThreadResources(ctrl);
    return 0;
}

References pthread_stk_ctrl_t::detached, pthread_stk_ctrl_t::done_event, pthread_stk_ctrl_t::joined, anonymous_namespace{stk_c_pthread.cpp}::ReleaseThreadResources(), pthread_stk_ctrl_t::retval, stk_critical_section_enter(), stk_critical_section_exit(), stk_event_wait(), STK_WAIT_INFINITE, pthread_stk_ctrl_t::task, and anonymous_namespace{stk_c_pthread.cpp}::WaitForTaskGone().

Here is the call graph for this function:

◆ pthread_key_create()

int pthread_key_create	(	pthread_key_t *	key,
		void(*	destructor )(void *) )

Allocate a new thread-specific data key.

Parameters

[out]	key	Receives the new key on success.
[in]	destructor	Optional; called with a thread's non-NULL value for this key when that thread finishes. May be NULL.

Returns: 0 on success, EINVAL if key is NULL, EAGAIN if STK_C_PTHREAD_KEYS_MAX slots are exhausted.

Definition at line 1116 of file stk_c_pthread.cpp.

{
    if (key == nullptr) { return EINVAL; }
 
    int result = EAGAIN;
 
    stk_critical_section_enter();
    for (std::size_t i = 0U; i < STK_C_PTHREAD_KEYS_MAX; ++i)
    {
        if (!s_Keys[i].used)
        {
            s_Keys[i].used       = true;
            s_Keys[i].destructor = destructor;
            *key                 = static_cast<pthread_key_t>(i);
            result               = 0;
            break;
        }
    }
    stk_critical_section_exit();
 
    return result;
}

References anonymous_namespace{stk_c_pthread.cpp}::KeyEntry::destructor, anonymous_namespace{stk_c_pthread.cpp}::s_Keys, STK_C_PTHREAD_KEYS_MAX, stk_critical_section_enter(), stk_critical_section_exit(), and anonymous_namespace{stk_c_pthread.cpp}::KeyEntry::used.

Here is the call graph for this function:

◆ pthread_key_delete()

int pthread_key_delete ( pthread_key_t key )

Free a thread-specific data key.

Does not run destructors and does not clear any thread's stored value for this key (matching POSIX); reusing a stale value after deletion is undefined behavior, as in real pthreads.

Returns: 0 on success, EINVAL if key was never created (or already deleted).

Definition at line 1139 of file stk_c_pthread.cpp.

{
    if (key >= STK_C_PTHREAD_KEYS_MAX) { return EINVAL; }
 
    int result = EINVAL;
 
    stk_critical_section_enter();
    if (s_Keys[key].used)
    {
        s_Keys[key].used       = false;
        s_Keys[key].destructor = nullptr;
        result                 = 0;
    }
    stk_critical_section_exit();
 
    return result;
}

References anonymous_namespace{stk_c_pthread.cpp}::KeyEntry::destructor, anonymous_namespace{stk_c_pthread.cpp}::s_Keys, STK_C_PTHREAD_KEYS_MAX, stk_critical_section_enter(), stk_critical_section_exit(), and anonymous_namespace{stk_c_pthread.cpp}::KeyEntry::used.

Here is the call graph for this function:

◆ pthread_mutex_destroy()

int pthread_mutex_destroy ( pthread_mutex_t * mutex )

Definition at line 766 of file stk_c_pthread.cpp.

{
    if (mutex == nullptr) { return EINVAL; }
 
    if (mutex->__handle != nullptr)
    {
        stk_mutex_destroy(mutex->__handle);
        mutex->__handle = nullptr;
    }
    return 0;
}

References pthread_mutex_t::__handle, and stk_mutex_destroy().

Here is the call graph for this function:

◆ pthread_mutex_init()

int pthread_mutex_init	(	pthread_mutex_t *	mutex,
		const pthread_mutexattr_t *	attr )

Initialize a mutex.

Parameters

[in] attr Optional, or NULL for defaults. Only NORMAL/DEFAULT type is supported; any other type returns ENOTSUP and leaves the mutex uninitialized.

Definition at line 757 of file stk_c_pthread.cpp.

{
    if (mutex == nullptr) { return EINVAL; }
    if ((attr != nullptr) && (attr->__type != PTHREAD_MUTEX_NORMAL)) { return ENOTSUP; }
 
    mutex->__handle = stk_mutex_create(&mutex->__mem, sizeof(mutex->__mem));
    return (mutex->__handle != nullptr) ? 0 : EAGAIN;
}

References pthread_mutex_t::__handle, pthread_mutex_t::__mem, pthread_mutexattr_t::__type, PTHREAD_MUTEX_NORMAL, and stk_mutex_create().

Here is the call graph for this function:

◆ pthread_mutex_lock()

int pthread_mutex_lock ( pthread_mutex_t * mutex )

Definition at line 778 of file stk_c_pthread.cpp.

{
    if (mutex == nullptr) { return EINVAL; }
 
    stk_mutex_lock(EnsureMutex(mutex));
    return 0;
}

References anonymous_namespace{stk_c_pthread.cpp}::EnsureMutex(), and stk_mutex_lock().

Here is the call graph for this function:

◆ pthread_mutex_timedlock()

int pthread_mutex_timedlock	(	pthread_mutex_t *	mutex,
		const struct timespec *	abstime )

Lock with an absolute deadline.

Returns: 0 on success, ETIMEDOUT if the deadline passed first.

See also: "pthread_cond_timedwait() / pthread_mutex_timedlock() limitation" in the file-level docs regarding the meaning of abstime.

Definition at line 802 of file stk_c_pthread.cpp.

{
    if ((mutex == nullptr) || (abstime == nullptr)) { return EINVAL; }
 
    const bool locked = stk_mutex_timed_lock(EnsureMutex(mutex), TimespecToRelativeTimeout(abstime));
    return locked ? 0 : ETIMEDOUT;
}

References anonymous_namespace{stk_c_pthread.cpp}::EnsureMutex(), stk_mutex_timed_lock(), and anonymous_namespace{stk_c_pthread.cpp}::TimespecToRelativeTimeout().

Here is the call graph for this function:

◆ pthread_mutex_trylock()

int pthread_mutex_trylock ( pthread_mutex_t * mutex )

Definition at line 786 of file stk_c_pthread.cpp.

{
    if (mutex == nullptr) { return EINVAL; }
 
    return stk_mutex_trylock(EnsureMutex(mutex)) ? 0 : EBUSY;
}

References anonymous_namespace{stk_c_pthread.cpp}::EnsureMutex(), and stk_mutex_trylock().

Here is the call graph for this function:

◆ pthread_mutex_unlock()

int pthread_mutex_unlock ( pthread_mutex_t * mutex )

Definition at line 793 of file stk_c_pthread.cpp.

{
    if (mutex == nullptr) { return EINVAL; }
    if (mutex->__handle == nullptr) { return EINVAL; }
 
    stk_mutex_unlock(mutex->__handle);
    return 0;
}

References pthread_mutex_t::__handle, and stk_mutex_unlock().

Here is the call graph for this function:

◆ pthread_mutexattr_destroy()

int pthread_mutexattr_destroy ( pthread_mutexattr_t * attr )

Definition at line 734 of file stk_c_pthread.cpp.

{
    if (attr == nullptr) { return EINVAL; }
    return 0;
}

◆ pthread_mutexattr_gettype()

int pthread_mutexattr_gettype	(	const pthread_mutexattr_t *	attr,
		int *	type )

Definition at line 749 of file stk_c_pthread.cpp.

{
    if ((attr == nullptr) || (type == nullptr)) { return EINVAL; }
 
    *type = attr->__type;
    return 0;
}

References pthread_mutexattr_t::__type.

◆ pthread_mutexattr_init()

int pthread_mutexattr_init ( pthread_mutexattr_t * attr )

Definition at line 726 of file stk_c_pthread.cpp.

{
    if (attr == nullptr) { return EINVAL; }
 
    attr->__type = PTHREAD_MUTEX_DEFAULT;
    return 0;
}

References pthread_mutexattr_t::__type, and PTHREAD_MUTEX_DEFAULT.

◆ pthread_mutexattr_settype()

int pthread_mutexattr_settype	(	pthread_mutexattr_t *	attr,
		int	type )

Set the mutex type.

Returns: 0 for PTHREAD_MUTEX_NORMAL/PTHREAD_MUTEX_DEFAULT, ENOTSUP for PTHREAD_MUTEX_RECURSIVE / PTHREAD_MUTEX_ERRORCHECK (not implemented).

Definition at line 740 of file stk_c_pthread.cpp.

{
    if (attr == nullptr) { return EINVAL; }
    if (type != PTHREAD_MUTEX_NORMAL) { return ENOTSUP; }
 
    attr->__type = type;
    return 0;
}

References pthread_mutexattr_t::__type, and PTHREAD_MUTEX_NORMAL.

◆ pthread_once()

int pthread_once	(	pthread_once_t *	once_control,
		void(*	init_routine )(void) )

Call init_routine exactly once for a given once_control, no matter how many threads call pthread_once() on it concurrently.

See also: "pthread_once() note" in the file-level docs.

Returns: 0 on success, EINVAL if once_control or init_routine is NULL.

Definition at line 1090 of file stk_c_pthread.cpp.

{
    if ((once_control == nullptr) || (init_routine == nullptr)) { return EINVAL; }
 
    if (once_control->__state == 2) { return 0; } // fast path: already done, no lock needed
 
    stk_mutex_t *const guard = EnsureOnceMutex(once_control);
    stk_mutex_lock(guard);
 
    // Re-check under the lock: another thread may have finished init_routine()
    // (or be running it right now, in which case this lock() call already blocked
    // until it was done) between our unlocked fast-path check above and here.
    if (once_control->__state != 2)
    {
        once_control->__state = 1;
        init_routine();
        once_control->__state = 2;
    }
 
    stk_mutex_unlock(guard);
    return 0;
}

References pthread_once_t::__state, anonymous_namespace{stk_c_pthread.cpp}::EnsureOnceMutex(), stk_mutex_lock(), and stk_mutex_unlock().

Here is the call graph for this function:

◆ pthread_rwlock_destroy()

int pthread_rwlock_destroy ( pthread_rwlock_t * rwlock )

Definition at line 908 of file stk_c_pthread.cpp.

{
    if (rwlock == nullptr) { return EINVAL; }
 
    if (rwlock->__handle != nullptr)
    {
        stk_rwmutex_destroy(rwlock->__handle);
        rwlock->__handle = nullptr;
    }
    return 0;
}

References pthread_rwlock_t::__handle, and stk_rwmutex_destroy().

Here is the call graph for this function:

◆ pthread_rwlock_init()

int pthread_rwlock_init	(	pthread_rwlock_t *	rwlock,
		const pthread_rwlockattr_t *	attr )

Initialize a read-write lock.

Parameters

[in] attr Optional, or NULL for defaults (no settable properties).

Definition at line 899 of file stk_c_pthread.cpp.

{
    if (rwlock == nullptr) { return EINVAL; }
 
    rwlock->__handle   = stk_rwmutex_create(&rwlock->__mem, sizeof(rwlock->__mem));
    rwlock->__wrlocked = false;
    return (rwlock->__handle != nullptr) ? 0 : EAGAIN;
}

References pthread_rwlock_t::__handle, pthread_rwlock_t::__mem, pthread_rwlock_t::__wrlocked, and stk_rwmutex_create().

Here is the call graph for this function:

◆ pthread_rwlock_rdlock()

int pthread_rwlock_rdlock ( pthread_rwlock_t * rwlock )

Acquire the lock for shared reading. Blocks until available.

Blocks if a writer is currently active or writers are waiting (writer-preference policy; see stk_rwmutex_read_lock() in stk_c.h).

Definition at line 920 of file stk_c_pthread.cpp.

{
    if (rwlock == nullptr) { return EINVAL; }
 
    stk_rwmutex_read_lock(EnsureRWLock(rwlock));
    return 0;
}

References anonymous_namespace{stk_c_pthread.cpp}::EnsureRWLock(), and stk_rwmutex_read_lock().

Here is the call graph for this function:

◆ pthread_rwlock_timedrdlock()

int pthread_rwlock_timedrdlock	(	pthread_rwlock_t *	rwlock,
		const struct timespec *	abstime )

Acquire the read lock with an absolute deadline.

Returns: 0 on success, ETIMEDOUT if the deadline passed first.

See also: "pthread_cond_timedwait() / pthread_mutex_timedlock() limitation" in the file-level docs regarding the meaning of abstime.

Definition at line 935 of file stk_c_pthread.cpp.

{
    if ((rwlock == nullptr) || (abstime == nullptr)) { return EINVAL; }
 
    const bool locked = stk_rwmutex_timed_read_lock(EnsureRWLock(rwlock), TimespecToRelativeTimeout(abstime));
    return locked ? 0 : ETIMEDOUT;
}

References anonymous_namespace{stk_c_pthread.cpp}::EnsureRWLock(), stk_rwmutex_timed_read_lock(), and anonymous_namespace{stk_c_pthread.cpp}::TimespecToRelativeTimeout().

Here is the call graph for this function:

◆ pthread_rwlock_timedwrlock()

int pthread_rwlock_timedwrlock	(	pthread_rwlock_t *	rwlock,
		const struct timespec *	abstime )

Acquire the write lock with an absolute deadline.

Returns: 0 on success, ETIMEDOUT if the deadline passed first.

See also: "pthread_cond_timedwait() / pthread_mutex_timedlock() limitation" in the file-level docs regarding the meaning of abstime.

Definition at line 962 of file stk_c_pthread.cpp.

{
    if ((rwlock == nullptr) || (abstime == nullptr)) { return EINVAL; }
 
    if (!stk_rwmutex_timed_lock(EnsureRWLock(rwlock), TimespecToRelativeTimeout(abstime))) { return ETIMEDOUT; }
 
    rwlock->__wrlocked = true;
    return 0;
}

References pthread_rwlock_t::__wrlocked, anonymous_namespace{stk_c_pthread.cpp}::EnsureRWLock(), stk_rwmutex_timed_lock(), and anonymous_namespace{stk_c_pthread.cpp}::TimespecToRelativeTimeout().

Here is the call graph for this function:

◆ pthread_rwlock_tryrdlock()

int pthread_rwlock_tryrdlock ( pthread_rwlock_t * rwlock )

Try to acquire the read lock without blocking.

Returns: 0 on success, EBUSY if a writer is active or waiting.

Definition at line 928 of file stk_c_pthread.cpp.

{
    if (rwlock == nullptr) { return EINVAL; }
 
    return stk_rwmutex_try_read_lock(EnsureRWLock(rwlock)) ? 0 : EBUSY;
}

References anonymous_namespace{stk_c_pthread.cpp}::EnsureRWLock(), and stk_rwmutex_try_read_lock().

Here is the call graph for this function:

◆ pthread_rwlock_trywrlock()

int pthread_rwlock_trywrlock ( pthread_rwlock_t * rwlock )

Try to acquire the write lock without blocking.

Returns: 0 on success, EBUSY otherwise.

Definition at line 952 of file stk_c_pthread.cpp.

{
    if (rwlock == nullptr) { return EINVAL; }
 
    if (!stk_rwmutex_trylock(EnsureRWLock(rwlock))) { return EBUSY; }
 
    rwlock->__wrlocked = true;
    return 0;
}

References pthread_rwlock_t::__wrlocked, anonymous_namespace{stk_c_pthread.cpp}::EnsureRWLock(), and stk_rwmutex_trylock().

Here is the call graph for this function:

◆ pthread_rwlock_unlock()

int pthread_rwlock_unlock ( pthread_rwlock_t * rwlock )

Release a read or write hold, whichever the calling thread holds.

See also: "pthread_rwlock_unlock() disambiguation" in the file-level docs.

Definition at line 972 of file stk_c_pthread.cpp.

{
    if (rwlock == nullptr) { return EINVAL; }
    if (rwlock->__handle == nullptr) { return EINVAL; }
 
    // See "pthread_rwlock_unlock() disambiguation" in stk_c_pthread.h: a write
    // hold is always exclusive, so __wrlocked unambiguously identifies which
    // underlying call the current holder must have made. Clear it before
    // releasing so a racing new writer's own acquisition can't be clobbered.
    if (rwlock->__wrlocked)
    {
        rwlock->__wrlocked = false;
        stk_rwmutex_unlock(rwlock->__handle);
    }
    else
    {
        stk_rwmutex_read_unlock(rwlock->__handle);
    }
    return 0;
}

References pthread_rwlock_t::__handle, pthread_rwlock_t::__wrlocked, stk_rwmutex_read_unlock(), and stk_rwmutex_unlock().

Here is the call graph for this function:

◆ pthread_rwlock_wrlock()

int pthread_rwlock_wrlock ( pthread_rwlock_t * rwlock )

Acquire the lock for exclusive writing. Blocks until available.

Blocks until all active readers have released their locks and no other writer is active.

Definition at line 943 of file stk_c_pthread.cpp.

{
    if (rwlock == nullptr) { return EINVAL; }
 
    stk_rwmutex_lock(EnsureRWLock(rwlock));
    rwlock->__wrlocked = true;
    return 0;
}

References pthread_rwlock_t::__wrlocked, anonymous_namespace{stk_c_pthread.cpp}::EnsureRWLock(), and stk_rwmutex_lock().

Here is the call graph for this function:

◆ pthread_rwlockattr_destroy()

int pthread_rwlockattr_destroy ( pthread_rwlockattr_t * attr )

Definition at line 893 of file stk_c_pthread.cpp.

{
    if (attr == nullptr) { return EINVAL; }
    return 0;
}

◆ pthread_rwlockattr_init()

int pthread_rwlockattr_init ( pthread_rwlockattr_t * attr )

Definition at line 885 of file stk_c_pthread.cpp.

{
    if (attr == nullptr) { return EINVAL; }
 
    attr->__reserved = 0;
    return 0;
}

References pthread_rwlockattr_t::__reserved.

◆ pthread_self()

pthread_t pthread_self ( void )

Return the calling thread's own handle.

Returns: A valid pthread_t for threads created via pthread_create(); NULL if called from a task that was not created through this shim (e.g. the application's original bootstrap task - see the file-level note).

Definition at line 707 of file stk_c_pthread.cpp.

{
    return static_cast<pthread_t>(stk_tls_get());
}

References stk_tls_get().

Here is the call graph for this function:

◆ pthread_setspecific()

int pthread_setspecific	(	pthread_key_t	key,
		const void *	value )

Set the calling thread's value for key.

See also: "pthread_key_t / thread-specific data limitation" in the file-level docs.

Returns: 0 on success, EINVAL if key is invalid or the calling task was not created via pthread_create().

Definition at line 1157 of file stk_c_pthread.cpp.

{
    if ((key >= STK_C_PTHREAD_KEYS_MAX) || !s_Keys[key].used) { return EINVAL; }
 
    ThreadCtrl *const ctrl = static_cast<ThreadCtrl *>(stk_tls_get());
    if (ctrl == nullptr) { return EINVAL; } // not a pthread_create()'d task; see file docs
 
    ctrl->tsd[key] = const_cast<void *>(value);
    return 0;
}

References anonymous_namespace{stk_c_pthread.cpp}::s_Keys, STK_C_PTHREAD_KEYS_MAX, stk_tls_get(), and pthread_stk_ctrl_t::tsd.

Here is the call graph for this function:

◆ pthread_spin_destroy()

int pthread_spin_destroy ( pthread_spinlock_t * lock )

Definition at line 1005 of file stk_c_pthread.cpp.

{
    if (lock == nullptr) { return EINVAL; }
 
    if (lock->__handle != nullptr)
    {
        stk_spinlock_destroy(lock->__handle);
        lock->__handle = nullptr;
    }
    return 0;
}

References pthread_spinlock_t::__handle, and stk_spinlock_destroy().

Here is the call graph for this function:

◆ pthread_spin_init()

int pthread_spin_init	(	pthread_spinlock_t *	lock,
		int	pshared )

Initialize a spinlock.

Parameters

[in] pshared Must be PTHREAD_PROCESS_PRIVATE.

Returns: 0 on success, ENOTSUP if pshared is PTHREAD_PROCESS_SHARED, EAGAIN if the underlying STK spinlock could not be created.

Definition at line 996 of file stk_c_pthread.cpp.

{
    if (lock == nullptr) { return EINVAL; }
    if (pshared != PTHREAD_PROCESS_PRIVATE) { return ENOTSUP; }
 
    lock->__handle = stk_spinlock_create(&lock->__mem, sizeof(lock->__mem));
    return (lock->__handle != nullptr) ? 0 : EAGAIN;
}

References pthread_spinlock_t::__handle, pthread_spinlock_t::__mem, PTHREAD_PROCESS_PRIVATE, and stk_spinlock_create().

Here is the call graph for this function:

◆ pthread_spin_lock()

int pthread_spin_lock ( pthread_spinlock_t * lock )

Acquire the spinlock, spinning until available.

See also: "pthread_spin_* recursion note" in the file-level docs.

Definition at line 1017 of file stk_c_pthread.cpp.

{
    if ((lock == nullptr) || (lock->__handle == nullptr)) { return EINVAL; }
 
    stk_spinlock_lock(lock->__handle);
    return 0;
}

References pthread_spinlock_t::__handle, and stk_spinlock_lock().

Here is the call graph for this function:

◆ pthread_spin_trylock()

int pthread_spin_trylock ( pthread_spinlock_t * lock )

Try to acquire the spinlock without blocking.

Returns: 0 on success, EBUSY if currently held.

Definition at line 1025 of file stk_c_pthread.cpp.

{
    if ((lock == nullptr) || (lock->__handle == nullptr)) { return EINVAL; }
 
    return stk_spinlock_trylock(lock->__handle) ? 0 : EBUSY;
}

References pthread_spinlock_t::__handle, and stk_spinlock_trylock().

Here is the call graph for this function:

◆ pthread_spin_unlock()

int pthread_spin_unlock ( pthread_spinlock_t * lock )

Definition at line 1032 of file stk_c_pthread.cpp.

{
    if ((lock == nullptr) || (lock->__handle == nullptr)) { return EINVAL; }
 
    stk_spinlock_unlock(lock->__handle);
    return 0;
}

References pthread_spinlock_t::__handle, and stk_spinlock_unlock().

Here is the call graph for this function:

◆ pthread_yield()

int pthread_yield ( void )

Voluntarily give up the CPU to another ready task (cooperative yield), then resume once rescheduled.

Returns: Always 0 (matches the non-standard GNU pthread_yield() signature; the underlying stk_yield() cannot fail).

Note: Non-standard - not in POSIX (POSIX uses sched_yield()), but widely available as a GNU/BSD extension under this name.

Definition at line 717 of file stk_c_pthread.cpp.

{
    stk_yield();
    return 0;
}

References stk_yield().

Here is the call graph for this function:

◆ stk_pthread_bind_kernel()

void stk_pthread_bind_kernel ( stk_kernel_t * kernel )

Bind the STK kernel instance that pthread_create() will add new threads to.

Must be called exactly once, before the first pthread_create() call. The kernel must already be created (stk_kernel_create()) and initialized (stk_kernel_init()); it does not need to be started yet, but in practice pthread_create() will only usefully run new threads once stk_kernel_start() has been called on it.

Parameters

[in] kernel Kernel handle obtained from stk_kernel_create(). Must be a KERNEL_DYNAMIC kernel (threads need to be able to finish/return).

Definition at line 453 of file stk_c_pthread.cpp.

{
    STK_C_ASSERT(kernel != nullptr);
 
    s_BoundKernel = kernel;
}

References anonymous_namespace{stk_c_pthread.cpp}::s_BoundKernel, and STK_C_ASSERT.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ PTHREAD_BARRIER_SERIAL_THREAD

◆ PTHREAD_COND_INITIALIZER

◆ PTHREAD_CREATE_DETACHED

◆ PTHREAD_CREATE_JOINABLE

◆ PTHREAD_DESTRUCTOR_ITERATIONS

◆ PTHREAD_KEYS_MAX

◆ PTHREAD_MUTEX_DEFAULT

◆ PTHREAD_MUTEX_ERRORCHECK

◆ PTHREAD_MUTEX_INITIALIZER

◆ PTHREAD_MUTEX_NORMAL

◆ PTHREAD_MUTEX_RECURSIVE

◆ PTHREAD_ONCE_INIT

◆ PTHREAD_PROCESS_PRIVATE

◆ PTHREAD_PROCESS_SHARED

◆ PTHREAD_RWLOCK_INITIALIZER

◆ STK_C_PTHREAD_DEFAULT_STACK_WORDS

◆ STK_C_PTHREAD_KEYS_MAX

◆ STK_C_PTHREAD_MAX_THREADS

◆ STK_C_PTHREAD_REAPER_STACK_WORDS

Typedef Documentation

◆ pthread_attr_t

◆ pthread_barrier_t

◆ pthread_barrierattr_t

◆ pthread_cond_t

◆ pthread_condattr_t

◆ pthread_key_t

◆ pthread_mutex_t

◆ pthread_mutexattr_t

◆ pthread_once_t

◆ pthread_rwlock_t

◆ pthread_rwlockattr_t

◆ pthread_spinlock_t

◆ pthread_t

Function Documentation

◆ pthread_attr_destroy()

◆ pthread_attr_getdetachstate()

◆ pthread_attr_getstack()

◆ pthread_attr_getstacksize()

◆ pthread_attr_init()

◆ pthread_attr_setdetachstate()

◆ pthread_attr_setstack()

◆ pthread_attr_setstacksize()

◆ pthread_barrier_destroy()

◆ pthread_barrier_init()

◆ pthread_barrier_wait()

◆ pthread_barrierattr_destroy()

◆ pthread_barrierattr_init()

◆ pthread_cond_broadcast()

◆ pthread_cond_destroy()

◆ pthread_cond_init()

◆ pthread_cond_signal()

◆ pthread_cond_timedwait()

◆ pthread_cond_wait()

◆ pthread_condattr_destroy()

◆ pthread_condattr_init()

◆ pthread_create()

◆ pthread_detach()

◆ pthread_equal()

◆ pthread_exit()

◆ pthread_getspecific()

◆ pthread_join()

◆ pthread_key_create()

◆ pthread_key_delete()

◆ pthread_mutex_destroy()

◆ pthread_mutex_init()

◆ pthread_mutex_lock()

◆ pthread_mutex_timedlock()

◆ pthread_mutex_trylock()

◆ pthread_mutex_unlock()

◆ pthread_mutexattr_destroy()

◆ pthread_mutexattr_gettype()

◆ pthread_mutexattr_init()

◆ pthread_mutexattr_settype()

◆ pthread_once()