sapi_posix_backend_task.c File Reference

POSIX sapi_task backend: one pthread per task (ADR-018 section 2.3). period_ms > 0 runs entry in a nanosleep()-paced loop (relative, EINTR-restartable - not clock_nanosleep(CLOCK_MONOTONIC,...), which is a Linux/glibc extension Darwin's libc does not implement, and this backend targets any POSIX host); period_ms == 0 runs entry once. More...

#include "safeapi/posix_backend/sapi_posix_backend.h"
#include <errno.h>
#include <pthread.h>
#include <signal.h>
#include "safeapi/oal/memory/sapi_mem_util.h"
#include <time.h>

Include dependency graph for sapi_posix_backend_task.c:

Go to the source code of this file.

Data Structures
struct	posix_task_state_t

Macros
#define	_POSIX_C_SOURCE   200809L

Typedefs
typedef char	posix_task_storage_fits_[(sizeof(posix_task_state_t)<=sizeof(sapi_task_storage_t)) ? 1 :-1]

Functions
static void	ms_to_timespec (sapi_duration_ms_t ms, struct timespec *out_ts)
static void	apply_priority_best_effort (pthread_t thread, uint32_t priority)
static void *	task_thread_main (void *arg)
static sapi_status_t	backend_create (sapi_task_storage_t *storage, const sapi_task_config_t *config, sapi_task_handle_t *out_handle)
static sapi_status_t	backend_suspend (sapi_task_handle_t handle)
static sapi_status_t	backend_start (sapi_task_handle_t handle)
static sapi_status_t	backend_destroy (sapi_task_handle_t handle)
const sapi_task_backend_t *	sapi_posix_backend_task (void)
	The POSIX sapi_task backend (one pthread per task).

Variables
static const sapi_task_backend_t	s_posix_task_backend

Detailed Description

POSIX sapi_task backend: one pthread per task (ADR-018 section 2.3). period_ms > 0 runs entry in a nanosleep()-paced loop (relative, EINTR-restartable - not clock_nanosleep(CLOCK_MONOTONIC,...), which is a Linux/glibc extension Darwin's libc does not implement, and this backend targets any POSIX host); period_ms == 0 runs entry once.

Known simplification (stated in ADR-018): sapi_task has no native "suspend, keep state, resume later" primitive in POSIX threads without signal-based hacks this backend does not use. suspend() here stops the thread cleanly (same as destroy() minus freeing the handle); start() after suspend() begins a fresh run from the top of entry's cycle rather than resuming mid-cycle. Acceptable for a first cut - a caller that needs true pause/resume semantics needs a backend with more OS support than a portable pthread implementation can offer.

Priority: applied via pthread_setschedparam() with SCHED_FIFO when the process holds the privilege to do so (typically CAP_SYS_NICE or root). If that fails, the task still runs - just under the default scheduling policy - rather than failing task creation outright, since most development/CI environments cannot grant real-time scheduling privilege. This fallback is a deliberate ADR-018 choice, not a silent bug.

Definition in file sapi_posix_backend_task.c.

Macro Definition Documentation

_POSIX_C_SOURCE

#define _POSIX_C_SOURCE   200809L

Definition at line 1 of file sapi_posix_backend_task.c.

Typedef Documentation

posix_task_storage_fits_

typedef char posix_task_storage_fits_[(sizeof(posix_task_state_t)<=sizeof(sapi_task_storage_t)) ? 1 :-1]

Definition at line 47 of file sapi_posix_backend_task.c.

Function Documentation

apply_priority_best_effort()

void apply_priority_best_effort ( pthread_t thread, uint32_t priority )

static

Best-effort SCHED_FIFO priority request. Failure is not fatal - the task keeps running under whatever scheduling policy it already has (see file header). priority is clamped into the platform's valid SCHED_FIFO range rather than passed through unchecked.

Definition at line 74 of file sapi_posix_backend_task.c.

backend_create()

sapi_status_t backend_create ( sapi_task_storage_t * storage, const sapi_task_config_t * config, sapi_task_handle_t * out_handle )

static

Definition at line 180 of file sapi_posix_backend_task.c.

backend_destroy()

sapi_status_t backend_destroy ( sapi_task_handle_t handle )

static

Definition at line 265 of file sapi_posix_backend_task.c.

backend_start()

sapi_status_t backend_start ( sapi_task_handle_t handle )

static

Definition at line 215 of file sapi_posix_backend_task.c.

backend_suspend()

sapi_status_t backend_suspend ( sapi_task_handle_t handle )

static

Definition at line 198 of file sapi_posix_backend_task.c.

ms_to_timespec()

void ms_to_timespec ( sapi_duration_ms_t ms, struct timespec * out_ts )

static

Definition at line 50 of file sapi_posix_backend_task.c.

sapi_posix_backend_task()

const sapi_task_backend_t * sapi_posix_backend_task

(

void

)

The POSIX sapi_task backend (one pthread per task).

Definition at line 273 of file sapi_posix_backend_task.c.

task_thread_main()

void * task_thread_main ( void * arg )

static

Definition at line 101 of file sapi_posix_backend_task.c.

Variable Documentation

s_posix_task_backend

const sapi_task_backend_t s_posix_task_backend

static

Initial value:

= { backend_create, backend_start, backend_suspend,
      backend_destroy }

Definition at line 270 of file sapi_posix_backend_task.c.