rte_posix_osadapter_timer.c

Go to the documentation of this file.

#define _POSIX_C_SOURCE 200809L

#include "rte/posix_osadapter/rte_posix_osadapter.h"
#include "rte_posix_osadapter_period.h"
#include "rte_posix_osadapter_report.h"
 
#include <errno.h>
#include <limits.h>
#include <pthread.h>
#include <sched.h>
#include <signal.h>
#include <stdbool.h>
#include <stddef.h>
#include "rte/oal/memory/rte_mem_util.h"
#include <time.h>

/* Fixed stack size of every timer thread, in bytes (OSA rule R1): 8 MiB. That is the default thread stack glibc derives
 * from an 8192 KiB RLIMIT_STACK (`ulimit -s` in the RBC Docker images), so the Linux timer stack there is unchanged; on
 * macOS it is larger than the 512 KiB default of a secondary thread (virtual size, pages are committed on use).
 * Overridable at compile time like RTE_POSIX_MEM_ARENA_SIZE; a value below PTHREAD_STACK_MIN is raised to it. */
#ifndef RTE_POSIX_TIMER_STACK_SIZE
#define RTE_POSIX_TIMER_STACK_SIZE ((size_t)8388608U)
#endif

typedef struct
{
    pthread_t thread;
    rte_timer_config_t config;
    bool joinable;                     /* controlling thread only, see file header */
    volatile sig_atomic_t should_stop; /* the only field both threads write, see file header */
    rte_timer_handle_t self_handle;
} posix_timer_state_t;
 
/* C99-compatible static assert: posix_timer_state_t must fit inside
 * rte_timer_storage_t's reserved bytes (a negative array size is a
 * compile error). */
typedef char posix_timer_storage_fits_[(sizeof(posix_timer_state_t) <= sizeof(rte_timer_storage_t)) ? 1 : -1];

static void create_timer_key(void);
static bool timer_key_ready(void);
static void *timer_thread_main(void *arg);
static void run_timer_loop(posix_timer_state_t *state);
static bool is_timer_thread(const posix_timer_state_t *state);
static rte_status_t join_timer_thread(posix_timer_state_t *state);
static bool set_creator_sched_attributes(pthread_attr_t *attr);
static rte_status_t create_timer_thread(posix_timer_state_t *state);
static rte_status_t osadapter_create(rte_timer_storage_t *storage, const rte_timer_config_t *config,
                                     rte_timer_handle_t *out_handle);
static rte_status_t osadapter_stop(rte_timer_handle_t handle);
static rte_status_t osadapter_start(rte_timer_handle_t handle);
static rte_status_t osadapter_destroy(rte_timer_handle_t handle);
static rte_status_t osadapter_now(rte_timestamp_ms_t *out_now_ms);

static const rte_osadapter_timer_t s_posix_timer_osadapter = { osadapter_create, osadapter_start, osadapter_stop,
                                                              osadapter_destroy, osadapter_now };
 
/* The thread-specific-data key of the self check (file header): created once per process by
 * create_timer_key() through the pthread_once() in timer_key_ready(), never deleted. s_timer_key_ready is
 * written only inside pthread_once() and read after it returned. */
static pthread_key_t s_timer_key;
static bool s_timer_key_ready = false;

 

const rte_osadapter_timer_t *rte_posix_osadapter_timer(void)
{
    return &s_posix_timer_osadapter;
}
 
 
/****Local functions ****/

static void create_timer_key(void)
{
    s_timer_key_ready = (pthread_key_create(&s_timer_key, NULL) == 0);
}

static bool timer_key_ready(void)
{
    static pthread_once_t key_once = PTHREAD_ONCE_INIT;
    bool ready = false;
 
    if (pthread_once(&key_once, create_timer_key) == 0)
    {
        ready = s_timer_key_ready;
    }
    return ready;
}

static void *timer_thread_main(void *arg)
{
    posix_timer_state_t *state = (posix_timer_state_t *)arg;
 
    if (pthread_setspecific(s_timer_key, state) == 0)
    {
        run_timer_loop(state);
    }
    else
    {
        /* OSA rule R2/R6: no self check possible - a callback calling stop/start on its own timer could not be told
         * apart from another thread. Report and run no callback; the controlling thread still joins this thread. */
        POSIX_OSA_REPORT_RT_ATTRIBUTE("timer thread-specific data not set - timer not run");
    }
    /* The controlling thread learns that this thread ended from pthread_join(). */
    return NULL;
}

