STK C pthread-compatible API

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_VERSION   (0x20261004)
	Interface version.
#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_CREATE_USER_NP   (0)
#define	PTHREAD_CREATE_PRIVILEGED_NP   (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" 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 stack size in bytes that threads created with attr will use.
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 (stackaddr is NULL 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_attr_setprivileged_np (pthread_attr_t *attr, int mode)
	Non-portable: select the STK access mode of threads created with attr.
int	pthread_attr_getprivileged_np (const pthread_attr_t *attr, int *mode)
	Non-portable: get the access mode set in attr.
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)
	Initialize a mutex attributes object with default values (PTHREAD_MUTEX_DEFAULT).
int	pthread_mutexattr_destroy (pthread_mutexattr_t *attr)
	Destroy a mutex attributes object (no-op; no owned resources).
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)
	Get the mutex type stored in attr.
int	pthread_mutex_init (pthread_mutex_t *mutex, const pthread_mutexattr_t *attr)
	Initialize a mutex.
int	pthread_mutex_destroy (pthread_mutex_t *mutex)
	Destroy a mutex, releasing the underlying STK mutex object.
int	pthread_mutex_lock (pthread_mutex_t *mutex)
	Lock a mutex, blocking until it becomes available.
int	pthread_mutex_trylock (pthread_mutex_t *mutex)
	Try to lock a mutex without blocking.
int	pthread_mutex_unlock (pthread_mutex_t *mutex)
	Unlock a mutex held by the calling thread.
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)
	Initialize a condition variable attributes object (no settable properties).
int	pthread_condattr_destroy (pthread_condattr_t *attr)
	Destroy a condition variable attributes object (no-op).
int	pthread_cond_init (pthread_cond_t *cond, const pthread_condattr_t *attr)
	Initialize a condition variable.
int	pthread_cond_destroy (pthread_cond_t *cond)
	Destroy a condition variable, releasing the underlying STK object.
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)
	Wake one thread waiting on cond (no effect if none is waiting).
int	pthread_cond_broadcast (pthread_cond_t *cond)
	Wake all threads waiting on cond (no effect if none is waiting).
int	pthread_rwlockattr_init (pthread_rwlockattr_t *attr)
	Initialize a read-write lock attributes object (no settable properties).
int	pthread_rwlockattr_destroy (pthread_rwlockattr_t *attr)
	Destroy a read-write lock attributes object (no-op).
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)
	Destroy a read-write lock, releasing the underlying STK object.
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)
	Destroy a spinlock.
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)
	Release a spinlock held by the calling thread.
int	pthread_barrierattr_init (pthread_barrierattr_t *attr)
	Initialize a barrier attributes object (no settable properties).
int	pthread_barrierattr_destroy (pthread_barrierattr_t *attr)
	Destroy a barrier attributes object (no-op).
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)
	Destroy a barrier, releasing the underlying STK barrier object.
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 418 of file stk_c_pthread.h.

Referenced by pthread_barrier_wait(), and stk_pthread_compile_check().

PTHREAD_COND_INITIALIZER

#define PTHREAD_COND_INITIALIZER   {0}

Definition at line 350 of file stk_c_pthread.h.

PTHREAD_CREATE_DETACHED

#define PTHREAD_CREATE_DETACHED   (1)

Definition at line 287 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 286 of file stk_c_pthread.h.

Referenced by pthread_attr_init(), pthread_attr_setdetachstate(), and stk_pthread_compile_check().

PTHREAD_CREATE_PRIVILEGED_NP

#define PTHREAD_CREATE_PRIVILEGED_NP   (1)

Definition at line 294 of file stk_c_pthread.h.

Referenced by pthread_attr_setprivileged_np(), and pthread_create().

PTHREAD_CREATE_USER_NP

#define PTHREAD_CREATE_USER_NP   (0)

Definition at line 293 of file stk_c_pthread.h.

Referenced by pthread_attr_init(), pthread_attr_setprivileged_np(), and stk_pthread_compile_check().

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" in the file-level docs.

Definition at line 452 of file stk_c_pthread.h.

Referenced by stk::pthread::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 444 of file stk_c_pthread.h.

Referenced by stk_pthread_compile_check().

PTHREAD_MUTEX_DEFAULT

#define PTHREAD_MUTEX_DEFAULT   (PTHREAD_MUTEX_NORMAL)

Definition at line 314 of file stk_c_pthread.h.

Referenced by pthread_mutex_init(), and pthread_mutexattr_init().

PTHREAD_MUTEX_ERRORCHECK

#define PTHREAD_MUTEX_ERRORCHECK   (1)

Definition at line 315 of file stk_c_pthread.h.

Referenced by stk::pthread::IsValidMutexType(), stk::pthread::PreLockCheck(), pthread_cond_timedwait(), pthread_cond_wait(), and stk_pthread_compile_check().

PTHREAD_MUTEX_INITIALIZER

#define PTHREAD_MUTEX_INITIALIZER   {0}

Definition at line 330 of file stk_c_pthread.h.

PTHREAD_MUTEX_NORMAL

#define PTHREAD_MUTEX_NORMAL   (0)

Definition at line 313 of file stk_c_pthread.h.

Referenced by stk::pthread::IsValidMutexType().

PTHREAD_MUTEX_RECURSIVE

#define PTHREAD_MUTEX_RECURSIVE   (2)

Definition at line 316 of file stk_c_pthread.h.

Referenced by stk::pthread::IsValidMutexType(), and stk_pthread_compile_check().

PTHREAD_ONCE_INIT

#define PTHREAD_ONCE_INIT   {0}

Definition at line 433 of file stk_c_pthread.h.

PTHREAD_PROCESS_PRIVATE

#define PTHREAD_PROCESS_PRIVATE   (0)

Definition at line 378 of file stk_c_pthread.h.

Referenced by pthread_spin_init(), and stk_pthread_compile_check().

PTHREAD_PROCESS_SHARED

#define PTHREAD_PROCESS_SHARED   (1)

Definition at line 379 of file stk_c_pthread.h.

PTHREAD_RWLOCK_INITIALIZER

#define PTHREAD_RWLOCK_INITIALIZER   {0}

Definition at line 376 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 228 of file stk_c_pthread.h.

Referenced by stk_pthread_compile_check().

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 244 of file stk_c_pthread.h.

Referenced by stk::pthread::IsKeyUsed(), pthread_key_create(), pthread_key_delete(), pthread_stk_ctrl_t::Reset(), and stk::pthread::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). Tasks adopted via pthread_self() / pthread_setspecific() count against this limit permanently.

Definition at line 216 of file stk_c_pthread.h.

