rte_posix_osadapter_period.c

Go to the documentation of this file.

/* _POSIX_C_SOURCE: glibc declares clock_gettime(), pthread_condattr_setclock() and PTHREAD_PRIO_INHERIT only under a
 * POSIX feature-test macro (this product builds strict C99), same as the other src/ files. _DARWIN_C_SOURCE (macOS
 * only): with _POSIX_C_SOURCE set, macOS's <pthread.h> declares pthread_cond_timedwait_relative_np() only under it. */
#define _POSIX_C_SOURCE 200809L
#if defined(__APPLE__)
#define _DARWIN_C_SOURCE
#endif

#include "rte_posix_osadapter_period.h"
#include "rte_posix_osadapter_lock.h"
#include "rte_posix_osadapter_report.h"
 
#include <errno.h>
#include <pthread.h>
#include <signal.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>

#define POSIX_PERIOD_NS_PER_MS 1000000L
#define POSIX_PERIOD_NS_PER_S  1000000000L
/* Result of a wait step that failed outside pthread_cond_*wait() (clock read, mutex release); any value other than 0
 * and ETIMEDOUT ends the wait with RTE_STATUS_INTERNAL_ERROR. */
#define POSIX_PERIOD_WAIT_FAILED (-1)
/* Longest wait of posix_period_wake_all() for the wake mutex, in ms (OSA rule R2). The holders only check a flag,
 * broadcast or start a wait, so this is far above a hold time; on expiry the stop falls back to the deadline (see the
 * header). Overridable at compile time like RTE_POSIX_MEM_LOCK_TIMEOUT_MS. */
#ifndef RTE_POSIX_PERIOD_WAKE_LOCK_TIMEOUT_MS
#define RTE_POSIX_PERIOD_WAKE_LOCK_TIMEOUT_MS 50U
#endif


static void create_wake_object(void);
static bool set_wake_clock(pthread_condattr_t *attr);
static bool time_left_ns(const struct timespec *deadline, int64_t *out_ns);
static rte_duration_ms_t ns_to_ms_rounded_up(int64_t ns);
static rte_status_t wait_to_deadline(const struct timespec *deadline, const volatile sig_atomic_t *should_stop);
static rte_status_t wait_locked(const struct timespec *deadline, const volatile sig_atomic_t *should_stop,
                                bool *out_waiting);
static int wait_for_wake(const struct timespec *deadline);

/* The process-wide wake object (see the header): created once by create_wake_object() through the pthread_once() in
 * posix_period_wake_ready(), never destroyed after a successful create. s_wake_ready is written only inside
 * pthread_once() and read after it returned. */
static pthread_mutex_t s_wake_lock;
static pthread_cond_t s_wake_cond;
static bool s_wake_ready = false;

 

rte_status_t posix_period_init(struct timespec *out_deadline)
{
    rte_status_t status = RTE_STATUS_INVALID_PARAM;
 
    if (out_deadline != NULL)
    {
        struct timespec now;
 
        /* Read into a local: a failed read leaves *out_deadline unwritten, it is never used as time 0. */
        if (clock_gettime(CLOCK_MONOTONIC, &now) == 0)
        {
            *out_deadline = now;
            status = RTE_STATUS_OK;
        }
        else
        {
            status = RTE_STATUS_INTERNAL_ERROR;
        }
    }
    return status;
}
 
void posix_period_advance(struct timespec *deadline, rte_duration_ms_t period_ms)
{
    if (deadline != NULL)
    {
        rte_duration_ms_t whole_s = period_ms / 1000U;
        rte_duration_ms_t rest_ms = period_ms % 1000U;
 
        deadline->tv_sec += (time_t)whole_s;
        deadline->tv_nsec += (long)rest_ms * POSIX_PERIOD_NS_PER_MS;
        if (deadline->tv_nsec >= POSIX_PERIOD_NS_PER_S)
        {
            deadline->tv_sec += 1;
            deadline->tv_nsec -= POSIX_PERIOD_NS_PER_S;
        }
    }
}
 
