stk_c_pthread.cpp

Go to the documentation of this file.

/*
 * SuperTinyKernel(TM) RTOS: Lightweight High-Performance Deterministic C++ RTOS for Embedded Systems.
 *
 * Source: https://github.com/SuperTinyKernel-RTOS
 *
 * Copyright (c) 2022-2026 Neutron Code Limited <stk@neutroncode.com>. All Rights Reserved.
 * License: MIT License, see LICENSE for a full text.
 */
 
#include <cstddef> // for std::size_t
#include <cstdint>
 
#include "stk_c.h"
#include "stk_c_memory.h"
#include "stk_c_pthread.h"
 
// Private malloc/free declarations (mirrors stk_c_memory.cpp): overcomes absence of
// declarations under a -ffreestanding compiler flag. Only used for the "unusual"
// stack-size fallback path; the common-size path is served entirely from a static
// BlockMemoryPool with zero heap use.
extern "C" void *malloc(std::size_t size);
extern "C" void free(void *ptr);
 
// =============================================================================
// Internal state
// =============================================================================
 
// Definition of the opaque type forward-declared in stk_c_pthread.h as
// `typedef struct pthread_stk_ctrl_t *pthread_t;`. Must live at global scope
// (matching the header's forward declaration) rather than inside the anonymous
// namespace below, so that pthread_t in caller code and this definition refer to
// the exact same type.
struct pthread_stk_ctrl_t
{
    bool             busy;
    bool             finished;   // start_routine returned / pthread_exit() called
    bool             detached;
    bool             joined;
    bool             reclaimed;  // resources already freed or handed to the reaper
 
    stk_task_t      *task;
    void            *(*start_routine)(void *);
    void            *arg;
    void            *retval;
 
    stk_word_t      *stack;
    bool             stack_owned;     // false => caller-supplied via pthread_attr_setstack()
    bool             stack_from_pool; // true  => came from s_StackPool, else malloc()
 
    stk_event_t     *done_event;
    stk_event_mem_t  done_event_mem;
 
    void            *tsd[STK_C_PTHREAD_KEYS_MAX]; // pthread_setspecific()/getspecific() storage
};
 