static void run_timer_loop(posix_timer_state_t *state)
{
    struct timespec deadline;
    bool running = (posix_period_init(&deadline) == RTE_STATUS_OK);
    bool clock_failed = !running;
 
    while (running)
    {
        posix_period_advance(&deadline, state->config.period_ms);
        if (posix_period_sleep_until(&deadline, &state->should_stop) != RTE_STATUS_OK)
        {
            clock_failed = true;
            running = false;
        }
        else if (state->should_stop != 0)
        {
            running = false;
        }
        else
        {
            state->config.callback(state->self_handle, state->config.user_ctx);
 
            /* A stop during the callback (from the callback itself or from another thread) ends the loop now, not one
             * period later: no further callback either way, and the joining thread does not wait for a period. */
            if ((state->config.mode != RTE_TIMER_MODE_PERIODIC) || (state->should_stop != 0))
            {
                running = false;
            }
        }
    }
 
    if (clock_failed)
    {
        /* OSA rule R3/R6: no monotonic time base - never pace from a guessed time 0. Report once; the controlling
         * thread still joins this thread. */
        POSIX_OSA_REPORT_RT_ATTRIBUTE("timer monotonic clock failed - timer stopped");
    }
}

static bool is_timer_thread(const posix_timer_state_t *state)
{
    return (pthread_getspecific(s_timer_key) == (const void *)state);
}

static rte_status_t join_timer_thread(posix_timer_state_t *state)
{
    rte_status_t status = RTE_STATUS_OK;
 
    if (state->joinable)
    {
        posix_period_wake_all(&state->should_stop);
        if (pthread_join(state->thread, NULL) == 0)
        {
            state->joinable = false;
        }
        else
        {
            status = RTE_STATUS_INTERNAL_ERROR;
        }
    }
    return status;
}

static bool set_creator_sched_attributes(pthread_attr_t *attr)
{
    bool applied = false;
    struct sched_param sched;
    int policy = 0;
 
    rte_mem_set(&sched, 0, sizeof(sched));
    if (pthread_getschedparam(pthread_self(), &policy, &sched) == 0)
    {
        if (pthread_attr_setinheritsched(attr, PTHREAD_EXPLICIT_SCHED) == 0)
        {
            if (pthread_attr_setschedpolicy(attr, policy) == 0)
            {
                if (pthread_attr_setschedparam(attr, &sched) == 0)
                {
                    applied = true;
                }
            }
        }
    }
    return applied;
}

static rte_status_t create_timer_thread(posix_timer_state_t *state)
{
    rte_status_t status = RTE_STATUS_INTERNAL_ERROR;
    pthread_attr_t attr;
 
    if (pthread_attr_init(&attr) == 0)
    {
        bool inherit_fallback = false;
        int rc = -1;
        size_t stack_size = (size_t)RTE_POSIX_TIMER_STACK_SIZE;
 
#if defined(PTHREAD_STACK_MIN)
        if (stack_size < (size_t)PTHREAD_STACK_MIN)
        {
            stack_size = (size_t)PTHREAD_STACK_MIN;
        }
#endif
        if (pthread_attr_setstacksize(&attr, stack_size) != 0)
        {
            /* OSA rule R1: fixed stack size - report that it was refused; the default stack is used. */
            POSIX_OSA_REPORT_RT_ATTRIBUTE("timer stack size not applied");
        }
 
        if (set_creator_sched_attributes(&attr))
        {
            rc = pthread_create(&state->thread, &attr, timer_thread_main, state);
            if (rc == EPERM)
            {
                /* The explicit-sched attributes were refused; no thread was created. */
                inherit_fallback = true;
            }
        }
        else
        {
            inherit_fallback = true;
        }
 
        if (inherit_fallback)
        {
            /* OSA rule R1/R6: scheduling not fixed at creation - report once per start, then create the thread under
             * inherited scheduling (ADR-018 fallback, the behaviour before attributes were set); stack size kept. */
            POSIX_OSA_REPORT_RT_ATTRIBUTE("timer scheduling not applied");
            rc = -1;
            if (pthread_attr_setinheritsched(&attr, PTHREAD_INHERIT_SCHED) == 0)
            {
                rc = pthread_create(&state->thread, &attr, timer_thread_main, state);
            }
        }
 
        if (rc == 0)
        {
            status = RTE_STATUS_OK;
        }
        (void)pthread_attr_destroy(&attr);
    }
    return status;
}
 
