reactor_common.h File Reference

Declarations of functions with implementations in reactor.c and reactor_threaded.c. More...

#include "lf_types.h"
#include "environment.h"
#include "tag.h"
#include "pqueue.h"
#include "vector.h"
#include "util.h"
#include "modes.h"
#include "port.h"

Go to the source code of this file.

Macros
#define	MIN_SLEEP_DURATION   USEC(10)
	Constant giving the minimum amount of time to sleep to wait for physical time to reach a logical time.

Functions
index_t	lf_combine_deadline_and_level (interval_t deadline, int level)
	Combine a deadline and a level into a single index for sorting in the reaction queue.
void	lf_create_environments (void)
	Create and initialize the required number of environments for the program.
void	lf_free (struct allocation_record_t **head)
	Free memory on the specified allocation record (a self struct).
event_t *	lf_get_new_event (environment_t *env)
void	lf_recycle_event (environment_t *env, event_t *e)
	Recycle the given event.
void	lf_replace_token (event_t *event, lf_token_t *token)
void	lf_set_default_command_line_options (void)
	Generated function that optionally sets default command-line options.
void	_lf_start_time_step (environment_t *env)
	Perform whatever is needed to start a time step.
void	lf_terminate_execution (environment_t *env)
	Function that is called when the program is about to exit.
void	_lf_initialize_trigger_objects ()
void	termination (void)
	Perform final wrap-up on exit.
void	_lf_trigger_reaction (environment_t *env, reaction_t *reaction, int worker_number)
	Trigger the specified reaction on the specified worker in the specified environment.
void	_lf_initialize_timer (environment_t *env, trigger_t *timer)
	Initialize the given timer. If this timer has a zero offset, enqueue the reactions it triggers. If this timer is to trigger reactions at a future tag as well, schedule it accordingly.
void	_lf_initialize_timers (environment_t *env)
	Initialize all the timers in the environment.
void	_lf_trigger_startup_reactions (environment_t *env)
	Trigger all the startup reactions in the specified environment.
void	_lf_trigger_shutdown_reactions (environment_t *env)
	Trigger all the shutdown reactions in the specified environment.
event_t *	_lf_create_dummy_events (environment_t *env, tag_t tag)
	Create a dummy event with the specified tag.
trigger_handle_t	_lf_schedule_at_tag (environment_t *env, trigger_t *trigger, tag_t tag, lf_token_t *token)
	Schedule an event at a specific tag (time, microstep).
trigger_handle_t	_lf_insert_reactions_for_trigger (environment_t *env, trigger_t *trigger, lf_token_t *token)
	Insert reactions triggered by trigger to the reaction queue.
void	_lf_advance_tag (environment_t *env, tag_t next_tag)
void	_lf_pop_events (environment_t *env)
	Pop all events from event_q with tag equal to current tag.
void	_lf_invoke_reaction (environment_t *env, reaction_t *reaction, int worker)
void	schedule_output_reactions (environment_t *env, reaction_t *reaction, int worker)
int	process_args (int argc, const char *argv[])
void	initialize_global ()
	Initialize global variables and start tracing before calling the _lf_initialize_trigger_objects function.

Variables
bool	_lf_normal_termination
unsigned int	_lf_number_of_workers
int	default_argc
const char **	default_argv
instant_t	duration
bool	fast
bool	keepalive_specified
struct allocation_record_t *	_lf_reactors_to_free

Detailed Description

Declarations of functions with implementations in reactor.c and reactor_threaded.c.

Author

Edward A. Lee (eal@b.nosp@m.erke.nosp@m.ley.e.nosp@m.du)

Marten Lohstroh

Soroush Bateni

Mehrdad Niknami

Alexander Schulz-Rosengarten

Erling Rennemo Jellum

Copyright

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

The functions declared in this file, as opposed to the ones in reactor.h, are not meant to be called by application programmers. They should be viewed as private functions that make up the C runtime. In some cases, the implementation of these functions is in reactor_common.c, and in other cases, alternative implementations are provided in reactor.c and reactor_threaded.c. A third possibility is that the function is code generated.

Macro Definition Documentation

MIN_SLEEP_DURATION

#define MIN_SLEEP_DURATION   USEC(10)

Constant giving the minimum amount of time to sleep to wait for physical time to reach a logical time.

Unless the "fast" option is given, an LF program will wait until physical time matches logical time before handling an event with a given logical time. The amount of time is less than this given threshold, then no wait will occur. The purpose of this is to prevent unnecessary delays caused by simply setting up and performing the wait.

Function Documentation

_lf_advance_tag()