namespace {
 
using ThreadCtrl = pthread_stk_ctrl_t;
 
constexpr std::size_t kDefaultStackBytes =
    static_cast<std::size_t>(STK_C_PTHREAD_DEFAULT_STACK_WORDS) * sizeof(stk_word_t);
 
ThreadCtrl s_Threads[STK_C_PTHREAD_MAX_THREADS];
 
// -----------------------------------------------------------------------------
// Bound kernel
// -----------------------------------------------------------------------------
stk_kernel_t *s_BoundKernel = nullptr;
 
// -----------------------------------------------------------------------------
// Static stack pool (zero heap) for default-size stacks
// -----------------------------------------------------------------------------
STK_BLOCKPOOL_STORAGE_DECL(s_PthreadStackStorage, STK_C_PTHREAD_MAX_THREADS, kDefaultStackBytes);
stk_blockpool_t *s_StackPool = nullptr;
 
stk_blockpool_t *EnsureStackPool()
{
    if (s_StackPool == nullptr)
    {
        stk_critical_section_enter();
        if (s_StackPool == nullptr)
        {
            s_StackPool = stk_blockpool_create_static(
                STK_C_PTHREAD_MAX_THREADS,
                kDefaultStackBytes,
                reinterpret_cast<uint8_t *>(s_PthreadStackStorage),
                sizeof(s_PthreadStackStorage),
                "pthread_stacks");
        }
        stk_critical_section_exit();
    }
 
    return s_StackPool;
}
 
// -----------------------------------------------------------------------------
// Reaper task: reclaims detached-thread resources once they finish.
// -----------------------------------------------------------------------------
ThreadCtrl        *s_ReapQueue[STK_C_PTHREAD_MAX_THREADS];
std::size_t         s_ReapHead  = 0U;
std::size_t         s_ReapCount = 0U;
 
stk_sem_t          *s_ReapSem = nullptr;
stk_sem_mem_t        s_ReapSemMem;
stk_task_t          *s_ReaperTask = nullptr;
stk_word_t           s_ReaperStack[STK_C_PTHREAD_REAPER_STACK_WORDS];
 
void ReleaseThreadResources(ThreadCtrl *ctrl);
void WaitForTaskGone(stk_task_t *task);
void ReaperEntry(void *arg);
 
void EnsureReaper()
{
    if (s_ReaperTask == nullptr)
    {
        stk_critical_section_enter();
        if (s_ReaperTask == nullptr)
        {
            STK_C_ASSERT(s_BoundKernel != nullptr);
 
            if (s_ReapSem == nullptr)
            {
                s_ReapSem = stk_sem_create(&s_ReapSemMem, sizeof(s_ReapSemMem), 0U, 0U);
            }
 
            s_ReaperTask = stk_task_create_user(ReaperEntry, nullptr, s_ReaperStack,
                                                STK_C_PTHREAD_REAPER_STACK_WORDS);
            if (s_ReaperTask != nullptr)
            {
                stk_task_set_name(s_ReaperTask, "pthread_reaper");
                stk_kernel_add_task(s_BoundKernel, s_ReaperTask);
            }
        }
        stk_critical_section_exit();
    }
}
 
void EnqueueReap(ThreadCtrl *ctrl)
{
    stk_critical_section_enter();
    STK_C_ASSERT(s_ReapCount < STK_C_PTHREAD_MAX_THREADS);
    if (s_ReapCount < STK_C_PTHREAD_MAX_THREADS)
    {
        const std::size_t tail = (s_ReapHead + s_ReapCount) % STK_C_PTHREAD_MAX_THREADS;
        s_ReapQueue[tail] = ctrl;
        ++s_ReapCount;
    }
    stk_critical_section_exit();
}
 
ThreadCtrl *DequeueReap()
{
    ThreadCtrl *result = nullptr;
 
    stk_critical_section_enter();
    if (s_ReapCount > 0U)
    {
        result = s_ReapQueue[s_ReapHead];
        s_ReapHead = (s_ReapHead + 1U) % STK_C_PTHREAD_MAX_THREADS;
        --s_ReapCount;
    }
    stk_critical_section_exit();
 
    return result;
}
 
void ReaperEntry(void * /*arg*/)
{
    for (;;)
    {
        STK_C_ASSERT(s_ReapSem != nullptr);
        stk_sem_wait(s_ReapSem, STK_WAIT_INFINITE);
 
        ThreadCtrl *ctrl = DequeueReap();
        if (ctrl != nullptr)
        {
            WaitForTaskGone(ctrl->task);
            ReleaseThreadResources(ctrl);
        }
    }
}
 
// Exactly-once trigger: called both when a detached thread finishes and when an
// already-running thread is detached. Whichever observes "finished && detached"
// first hands the thread off to the reaper.
void MaybeReap(ThreadCtrl *ctrl)
{
    bool do_reap = false;
 
    stk_critical_section_enter();
    if (ctrl->finished && ctrl->detached && !ctrl->reclaimed)
    {
        ctrl->reclaimed = true;
        do_reap = true;
    }
    stk_critical_section_exit();
 
    if (do_reap)
    {
        EnsureReaper();
        EnqueueReap(ctrl);
        stk_sem_signal(s_ReapSem);
    }
}
 
// -----------------------------------------------------------------------------
// Slot management
// -----------------------------------------------------------------------------
ThreadCtrl *AcquireThreadSlot()
{
    ThreadCtrl *result = nullptr;
 
    stk_critical_section_enter();
    for (std::size_t i = 0U; i < STK_C_PTHREAD_MAX_THREADS; ++i)
    {
        if (!s_Threads[i].busy)
        {
            s_Threads[i] = ThreadCtrl();
            s_Threads[i].busy = true;
            result = &s_Threads[i];
            break;
        }
    }
    stk_critical_section_exit();
 
    return result;
}
 
// Poll until 'task' no longer appears in the kernel's active task list, i.e. it has
// been fully torn down (its ITask/OnExit teardown has completed) and it is safe to
// free resources - most importantly, the stack it was running on.
void WaitForTaskGone(stk_task_t *task)
{
    stk_task_t *buf[STK_C_KERNEL_MAX_TASKS];
 
    for (;;)
    {
        const std::size_t n = stk_kernel_enumerate_tasks(s_BoundKernel, buf, STK_C_KERNEL_MAX_TASKS);
 
        bool found = false;
        for (std::size_t i = 0U; i < n; ++i)
        {
            if (buf[i] == task)
            {
                found = true;
                break;
            }
        }
 
        if (!found)
        {
            break;
        }
 
        stk_sleep_ms(1);
    }
}
 
void ReleaseThreadResources(ThreadCtrl *ctrl)
{
    if (ctrl->done_event != nullptr)
    {
        stk_event_destroy(ctrl->done_event);
        ctrl->done_event = nullptr;
    }
 
    if (ctrl->stack_owned && (ctrl->stack != nullptr))
    {
        if (ctrl->stack_from_pool)
        {
            (void)stk_blockpool_free(s_StackPool, ctrl->stack);
        }
        else
        {
            free(ctrl->stack);
        }
    }
    ctrl->stack = nullptr;
 
    stk_critical_section_enter();
    ctrl->busy = false;
    stk_critical_section_exit();
}
 
// -----------------------------------------------------------------------------
// Trampoline
// -----------------------------------------------------------------------------
void PthreadTrampoline(void *arg)
{
    ThreadCtrl *const ctrl = static_cast<ThreadCtrl *>(arg);
 
    stk_tls_set(ctrl);
 
    void *const result = ctrl->start_routine(ctrl->arg);
 
    RunKeyDestructors(ctrl);
 
    stk_critical_section_enter();
    ctrl->retval   = result;
    ctrl->finished = true;
    stk_critical_section_exit();
 
    stk_event_set(ctrl->done_event);
    MaybeReap(ctrl);
 
    // Natural return: STK finishes/frees the underlying dynamic task automatically.
    // A joiner (or the reaper, for detached threads) reclaims *our* resources
    // (stack, control block) only after confirming via WaitForTaskGone() that this
    // task has fully left the kernel's task list.
}
 
// -----------------------------------------------------------------------------
// Absolute-deadline -> relative-timeout helper
//
// STK has no wall clock; abstime is interpreted as a point on the same timeline as
// stk_time_now_ms() (see the "timedwait limitation" note in stk_c_pthread.h).
// -----------------------------------------------------------------------------
stk_timeout_t TimespecToRelativeTimeout(const struct timespec *abstime)
{
    const stk_time_t now_ms    = stk_time_now_ms();
    const stk_time_t target_ms = (static_cast<stk_time_t>(abstime->tv_sec) * 1000LL) +
                                  (static_cast<stk_time_t>(abstime->tv_nsec) / 1000000LL);
 
    stk_time_t rel_ms = target_ms - now_ms;
    if (rel_ms < 0LL)
    {
        rel_ms = 0LL;
    }
    if (rel_ms > static_cast<stk_time_t>(INT32_MAX))
    {
        rel_ms = static_cast<stk_time_t>(INT32_MAX);
    }
 
    return stk_ticks_from_ms_clamped_to_timeout(static_cast<stk_timeout_t>(rel_ms));
}
 
stk_mutex_t *EnsureMutex(pthread_mutex_t *m)
{
    if (m->__handle == nullptr)
    {
        stk_critical_section_enter();
        if (m->__handle == nullptr)
        {
            m->__handle = stk_mutex_create(&m->__mem, sizeof(m->__mem));
        }
        stk_critical_section_exit();
    }
 
    return m->__handle;
}
 
stk_cv_t *EnsureCond(pthread_cond_t *c)
{
    if (c->__handle == nullptr)
    {
        stk_critical_section_enter();
        if (c->__handle == nullptr)
        {
            c->__handle = stk_cv_create(&c->__mem, sizeof(c->__mem));
        }
        stk_critical_section_exit();
    }
 
    return c->__handle;
}
 
stk_rwmutex_t *EnsureRWLock(pthread_rwlock_t *rw)
{
    if (rw->__handle == nullptr)
    {
        stk_critical_section_enter();
        if (rw->__handle == nullptr)
        {
            rw->__handle = stk_rwmutex_create(&rw->__mem, sizeof(rw->__mem));
        }
        stk_critical_section_exit();
    }
 
    return rw->__handle;
}
 
stk_mutex_t *EnsureOnceMutex(pthread_once_t *o)
{
    if (o->__handle == nullptr)
    {
        stk_critical_section_enter();
        if (o->__handle == nullptr)
        {
            o->__handle = stk_mutex_create(&o->__mem, sizeof(o->__mem));
        }
        stk_critical_section_exit();
    }
 
    return o->__handle;
}
 
// -----------------------------------------------------------------------------
// Thread-specific data (keys)
// -----------------------------------------------------------------------------
struct KeyEntry
{
    bool  used;
    void (*destructor)(void *);
};
 
KeyEntry s_Keys[STK_C_PTHREAD_KEYS_MAX];
 
// Runs at thread termination (natural return or pthread_exit()) for a thread that
// was created via pthread_create() - see the "thread-specific data limitation"
// note in stk_c_pthread.h. Mirrors POSIX: each pass calls the destructor for every
// key whose value is currently non-NULL (clearing the value first, so a
// destructor that reads it back via pthread_getspecific() sees NULL), and repeats
// while any destructor call left a *new* non-NULL value, up to
// PTHREAD_DESTRUCTOR_ITERATIONS passes.
void RunKeyDestructors(ThreadCtrl *ctrl)
{
    for (int iter = 0; iter < PTHREAD_DESTRUCTOR_ITERATIONS; ++iter)
    {
        bool any_ran = false;
 
        for (std::size_t i = 0U; i < STK_C_PTHREAD_KEYS_MAX; ++i)
        {
            void *const value = ctrl->tsd[i];
            if (value == nullptr) { continue; }
 
            void (*destructor)(void *) = nullptr;
            stk_critical_section_enter();
            if (s_Keys[i].used) { destructor = s_Keys[i].destructor; }
            stk_critical_section_exit();
 
            ctrl->tsd[i] = nullptr; // clear before calling, per POSIX
            if (destructor != nullptr)
            {
                destructor(value);
                any_ran = true;
            }
        }
 
        if (!any_ran) { break; }
    }
}
 
} // anonymous namespace
 
