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}

Copyright

(c) 2020-2024, The University of California at Berkeley. License: BSD 2-clause

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

enum 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

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.

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

env	Environment in which we are executing.

Enter critical section within an environment.

Parameters

env	Environment 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

env	Environment in which we are executing.

Leave a critical section within an environment.

Parameters

env	Environment 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

env	Environment in which we are executing.

Notify of new event.

Parameters

env	Environment 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

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

(

)

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

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 )

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

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 )

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.