Referenced by stk::pthread::AcquireThreadSlot(), stk::pthread::DequeueReap(), stk::pthread::EnqueueReap(), stk::pthread::EnsureStackPool(), and stk::pthread::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 236 of file stk_c_pthread.h.

Referenced by stk::pthread::EnsureReaper().

STK_C_PTHREAD_VERSION

#define STK_C_PTHREAD_VERSION   (0x20261004)

Interface version.

Definition at line 202 of file stk_c_pthread.h.

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 439 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

PTHREAD_MUTEX_NORMAL / DEFAULT, PTHREAD_MUTEX_RECURSIVE and PTHREAD_MUTEX_ERRORCHECK are supported. The underlying stk::sync::Mutex is always recursive, so PTHREAD_MUTEX_NORMAL behaves like PTHREAD_MUTEX_RECURSIVE (POSIX leaves relocking a NORMAL mutex undefined, so this is conforming). Behavior per type:

• NORMAL/DEFAULT, RECURSIVE: relocking by the owner succeeds and must be balanced by the same number of unlocks (maximum depth stk::sync::Mutex::RECURSION_MAX, then EAGAIN).
• ERRORCHECK: relocking by the owner returns EDEADLK (trylock: EBUSY).
• all types: unlocking a mutex not owned by the caller returns EPERM.

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 RWMutex::TimedReadLock()).

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_* note" in the file-level docs.

pthread_t

typedef struct pthread_stk_ctrl_t* pthread_t

Opaque thread handle.

Definition at line 273 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).

Parameters

[in]

attr

Attributes object to destroy.

Definition at line 777 of file stk_c_pthread.cpp.

{
    return (attr != nullptr) ? 0 : EINVAL;
}

Referenced by stk_pthread_compile_check().

Here is the caller graph for this function:

pthread_attr_getdetachstate()

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

Get the current detach-state setting.

Parameters

[in]	attr	Attributes object to query.
[out]	detachstate	Receives PTHREAD_CREATE_JOINABLE or PTHREAD_CREATE_DETACHED.

Definition at line 853 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((attr != nullptr) && (detachstate != nullptr))
    {
        *detachstate = attr->__detachstate;
        result = 0;
    }
 
    return result;
}

References pthread_attr_t::__detachstate.

pthread_attr_getprivileged_np()

int pthread_attr_getprivileged_np	(	const pthread_attr_t *	attr,
		int *	mode )

Non-portable: get the access mode set in attr.

Parameters

[in]	attr	Attributes object to query.
[out]	mode	Receives PTHREAD_CREATE_USER_NP or PTHREAD_CREATE_PRIVILEGED_NP.

Definition at line 880 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((attr != nullptr) && (mode != nullptr))
    {
        *mode = attr->__privileged;
        result = 0;
    }
 
    return result;
}

References pthread_attr_t::__privileged.

Referenced by stk_pthread_compile_check().

Here is the caller graph for this function:

pthread_attr_getstack()

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

Get the previously-set external stack (stackaddr is NULL if none set).

Parameters

[in]	attr	Attributes object to query.
[out]	stackaddr	Receives the external stack address, or NULL if none was set.
[out]	stacksize	Receives the configured stack size in bytes (0 if no size was set).

Definition at line 825 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((attr != nullptr) && (stackaddr != nullptr) && (stacksize != nullptr))
    {
        *stackaddr = attr->__ext_stack;
        *stacksize = attr->__stack_bytes;
        result = 0;
    }
 
    return result;
}

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 stack size in bytes that threads created with attr will use.

If no size was set, reports STK_C_PTHREAD_DEFAULT_STACK_WORDS * sizeof(stk_word_t).

Parameters

[in]	attr	Attributes object to query.
[out]	stacksize	Receives the stack size in bytes (the default size if none was set).

Definition at line 795 of file stk_c_pthread.cpp.

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

References pthread_attr_t::__stack_bytes, and stk::pthread::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).

Parameters

[out]

attr

Attributes object to initialize.

Definition at line 761 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (attr != nullptr)
    {
        attr->__stack_bytes = 0U;
        attr->__ext_stack   = nullptr;
        attr->__detachstate = PTHREAD_CREATE_JOINABLE;
        attr->__privileged  = PTHREAD_CREATE_USER_NP;
        result = 0;
    }
 
    return result;
}

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

Referenced by stk_pthread_compile_check().

Here is the caller graph for this function:

pthread_attr_setdetachstate()

int pthread_attr_setdetachstate	(	pthread_attr_t *	attr,
		int	detachstate )

Set PTHREAD_CREATE_JOINABLE or PTHREAD_CREATE_DETACHED.

Parameters

[in,out]	attr	Attributes object to modify.
[in]	detachstate	PTHREAD_CREATE_JOINABLE or PTHREAD_CREATE_DETACHED.

Definition at line 839 of file stk_c_pthread.cpp.

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

References pthread_attr_t::__detachstate, PTHREAD_CREATE_DETACHED, and PTHREAD_CREATE_JOINABLE.

Referenced by stk_pthread_compile_check().

Here is the caller graph for this function:

pthread_attr_setprivileged_np()

int pthread_attr_setprivileged_np	(	pthread_attr_t *	attr,
		int	mode )

Non-portable: select the STK access mode of threads created with attr.

PTHREAD_CREATE_USER_NP (default) creates the thread via stk_task_create_user(); PTHREAD_CREATE_PRIVILEGED_NP via stk_task_create_privileged() (needed e.g. for direct GPIO/peripheral access on some MCUs).

Parameters

[in,out]	attr	Attributes object to modify.
[in]	mode	PTHREAD_CREATE_USER_NP or PTHREAD_CREATE_PRIVILEGED_NP.

Returns

0 on success, EINVAL on NULL attr or unknown mode.

Definition at line 866 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((attr != nullptr) &&
        ((mode == PTHREAD_CREATE_USER_NP) || (mode == PTHREAD_CREATE_PRIVILEGED_NP)))
    {
        attr->__privileged = mode;
        result = 0;
    }
 
    return result;
}

References pthread_attr_t::__privileged, PTHREAD_CREATE_PRIVILEGED_NP, and PTHREAD_CREATE_USER_NP.

Referenced by stk_pthread_compile_check().

Here is the caller graph for this function:

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,out]	attr	Attributes object to modify.
[in]	stackaddr	Pointer to a stk_word_t-aligned buffer.
[in]	stacksize	Size of the buffer in bytes.

Definition at line 808 of file stk_c_pthread.cpp.

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

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.

Parameters

[in,out]	attr	Attributes object to modify.
[in]	stacksize	Requested stack size in bytes. Must not be 0.

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 782 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((attr != nullptr) && (stacksize != 0U))
    {
        attr->__stack_bytes = stacksize;
        result = 0;
    }
 
    return result;
}

References pthread_attr_t::__stack_bytes.