// =============================================================================
// C-interface
// =============================================================================
extern "C" {
 
// -----------------------------------------------------------------------------
// Bootstrap
// -----------------------------------------------------------------------------
void stk_pthread_bind_kernel(stk_kernel_t *kernel)
{
    STK_C_ASSERT(kernel != nullptr);
 
    s_BoundKernel = kernel;
}
 
// -----------------------------------------------------------------------------
// Thread attributes
// -----------------------------------------------------------------------------
int pthread_attr_init(pthread_attr_t *attr)
{
    if (attr == nullptr) { return EINVAL; }
 
    attr->__stack_bytes = 0U;
    attr->__ext_stack   = nullptr;
    attr->__detachstate = PTHREAD_CREATE_JOINABLE;
    return 0;
}
 
int pthread_attr_destroy(pthread_attr_t *attr)
{
    if (attr == nullptr) { return EINVAL; }
    return 0;
}
 
int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize)
{
    if ((attr == nullptr) || (stacksize == 0U)) { return EINVAL; }
 
    attr->__stack_bytes = stacksize;
    return 0;
}
 
int pthread_attr_getstacksize(const pthread_attr_t *attr, size_t *stacksize)
{
    if ((attr == nullptr) || (stacksize == nullptr)) { return EINVAL; }
 
    *stacksize = (attr->__stack_bytes != 0U) ? attr->__stack_bytes : kDefaultStackBytes;
    return 0;
}
 
