reactor-c
C Runtime for Lingua Franca
Loading...
Searching...
No Matches
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_tlf_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

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
envThe environment in which we are executing
next_tagThe 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
envEnvironment in which we are executing.
tagThe 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
envEnvironment in which we are executing.
timerThe timer to initialize.

◆ _lf_initialize_timers()

void _lf_initialize_timers ( environment_t * env)

Initialize all the timers in the environment.

Parameters
envEnvironment 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
envEnvironment in which we are executing.
triggerThe trigger.
tokenThe 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
envEnvironment in which we are executing.
reactionThe reaction that has just executed.
workerThe 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
envThe 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, ...);
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).
Definition reactor_common.c:482

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
envEnvironment in which we are executing.
triggerThe trigger to be invoked at a later logical time.
tagLogical tag of the event
tokenThe 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
envThe 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
envEnvironment in which we are executing.
reactionThe reaction.
worker_numberThe 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
envEnvironment 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
envEnvironment 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
levelThe 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
headPointer 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
envEnvironment 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
envEnvironment in which we are executing.
eThe 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
eventThe event.
tokenThe 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
envThe 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
envEnvironment in which we are executing.
reactionThe reaction that has just executed.
workerThe 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.