Referenced by stk_pthread_compile_check().

Here is the caller graph for this function:

pthread_barrier_destroy()

int pthread_barrier_destroy

(

pthread_barrier_t *

barrier

)

Destroy a barrier, releasing the underlying STK barrier object.

No thread may be blocked in pthread_barrier_wait() on it. After destruction it must be re-initialized with pthread_barrier_init() before further use.

Parameters

[in,out]

barrier

Barrier to destroy.

Returns

0 on success, EINVAL if barrier is NULL.

Definition at line 1648 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (barrier != nullptr)
    {
        if (barrier->__handle != nullptr)
        {
            HandleOf(barrier)->~Barrier();
            barrier->__handle = nullptr;
        }
        result = 0;
    }
 
    return result;
}

References pthread_barrier_t::__handle, and stk::pthread::HandleOf().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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

[out]	barrier	Barrier to initialize.
[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 1634 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((barrier != nullptr) && (count != 0U))
    {
        barrier->__handle = ConstructIn<stk::sync::Barrier>(barrier->__mem, static_cast<uint32_t>(count));
        result = 0;
    }
 
    return result;
}

References pthread_barrier_t::__handle, pthread_barrier_t::__mem, and stk::ConstructIn().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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.

Parameters

[in,out]

barrier

Barrier to wait on.

Returns

PTHREAD_BARRIER_SERIAL_THREAD to exactly one arbitrary caller, 0 to the rest, EINVAL if barrier is NULL or was never initialized.

See also

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

Definition at line 1665 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((barrier != nullptr) && (barrier->__handle != nullptr))
    {
        result = HandleOf(barrier)->Wait() ? PTHREAD_BARRIER_SERIAL_THREAD : 0;
    }
 
    return result;
}

References pthread_barrier_t::__handle, stk::pthread::HandleOf(), and PTHREAD_BARRIER_SERIAL_THREAD.

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_barrierattr_destroy()

int pthread_barrierattr_destroy

(

pthread_barrierattr_t *

attr

)

Destroy a barrier attributes object (no-op).

Parameters

[in]

attr

Attributes object to destroy.

Returns

0 on success, EINVAL if attr is NULL.

Definition at line 1629 of file stk_c_pthread.cpp.

{
    return (attr != nullptr) ? 0 : EINVAL;
}

pthread_barrierattr_init()

int pthread_barrierattr_init

(

pthread_barrierattr_t *

attr

)

Initialize a barrier attributes object (no settable properties).

Parameters

[out]

attr

Attributes object to initialize.

Returns

0 on success, EINVAL if attr is NULL.

Definition at line 1616 of file stk_c_pthread.cpp.

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

References pthread_barrierattr_t::__reserved.

pthread_cond_broadcast()

int pthread_cond_broadcast

(

pthread_cond_t *

cond

)

Wake all threads waiting on cond (no effect if none is waiting).

Parameters

[in,out]

cond

Condition variable to broadcast.

Returns

0 on success, EINVAL if cond is NULL.

Definition at line 1353 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (cond != nullptr)
    {
        EnsureCond(cond)->NotifyAll();
        result = 0;
    }
 
    return result;
}

References stk::pthread::EnsureCond(), and stk::sync::ConditionVariable::NotifyAll().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_cond_destroy()

int pthread_cond_destroy

(

pthread_cond_t *

cond

)

Destroy a condition variable, releasing the underlying STK object.

Safe on a never-used PTHREAD_COND_INITIALIZER object. No thread may be waiting on it; destroying a condition variable in use is undefined behavior.

Parameters

[in,out]

cond

Condition variable to destroy.

Returns

0 on success, EINVAL if cond is NULL.

Definition at line 1282 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (cond != nullptr)
    {
        if (cond->__handle != nullptr)
        {
            HandleOf(cond)->~ConditionVariable();
            cond->__handle = nullptr;
        }
        result = 0;
    }
 
    return result;
}

References pthread_cond_t::__handle, and stk::pthread::HandleOf().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_cond_init()

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

Initialize a condition variable.

Parameters

[out]	cond	Condition variable to initialize.
[in]	attr	Optional, or NULL for defaults (no settable properties; the argument is ignored).

Returns

0 on success, EINVAL if cond is NULL.

Definition at line 1269 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (cond != nullptr)
    {
        cond->__handle = ConstructIn<stk::sync::ConditionVariable>(cond->__mem);
        result = 0;
    }
 
    return result;
}

References pthread_cond_t::__handle, pthread_cond_t::__mem, and stk::ConstructIn().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_cond_signal()

int pthread_cond_signal

(

pthread_cond_t *

cond

)

Wake one thread waiting on cond (no effect if none is waiting).

The condition variable is created lazily if needed. Signals are not queued: a signal sent while nobody waits is lost.

Parameters

[in,out]

cond

Condition variable to signal.

Returns

0 on success, EINVAL if cond is NULL.

Definition at line 1340 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (cond != nullptr)
    {
        EnsureCond(cond)->NotifyOne();
        result = 0;
    }
 
    return result;
}

References stk::pthread::EnsureCond(), and stk::sync::ConditionVariable::NotifyOne().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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.

mutex is re-locked before returning in all cases, including on timeout.

Parameters

[in,out]	cond	Condition variable to wait on.
[in,out]	mutex	Mutex protecting the predicate; must be locked by the caller. It is released while waiting and re-locked before returning.
[in]	abstime	Absolute deadline on the stk_time_now_ms() timeline (not CLOCK_REALTIME); see the file-level docs.

Returns

0 on success, ETIMEDOUT if the deadline passed first, EINVAL if cond, mutex or abstime is NULL, or mutex has never been initialized/locked.

See also

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

Definition at line 1319 of file stk_c_pthread.cpp.

{
    int result = 0;
 
    if ((cond == nullptr) || (mutex == nullptr) || (mutex->__handle == nullptr) || (abstime == nullptr))
    {
        result = EINVAL;
    }
    else if ((mutex->__type == PTHREAD_MUTEX_ERRORCHECK) && !IsMutexOwner(HandleOf(mutex)))
    {
        result = EPERM;
    }
    else
    {
        const bool signaled = EnsureCond(cond)->Wait(*HandleOf(mutex), TimespecToRelativeTimeout(abstime));
        result = signaled ? 0 : ETIMEDOUT;
    }
 
    return result;
}

References pthread_mutex_t::__handle, pthread_mutex_t::__type, stk::pthread::EnsureCond(), stk::pthread::HandleOf(), stk::pthread::IsMutexOwner(), PTHREAD_MUTEX_ERRORCHECK, stk::pthread::TimespecToRelativeTimeout(), and stk::sync::ConditionVariable::Wait().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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.