int pthread_attr_setstack(pthread_attr_t *attr, void *stackaddr, size_t stacksize)
{
    if ((attr == nullptr) || (stackaddr == nullptr) || (stacksize < sizeof(stk_word_t))) { return EINVAL; }
    if ((reinterpret_cast<uintptr_t>(stackaddr) & STK_ALIGN_MASK) != 0U) { return EINVAL; }
 
    attr->__ext_stack   = static_cast<stk_word_t *>(stackaddr);
    attr->__stack_bytes = stacksize;
    return 0;
}
 
int pthread_attr_getstack(const pthread_attr_t *attr, void **stackaddr, size_t *stacksize)
{
    if ((attr == nullptr) || (stackaddr == nullptr) || (stacksize == nullptr)) { return EINVAL; }
 
    *stackaddr = attr->__ext_stack;
    *stacksize = attr->__stack_bytes;
    return 0;
}
 
int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate)
{
    if ((attr == nullptr) ||
        ((detachstate != PTHREAD_CREATE_JOINABLE) && (detachstate != PTHREAD_CREATE_DETACHED)))
    {
        return EINVAL;
    }
 
    attr->__detachstate = detachstate;
    return 0;
}
 
int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *detachstate)
{
    if ((attr == nullptr) || (detachstate == nullptr)) { return EINVAL; }
 
    *detachstate = attr->__detachstate;
    return 0;
}
 
