SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
stk_c_pthread.h File Reference

A minimal, POSIX-named pthreads-style API for STK. The public interface is self-contained (it needs neither stk_c.h nor any other STK header besides stk_config.h, and no C++ headers), so it can be used from C. The implementation (stk_c_pthread.cpp) calls the STK C++ API directly for thread/task control, TLS, critical sections, sleep/yield/time and the synchronization primitives; the pthread_stk_*_mem_t blobs embedded in the pthread_* types are used as in-place storage for those C++ objects. More...

#include <cstdint>
#include <cstddef>
#include <ctime>
#include <stk_config.h>
#include "sched.h"
Include dependency graph for stk_c_pthread.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  pthread_stk_mutex_mem_t
struct  pthread_stk_cv_mem_t
struct  pthread_stk_rwmutex_mem_t
struct  pthread_stk_barrier_mem_t
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 _SYS__PTHREADTYPES_H_
#define STK_C_PTHREADTYPES_GUARD
#define STK_SYNC_DEBUG_NAMES   (0)
#define __stk_pthread_aligned
 Alignment attribute of the opaque object storage (one machine word).
#define STK_C_PTHREAD_MUTEX_WORDS   (10U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))
 Sizes (in pthread_stk_word_t units) of the opaque storage for the C++ sync objects.
#define STK_C_PTHREAD_CV_WORDS   (7U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))
#define STK_C_PTHREAD_RWMUTEX_WORDS   (17U + (STK_SYNC_DEBUG_NAMES ? 3U : 0U))
#define STK_C_PTHREAD_BARRIER_WORDS   (STK_C_PTHREAD_MUTEX_WORDS + STK_C_PTHREAD_CV_WORDS + 4U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))
#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 pthread_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 pthread_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 STK_C_PTHREAD_NAME_MAX   (16U)
 Capacity of a thread name buffer including the terminating NUL (like Linux, 16).
#define STK_C_PTHREAD_RUNTIME_PRIORITY   (1)
 1 (default): pthread_setschedparam() / pthread_setschedprio() change the priority of a running thread with stk::SetWeight(), which requires a kernel switch strategy with WEIGHT_API = 1 and PRIORITY_INHERITANCE_API = 1 (sched::SwitchStrategyFixedPriority). Set it to 0 for other strategies: the functions then return ENOTSUP for any change (an unchanged value still succeeds).
#define CLOCK_REALTIME   (0)
#define CLOCK_MONOTONIC   (1)
#define PTHREAD_CANCEL_ENABLE   (0)
#define PTHREAD_CANCEL_DISABLE   (1)
#define PTHREAD_CANCEL_DEFERRED   (0)
#define PTHREAD_CANCEL_ASYNCHRONOUS   (1)
#define PTHREAD_CANCELED   ((void *)(intptr_t)-1)
 Value returned by pthread_join() for a cancelled thread.
#define STK_C_PTHREAD_CLEANUP_MAX   (8U)
 Maximum nesting depth of pthread_cleanup_push() per thread.
#define PTHREAD_INHERIT_SCHED   (0)
#define PTHREAD_EXPLICIT_SCHED   (1)
#define PTHREAD_SCOPE_SYSTEM   (0)
#define PTHREAD_SCOPE_PROCESS   (1)
#define PTHREAD_PRIO_NONE   (0)
#define PTHREAD_PRIO_INHERIT   (1)
#define PTHREAD_PRIO_PROTECT   (2)
#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 STK_C_PTHREAD_ZERO_INIT   {}
 All-zero aggregate initializer of the static initializers below. C++ uses {} (value-initialization): {0} initializes only the first member and makes -Wmissing-field-initializers warn there, while in C {0} is accepted by the compilers without a warning.
#define PTHREAD_MUTEX_INITIALIZER   STK_C_PTHREAD_ZERO_INIT
#define PTHREAD_COND_INITIALIZER   STK_C_PTHREAD_ZERO_INIT
#define PTHREAD_RWLOCK_INITIALIZER   STK_C_PTHREAD_ZERO_INIT
#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   STK_C_PTHREAD_ZERO_INIT
#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.
#define SIGKILL   9
#define SIGTERM   15