void _lf_advance_tag	(	environment_t *	env,
		tag_t	next_tag )

Advance from the current tag to the next. If the given next_time is equal to the current time, then increase the microstep. Otherwise, update the current time and set the microstep to zero.

Parameters

env	The environment in which we are executing
next_tag	The tag step to advance to.

_lf_create_dummy_events()

event_t * _lf_create_dummy_events	(	environment_t *	env,
		tag_t	tag )

Create a dummy event with the specified tag.

A dummy event is an event with no triggers that can be put on the event queue to trigger a tag advance to the specified tag.

Parameters

env	Environment in which we are executing.
tag	The tag of that event.

Returns

A pointer to the dummy event.

_lf_initialize_timer()

void _lf_initialize_timer	(	environment_t *	env,
		trigger_t *	timer )

Initialize the given timer. If this timer has a zero offset, enqueue the reactions it triggers. If this timer is to trigger reactions at a future tag as well, schedule it accordingly.

Parameters

env	Environment in which we are executing.
timer	The timer to initialize.

_lf_initialize_timers()

void _lf_initialize_timers

(

environment_t *

env

)

Initialize all the timers in the environment.

Parameters

env	Environment in which we are executing.

_lf_initialize_trigger_objects()

void _lf_initialize_trigger_objects

(

)

Generated function that produces a table containing all triggers (i.e., inputs, timers, and actions).

_lf_insert_reactions_for_trigger()

trigger_handle_t _lf_insert_reactions_for_trigger	(	environment_t *	env,
		trigger_t *	trigger,
		lf_token_t *	token )

Insert reactions triggered by trigger to the reaction queue.

Parameters

env	Environment in which we are executing.
trigger	The trigger.
token	The token wrapping the payload or NULL for no payload.

Returns

1 if successful, or 0 if no new reaction was scheduled because the function was called incorrectly.

_lf_invoke_reaction()

void _lf_invoke_reaction	(	environment_t *	env,
		reaction_t *	reaction,
		int	worker )

Invoke the given reaction

Parameters

env	Environment in which we are executing.
reaction	The reaction that has just executed.
worker	The thread number of the worker thread or 0 for single-threaded execution (for tracing).

_lf_pop_events()

void _lf_pop_events

(

environment_t *

env

)

Pop all events from event_q with tag equal to current tag.

This will extract all the reactions triggered by these events and stick them onto the reaction queue.

Parameters

env	The environment in which we are executing

_lf_schedule_at_tag()

trigger_handle_t _lf_schedule_at_tag	(	environment_t *	env,
		trigger_t *	trigger,
		tag_t	tag,
		lf_token_t *	token )

Schedule an event at a specific tag (time, microstep).

If there is an event found at the requested tag, the payload is replaced and 0 is returned.

Note that this function is an internal API that must be called with a tag that is in the future relative to the current tag (or the environment has not started executing). Also, it must be called with tags that are in order for a given trigger. This means that the following order is illegal:

_lf_schedule_at_tag(trigger1, bigger_tag, ...);
_lf_schedule_at_tag(trigger1, smaller_tag, ...);

where bigger_tag > smaller_tag. This function is primarily used for network communication (which is assumed to be in order).

This function assumes the caller holds the mutex lock.

Parameters

env	Environment in which we are executing.
trigger	The trigger to be invoked at a later logical time.
tag	Logical tag of the event
token	The token wrapping the payload or NULL for no payload.

Returns

A positive trigger handle for success, 0 if no new event was scheduled (instead, the payload was updated), or -1 for error (the tag is equal to or less than the current tag).

_lf_start_time_step()

void _lf_start_time_step

(

environment_t *

env

)

Perform whatever is needed to start a time step.

For example, this function resets outputs to be absent at the start of a new time step.

Parameters

env	The environment in which we are executing

_lf_trigger_reaction()

void _lf_trigger_reaction	(	environment_t *	env,
		reaction_t *	reaction,
		int	worker_number )

Trigger the specified reaction on the specified worker in the specified environment.

Parameters

env	Environment in which we are executing.
reaction	The reaction.
worker_number	The ID of the worker that is making this call. 0 should be used if there is only one worker (e.g., when the program is using the single-threaded C runtime). -1 is used for an anonymous call in a context where a worker number does not make sense (e.g., the caller is not a worker thread).

_lf_trigger_shutdown_reactions()

void _lf_trigger_shutdown_reactions

(

environment_t *

env

)

Trigger all the shutdown reactions in the specified environment.

Parameters

env	Environment in which we are executing.

_lf_trigger_startup_reactions()

void _lf_trigger_startup_reactions