// -----------------------------------------------------------------------------
// Thread lifecycle
// -----------------------------------------------------------------------------
int pthread_create(pthread_t *thread, const pthread_attr_t *attr,
                    void *(*start_routine)(void *), void *arg)
{
    STK_C_ASSERT(s_BoundKernel != nullptr);
    STK_C_ASSERT(thread != nullptr);
    STK_C_ASSERT(start_routine != nullptr);
 
    if ((s_BoundKernel == nullptr) || (thread == nullptr) || (start_routine == nullptr))
    {
        return EINVAL;
    }
 
    pthread_stk_ctrl_t *const ctrl = AcquireThreadSlot();
    if (ctrl == nullptr)
    {
        return EAGAIN;
    }
 
    const size_t stack_bytes = ((attr != nullptr) && (attr->__stack_bytes != 0U)) ?
        attr->__stack_bytes : kDefaultStackBytes;
    const uint32_t stack_words =
        static_cast<uint32_t>((stack_bytes + sizeof(stk_word_t) - 1U) / sizeof(stk_word_t));
 
    if ((attr != nullptr) && (attr->__ext_stack != nullptr))
    {
        ctrl->stack           = attr->__ext_stack;
        ctrl->stack_owned      = false;
        ctrl->stack_from_pool  = false;
    }
    else if (stack_bytes == kDefaultStackBytes)
    {
        stk_blockpool_t *const pool = EnsureStackPool();
        void *const blk = (pool != nullptr) ? stk_blockpool_try_alloc(pool) : nullptr;
        if (blk != nullptr)
        {
            ctrl->stack          = static_cast<stk_word_t *>(blk);
            ctrl->stack_owned     = true;
            ctrl->stack_from_pool = true;
        }
        else
        {
            ctrl->stack          = static_cast<stk_word_t *>(malloc(stack_bytes));
            ctrl->stack_owned     = true;
            ctrl->stack_from_pool = false;
        }
    }
    else
    {
        ctrl->stack          = static_cast<stk_word_t *>(malloc(stack_bytes));
        ctrl->stack_owned     = true;
        ctrl->stack_from_pool = false;
    }
 
    if (ctrl->stack == nullptr)
    {
        stk_critical_section_enter();
        ctrl->busy = false;
        stk_critical_section_exit();
        return EAGAIN;
    }
 
    ctrl->start_routine = start_routine;
    ctrl->arg            = arg;
    ctrl->retval          = nullptr;
    ctrl->detached        = ((attr != nullptr) && (attr->__detachstate == PTHREAD_CREATE_DETACHED));
 
    ctrl->done_event = stk_event_create(&ctrl->done_event_mem, sizeof(ctrl->done_event_mem),
                                        true /* manual_reset */);
 
    ctrl->task = stk_task_create_user(PthreadTrampoline, ctrl, ctrl->stack, stack_words);
    if (ctrl->task == nullptr)
    {
        if (ctrl->done_event != nullptr) { stk_event_destroy(ctrl->done_event); }
        if (ctrl->stack_owned)
        {
            if (ctrl->stack_from_pool) { (void)stk_blockpool_free(s_StackPool, ctrl->stack); }
            else                       { free(ctrl->stack); }
        }
        stk_critical_section_enter();
        ctrl->busy = false;
        stk_critical_section_exit();
        return EAGAIN;
    }
 
    EnsureReaper();
 
    stk_kernel_add_task(s_BoundKernel, ctrl->task);
 
    *thread = ctrl;
    return 0;
}
 
int pthread_join(pthread_t thread, void **retval)
{
    pthread_stk_ctrl_t *const ctrl = thread;
    if (ctrl == nullptr) { return EINVAL; }
 
    bool ok = false;
    stk_critical_section_enter();
    if (!ctrl->detached && !ctrl->joined)
    {
        ctrl->joined = true;
        ok = true;
    }
    stk_critical_section_exit();
 
    if (!ok) { return EINVAL; }
 
    stk_event_wait(ctrl->done_event, STK_WAIT_INFINITE);
 
    if (retval != nullptr)
    {
        *retval = ctrl->retval;
    }
 
    WaitForTaskGone(ctrl->task);
    ReleaseThreadResources(ctrl);
    return 0;
}
 
int pthread_detach(pthread_t thread)
{
    pthread_stk_ctrl_t *const ctrl = thread;
    if (ctrl == nullptr) { return EINVAL; }
 
    bool ok = false;
    stk_critical_section_enter();
    if (!ctrl->joined && !ctrl->detached)
    {
        ctrl->detached = true;
        ok = true;
    }
    stk_critical_section_exit();
 
    if (!ok) { return EINVAL; }
 
    MaybeReap(ctrl);
    return 0;
}
 
void pthread_exit(void *retval)
{
    pthread_stk_ctrl_t *const ctrl = static_cast<pthread_stk_ctrl_t *>(stk_tls_get());
 
    if (ctrl != nullptr)
    {
        RunKeyDestructors(ctrl);
 
        stk_critical_section_enter();
        ctrl->retval   = retval;
        ctrl->finished = true;
        stk_critical_section_exit();
 
        stk_event_set(ctrl->done_event);
        MaybeReap(ctrl);
 
        STK_C_ASSERT(s_BoundKernel != nullptr);
        stk_kernel_schedule_task_removal(s_BoundKernel, ctrl->task);
    }
 
    // Safety net: if the task is somehow still running past the removal request
    // (or ctrl was NULL, i.e. this wasn't called from a pthread_create()'d thread),
    // park here instead of falling back into caller code that isn't expecting to
    // regain control.
    for (;;)
    {
        stk_sleep(STK_WAIT_INFINITE);
    }
}
 
pthread_t pthread_self(void)
{
    return static_cast<pthread_t>(stk_tls_get());
}
 
int pthread_equal(pthread_t t1, pthread_t t2)
{
    return (t1 == t2) ? 1 : 0;
}
 
int pthread_yield(void)
{
    stk_yield();
    return 0;
}
 
// -----------------------------------------------------------------------------
// Mutex
// -----------------------------------------------------------------------------
int pthread_mutexattr_init(pthread_mutexattr_t *attr)
{
    if (attr == nullptr) { return EINVAL; }
 
    attr->__type = PTHREAD_MUTEX_DEFAULT;
    return 0;
}
 
