Platform API

API for functions that have platform-specific implementations. More...

Files
file	clock.h
	A higher level API to the clock utilities provided by the platform API.
file	low_level_platform.h
	Platform API support for the C target of Lingua Franca.
file	platform.h
	Platform API for runtime plugins to use while sharing implementation source code and binaries with the core and with each other.

Data Structures
struct	lf_scheduling_policy_t
	A struct supporting thread scheduling policies. More...

Typedefs
typedef void *	lf_platform_mutex_ptr_t
	Pointer to the platform-specific implementation of a mutex.

Enumerations
enum	lf_scheduling_policy_type_t { LF_SCHED_FAIR , LF_SCHED_TIMESLICE , LF_SCHED_PRIORITY }
	The thread scheduling policies. More...

Functions
int	_lf_clock_gettime (instant_t *t)
	Get the value of an internal (and platform-specific) physical clock.
int	_lf_cond_timedwait (lf_cond_t *cond, instant_t wakeup_time)
	Block the current thread on the condition variable with a timeout.
void	_lf_initialize_clock (void)
	Initialize the LF clock.
int	_lf_interruptable_sleep_until_locked (environment_t *env, instant_t wakeup_time)
	Sleep until the given wakeup time.
void	initialize_lf_thread_id (void)
	Initialize the thread ID for the current thread.
int	lf_available_cores (void)
	Get the number of cores on the host machine.
int	lf_clock_cond_timedwait (lf_cond_t *cond, instant_t wakeup_time)
	Block the calling thread on the condition variable until it is signaled or until wakeup_time is reached.
int	lf_clock_gettime (instant_t *now)
	Retrieve the current physical time from the platform API.
int	lf_clock_interruptable_sleep_until_locked (environment_t *env, instant_t wakeup_time)
	Block the calling thread until wakeup_time is reached or the thread is interrupted by an asynchronous scheduling.
int	lf_cond_broadcast (lf_cond_t *cond)
	Wake up all threads waiting for condition variable cond.
int	lf_cond_init (lf_cond_t *cond, lf_mutex_t *mutex)
	Initialize a conditional variable.
int	lf_cond_signal (lf_cond_t *cond)
	Wake up one thread waiting for condition variable cond.
int	lf_cond_wait (lf_cond_t *cond)
	Wait for condition variable "cond" to be signaled or broadcast.
int	lf_critical_section_enter (environment_t *env)
	Enter critical section within an environment.
int	lf_critical_section_exit (environment_t *env)
	Leave a critical section within an environment.
int	lf_mutex_init (lf_mutex_t *mutex)
	Initialize a mutex.
int	lf_mutex_lock (lf_mutex_t *mutex)
	Lock the specified mutex.
int	lf_mutex_unlock (lf_mutex_t *mutex)
	Unlock the specified mutex.
int	lf_notify_of_event (environment_t *env)
	Notify of new event.
void	lf_platform_mutex_free (lf_platform_mutex_ptr_t mutex)
	Free all resources associated with the provided mutex.
int	lf_platform_mutex_lock (lf_platform_mutex_ptr_t mutex)
	Acquire the given mutex.
lf_platform_mutex_ptr_t	lf_platform_mutex_new ()
	Create a new mutex and return (a pointer to) it.
int	lf_platform_mutex_unlock (lf_platform_mutex_ptr_t mutex)
	Release the given mutex.
int	lf_sleep (interval_t sleep_duration)
	Pause execution for a given duration.
int	lf_thread_create (lf_thread_t *thread, void *(*lf_thread)(void *), void *arguments)
	Create a new thread.
int	lf_thread_id (void)
	Return the ID of the current thread.
int	lf_thread_join (lf_thread_t thread, void **thread_return)
	Wait for the specified thread to exit.
lf_thread_t	lf_thread_self (void)
	Return the lf_thread_t of the calling thread.
int	lf_thread_set_cpu (lf_thread_t thread, size_t cpu_number)
	Pin a thread to a specific CPU.
int	lf_thread_set_priority (lf_thread_t thread, int priority)
	Set the priority of a thread.
int	lf_thread_set_scheduling_policy (lf_thread_t thread, lf_scheduling_policy_t *policy)
	Set the scheduling policy of a thread.

Detailed Description

API for functions that have platform-specific implementations.

These functions are not meant to be used directly by users, but are useful for developers. They are used to implement the platform-independent API for specific platforms.

Typedef Documentation

lf_platform_mutex_ptr_t

typedef void* lf_platform_mutex_ptr_t

#include </Users/runner/work/reactor-c/reactor-c/platform/api/platform.h>

Pointer to the platform-specific implementation of a mutex.

Enumeration Type Documentation

lf_scheduling_policy_type_t

enum lf_scheduling_policy_type_t

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

The thread scheduling policies.