rte_status_t posix_period_sleep_until(const struct timespec *deadline, const volatile sig_atomic_t *should_stop)
{
    rte_status_t status = RTE_STATUS_INVALID_PARAM;
 
    if ((deadline != NULL) && (should_stop != NULL))
    {
        if (posix_period_wake_ready())
        {
            status = wait_to_deadline(deadline, should_stop);
        }
        else
        {
            status = RTE_STATUS_INTERNAL_ERROR; /* no wake object: never wait on an uninitialised mutex */
        }
    }
    return status;
}
 
bool posix_period_wake_ready(void)
{
    static pthread_once_t wake_once = PTHREAD_ONCE_INIT;
    bool ready = false;
 
    if (pthread_once(&wake_once, create_wake_object) == 0)
    {
        ready = s_wake_ready;
    }
    return ready;
}
 
void posix_period_wake_all(volatile sig_atomic_t *should_stop)
{
    if (should_stop != NULL)
    {
        bool locked = false;
 
        if (posix_period_wake_ready())
        {
            locked = (posix_osa_lock_bounded(&s_wake_lock, RTE_POSIX_PERIOD_WAKE_LOCK_TIMEOUT_MS) == RTE_STATUS_OK);
        }
        /* Stored under the mutex when it is held, so the waiter's check-then-wait cannot fall between this store and
         * the broadcast (header: why no wake-up is lost). Without the mutex the store still ends the thread at its
         * next deadline. */
        *should_stop = 1;
        if (locked)
        {
            /* A failed broadcast or release leaves the deadline fallback; nothing to report to the stopping caller. */
            (void)pthread_cond_broadcast(&s_wake_cond);
            (void)pthread_mutex_unlock(&s_wake_lock);
        }
    }
}
 
 
/****Local functions ****/

static void create_wake_object(void)
{
    pthread_mutexattr_t mutex_attr;
    pthread_condattr_t cond_attr;
    bool mutex_created = false;
    bool created = false;
 
    /* OSA rule R2 (REQ-OAL-MUTEX-004): priority inheritance requested at run time on every host, exactly as mutex.c's
     * create does (no _POSIX_THREAD_PRIO_INHERIT compile gate); no plain-mutex fallback. */
    if (pthread_mutexattr_init(&mutex_attr) == 0)
    {
        if (pthread_mutexattr_setprotocol(&mutex_attr, PTHREAD_PRIO_INHERIT) == 0)
        {
            mutex_created = (pthread_mutex_init(&s_wake_lock, &mutex_attr) == 0);
        }
        (void)pthread_mutexattr_destroy(&mutex_attr);
    }
 
    if (mutex_created)
    {
        if (pthread_condattr_init(&cond_attr) == 0)
        {
            if (set_wake_clock(&cond_attr))
            {
                created = (pthread_cond_init(&s_wake_cond, &cond_attr) == 0);
            }
            (void)pthread_condattr_destroy(&cond_attr);
        }
        if (!created)
        {
            (void)pthread_mutex_destroy(&s_wake_lock);
        }
    }
 
    s_wake_ready = created;
    if (!created)
    {
        /* OSA rule R2/R6: no bounded, wakeable wait possible - no timer or task is created without it. Reported once
         * (pthread_once()); every create then returns RTE_STATUS_INTERNAL_ERROR. */
        POSIX_OSA_REPORT_RT_ATTRIBUTE("period wake object refused - timer/task create failed");
    }
}
 
#if defined(__APPLE__)
static bool set_wake_clock(pthread_condattr_t *attr)
{
    (void)attr;
    return true;
}
#else
static bool set_wake_clock(pthread_condattr_t *attr)
{
    return (pthread_condattr_setclock(attr, CLOCK_MONOTONIC) == 0);
}
#endif

static bool time_left_ns(const struct timespec *deadline, int64_t *out_ns)
{
    bool read = false;
    struct timespec now;
 
    if (clock_gettime(CLOCK_MONOTONIC, &now) == 0)
    {
        *out_ns = (((int64_t)deadline->tv_sec - (int64_t)now.tv_sec) * POSIX_PERIOD_NS_PER_S) +
                  ((int64_t)deadline->tv_nsec - (int64_t)now.tv_nsec);
        read = true;
    }
    return read;
}