Waits without a timeout. As in POSIX, spurious wakeups are possible, so always re-check the predicate in a loop. mutex must be locked by the caller and must have been used or initialized before (its underlying STK mutex must exist). Must not be called from ISR context.

Parameters

[in,out]	cond	Condition variable to wait on.
[in,out]	mutex	Mutex protecting the predicate; must be locked by the caller. It is released while waiting and re-locked before returning.

Note

mutex must be held exactly once. Waiting on a NORMAL/RECURSIVE mutex locked more than once is undefined (as in POSIX): only one level is released, so other threads cannot acquire it.

Returns

0 on success, EPERM (ERRORCHECK, mutex not owned by the caller), EINVAL if cond or mutex is NULL, or mutex has never been initialized/locked.

Definition at line 1299 of file stk_c_pthread.cpp.

{
    int result = 0;
 
    if ((cond == nullptr) || (mutex == nullptr) || (mutex->__handle == nullptr))
    {
        result = EINVAL;
    }
    else if ((mutex->__type == PTHREAD_MUTEX_ERRORCHECK) && !IsMutexOwner(HandleOf(mutex)))
    {
        result = EPERM;
    }
    else
    {
        (void)EnsureCond(cond)->Wait(*HandleOf(mutex)); // WAIT_INFINITE
    }
 
    return result;
}

References pthread_mutex_t::__handle, pthread_mutex_t::__type, stk::pthread::EnsureCond(), stk::pthread::HandleOf(), stk::pthread::IsMutexOwner(), PTHREAD_MUTEX_ERRORCHECK, and stk::sync::ConditionVariable::Wait().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_condattr_destroy()

int pthread_condattr_destroy

(

pthread_condattr_t *

attr

)

Destroy a condition variable attributes object (no-op).

Parameters

[in]

attr

Attributes object to destroy.

Returns

0 on success, EINVAL if attr is NULL.

Definition at line 1264 of file stk_c_pthread.cpp.

{
    return (attr != nullptr) ? 0 : EINVAL;
}

pthread_condattr_init()

int pthread_condattr_init

(

pthread_condattr_t *

attr

)

Initialize a condition variable attributes object (no settable properties).

Parameters

[out]

attr

Attributes object to initialize.

Returns

0 on success, EINVAL if attr is NULL.

Definition at line 1251 of file stk_c_pthread.cpp.

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

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 a bound kernel whose type includes KERNEL_DYNAMIC and KERNEL_SYNC (see the file-level docs).

Definition at line 896 of file stk_c_pthread.cpp.

{
    STK_C_ASSERT(s_BoundKernel != nullptr);
    STK_C_ASSERT(thread != nullptr);
    STK_C_ASSERT(start_routine != nullptr);
 
    int result = 0;
 
    if ((s_BoundKernel == nullptr) || (thread == nullptr) || (start_routine == nullptr))
    {
        result = EINVAL;
    }
    else
    {
        pthread_stk_ctrl_t *const ctrl = AcquireThreadSlot();
 
        if (ctrl == nullptr)
        {
            result = EAGAIN;
        }
        else
        {
            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 (!AllocateStack(ctrl, attr, stack_bytes))
            {
                {
                    const CsLock cs_;
 
                    ctrl->busy = false;
                }
                result = EAGAIN;
            }
            else
            {
                ctrl->start_routine = start_routine;
                ctrl->arg           = arg;
                ctrl->retval        = nullptr;
                ctrl->detached      = ((attr != nullptr) && (attr->__detachstate == PTHREAD_CREATE_DETACHED));
                ctrl->done_event    = ConstructIn<sync::Event>(ctrl->done_event_buf, true /* manual_reset */);
 
                const bool privileged = (attr != nullptr) && (attr->__privileged == PTHREAD_CREATE_PRIVILEGED_NP);
 
                ctrl->task.Initialize(ctrl, ctrl->stack, stack_words,
                                      privileged ? stk::ACCESS_PRIVILEGED : stk::ACCESS_USER);
 
                ToKernel(s_BoundKernel)->AddTask(&ctrl->task);
 
                *thread = ctrl;
            }
        }
    }
 
    return result;
}

References pthread_attr_t::__detachstate, pthread_attr_t::__privileged, pthread_attr_t::__stack_bytes, stk::ACCESS_PRIVILEGED, stk::ACCESS_USER, stk::pthread::AcquireThreadSlot(), stk::IKernel::AddTask(), stk::pthread::AllocateStack(), pthread_stk_ctrl_t::arg, pthread_stk_ctrl_t::busy, stk::ConstructIn(), pthread_stk_ctrl_t::detached, pthread_stk_ctrl_t::done_event, pthread_stk_ctrl_t::done_event_buf, stk::pthread::PthreadTask::Initialize(), stk::pthread::kDefaultStackBytes, PTHREAD_CREATE_DETACHED, PTHREAD_CREATE_PRIVILEGED_NP, pthread_stk_ctrl_t::retval, stk::pthread::s_BoundKernel, pthread_stk_ctrl_t::stack, pthread_stk_ctrl_t::start_routine, STK_C_ASSERT, pthread_stk_ctrl_t::task, and stk::pthread::ToKernel().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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.

Parameters

[in]

thread

Thread to detach, as returned by pthread_create().

Returns

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

Definition at line 1003 of file stk_c_pthread.cpp.

{
    pthread_stk_ctrl_t *const ctrl = thread;
    int result = 0;
 
    if (ctrl == nullptr)
    {
        result = EINVAL;
    }
    else
    {
        bool ok = false;
        {
            const CsLock cs_;
 
            if (!ctrl->joined && !ctrl->detached)
            {
                ctrl->detached = true;
                ok = true;
            }
        }
 
        if (!ok)
        {
            result = EINVAL;
        }
        else
        {
            MaybeReap(ctrl);
        }
    }
 
    return result;
}

References pthread_stk_ctrl_t::detached, pthread_stk_ctrl_t::joined, and stk::pthread::MaybeReap().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_equal()

int pthread_equal	(	pthread_t	t1,
		pthread_t	t2 )

Compare two thread handles for equality.

Parameters

[in]	t1	First thread handle.
[in]	t2	Second thread handle.

Definition at line 1078 of file stk_c_pthread.cpp.

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

Referenced by stk_pthread_compile_check().

Here is the caller graph for this function:

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. For an adopted task (see "pthread_self() and foreign tasks") only the key destructors run and the task then parks forever.

Definition at line 1038 of file stk_c_pthread.cpp.