int pthread_mutexattr_destroy(pthread_mutexattr_t *attr)
{
    if (attr == nullptr) { return EINVAL; }
    return 0;
}
 
int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type)
{
    if (attr == nullptr) { return EINVAL; }
    if (type != PTHREAD_MUTEX_NORMAL) { return ENOTSUP; }
 
    attr->__type = type;
    return 0;
}
 
int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type)
{
    if ((attr == nullptr) || (type == nullptr)) { return EINVAL; }
 
    *type = attr->__type;
    return 0;
}
 
int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *attr)
{
    if (mutex == nullptr) { return EINVAL; }
    if ((attr != nullptr) && (attr->__type != PTHREAD_MUTEX_NORMAL)) { return ENOTSUP; }
 
    mutex->__handle = stk_mutex_create(&mutex->__mem, sizeof(mutex->__mem));
    return (mutex->__handle != nullptr) ? 0 : EAGAIN;
}
 
int pthread_mutex_destroy(pthread_mutex_t *mutex)
{
    if (mutex == nullptr) { return EINVAL; }
 
    if (mutex->__handle != nullptr)
    {
        stk_mutex_destroy(mutex->__handle);
        mutex->__handle = nullptr;
    }
    return 0;
}
 
int pthread_mutex_lock(pthread_mutex_t *mutex)
{
    if (mutex == nullptr) { return EINVAL; }
 
    stk_mutex_lock(EnsureMutex(mutex));
    return 0;
}
 
int pthread_mutex_trylock(pthread_mutex_t *mutex)
{
    if (mutex == nullptr) { return EINVAL; }
 
    return stk_mutex_trylock(EnsureMutex(mutex)) ? 0 : EBUSY;
}
 
int pthread_mutex_unlock(pthread_mutex_t *mutex)
{
    if (mutex == nullptr) { return EINVAL; }
    if (mutex->__handle == nullptr) { return EINVAL; }
 
    stk_mutex_unlock(mutex->__handle);
    return 0;
}
 
int pthread_mutex_timedlock(pthread_mutex_t *mutex, const struct timespec *abstime)
{
    if ((mutex == nullptr) || (abstime == nullptr)) { return EINVAL; }
 
    const bool locked = stk_mutex_timed_lock(EnsureMutex(mutex), TimespecToRelativeTimeout(abstime));
    return locked ? 0 : ETIMEDOUT;
}
 
// -----------------------------------------------------------------------------
// Condition variable
// -----------------------------------------------------------------------------
int pthread_condattr_init(pthread_condattr_t *attr)
{
    if (attr == nullptr) { return EINVAL; }
 
    attr->__reserved = 0;
    return 0;
}
 
int pthread_condattr_destroy(pthread_condattr_t *attr)
{
    if (attr == nullptr) { return EINVAL; }
    return 0;
}
 
int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t * /*attr*/)
{
    if (cond == nullptr) { return EINVAL; }
 
    cond->__handle = stk_cv_create(&cond->__mem, sizeof(cond->__mem));
    return (cond->__handle != nullptr) ? 0 : EAGAIN;
}
 
int pthread_cond_destroy(pthread_cond_t *cond)
{
    if (cond == nullptr) { return EINVAL; }
 
    if (cond->__handle != nullptr)
    {
        stk_cv_destroy(cond->__handle);
        cond->__handle = nullptr;
    }
    return 0;
}
 
int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex)
{
    if ((cond == nullptr) || (mutex == nullptr) || (mutex->__handle == nullptr)) { return EINVAL; }
 
    (void)stk_cv_wait(EnsureCond(cond), mutex->__handle, STK_WAIT_INFINITE);
    return 0;
}
 
int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime)
{
    if ((cond == nullptr) || (mutex == nullptr) || (mutex->__handle == nullptr) || (abstime == nullptr))
    {
        return EINVAL;
    }
 
    const bool signaled = stk_cv_wait(EnsureCond(cond), mutex->__handle, TimespecToRelativeTimeout(abstime));
    return signaled ? 0 : ETIMEDOUT;
}
 
int pthread_cond_signal(pthread_cond_t *cond)
{
    if (cond == nullptr) { return EINVAL; }
 
    stk_cv_notify_one(EnsureCond(cond));
    return 0;
}
 
int pthread_cond_broadcast(pthread_cond_t *cond)
{
    if (cond == nullptr) { return EINVAL; }
 
    stk_cv_notify_all(EnsureCond(cond));
    return 0;
}
 
// -----------------------------------------------------------------------------
// Read-write lock
// -----------------------------------------------------------------------------
int pthread_rwlockattr_init(pthread_rwlockattr_t *attr)
{
    if (attr == nullptr) { return EINVAL; }
 
    attr->__reserved = 0;
    return 0;
}
 