static rte_status_t osadapter_create(rte_timer_storage_t *storage, const rte_timer_config_t *config,
                                     rte_timer_handle_t *out_handle)
{
    posix_timer_state_t *state;
    bool ready;
 
    if ((storage == NULL) || (config == NULL) || (out_handle == NULL) || (config->callback == NULL)
        || (config->period_ms == 0U))
    {
        return RTE_STATUS_INVALID_PARAM;
    }
    ready = timer_key_ready();
    if (ready)
    {
        ready = posix_period_wake_ready();
    }
    if (!ready)
    {
        /* The self-check key or the period wake object could not be created (file header): no timer without them;
         * storage left untouched. */
        return RTE_STATUS_INTERNAL_ERROR;
    }
 
    state = (posix_timer_state_t *)(void *)storage;
    rte_mem_set(state, 0, sizeof(*state));
    state->config = *config;
    state->self_handle = (rte_timer_handle_t)(void *)storage;
    *out_handle = state->self_handle;
    return RTE_STATUS_OK;
}
 
static rte_status_t osadapter_stop(rte_timer_handle_t handle)
{
    posix_timer_state_t *state = (posix_timer_state_t *)(void *)handle;
    rte_status_t status;
 
    if (state == NULL)
    {
        return RTE_STATUS_INVALID_PARAM;
    }
    /* Set (and the waiting thread woken) before the self check, so the timer loop ends whichever branch is taken. On
     * the join branch join_timer_thread() sets it and wakes once more, which is harmless. */
    posix_period_wake_all(&state->should_stop);
    if (is_timer_thread(state))
    {
        /* Self-call rule (file header): the timer thread cannot join itself. It ends after this callback; the next
         * stop/start/destroy from another thread joins it. */
        status = RTE_STATUS_OK;
    }
    else
    {
        status = join_timer_thread(state);
    }
    return status;
}
 
static rte_status_t osadapter_start(rte_timer_handle_t handle)
{
    posix_timer_state_t *state = (posix_timer_state_t *)(void *)handle;
    rte_status_t status;
 
    if (state == NULL)
    {
        return RTE_STATUS_INVALID_PARAM;
    }
 
    if (is_timer_thread(state))
    {
        /* Self-call rule (file header): a restart from the timer's own callback would leave this thread running next
         * to the new one. Refused, nothing changed. */
        status = RTE_STATUS_NOT_SUPPORTED;
    }
    else
    {
        /* rte_timer_start() on a timer whose thread exists (running, or a one-shot that has fired) means "restart":
         * join the old thread before starting a fresh one. */
        status = join_timer_thread(state);
        if (status == RTE_STATUS_OK)
        {
            state->should_stop = 0;
            status = create_timer_thread(state);
            if (status == RTE_STATUS_OK)
            {
                state->joinable = true;
            }
        }
    }
    return status;
}
 
static rte_status_t osadapter_destroy(rte_timer_handle_t handle)
{
    return osadapter_stop(handle);
}
 
static rte_status_t osadapter_now(rte_timestamp_ms_t *out_now_ms)
{
    struct timespec ts;
 
    if (out_now_ms == NULL)
    {
        return RTE_STATUS_INVALID_PARAM;
    }
    if (clock_gettime(CLOCK_MONOTONIC, &ts) != 0)
    {
        *out_now_ms = 0U;
        return RTE_STATUS_INTERNAL_ERROR;
    }
    *out_now_ms = (rte_timestamp_ms_t)(((uint64_t)ts.tv_sec * 1000ULL) + ((uint64_t)ts.tv_nsec / 1000000ULL));
    return RTE_STATUS_OK;
}