(

environment_t *

env

)

Trigger all the startup reactions in the specified environment.

Parameters

env	Environment in which we are executing.

initialize_global()

void initialize_global

(

void

)

Initialize global variables and start tracing before calling the _lf_initialize_trigger_objects function.

Initialize global variables and start tracing before calling the _lf_initialize_trigger_objects function.

lf_combine_deadline_and_level()

index_t lf_combine_deadline_and_level	(	interval_t	deadline,
		int	level )

Combine a deadline and a level into a single index for sorting in the reaction queue.

This shifts the deadline right by 16 bits and inserts the level in the low-order 16 bits. If the deadline is larger than ULLONG_MAX >> 16, then it is treated as the largest possible deadline. @oaran deadline THe deadline.

Parameters

level

The level in the reaction graph.

lf_create_environments()

void lf_create_environments

(

void

)

Create and initialize the required number of environments for the program.

Note

This function will be code generated by the compiler.

lf_free()

void lf_free

(

struct allocation_record_t **

head

)

Free memory on the specified allocation record (a self struct).

This will mark the allocation record empty by setting *head to NULL. If the argument is NULL, do nothing.

Parameters

head	Pointer to the head of a list on which allocations are recorded.

lf_get_new_event()

event_t * lf_get_new_event

(

environment_t *

env

)

Get a new event. If there is a recycled event available, use that. If not, allocate a new one. In either case, all fields will be zero'ed out.

Parameters

env	Environment in which we are executing.

lf_recycle_event()

void lf_recycle_event	(	environment_t *	env,
		event_t *	e )

Recycle the given event.

This will zero out the event and push it onto the recycle queue.

Parameters

env	Environment in which we are executing.
e	The event to recycle.

lf_replace_token()

void lf_replace_token	(	event_t *	event,
		lf_token_t *	token )

Replace the token on the specified event with the specified token and free the old token.

Parameters

event	The event.
token	The token.

lf_set_default_command_line_options()

void lf_set_default_command_line_options

(

void

)

Generated function that optionally sets default command-line options.

lf_terminate_execution()

void lf_terminate_execution

(

environment_t *

env

)

Function that is called when the program is about to exit.

This function will be invoked after all shutdown actions have completed. For non-federated programs, the code generator generates an empty function to implement this. For federated programs, the function is implemented in federate.c.

Parameters

env	The environment in which we are executing

process_args()

int process_args	(	int	argc,
		const char *	argv[] )

Process the command-line arguments. If the command line arguments are not understood, then print a usage message and return 0. Otherwise, return 1.

Returns

1 if the arguments processed successfully, 0 otherwise. TODO: Not necessary for NO_CLI

schedule_output_reactions()

void schedule_output_reactions	(	environment_t *	env,
		reaction_t *	reaction,
		int	worker )

For the specified reaction, if it has produced outputs, insert the resulting triggered reactions into the reaction queue. This procedure assumes the mutex lock is NOT held and grabs the lock only when it actually inserts something onto the reaction queue.

Parameters

env	Environment in which we are executing.
reaction	The reaction that has just executed.
worker	The thread number of the worker thread or 0 for single-threaded execution (for tracing).

termination()

void termination

(

void

)

Perform final wrap-up on exit.

This function will be registered to execute on exit. It reports elapsed logical and physical times and reports if any memory allocated for tokens has not been freed.

Report elapsed logical and physical times and report if any memory allocated for tokens has not been freed.

Function to be invoked upon exiting.

Variable Documentation

_lf_normal_termination

bool _lf_normal_termination

extern

Flag used to disable cleanup operations on abnormal termination.

_lf_number_of_workers

unsigned int _lf_number_of_workers

extern

The number of worker threads for threaded execution. By default, execution is not threaded and this variable will have value 0.

If the execution is threaded, a value of 0 indicates that the runtime should decide on the number of workers (which will be decided based on the number of available cores on the host machine).

_lf_reactors_to_free

struct allocation_record_t* _lf_reactors_to_free

extern

Head of a list of pointers to dynamically generated reactor self structs to be freed in terminate().

default_argc

int default_argc

extern

default_argv

const char** default_argv

extern

duration

instant_t duration

extern

The logical time to elapse during execution, or -1 if no timeout time has been given. When the logical equal to start_time + duration has been reached, execution will terminate.

fast

bool fast

extern

Indicator of whether to wait for physical time to match logical time. By default, execution will wait. The command-line argument -fast will eliminate the wait and allow logical time to exceed physical time.

keepalive_specified

bool keepalive_specified

extern

Indicator of whether the keepalive command-line option was given.