static rte_duration_ms_t ns_to_ms_rounded_up(int64_t ns)
{
    int64_t ms = (ns + (POSIX_PERIOD_NS_PER_MS - 1L)) / POSIX_PERIOD_NS_PER_MS;
    rte_duration_ms_t result = (rte_duration_ms_t)UINT32_MAX;
 
    if (ms < (int64_t)UINT32_MAX)
    {
        result = (rte_duration_ms_t)ms;
    }
    return result;
}

static rte_status_t wait_to_deadline(const struct timespec *deadline, const volatile sig_atomic_t *should_stop)
{
    rte_status_t status = RTE_STATUS_OK;
    bool waiting = (*should_stop == 0);
 
    while (waiting)
    {
        int64_t remaining_ns = 0;
 
        if (!time_left_ns(deadline, &remaining_ns))
        {
            status = RTE_STATUS_INTERNAL_ERROR; /* no time base - never wait against a guess */
            waiting = false;
        }
        else if (remaining_ns <= 0)
        {
            waiting = false; /* deadline reached or already passed (overrun): no wait */
        }
        else
        {
            rte_status_t lock_status = posix_osa_lock_bounded(&s_wake_lock, ns_to_ms_rounded_up(remaining_ns));
 
            if (lock_status == RTE_STATUS_OK)
            {
                status = wait_locked(deadline, should_stop, &waiting);
            }
            else if (lock_status == RTE_STATUS_TIMEOUT)
            {
                /* Not an error: the mutex stayed busy for the time left. The clock is read again at the top of the
                 * loop, so the deadline (not the lock bound, which Linux measures on CLOCK_REALTIME) decides. */
                waiting = (*should_stop == 0);
            }
            else
            {
                status = RTE_STATUS_INTERNAL_ERROR; /* a failed lock clock read or an error from the pthread call */
                waiting = false;
            }
        }
    }
    return status;
}

static rte_status_t wait_locked(const struct timespec *deadline, const volatile sig_atomic_t *should_stop,
                                bool *out_waiting)
{
    rte_status_t status = RTE_STATUS_OK;
    int rc = 0;
 
    /* Checked under the mutex the waker holds while it stores the flag and broadcasts: no wake-up can be lost. */
    if (*should_stop == 0)
    {
        rc = wait_for_wake(deadline);
    }
    *out_waiting = (*should_stop == 0);
    if (pthread_mutex_unlock(&s_wake_lock) != 0)
    {
        rc = POSIX_PERIOD_WAIT_FAILED;
    }
    if ((rc != 0) && (rc != ETIMEDOUT))
    {
        status = RTE_STATUS_INTERNAL_ERROR;
        *out_waiting = false;
    }
    return status;
}
 
#if defined(__APPLE__)
static int wait_for_wake(const struct timespec *deadline)
{
    int rc = ETIMEDOUT;
    int64_t remaining_ns = 0;
 
    if (!time_left_ns(deadline, &remaining_ns))
    {
        rc = POSIX_PERIOD_WAIT_FAILED;
    }
    else if (remaining_ns > 0)
    {
        struct timespec relative;
        int64_t whole_s = remaining_ns / POSIX_PERIOD_NS_PER_S;
        int64_t rest_ns = remaining_ns % POSIX_PERIOD_NS_PER_S;
 
        relative.tv_sec = (time_t)whole_s;
        relative.tv_nsec = (long)rest_ns;
        rc = pthread_cond_timedwait_relative_np(&s_wake_cond, &s_wake_lock, &relative);
    }
    else
    {
        /* deadline passed while the mutex was taken: rc stays ETIMEDOUT */
    }
    return rc;
}
#else
static int wait_for_wake(const struct timespec *deadline)
{
    return pthread_cond_timedwait(&s_wake_cond, &s_wake_lock, deadline);
}
#endif