{
    pthread_stk_ctrl_t *const ctrl = CurrentCtrl();
 
    if (ctrl != nullptr)
    {
        RunKeyDestructors(ctrl);
 
        // An adopted (foreign) task has no ITask we could ask the kernel to remove, so for
        // it pthread_exit() only runs the destructors and then parks (see below).
        if (!ctrl->adopted)
        {
            {
                const CsLock cs_;
 
                ctrl->retval   = retval;
                ctrl->finished = true;
            }
 
            (void)ctrl->done_event->Set();
            MaybeReap(ctrl); // reaper/joiner will wait for ctrl->exited before freeing anything
 
            STK_C_ASSERT(s_BoundKernel != nullptr);
            ToKernel(s_BoundKernel)->ScheduleTaskRemoval(&ctrl->task);
        }
    }
 
    // Park here instead of falling back into caller code that isn't expecting to
    // regain control (the removal above takes effect on the next scheduling round).
    for (;;)
    {
        stk::Sleep(stk::WAIT_INFINITE);
    }
}

References pthread_stk_ctrl_t::adopted, stk::pthread::CurrentCtrl(), pthread_stk_ctrl_t::done_event, pthread_stk_ctrl_t::finished, stk::pthread::MaybeReap(), pthread_stk_ctrl_t::retval, stk::pthread::RunKeyDestructors(), stk::pthread::s_BoundKernel, stk::IKernel::ScheduleTaskRemoval(), stk::sync::Event::Set(), stk::Sleep(), STK_C_ASSERT, pthread_stk_ctrl_t::task, stk::pthread::ToKernel(), and stk::WAIT_INFINITE.

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_getspecific()

void * pthread_getspecific

(

pthread_key_t

key

)

Get the calling thread's value for key.

Parameters

[in]

key

Key to read the calling thread's value for.

Returns

The stored value, or NULL if key is invalid or the calling thread has not set a value for it (never adopts a foreign task).

Definition at line 1794 of file stk_c_pthread.cpp.

{
    void *result = nullptr;
 
    if (IsKeyUsed(key))
    {
        ThreadCtrl *const ctrl = CurrentCtrl(); // no adoption: a task that never called setspecific() has no values
 
        if (ctrl != nullptr)
        {
            result = ctrl->tsd[key];
        }
    }
 
    return result;
}

References stk::pthread::CurrentCtrl(), stk::pthread::IsKeyUsed(), and pthread_stk_ctrl_t::tsd.

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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, detached or adopted, EDEADLK if thread is the calling thread.

Definition at line 956 of file stk_c_pthread.cpp.

{
    pthread_stk_ctrl_t *const ctrl = thread;
    int result = 0;
 
    if (ctrl == nullptr)
    {
        result = EINVAL;
    }
    else if (ctrl == CurrentCtrl())
    {
        result = EDEADLK; // joining yourself would wait forever
    }
    else
    {
        bool ok = false;
        {
            const CsLock cs_;
 
            if (!ctrl->detached && !ctrl->joined)
            {
                ctrl->joined = true;
                ok = true;
            }
        }
 
        if (!ok)
        {
            result = EINVAL;
        }
        else
        {
            (void)ctrl->done_event->Wait(); // WAIT_INFINITE
 
            if (retval != nullptr)
            {
                *retval = ctrl->retval;
            }
 
            WaitForTaskExit(ctrl);
            ReleaseThreadResources(ctrl);
        }
    }
 
    return result;
}

References stk::pthread::CurrentCtrl(), pthread_stk_ctrl_t::detached, pthread_stk_ctrl_t::done_event, pthread_stk_ctrl_t::joined, stk::pthread::ReleaseThreadResources(), pthread_stk_ctrl_t::retval, stk::sync::Event::Wait(), and stk::pthread::WaitForTaskExit().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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 1728 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (key != nullptr)
    {
        result = EAGAIN;
 
        const CsLock cs_;
 
        for (std::size_t i = 0U; (result != 0) && (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;
            }
        }
    }
 
    return result;
}

References stk::pthread::s_Keys, and STK_C_PTHREAD_KEYS_MAX.

Referenced by stk_pthread_compile_check().

Here is the caller 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.

Parameters

[in]

key

Key to delete, as returned by pthread_key_create().

Returns

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

Definition at line 1753 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (key < STK_C_PTHREAD_KEYS_MAX)
    {
        const CsLock cs_;
 
        if (s_Keys[key].used)
        {
            s_Keys[key].used       = false;
            s_Keys[key].destructor = nullptr;
            result                 = 0;
        }
    }
 
    return result;
}

References stk::pthread::s_Keys, and STK_C_PTHREAD_KEYS_MAX.

Referenced by stk_pthread_compile_check().

Here is the caller graph for this function:

pthread_mutex_destroy()

int pthread_mutex_destroy

(

pthread_mutex_t *

mutex

)

Destroy a mutex, releasing the underlying STK mutex object.

Safe to call on a mutex that was statically initialized with PTHREAD_MUTEX_INITIALIZER but never used (nothing to destroy). The mutex must not be locked and no thread may be blocked on it; destroying a mutex in use is undefined behavior. After destruction the object may be re-initialized with pthread_mutex_init().

Parameters

[in,out]

mutex

Mutex to destroy.

Returns

0 on success, EINVAL if mutex is NULL.

Definition at line 1155 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (mutex != nullptr)
    {
        if (mutex->__handle != nullptr)
        {
            HandleOf(mutex)->~Mutex();
            mutex->__handle = nullptr;
        }
        result = 0;
    }
 
    return result;
}

References pthread_mutex_t::__handle, stk::pthread::HandleOf(), and stk::sync::Mutex::~Mutex().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_mutex_init()

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

Initialize a mutex.

Parameters

[out]	mutex	Mutex to initialize (storage is embedded in the object, nothing is allocated).
[in]	attr	Optional, or NULL for defaults (PTHREAD_MUTEX_DEFAULT).

Returns

0 on success, EINVAL if mutex is NULL or attr holds an invalid type (the mutex is left uninitialized).

Definition at line 1136 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (mutex != nullptr)
    {
        const int type = (attr != nullptr) ? attr->__type : PTHREAD_MUTEX_DEFAULT;
 
        if (IsValidMutexType(type))
        {
            mutex->__type   = type;
            mutex->__handle = ConstructIn<stk::sync::Mutex>(mutex->__mem);
            result = 0;
        }
    }
 
    return result;
}

References pthread_mutex_t::__handle, pthread_mutex_t::__mem, pthread_mutex_t::__type, pthread_mutexattr_t::__type, stk::ConstructIn(), stk::pthread::IsValidMutexType(), and PTHREAD_MUTEX_DEFAULT.

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_mutex_lock()

int pthread_mutex_lock

(

pthread_mutex_t *

mutex

)

Lock a mutex, blocking until it becomes available.

