reactor-c
C Runtime for Lingua Franca
Loading...
Searching...
No Matches
low_level_platform.h File Reference

Platform API support for the C target of Lingua Franca. More...

#include "tag.h"
#include <assert.h>
#include "platform/lf_atomic.h"

Go to the source code of this file.

Data Structures

struct  lf_scheduling_policy_t
 

Macros

#define LF_TIMEOUT   1
 
#define LF_SCHED_MAX_PRIORITY   99
 
#define LF_SCHED_MIN_PRIORITY   0
 
#define DEPRECATED(X)
 

Enumerations

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

Functions

int lf_notify_of_event (environment_t *env)
 Notify of new event.
 
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_available_cores ()
 Get the number of cores on the host machine.
 
lf_thread_t lf_thread_self ()
 Return the lf_thread_t of the calling thread.
 
int lf_thread_create (lf_thread_t *thread, void *(*lf_thread)(void *), void *arguments)
 Helper function for creating a thread.
 
int lf_thread_join (lf_thread_t thread, void **thread_return)
 
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. Priority ranges from 0 to 99 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_THREAD_PRIORITY.
 
int lf_thread_set_scheduling_policy (lf_thread_t thread, lf_scheduling_policy_t *policy)
 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.
 
int lf_mutex_init (lf_mutex_t *mutex)
 
int lf_mutex_lock (lf_mutex_t *mutex)
 
int lf_mutex_unlock (lf_mutex_t *mutex)
 
int lf_cond_init (lf_cond_t *cond, lf_mutex_t *mutex)
 
int lf_cond_broadcast (lf_cond_t *cond)
 
int lf_cond_signal (lf_cond_t *cond)
 
int lf_cond_wait (lf_cond_t *cond)
 
int _lf_cond_timedwait (lf_cond_t *cond, instant_t wakeup_time)
 
int lf_thread_id ()
 Cross-platform version of the C11 thread_local keyword.
 
void initialize_lf_thread_id ()
 Initialize the thread ID for the current thread.
 
void _lf_initialize_clock (void)
 
int _lf_clock_gettime (instant_t *t)
 
int lf_sleep (interval_t sleep_duration)
 
int _lf_interruptable_sleep_until_locked (environment_t *env, instant_t wakeup_time)
 Sleep until the given wakeup time. This should not be used directly as it does not account for clock synchronization offsets. See clock.h.
 
 DEPRECATED (int lf_nanosleep(interval_t sleep_duration))
 

Detailed Description

Platform API support for the C target of Lingua Franca.

Author
{Soroush Bateni sorou.nosp@m.sh@u.nosp@m.tdall.nosp@m.as.e.nosp@m.du}

This file detects the platform on which the C compiler is being run (e.g. Windows, Linux, Mac) and conditionally includes platform-specific files that define core datatypes and function signatures for Lingua Franca.

Macro Definition Documentation

◆ DEPRECATED

#define DEPRECATED ( X )
Value:
X

Macros for marking function as deprecated

◆ LF_SCHED_MAX_PRIORITY

#define LF_SCHED_MAX_PRIORITY   99

◆ LF_SCHED_MIN_PRIORITY

#define LF_SCHED_MIN_PRIORITY   0

◆ LF_TIMEOUT

#define LF_TIMEOUT   1

Enumeration Type Documentation

◆ lf_scheduling_policy_type_t

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)

Fetch 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.

Returns
0 for success, or -1 for failure

◆ _lf_cond_timedwait()

int _lf_cond_timedwait ( lf_cond_t * cond,
instant_t wakeup_time )

Block the current thread on the condition variable 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.

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

◆ _lf_initialize_clock()

void _lf_initialize_clock ( void )

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 )

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
envThe environment within which to sleep.
wakeup_timeThe time instant at which to wake up.
Returns
int 0 if sleep completed, or -1 if it was interrupted.

◆ DEPRECATED()

DEPRECATED ( int lf_nanosleepinterval_t sleep_duration)
Deprecated
version of "lf_sleep"

◆ initialize_lf_thread_id()

void initialize_lf_thread_id ( )

Initialize the thread ID for the current thread.

◆ lf_available_cores()

int lf_available_cores ( )

Get the number of cores on the host machine.

◆ lf_cond_broadcast()

int lf_cond_broadcast ( lf_cond_t * cond)

Wake up all threads waiting for condition variable cond.

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

◆ lf_cond_init()

int lf_cond_init ( lf_cond_t * cond,
lf_mutex_t * mutex )

Initialize a conditional variable.

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

◆ lf_cond_signal()

int lf_cond_signal ( lf_cond_t * cond)

Wake up one thread waiting for condition variable cond.

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

◆ lf_cond_wait()

int lf_cond_wait ( lf_cond_t * cond)

Wait for condition variable "cond" to be signaled or broadcast. The cond->mutex is assumed to be locked when this is called.

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

◆ lf_critical_section_enter()

int lf_critical_section_enter ( environment_t * env)

Enter critical section within an environment.

Parameters
envEnvironment in which we are executing.

Enter critical section within an environment.

Parameters
envEnvironment within which we are executing or GLOBAL_ENVIRONMENT.

◆ lf_critical_section_exit()

int lf_critical_section_exit ( environment_t * env)

Leave a critical section within an environment.

Parameters
envEnvironment in which we are executing.

Leave a critical section within an environment.

Parameters
envEnvironment within which we are executing or GLOBAL_ENVIRONMENT.

◆ lf_mutex_init()

int lf_mutex_init ( lf_mutex_t * mutex)

Initialize a mutex.

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

◆ lf_mutex_lock()

int lf_mutex_lock ( lf_mutex_t * mutex)

Lock a mutex.

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

◆ lf_mutex_unlock()

int lf_mutex_unlock ( lf_mutex_t * mutex)

Unlock a mutex.

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

◆ lf_notify_of_event()

int lf_notify_of_event ( environment_t * env)

Notify of new event.

Parameters
envEnvironment in which we are executing.

Notify of new event.

Parameters
envEnvironment within which we are executing.

◆ lf_sleep()

int lf_sleep ( interval_t sleep_duration)

Pause execution for a given 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 )

Helper function for creating a thread.

Create a new thread, starting with execution of lf_thread getting passed arguments. The new handle is stored in thread_id.

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

◆ lf_thread_id()

int lf_thread_id ( )

Cross-platform version of the C11 thread_local keyword.

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 )

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

Parameters
threadThe thread.
thread_returnA 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 ( )

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 )

Pin a thread to a specific CPU.

Parameters
threadThe thread
cpu_numberthe 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 )

Set the priority of a thread. Priority ranges from 0 to 99 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_THREAD_PRIORITY.

Parameters
threadThe thread.
priorityThe 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 )

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.