Typedefs

typedef uintptr_t pthread_stk_word_t
 Native machine word used for stacks and opaque object storage (same as stk::Word).
typedef struct pthread_stk_mutex_mem_t pthread_stk_mutex_mem_t
typedef struct pthread_stk_cv_mem_t pthread_stk_cv_mem_t
typedef struct pthread_stk_rwmutex_mem_t pthread_stk_rwmutex_mem_t
typedef struct pthread_stk_barrier_mem_t pthread_stk_barrier_mem_t
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 (void *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.
int pthread_attr_setschedparam (pthread_attr_t *attr, const struct sched_param *param)
 Set the scheduling priority (task weight) of threads created with attr.
int pthread_attr_getschedparam (const pthread_attr_t *attr, struct sched_param *param)
 Get the scheduling priority stored in attr.
int pthread_attr_setschedpolicy (pthread_attr_t *attr, int policy)
 Set the scheduling policy stored in attr (SCHED_OTHER, SCHED_FIFO or SCHED_RR).
int pthread_attr_getschedpolicy (const pthread_attr_t *attr, int *policy)
 Get the scheduling policy stored in attr.
int pthread_attr_setinheritsched (pthread_attr_t *attr, int inheritsched)
 Select whether a new thread inherits the priority of the creating thread.
int pthread_attr_getinheritsched (const pthread_attr_t *attr, int *inheritsched)
 Get the inherit-scheduling mode stored in attr.
int pthread_attr_setscope (pthread_attr_t *attr, int scope)
 Set the contention scope. Only PTHREAD_SCOPE_SYSTEM is supported.
int pthread_attr_getscope (const pthread_attr_t *attr, int *scope)
 Get the contention scope (always PTHREAD_SCOPE_SYSTEM).
int pthread_attr_setguardsize (pthread_attr_t *attr, size_t guardsize)
 Set the guard size. Accepted and stored, but STK has no guard pages: it has no effect.
int pthread_attr_getguardsize (const pthread_attr_t *attr, size_t *guardsize)
 Get the stored guard size (0 by default).
int pthread_attr_setname_np (pthread_attr_t *attr, const char *name)
 Set the name of threads created with attr (non-portable, GNU-style).
int pthread_attr_getname_np (const pthread_attr_t *attr, char *name, size_t len)
 Get the name stored in attr.
int pthread_getschedparam (pthread_t thread, int *policy, struct sched_param *param)
 Get the policy and priority (task weight) of a thread.
int pthread_setschedparam (pthread_t thread, int policy, const struct sched_param *param)
 Change the policy/priority of a running thread.
int pthread_setschedprio (pthread_t thread, int prio)
 Change the priority of a running thread (the policy is kept). See pthread_setschedparam().
int pthread_setname_np (pthread_t thread, const char *name)
 Set the name of a thread (shown by debug/trace tools), non-portable GNU-style.
int pthread_getname_np (pthread_t thread, char *name, size_t len)
 Get the name of a thread.
int pthread_setconcurrency (int level)
 Set the concurrency level hint. Accepted and ignored (STK always schedules kernel tasks).
int pthread_getconcurrency (void)
 Get the concurrency level hint.
int pthread_tryjoin_np (pthread_t thread, void **retval)
 Try to join a thread without blocking (GNU extension).
int pthread_timedjoin_np (pthread_t thread, void **retval, const struct timespec *abstime)
 Join a thread, waiting until the absolute deadline abstime (GNU extension).
int pthread_mutexattr_setpshared (pthread_mutexattr_t *attr, int pshared)
 Set/get the process-shared attribute of mutex, condition variable, rwlock and barrier attributes.
int pthread_mutexattr_getpshared (const pthread_mutexattr_t *attr, int *pshared)
int pthread_condattr_setpshared (pthread_condattr_t *attr, int pshared)
int pthread_condattr_getpshared (const pthread_condattr_t *attr, int *pshared)
int pthread_rwlockattr_setpshared (pthread_rwlockattr_t *attr, int pshared)
int pthread_rwlockattr_getpshared (const pthread_rwlockattr_t *attr, int *pshared)
int pthread_barrierattr_setpshared (pthread_barrierattr_t *attr, int pshared)
int pthread_barrierattr_getpshared (const pthread_barrierattr_t *attr, int *pshared)
int pthread_mutexattr_setprotocol (pthread_mutexattr_t *attr, int protocol)
 Set the mutex protocol.
int pthread_mutexattr_getprotocol (const pthread_mutexattr_t *attr, int *protocol)
 Get the mutex protocol stored in attr.
int pthread_condattr_setclock (pthread_condattr_t *attr, clockid_t clock_id)
 Set the clock used by pthread_cond_timedwait() deadlines.
int pthread_condattr_getclock (const pthread_condattr_t *attr, clockid_t *clock_id)
 Get the clock stored in attr.
int pthread_mutex_clocklock (pthread_mutex_t *mutex, clockid_t clock_id, const struct timespec *abstime)
 pthread_mutex_timedlock() with an explicit clock.
int pthread_cond_clockwait (pthread_cond_t *cond, pthread_mutex_t *mutex, clockid_t clock_id, const struct timespec *abstime)
 pthread_cond_timedwait() with an explicit clock. See pthread_mutex_clocklock() for clock_id.
int pthread_rwlock_clockrdlock (pthread_rwlock_t *rwlock, clockid_t clock_id, const struct timespec *abstime)
 pthread_rwlock_timedrdlock() with an explicit clock. See pthread_mutex_clocklock() for clock_id.
int pthread_rwlock_clockwrlock (pthread_rwlock_t *rwlock, clockid_t clock_id, const struct timespec *abstime)
 pthread_rwlock_timedwrlock() with an explicit clock. See pthread_mutex_clocklock() for clock_id.
int pthread_cancel (pthread_t thread)
 Request cancellation of a thread.
int pthread_setcancelstate (int state, int *oldstate)
 Enable or disable cancellation of the calling thread.
int pthread_setcanceltype (int type, int *oldtype)
 Set the cancellation type. Only PTHREAD_CANCEL_DEFERRED is supported.
void pthread_testcancel (void)
 Create a cancellation point: terminate the calling thread if a cancellation is pending and enabled.
void pthread_cleanup_push (void(*routine)(void *), void *arg)
 Push a cleanup handler (run in LIFO order by pthread_exit() and by cancellation).
void pthread_cleanup_pop (int execute)
 Pop the most recent cleanup handler, running it if execute is non-zero.
int pthread_getattr_np (pthread_t thread, pthread_attr_t *attr)
 Get the attributes of a running thread (GNU extension).
int pthread_kill (pthread_t thread, int sig)
 Send a "signal" to a thread. STK has no signals, three values are supported:
int pthread_atfork (void(*prepare)(void), void(*parent)(void), void(*child)(void))
 Register fork handlers. STK has no fork(): the handlers are never run, the call only exists so that code and libraries which register them link and work.

Detailed Description

A minimal, POSIX-named pthreads-style API for STK. The public interface is self-contained (it needs neither stk_c.h nor any other STK header besides stk_config.h, and no C++ headers), so it can be used from C. The implementation (stk_c_pthread.cpp) calls the STK C++ API directly for thread/task control, TLS, critical sections, sleep/yield/time and the synchronization primitives; the pthread_stk_*_mem_t blobs embedded in the pthread_* types are used as in-place storage for those C++ objects.

Covers thread lifecycle and attributes, mutexes, condition variables, read-write locks, spinlocks, barriers, pthread_once() and thread-specific data. This is deliberately a subset of full POSIX threads, scoped to what maps cleanly onto STK's task/synchronization model:

| POSIX area | Support | |--------------------------------------------------------------------------------------------—+----------------------------------------------------------------------------------—| | pthread_create/join/detach/exit/self/equal | Yes | | pthread_yield (non-POSIX; POSIX uses sched_yield()) | Yes (GNU/BSD-style extension) | | pthread_attr_t (stacksize, stack, detachstate) | Yes | | pthread_attr_set/getprivileged_np | Yes (non-portable STK extension) | | pthread_mutex_t (normal/default) | Yes (recursive in practice, see PTHREAD_MUTEX_NORMAL note) | | pthread_mutex_t (recursive, errorcheck) | Yes | | pthread_cond_t (wait/timedwait/signal/broadcast) | Yes | | pthread_rwlock_t (rdlock/wrlock/tryrdlock/trywrlock/timed variants/unlock) | Yes | | pthread_spin_* (init/destroy/lock/trylock/unlock) | Yes | | pthread_barrier_t (init/destroy/wait) | Yes | | pthread_once | Yes | | pthread_key_t (create/delete/setspecific/getspecific, destructors) | Yes | | pthread_attr_set/getschedparam/schedpolicy/inheritsched/scope/guardsize | Yes (priority = task weight at creation; policy informational) | | pthread_getschedparam / pthread_setschedparam / pthread_setschedprio | Yes (run-time change via stk::SetWeight(), needs sched::SwitchStrategyFixedPriority)| | sched_yield, sched_get_priority_min/max (<sched.h>) | Yes | | pthread_set/getname_np, pthread_attr_set/getname_np | Yes (GNU-style extension) | | pthread_timedjoin_np / pthread_tryjoin_np | Yes (GNU-style extension) | | pthread_mutex_clocklock / cond_clockwait / rwlock_clockrd/wrlock | Yes (CLOCK_REALTIME and CLOCK_MONOTONIC share the STK tick timeline) | | pthread_*attr_set/getpshared, mutexattr protocol, condattr clock | Yes (PROCESS_PRIVATE only; PRIO_NONE/INHERIT) | | sem_init/destroy/wait/trywait/timedwait/clockwait/post/getvalue (<semaphore.h>) | Yes (unnamed semaphores, see semaphore.h) | | stk_pthread_bind_kernel() | Yes (STK-specific bootstrap, not POSIX; required before pthread_create()) | | pthread_cancel/setcancelstate/setcanceltype/testcancel/cleanup_push/pop | Yes (deferred only; asynchronous cancellation: ENOTSUP) | | pthread_getattr_np | Yes (GNU-style extension) | | clock_gettime/getres, nanosleep, clock_nanosleep, usleep, sleep, timer_* (<time.h>) | Yes (see time.h; timers need a TimerHost, stk_posix_timer_bind_host()) | | gettimeofday (<sys/time.h>), time (<time.h>) | Yes (kernel time + optional offset, stk_posix_set_wall_time()) | | sysconf, getpid (<unistd.h>) | Yes (limits of this shim and kernel, single "process") | | mq_open/close/unlink/send/receive/timed variants/getattr/setattr (<mqueue.h>) | Yes (priorities honored; mq_notify: ENOSYS) | | C11 thrd_*, mtx_*, cnd_*, tss_*, call_once (<threads.h>) | Yes (wrappers over this shim, see threads.h) | | SCHED_FIFO / SCHED_RR policy enforcement | No (the kernel switch strategy defines scheduling, SCHED_* is informational) |

Requirements on the STK kernel configuration
  • The kernel type configured for the bound core (STK_C_KERNEL_TYPE_CPU_X in stk_config.h, X being the core number passed to stk_kernel_create()) must include KERNEL_DYNAMIC (threads finish by returning from their entry function or calling pthread_exit(), which STK only supports for dynamic kernels) and KERNEL_SYNC (which enables the Mutex/Event/Semaphore primitives this shim is built on). The shim cannot verify this: a mismatch is a build configuration error and is not reported through an error code.
  • STK_C_KERNEL_MAX_TASKS must be large enough to hold: the application's own pre-existing tasks + one internal reaper task (added to the kernel by stk_pthread_bind_kernel(), whether or not any thread is ever detached) + the maximum number of concurrently-alive pthreads (joined-but-not-yet-collected and detached-but-not-yet-reaped threads still count as "alive" until reclaimed).
Memory
A thread created with the default stack size (STK_C_PTHREAD_DEFAULT_STACK_WORDS) takes its stack from a static pool and uses no heap. Any other size set via pthread_attr_setstacksize() is allocated with malloc() and freed when the thread is reclaimed. A stack supplied through pthread_attr_setstack() is used as-is and is never freed by the shim. The internal reaper task uses a static stack of STK_C_PTHREAD_REAPER_STACK_WORDS words.
  • STK_C_PTHREAD_MAX_THREADS (this file) bounds how many pthread_t's can exist concurrently; increase it via a -D define or in stk_config.h.
Bootstrapping
This shim never creates or starts a kernel itself. The application must create and start its own STK kernel exactly as it would without pthreads, and then call stk_pthread_bind_kernel() once (before the first pthread_create() call) so the shim knows which kernel to add new threads to (the call also adds the internal reaper task to that kernel):
stk_task_t *main_task = stk_task_create_user(MainEntry, NULL, main_stack, MAIN_STACK_WORDS);
stk_kernel_add_task(k, main_task);
stk_kernel_start(k); // never returns; MainEntry() may now call pthread_create()
stk_task_t * stk_task_create_user(stk_task_entry_t entry, void *arg, stk_word_t *stack, uint32_t stack_size)
Create user-mode task.
Definition stk_c.cpp:662
struct stk_kernel_t stk_kernel_t
Opaque handle to a kernel instance.
Definition stk_c.h:188
void stk_kernel_start(stk_kernel_t *k)
Start the scheduler - never returns.
Definition stk_c.cpp:478
stk_add_result_t stk_kernel_add_task(stk_kernel_t *k, stk_task_t *tsk)
Add task to non-HRT kernel (static or dynamic).
Definition stk_c.cpp:506
#define STK_PERIODICITY_DEFAULT
Default tick period (1 ms).
Definition stk_c.h:196
void stk_kernel_init(stk_kernel_t *k, uint32_t tick_period_us)
Initialize kernel with given tick period.
Definition stk_c.cpp:471
stk_kernel_t * stk_kernel_create(uint8_t core_nr)
Create kernel.
Definition stk_c.cpp:403
void stk_pthread_bind_kernel(void *kernel)
Bind the STK kernel instance that pthread_create() will add new threads to.
pthread_self() and foreign tasks (adoption)
pthread_self() is backed by STK's per-task TLS slot (stk_tls_get()), which this shim populates for every thread it creates via pthread_create(). A task the shim did not create - typically the application's bootstrap task added to the kernel before stk_kernel_start() - is adopted on first use: the first call to pthread_self() or pthread_setspecific() from such a task gives it a pthread_t and stores that handle in its TLS slot. Consequences:
  • each adopted task permanently consumes one STK_C_PTHREAD_MAX_THREADS slot, so size that limit as (pthread_create()'d threads + adopted tasks);
  • an adopted thread is not joinable and never reaped (pthread_join() and pthread_detach() return EINVAL for it);
  • the task's TLS slot now belongs to this shim: the application must not call stk_tls_set() in a task that uses the pthread API (it would replace the handle);
  • pthread_exit() from an adopted task runs its key destructors and then parks the task forever (the shim holds no kernel task object for it, so it cannot ask the kernel to remove it);
  • pthread_getspecific() never adopts (it returns NULL for a task that has not yet stored any value), so merely reading does not consume a slot. pthread_self() returns NULL only if no slot is left to adopt into.
Context restrictions
The blocking calls - pthread_join(), the lock/wait functions of mutexes, condition variables and read-write locks (including the timed variants, which block until the deadline), pthread_barrier_wait() and pthread_once() - must not be called from an ISR: the underlying STK primitives are ISR-unsafe for blocking operations. STK's non-blocking operations (try-lock, unlock, notify) are ISR-safe, but the shim adds lazy initialization and bookkeeping around them, so treat the pthread API as task-context only.
pthread_cond_timedwait() / pthread_mutex_timedlock() limitation
STK has no wall-clock (CLOCK_REALTIME) concept - only a monotonic tick count since stk_kernel_init(). abstime is therefore a point on the timeline of stk::GetTimeNowMs() (C alias: stk_time_now_ms()): derive it by adding a duration to a value read from that function, never from a time-of-day clock:
stk_time_t deadline_ms = stk_time_now_ms() + 500; // 500 ms from now
struct timespec abstime;
abstime.tv_sec = (time_t)(deadline_ms / 1000);
abstime.tv_nsec = (long)((deadline_ms % 1000) * 1000000);
int rc = pthread_cond_timedwait(&cond, &mutex, &abstime); // 0 or ETIMEDOUT
int64_t stk_time_t
Time value.
Definition stk_c.h:170
stk_time_t stk_time_now_ms(void)
Returns current time in milliseconds since kernel start.
Definition stk_c.cpp:791
int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime)
As pthread_cond_wait(), with an absolute deadline.

abstime is converted to a relative timeout in milliseconds (and then to kernel ticks). A deadline that is already in the past yields a zero timeout, so the call behaves like a non-blocking attempt, and very distant deadlines are clamped to INT32_MAX ms. The remaining time is rounded UP to whole kernel ticks, so a call never reports ETIMEDOUT before abstime has passed. The same interpretation applies to pthread_rwlock_timedrdlock() and pthread_rwlock_timedwrlock().

pthread_rwlock_unlock() disambiguation
POSIX uses a single pthread_rwlock_unlock() call to release either a read or a write hold, but the underlying stk::sync::RWMutex exposes separate ReadUnlock() / Unlock() calls. This shim disambiguates by recording, inside the pthread_rwlock_t itself, whether the lock is currently held for writing; this is safe because a write hold is always exclusive (no reader can be active while it is set), so the flag unambiguously identifies which underlying call to make. As with real pthreads, calling pthread_rwlock_unlock() on a lock you do not hold is undefined behavior and is not detected here.
pthread_spin_* note
Spinlocks busy-wait and are not recursive: relocking from the owning thread deadlocks. Only PTHREAD_PROCESS_PRIVATE is supported for the pshared argument to pthread_spin_init(); PTHREAD_PROCESS_SHARED returns ENOTSUP (STK has no cross-process concept).
pthread_barrier_wait() note
Like the underlying stk::sync::Barrier::Wait(), pthread_barrier_wait() is ISR-unsafe - do not call it from interrupt context. It returns PTHREAD_BARRIER_SERIAL_THREAD to exactly one arbitrary calling thread per round (the one whose arrival trips the barrier) and 0 to the rest, matching POSIX.
pthread_once() note
Each pthread_once_t lazily creates its own guard mutex (on first use; it is embedded in the pthread_once_t and never explicitly destroyed) and blocks concurrent callers on it while init_routine runs, so - unlike a naive flag check - a thread that calls pthread_once() while another thread's init_routine is still running correctly waits for it to finish rather than racing ahead. init_routine must not itself call pthread_once() on the same pthread_once_t (self-deadlock, as in real POSIX).
pthread_key_t / thread-specific data
Per-thread values set via pthread_setspecific() are stored in the thread's control block (reached through STK's per-task TLS slot). Foreign tasks are adopted on first pthread_setspecific() as described above (ENOMEM if no slot is left). Destructors (if any) run when a thread finishes (natural return or pthread_exit()), for at most PTHREAD_DESTRUCTOR_ITERATIONS passes - matching POSIX, a destructor that calls pthread_setspecific() to set a new non-NULL value for its own key causes another pass. They do not run for an adopted task that simply never exits. STK_C_PTHREAD_KEYS_MAX (this file) bounds how many keys can exist concurrently.

Definition in file stk_c_pthread.h.

Macro Definition Documentation

◆ _SYS__PTHREADTYPES_H_

#define _SYS__PTHREADTYPES_H_

Definition at line 23 of file stk_c_pthread.h.

◆ STK_C_PTHREADTYPES_GUARD

#define STK_C_PTHREADTYPES_GUARD

Definition at line 24 of file stk_c_pthread.h.

◆ STK_SYNC_DEBUG_NAMES

#define STK_SYNC_DEBUG_NAMES   (0)

Definition at line 49 of file stk_c_pthread.h.