The underlying STK mutex is created lazily on first use for a mutex statically initialized with PTHREAD_MUTEX_INITIALIZER. Blocking puts the calling task to sleep so other tasks can run. For NORMAL and RECURSIVE types relocking from the owning thread succeeds and must be balanced by the same number of unlocks (the underlying STK mutex is recursive). For ERRORCHECK relocking from the owner returns EDEADLK. Must not be called from ISR context.

Parameters

[in,out]

mutex

Mutex to lock.

Returns

0 on success, EDEADLK (ERRORCHECK, already owned by the caller), EAGAIN (maximum recursion depth exceeded), EINVAL if mutex is NULL.

Definition at line 1172 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (mutex != nullptr)
    {
        sync::Mutex *const m = EnsureMutex(mutex);
 
        result = PreLockCheck(mutex, m, EDEADLK);
        if (result == 0)
        {
            m->Lock();
        }
    }
 
    return result;
}

References stk::pthread::EnsureMutex(), stk::sync::Mutex::Lock(), and stk::pthread::PreLockCheck().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_mutex_timedlock()

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

Lock with an absolute deadline.

If abstime is already in the past the call degenerates into a non-blocking attempt. Timeouts are rounded to STK kernel ticks.

Parameters

[in,out]	mutex	Mutex to lock.
[in]	abstime	Absolute deadline on the stk_time_now_ms() timeline (not CLOCK_REALTIME); see the file-level docs.

Returns

0 on success, ETIMEDOUT if the deadline passed first, EDEADLK (ERRORCHECK, already owned by the caller), EAGAIN (maximum recursion depth exceeded), EINVAL if mutex or abstime is NULL.

See also

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

Definition at line 1230 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((mutex != nullptr) && (abstime != nullptr))
    {
        sync::Mutex *const m = EnsureMutex(mutex);
 
        result = PreLockCheck(mutex, m, EDEADLK);
        if (result == 0)
        {
            result = m->TimedLock(TimespecToRelativeTimeout(abstime)) ? 0 : ETIMEDOUT;
        }
    }
 
    return result;
}

References stk::pthread::EnsureMutex(), stk::pthread::PreLockCheck(), stk::sync::Mutex::TimedLock(), and stk::pthread::TimespecToRelativeTimeout().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_mutex_trylock()

int pthread_mutex_trylock

(

pthread_mutex_t *

mutex

)

Try to lock a mutex without blocking.

For NORMAL and RECURSIVE types succeeds if the caller already owns the mutex (nesting depth is incremented). For ERRORCHECK returns EBUSY.

Parameters

[in,out]

mutex

Mutex to try to lock.

Returns

0 on success, EBUSY if the mutex is currently locked (or, for ERRORCHECK, owned by the caller), EAGAIN (maximum recursion depth exceeded), EINVAL if mutex is NULL.

Definition at line 1190 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (mutex != nullptr)
    {
        sync::Mutex *const m = EnsureMutex(mutex);
 
        result = PreLockCheck(mutex, m, EBUSY);
        if (result == 0)
        {
            result = m->TryLock() ? 0 : EBUSY;
        }
    }
 
    return result;
}

References stk::pthread::EnsureMutex(), stk::pthread::PreLockCheck(), and stk::sync::Mutex::TryLock().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_mutex_unlock()

int pthread_mutex_unlock

(

pthread_mutex_t *

mutex

)

Unlock a mutex held by the calling thread.

Unlike pthread_mutex_lock(), never creates the underlying STK mutex: unlocking a statically initialized mutex that has never been locked is an error. As with real pthreads, unlocking a mutex the caller does not own is undefined behavior and is not detected here.

Parameters

[in,out]

mutex

Mutex to unlock; must be locked by the calling thread.

Returns

0 on success, EPERM if the caller does not own the mutex, EINVAL if mutex is NULL or was never initialized/used.

Definition at line 1208 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((mutex != nullptr) && (mutex->__handle != nullptr))
    {
        sync::Mutex *const m = HandleOf(mutex);
 
        if (IsMutexOwner(m))
        {
            m->Unlock();
            result = 0;
        }
        else
        {
            result = EPERM;
        }
    }
 
    return result;
}

References pthread_mutex_t::__handle, stk::pthread::HandleOf(), stk::pthread::IsMutexOwner(), and stk::sync::Mutex::Unlock().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_mutexattr_destroy()

int pthread_mutexattr_destroy

(

pthread_mutexattr_t *

attr

)

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

Parameters

[in]

attr

Attributes object to destroy.

Returns

0 on success, EINVAL if attr is NULL.

Definition at line 1105 of file stk_c_pthread.cpp.

{
    return (attr != nullptr) ? 0 : EINVAL;
}

Referenced by stk_pthread_compile_check().

Here is the caller graph for this function:

pthread_mutexattr_gettype()

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

Get the mutex type stored in attr.

Parameters

[in]	attr	Attributes object to query.
[out]	type	Receives the mutex type.

Returns

0 on success, EINVAL if attr or type is NULL.

Definition at line 1123 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((attr != nullptr) && (type != nullptr))
    {
        *type = attr->__type;
        result = 0;
    }
 
    return result;
}

References pthread_mutexattr_t::__type.

pthread_mutexattr_init()

int pthread_mutexattr_init

(

pthread_mutexattr_t *

attr

)

Initialize a mutex attributes object with default values (PTHREAD_MUTEX_DEFAULT).

Parameters

[out]

attr

Attributes object to initialize.

Returns

0 on success, EINVAL if attr is NULL.

Definition at line 1092 of file stk_c_pthread.cpp.

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

References pthread_mutexattr_t::__type, and PTHREAD_MUTEX_DEFAULT.

Referenced by stk_pthread_compile_check().

Here is the caller graph for this function:

pthread_mutexattr_settype()

int pthread_mutexattr_settype	(	pthread_mutexattr_t *	attr,
		int	type )

Set the mutex type.

Parameters

[in,out]	attr	Attributes object to modify.
[in]	type	PTHREAD_MUTEX_NORMAL / DEFAULT / RECURSIVE / ERRORCHECK.

Returns

0 on success, EINVAL if attr is NULL or type is not one of the supported values.

Definition at line 1110 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((attr != nullptr) && IsValidMutexType(type))
    {
        attr->__type = type;
        result = 0;
    }
 
    return result;
}

References pthread_mutexattr_t::__type, and stk::pthread::IsValidMutexType().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

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.

Parameters

[in,out]	once_control	Control object, statically initialized with PTHREAD_ONCE_INIT.
[in]	init_routine	Function to call exactly once. Must not call pthread_once() on the same once_control.

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 1680 of file stk_c_pthread.cpp.