int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr)
{
    if (attr == nullptr) { return EINVAL; }
    return 0;
}
 
int pthread_rwlock_init(pthread_rwlock_t *rwlock, const pthread_rwlockattr_t * /*attr*/)
{
    if (rwlock == nullptr) { return EINVAL; }
 
    rwlock->__handle   = stk_rwmutex_create(&rwlock->__mem, sizeof(rwlock->__mem));
    rwlock->__wrlocked = false;
    return (rwlock->__handle != nullptr) ? 0 : EAGAIN;
}
 
int pthread_rwlock_destroy(pthread_rwlock_t *rwlock)
{
    if (rwlock == nullptr) { return EINVAL; }
 
    if (rwlock->__handle != nullptr)
    {
        stk_rwmutex_destroy(rwlock->__handle);
        rwlock->__handle = nullptr;
    }
    return 0;
}
 
int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock)
{
    if (rwlock == nullptr) { return EINVAL; }
 
    stk_rwmutex_read_lock(EnsureRWLock(rwlock));
    return 0;
}
 
int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock)
{
    if (rwlock == nullptr) { return EINVAL; }
 
    return stk_rwmutex_try_read_lock(EnsureRWLock(rwlock)) ? 0 : EBUSY;
}
 
int pthread_rwlock_timedrdlock(pthread_rwlock_t *rwlock, const struct timespec *abstime)
{
    if ((rwlock == nullptr) || (abstime == nullptr)) { return EINVAL; }
 
    const bool locked = stk_rwmutex_timed_read_lock(EnsureRWLock(rwlock), TimespecToRelativeTimeout(abstime));
    return locked ? 0 : ETIMEDOUT;
}
 
int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock)
{
    if (rwlock == nullptr) { return EINVAL; }
 
    stk_rwmutex_lock(EnsureRWLock(rwlock));
    rwlock->__wrlocked = true;
    return 0;
}
 
int pthread_rwlock_trywrlock(pthread_rwlock_t *rwlock)
{
    if (rwlock == nullptr) { return EINVAL; }
 
    if (!stk_rwmutex_trylock(EnsureRWLock(rwlock))) { return EBUSY; }
 
    rwlock->__wrlocked = true;
    return 0;
}
 
int pthread_rwlock_timedwrlock(pthread_rwlock_t *rwlock, const struct timespec *abstime)
{
    if ((rwlock == nullptr) || (abstime == nullptr)) { return EINVAL; }
 
    if (!stk_rwmutex_timed_lock(EnsureRWLock(rwlock), TimespecToRelativeTimeout(abstime))) { return ETIMEDOUT; }
 
    rwlock->__wrlocked = true;
    return 0;
}
 
int pthread_rwlock_unlock(pthread_rwlock_t *rwlock)
{
    if (rwlock == nullptr) { return EINVAL; }
    if (rwlock->__handle == nullptr) { return EINVAL; }
 
    // See "pthread_rwlock_unlock() disambiguation" in stk_c_pthread.h: a write
    // hold is always exclusive, so __wrlocked unambiguously identifies which
    // underlying call the current holder must have made. Clear it before
    // releasing so a racing new writer's own acquisition can't be clobbered.
    if (rwlock->__wrlocked)
    {
        rwlock->__wrlocked = false;
        stk_rwmutex_unlock(rwlock->__handle);
    }
    else
    {
        stk_rwmutex_read_unlock(rwlock->__handle);
    }
    return 0;
}
 
// -----------------------------------------------------------------------------
// Spin lock
// -----------------------------------------------------------------------------
int pthread_spin_init(pthread_spinlock_t *lock, int pshared)
{
    if (lock == nullptr) { return EINVAL; }
    if (pshared != PTHREAD_PROCESS_PRIVATE) { return ENOTSUP; }
 
    lock->__handle = stk_spinlock_create(&lock->__mem, sizeof(lock->__mem));
    return (lock->__handle != nullptr) ? 0 : EAGAIN;
}
 
int pthread_spin_destroy(pthread_spinlock_t *lock)
{
    if (lock == nullptr) { return EINVAL; }
 
    if (lock->__handle != nullptr)
    {
        stk_spinlock_destroy(lock->__handle);
        lock->__handle = nullptr;
    }
    return 0;
}
 
int pthread_spin_lock(pthread_spinlock_t *lock)
{
    if ((lock == nullptr) || (lock->__handle == nullptr)) { return EINVAL; }
 
    stk_spinlock_lock(lock->__handle);
    return 0;
}
 
int pthread_spin_trylock(pthread_spinlock_t *lock)
{
    if ((lock == nullptr) || (lock->__handle == nullptr)) { return EINVAL; }
 
    return stk_spinlock_trylock(lock->__handle) ? 0 : EBUSY;
}
 