Enumerator
LF_SCHED_FAIR
LF_SCHED_TIMESLICE
LF_SCHED_PRIORITY

Function Documentation

_lf_clock_gettime()

int _lf_clock_gettime

(

instant_t *

t

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Get the value of an internal (and platform-specific) physical clock.

Ideally, the underlying platform clock should be monotonic. However, the core lib enforces monotonicity at higher level APIs (see clock.h).

This should not be used directly as it does not apply clock synchronization offsets.

Parameters

t	A pointer to the place to store the result.

Returns

0 for success, or -1 for failure

_lf_cond_timedwait()

int _lf_cond_timedwait	(	lf_cond_t *	cond,
		instant_t	wakeup_time )

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Block the current thread on the condition variable with a timeout.

This will block until the condition variable pointed by cond is signaled or the time given by wakeup_time is reached. This should not be used directly as it does not account for clock synchronization offsets. Use lf_clock_cond_timedwait from clock.h instead.

Parameters

cond	The condition variable.
wakeup_time	The timeout time.

Returns

0 on success, LF_TIMEOUT on timeout, and platform-specific error number otherwise.

_lf_initialize_clock()

void _lf_initialize_clock

(

void

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Initialize the LF clock.

Must be called before using other clock-related APIs.

_lf_interruptable_sleep_until_locked()

int _lf_interruptable_sleep_until_locked	(	environment_t *	env,
		instant_t	wakeup_time )

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Sleep until the given wakeup time.

This should not be used directly as it does not account for clock synchronization offsets. See clock.h.

This assumes the lock for the given environment is held.

Parameters

env	The environment within which to sleep.
wakeup_time	The time instant at which to wake up.

Returns

int 0 if sleep completed, or -1 if it was interrupted.

initialize_lf_thread_id()

void initialize_lf_thread_id

(

void

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Initialize the thread ID for the current thread.

lf_available_cores()

int lf_available_cores

(

void

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Get the number of cores on the host machine.

lf_clock_cond_timedwait()

int lf_clock_cond_timedwait	(	lf_cond_t *	cond,
		instant_t	wakeup_time )

#include </Users/runner/work/reactor-c/reactor-c/include/core/clock.h>

Block the calling thread on the condition variable until it is signaled or until wakeup_time is reached.

Before calling the appropriate function in the platform API, the wakeup_time will be translated into the correct timescale by removing any clock synchronization offset.

Returns

0 on success, LF_TIMEOUT on timeout, platform-specific error otherwise.

lf_clock_gettime()

int lf_clock_gettime

(

instant_t *

now

)

#include </Users/runner/work/reactor-c/reactor-c/include/core/clock.h>

Retrieve the current physical time from the platform API.

This adds any clock synchronization offset and guarantees monotonicity. Specifically, each returned value will be at least one nanosecond larger than any previously returned time.

Parameters

now	A pointer to the location in which to store the result.

Returns

0 on success, -1 on failure to read the platform clock.

lf_clock_interruptable_sleep_until_locked()

int lf_clock_interruptable_sleep_until_locked	(	environment_t *	env,
		instant_t	wakeup_time )

#include </Users/runner/work/reactor-c/reactor-c/include/core/clock.h>

Block the calling thread until wakeup_time is reached or the thread is interrupted by an asynchronous scheduling.

This is used by the single-threaded runtime. Before calling the appropriate function in the platform API, the wakeup_time will be translated into the correct timescale by removing any clock synchronization offset.

Returns

0 on success or -1 if interrupted.

lf_cond_broadcast()

int lf_cond_broadcast

(

lf_cond_t *

cond

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Wake up all threads waiting for condition variable cond.

Parameters

cond	The condition variable.

Returns

0 on success, platform-specific error number otherwise.

lf_cond_init()

int lf_cond_init	(	lf_cond_t *	cond,
		lf_mutex_t *	mutex )

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Initialize a conditional variable.

Parameters

cond	The condition variable.
mutex	The associated mutex.

Returns

0 on success, platform-specific error number otherwise.

lf_cond_signal()

int lf_cond_signal

(

lf_cond_t *

cond

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Wake up one thread waiting for condition variable cond.

Parameters

cond	The condition variable.

Returns

0 on success, platform-specific error number otherwise.

lf_cond_wait()

int lf_cond_wait

(

lf_cond_t *

cond

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Wait for condition variable "cond" to be signaled or broadcast.

The cond->mutex is assumed to be locked when this is called.

Parameters

cond	The condition variable.

Returns

0 on success, platform-specific error number otherwise.

lf_critical_section_enter()

int lf_critical_section_enter

(

environment_t *

env

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Enter critical section within an environment.

Parameters

env	Environment in which we are executing.

lf_critical_section_exit()

int lf_critical_section_exit

(

environment_t *

env

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Leave a critical section within an environment.

Parameters

env	Environment in which we are executing.

lf_mutex_init()

int lf_mutex_init

(

lf_mutex_t *

mutex

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Initialize a mutex.

Parameters

mutex

The mutex

Returns

0 on success

lf_mutex_lock()

int lf_mutex_lock

(

lf_mutex_t *

mutex

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Lock the specified mutex.

Parameters

mutex

The mutex

Returns

0 on success

lf_mutex_unlock()

int lf_mutex_unlock

(

lf_mutex_t *

mutex

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Unlock the specified mutex.

Parameters

mutex

The mutex

Returns

0 on success

lf_notify_of_event()

int lf_notify_of_event

(

environment_t *

env

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Notify of new event.

Parameters

env	Environment in which we are executing.

lf_platform_mutex_free()

void lf_platform_mutex_free

(

lf_platform_mutex_ptr_t

mutex

)

#include </Users/runner/work/reactor-c/reactor-c/platform/api/platform.h>

Free all resources associated with the provided mutex.

lf_platform_mutex_lock()

int lf_platform_mutex_lock

(

lf_platform_mutex_ptr_t

mutex

)

#include </Users/runner/work/reactor-c/reactor-c/platform/api/platform.h>

Acquire the given mutex.

Returns

0 on success, platform-specific error number otherwise.

lf_platform_mutex_new()

lf_platform_mutex_ptr_t lf_platform_mutex_new

(

)

#include </Users/runner/work/reactor-c/reactor-c/platform/api/platform.h>

Create a new mutex and return (a pointer to) it.

lf_platform_mutex_unlock()

int lf_platform_mutex_unlock

(

lf_platform_mutex_ptr_t

mutex

)

#include </Users/runner/work/reactor-c/reactor-c/platform/api/platform.h>

Release the given mutex.

Returns

0 on success, platform-specific error number otherwise.

lf_sleep()

int lf_sleep

(

interval_t

sleep_duration

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Pause execution for a given duration.

Parameters

sleep_duration

The duration.

Returns

0 for success, or -1 for failure.

lf_thread_create()

int lf_thread_create	(	lf_thread_t *	thread,
		void *(*	lf_thread )(void *),
		void *	arguments )

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Create a new thread.

Start execution of the specified function with the passed arguments. The new thread handle is stored in thread_id.

Parameters

thread	A pointer to where to store the handle.
lf_thread	The function to invoke.
arguments	The arguments to pass to the function.

Returns

0 on success, platform-specific error number otherwise.

lf_thread_id()

int lf_thread_id

(

void

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Return the ID of the current thread.

The only guarantee is that these IDs will be a contiguous range of numbers starting at 0.

lf_thread_join()

int lf_thread_join	(	lf_thread_t	thread,
		void **	thread_return )

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Wait for the specified thread to exit.

Make the calling thread wait for termination of the specified thread. The exit status of the thread is stored in thread_return if thread_return is not NULL.

Parameters

thread	The thread.
thread_return	A pointer to where to store the exit status of the thread.

Returns

0 on success, platform-specific error number otherwise.

lf_thread_self()

lf_thread_t lf_thread_self

(

void

)

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Return the lf_thread_t of the calling thread.

lf_thread_set_cpu()

int lf_thread_set_cpu	(	lf_thread_t	thread,
		size_t	cpu_number )

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Pin a thread to a specific CPU.

Parameters

thread	The thread
cpu_number	the CPU ID

Returns

0 on success, platform-specific error number otherwise.

lf_thread_set_priority()

int lf_thread_set_priority	(	lf_thread_t	thread,
		int	priority )

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Set the priority of a thread.

Priority ranges from LF_SCHED_MIN_PRIORITY to LF_SCHED_MAX_PRIORITY, where a higher number indicates higher priority. Setting the priority of a thread only makes sense if the thread is scheduled with LF_SCHED_TIMESLICE or LF_SCHED_PRIORITY.

Parameters

thread	The thread.
priority	The priority.

Returns

int 0 on success, platform-specific error otherwise

lf_thread_set_scheduling_policy()

int lf_thread_set_scheduling_policy	(	lf_thread_t	thread,
		lf_scheduling_policy_t *	policy )

#include </Users/runner/work/reactor-c/reactor-c/low_level_platform/api/low_level_platform.h>

Set the scheduling policy of a thread.

This is based on the scheduling concept from Linux explained here: https://man7.org/linux/man-pages/man7/sched.7.html A scheduling policy is specific to a thread/worker. We have three policies LF_SCHED_PRIORITY, which corresponds to SCHED_FIFO on Linux. LF_SCHED_TIMESLICE, which corresponds to SCHED_RR on Linux. LF_SCHED_FAIR, which corresponds to SCHED_OTHER on Linux.

Returns

int 0 on success, platform-specific error number otherwise.