{
    int result = 0;
 
    if ((once_control == nullptr) || (init_routine == nullptr))
    {
        result = EINVAL;
    }
    else if (LoadAcquire(&once_control->__state) != kOnceDone) // fast path: already done, no lock needed
    {
        stk::sync::Mutex *const guard = EnsureOnceMutex(once_control);
 
        // The guard is held only while init_routine() runs, so "owned by the caller" means
        // init_routine() re-entered pthread_once() on the same control object. The guard is a
        // recursive Mutex, so Lock() would succeed and init_routine() would recurse until the
        // stack overflows; report the misuse instead (POSIX leaves it undefined).
        if (IsMutexOwner(guard))
        {
            result = EDEADLK;
        }
        else
        {
            guard->Lock();
 
            // 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 != kOnceDone)
            {
                once_control->__state = kOnceRunning;
                init_routine();
                StoreRelease(&once_control->__state, kOnceDone); // release: publish init_routine()'s effects
            }
 
            guard->Unlock();
        }
    }
    else
    {
        // already initialized: nothing to do
    }
 
    return result;
}

References pthread_once_t::__state, stk::pthread::EnsureOnceMutex(), stk::pthread::IsMutexOwner(), stk::pthread::kOnceDone, stk::pthread::kOnceRunning, stk::pthread::LoadAcquire(), stk::sync::Mutex::Lock(), stk::pthread::StoreRelease(), and stk::sync::Mutex::Unlock().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_rwlock_destroy()

int pthread_rwlock_destroy

(

pthread_rwlock_t *

rwlock

)

Destroy a read-write lock, releasing the underlying STK object.

Safe on a never-used PTHREAD_RWLOCK_INITIALIZER object. The lock must not be held and no thread may be blocked on it.

Parameters

[in,out]

rwlock

Read-write lock to destroy.

Returns

0 on success, EINVAL if rwlock is NULL.

Definition at line 1401 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (rwlock != nullptr)
    {
        if (rwlock->__handle != nullptr)
        {
            HandleOf(rwlock)->~RWMutex();
            rwlock->__handle = nullptr;
        }
        result = 0;
    }
 
    return result;
}

References pthread_rwlock_t::__handle, and stk::pthread::HandleOf().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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

[out]	rwlock	Read-write lock to initialize.
[in]	attr	Optional, or NULL for defaults (no settable properties).

Returns

0 on success, EINVAL if rwlock is NULL.

Definition at line 1387 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (rwlock != nullptr)
    {
        rwlock->__handle   = ConstructIn<stk::sync::RWMutex>(rwlock->__mem);
        rwlock->__wrlocked = false;
        result = 0;
    }
 
    return result;
}

References pthread_rwlock_t::__handle, pthread_rwlock_t::__mem, pthread_rwlock_t::__wrlocked, and stk::ConstructIn().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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 RWMutex::TimedReadLock()).

Parameters

[in,out]

rwlock

Read-write lock to acquire for reading.

Definition at line 1418 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (rwlock != nullptr)
    {
        EnsureRWLock(rwlock)->ReadLock();
        result = 0;
    }
 
    return result;
}

References stk::pthread::EnsureRWLock(), and stk::sync::RWMutex::ReadLock().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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.

Parameters

[in,out]	rwlock	Read-write lock to acquire for reading.
[in]	abstime	Absolute deadline on the stk_time_now_ms() timeline (not CLOCK_REALTIME); see the file-level docs.

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 1443 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((rwlock != nullptr) && (abstime != nullptr))
    {
        const bool locked = EnsureRWLock(rwlock)->TimedReadLock(TimespecToRelativeTimeout(abstime));
        result = locked ? 0 : ETIMEDOUT;
    }
 
    return result;
}

References stk::pthread::EnsureRWLock(), stk::sync::RWMutex::TimedReadLock(), and stk::pthread::TimespecToRelativeTimeout().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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.

Parameters

[in,out]	rwlock	Read-write lock to acquire for writing.
[in]	abstime	Absolute deadline on the stk_time_now_ms() timeline (not CLOCK_REALTIME); see the file-level docs.

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 1490 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((rwlock != nullptr) && (abstime != nullptr))
    {
        if (EnsureRWLock(rwlock)->TimedLock(TimespecToRelativeTimeout(abstime)))
        {
            rwlock->__wrlocked = true;
            result = 0;
        }
        else
        {
            result = ETIMEDOUT;
        }
    }
 
    return result;
}

References pthread_rwlock_t::__wrlocked, stk::pthread::EnsureRWLock(), and stk::pthread::TimespecToRelativeTimeout().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_rwlock_tryrdlock()

int pthread_rwlock_tryrdlock

(

pthread_rwlock_t *

rwlock

)

Try to acquire the read lock without blocking.

Parameters

[in,out]

rwlock

Read-write lock to try to acquire for reading.

Returns

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

Definition at line 1431 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (rwlock != nullptr)
    {
        result = EnsureRWLock(rwlock)->TryReadLock() ? 0 : EBUSY;
    }
 
    return result;
}

References stk::pthread::EnsureRWLock(), and stk::sync::RWMutex::TryReadLock().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_rwlock_trywrlock()

int pthread_rwlock_trywrlock

(

pthread_rwlock_t *

rwlock

)

Try to acquire the write lock without blocking.

Parameters

[in,out]

rwlock

Read-write lock to try to acquire for writing.

Returns

0 on success, EBUSY otherwise.

Definition at line 1470 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (rwlock != nullptr)
    {
        if (EnsureRWLock(rwlock)->TryLock())
        {
            rwlock->__wrlocked = true;
            result = 0;
        }
        else
        {
            result = EBUSY;
        }
    }
 
    return result;
}

References pthread_rwlock_t::__wrlocked, and stk::pthread::EnsureRWLock().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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.

Parameters

[in,out]

rwlock

Read-write lock to release; must be held by the calling thread (for reading or writing).

See also

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

Definition at line 1510 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((rwlock != nullptr) && (rwlock->__handle != nullptr))
    {
        // See "pthread_rwlock_unlock() disambiguation" in stk_c_pthread.h: a write
        // hold is always exclusive, so __wrlocked unambiguously identifies which
        // underlying call (Unlock() vs ReadUnlock()) 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;
            HandleOf(rwlock)->Unlock();
        }
        else
        {
            HandleOf(rwlock)->ReadUnlock();
        }
        result = 0;
    }
 
    return result;
}

References pthread_rwlock_t::__handle, pthread_rwlock_t::__wrlocked, stk::pthread::HandleOf(), and stk::sync::Mutex::Unlock().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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.

Parameters

[in,out]

rwlock

Read-write lock to acquire for writing.

Definition at line 1456 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (rwlock != nullptr)
    {
        EnsureRWLock(rwlock)->Lock();
        rwlock->__wrlocked = true;
        result = 0;
    }
 
    return result;
}

References pthread_rwlock_t::__wrlocked, stk::pthread::EnsureRWLock(), and stk::sync::RWMutex::Lock().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_rwlockattr_destroy()