int pthread_spin_unlock(pthread_spinlock_t *lock)
{
    if ((lock == nullptr) || (lock->__handle == nullptr)) { return EINVAL; }
 
    stk_spinlock_unlock(lock->__handle);
    return 0;
}
 
// -----------------------------------------------------------------------------
// Barrier
// -----------------------------------------------------------------------------
int pthread_barrierattr_init(pthread_barrierattr_t *attr)
{
    if (attr == nullptr) { return EINVAL; }
 
    attr->__reserved = 0;
    return 0;
}
 
int pthread_barrierattr_destroy(pthread_barrierattr_t *attr)
{
    if (attr == nullptr) { return EINVAL; }
    return 0;
}
 
int pthread_barrier_init(pthread_barrier_t *barrier, const pthread_barrierattr_t * /*attr*/,
                          unsigned int count)
{
    if (barrier == nullptr) { return EINVAL; }
    if (count == 0U) { return EINVAL; }
 
    barrier->__handle = stk_barrier_create(&barrier->__mem, sizeof(barrier->__mem),
                                            static_cast<uint32_t>(count));
    return (barrier->__handle != nullptr) ? 0 : EAGAIN;
}
 
int pthread_barrier_destroy(pthread_barrier_t *barrier)
{
    if (barrier == nullptr) { return EINVAL; }
 
    if (barrier->__handle != nullptr)
    {
        stk_barrier_destroy(barrier->__handle);
        barrier->__handle = nullptr;
    }
    return 0;
}
 
int pthread_barrier_wait(pthread_barrier_t *barrier)
{
    if ((barrier == nullptr) || (barrier->__handle == nullptr)) { return EINVAL; }
 
    return stk_barrier_wait(barrier->__handle) ? PTHREAD_BARRIER_SERIAL_THREAD : 0;
}
 
// -----------------------------------------------------------------------------
// Once
// -----------------------------------------------------------------------------
int pthread_once(pthread_once_t *once_control, void (*init_routine)(void))
{
    if ((once_control == nullptr) || (init_routine == nullptr)) { return EINVAL; }
 
    if (once_control->__state == 2) { return 0; } // fast path: already done, no lock needed
 
    stk_mutex_t *const guard = EnsureOnceMutex(once_control);
    stk_mutex_lock(guard);
 
    // Re-check under the lock: another thread may have finished init_routine()
    // (or be running it right now, in which case this lock() call already blocked
    // until it was done) between our unlocked fast-path check above and here.
    if (once_control->__state != 2)
    {
        once_control->__state = 1;
        init_routine();
        once_control->__state = 2;
    }
 
    stk_mutex_unlock(guard);
    return 0;
}
 
// -----------------------------------------------------------------------------
// Thread-specific data (keys)
// -----------------------------------------------------------------------------
int pthread_key_create(pthread_key_t *key, void (*destructor)(void *))
{
    if (key == nullptr) { return EINVAL; }
 
    int result = EAGAIN;
 
    stk_critical_section_enter();
    for (std::size_t i = 0U; i < STK_C_PTHREAD_KEYS_MAX; ++i)
    {
        if (!s_Keys[i].used)
        {
            s_Keys[i].used       = true;
            s_Keys[i].destructor = destructor;
            *key                 = static_cast<pthread_key_t>(i);
            result               = 0;
            break;
        }
    }
    stk_critical_section_exit();
 
    return result;
}
 
int pthread_key_delete(pthread_key_t key)
{
    if (key >= STK_C_PTHREAD_KEYS_MAX) { return EINVAL; }
 
    int result = EINVAL;
 
    stk_critical_section_enter();
    if (s_Keys[key].used)
    {
        s_Keys[key].used       = false;
        s_Keys[key].destructor = nullptr;
        result                 = 0;
    }
    stk_critical_section_exit();
 
    return result;
}
 
int pthread_setspecific(pthread_key_t key, const void *value)
{
    if ((key >= STK_C_PTHREAD_KEYS_MAX) || !s_Keys[key].used) { return EINVAL; }
 
    ThreadCtrl *const ctrl = static_cast<ThreadCtrl *>(stk_tls_get());
    if (ctrl == nullptr) { return EINVAL; } // not a pthread_create()'d task; see file docs
 
    ctrl->tsd[key] = const_cast<void *>(value);
    return 0;
}
 
void *pthread_getspecific(pthread_key_t key)
{
    if ((key >= STK_C_PTHREAD_KEYS_MAX) || !s_Keys[key].used) { return nullptr; }
 
    ThreadCtrl *const ctrl = static_cast<ThreadCtrl *>(stk_tls_get());
    if (ctrl == nullptr) { return nullptr; } // not a pthread_create()'d task; see file docs
 
    return ctrl->tsd[key];
}
 
// =============================================================================
} // extern "C"
// =============================================================================