int pthread_rwlockattr_destroy

(

pthread_rwlockattr_t *

attr

)

Destroy a read-write lock attributes object (no-op).

Parameters

[in]

attr

Attributes object to destroy.

Returns

0 on success, EINVAL if attr is NULL.

Definition at line 1382 of file stk_c_pthread.cpp.

{
    return (attr != nullptr) ? 0 : EINVAL;
}

pthread_rwlockattr_init()

int pthread_rwlockattr_init

(

pthread_rwlockattr_t *

attr

)

Initialize a read-write lock attributes object (no settable properties).

Parameters

[out]

attr

Attributes object to initialize.

Returns

0 on success, EINVAL if attr is NULL.

Definition at line 1369 of file stk_c_pthread.cpp.

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

References pthread_rwlockattr_t::__reserved.

pthread_self()

pthread_t pthread_self

(

void

)

Return the calling thread's own handle.

Returns

The calling thread's handle. A task not created through this shim (e.g. the bootstrap task) is adopted on first call; NULL only if no pthread slot is left to adopt into (see the file-level note).

Definition at line 1073 of file stk_c_pthread.cpp.

{
    return static_cast<pthread_t>(CurrentCtrlOrAdopt()); // NULL only if the slot pool is exhausted
}

References stk::pthread::CurrentCtrlOrAdopt().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_setspecific()

int pthread_setspecific	(	pthread_key_t	key,
		const void *	value )

Set the calling thread's value for key.

Parameters

[in]	key	Key to set the calling thread's value for.
[in]	value	Value to associate with the key for the calling thread (may be NULL).

See also

"pthread_key_t / thread-specific data" in the file-level docs.

Returns

0 on success, EINVAL if key is invalid, ENOMEM if the calling task is a foreign task and no pthread slot is left to adopt it into.

Definition at line 1772 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (IsKeyUsed(key))
    {
        ThreadCtrl *const ctrl = CurrentCtrlOrAdopt(); // foreign tasks are adopted on first use
 
        if (ctrl == nullptr)
        {
            result = ENOMEM; // pthread slot pool exhausted
        }
        else
        {
            ctrl->tsd[key] = const_cast<void *>(value);
            result = 0;
        }
    }
 
    return result;
}

References stk::pthread::CurrentCtrlOrAdopt(), stk::pthread::IsKeyUsed(), and pthread_stk_ctrl_t::tsd.

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_spin_destroy()

int pthread_spin_destroy

(

pthread_spinlock_t *

lock

)

Destroy a spinlock.

The spinlock must not be held. After destruction it must be re-initialized with pthread_spin_init() before further use.

Parameters

[in,out]

lock

Spinlock to destroy.

Returns

0 on success, EINVAL if lock is NULL.

Definition at line 1558 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (lock != nullptr)
    {
        if (lock->__handle != nullptr)
        {
            HandleOf(lock)->~SpinLock();
            lock->__handle = nullptr;
        }
        result = 0;
    }
 
    return result;
}

References pthread_spinlock_t::__handle, and stk::pthread::HandleOf().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_spin_init()

int pthread_spin_init	(	pthread_spinlock_t *	lock,
		int	pshared )

Initialize a spinlock.

Parameters

[out]	lock	Spinlock to initialize.
[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 1538 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if (lock != nullptr)
    {
        if (pshared != PTHREAD_PROCESS_PRIVATE)
        {
            result = ENOTSUP;
        }
        else
        {
            lock->__handle = ConstructIn<stk::hw::SpinLock>(lock->__mem);
            result = 0;
        }
    }
 
    return result;
}

References pthread_spinlock_t::__handle, pthread_spinlock_t::__mem, stk::ConstructIn(), and PTHREAD_PROCESS_PRIVATE.

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_spin_lock()

int pthread_spin_lock

(

pthread_spinlock_t *

lock

)

Acquire the spinlock, spinning until available.

Busy-waits (the task is not put to sleep), so hold it only for very short critical sections. Not recursive: relocking from the owning thread deadlocks.

Parameters

[in,out]

lock

Spinlock to acquire.

Returns

0 on success, EINVAL if lock is NULL or was never initialized.

See also

"pthread_spin_* note" in the file-level docs.

Definition at line 1575 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((lock != nullptr) && (lock->__handle != nullptr))
    {
        HandleOf(lock)->Lock();
        result = 0;
    }
 
    return result;
}

References pthread_spinlock_t::__handle, stk::pthread::HandleOf(), and stk::sync::Mutex::Lock().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_spin_trylock()

int pthread_spin_trylock

(

pthread_spinlock_t *

lock

)

Try to acquire the spinlock without blocking.

Parameters

[in,out]

lock

Spinlock to try to acquire.

Returns

0 on success, EBUSY if currently held, EINVAL if lock is NULL or was never initialized.

Definition at line 1588 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((lock != nullptr) && (lock->__handle != nullptr))
    {
        result = HandleOf(lock)->TryLock() ? 0 : EBUSY;
    }
 
    return result;
}

References pthread_spinlock_t::__handle, stk::pthread::HandleOf(), and stk::sync::Mutex::TryLock().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller graph for this function:

pthread_spin_unlock()

int pthread_spin_unlock

(

pthread_spinlock_t *

lock

)

Release a spinlock held by the calling thread.

Parameters

[in,out]

lock

Spinlock to release; must be held by the calling thread.

Returns

0 on success, EINVAL if lock is NULL or was never initialized.

Definition at line 1600 of file stk_c_pthread.cpp.

{
    int result = EINVAL;
 
    if ((lock != nullptr) && (lock->__handle != nullptr))
    {
        HandleOf(lock)->Unlock();
        result = 0;
    }
 
    return result;
}

References pthread_spinlock_t::__handle, stk::pthread::HandleOf(), and stk::sync::Mutex::Unlock().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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 1083 of file stk_c_pthread.cpp.

{
    stk::Yield();
    return 0;
}

References stk::Yield().

Referenced by stk_pthread_compile_check().

Here is the call graph for this function:

Here is the caller 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.

Note

Also adds the internal reaper task to the kernel, so STK_C_KERNEL_MAX_TASKS must have room for it. Binding a second, different kernel is not supported (the reaper stays with the first).

Parameters

[in]

kernel

Kernel handle obtained from stk_kernel_create(). Its configured type (STK_C_KERNEL_TYPE_CPU_X) must include KERNEL_DYNAMIC (threads need to be able to finish/return) and KERNEL_SYNC.

Definition at line 749 of file stk_c_pthread.cpp.

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

References stk::pthread::EnsureReaper(), stk::pthread::s_BoundKernel, and STK_C_ASSERT.

Here is the call graph for this function: