This page is showing examples in the target language CC++PythonTypeScriptRust. You can change the target language in the left sidebar.

Action Declaration

An action declaration has one of the following forms:

    logical action <name>(<min_delay>, <min_spacing>, <policy>)
    physical action <name>(<min_delay>, <min_spacing>, <policy>)

The min_delay, min_spacing, and policy are all optional. If only one argument is given in parentheses, then it is interpreted as an min_delay, if two are given, then they are interpreted as min_delay and min_spacing. The min_delay and min_spacing are time values. The policy argument is a string that can be one of the following: "defer" (the default), "drop", or "replace". Note that the quotation marks are needed.

    logical action <name>(<min_delay>, <min_spacing>, <policy>):<type>
    physical action <name>(<min_delay>, <min_spacing>, <policy>):<type>

Logical Actions

Timers are useful to trigger reactions once or periodically. Actions are used to trigger reactions more irregularly. An action, like an output or input port, can carry data, but unlike a port, an action is visible only within the reactor that defines it.

There are two kinds of actions, logical and physical. A logical action is used by a reactor to schedule a trigger at a fixed logical time interval d into the future. The time interval d, which is called a delay, is relative to the logical time t at which the scheduling occurs. If a reaction executes at logical time t and schedules an action a with delay d, then any reaction that is triggered by a will be invoked at logical time t + d. For example, the following reaction schedules something (printing the current elapsed logical time) 200 msec after an input x arrives:

target C;
reactor Schedule {
    input x:int;
    logical action a;
    reaction(x) -> a {=
        lf_schedule(a, MSEC(200));
    =}
    reaction(a) {=
        interval_t elapsed_time = lf_time_logical_elapsed();
        printf("Action triggered at logical time %lld nsec after start.\n", elapsed_time);
    =}
}

target Cpp;

reactor Schedule {
    input x:int;
    logical action a;
    reaction(x) -> a {=
        a.schedule(200ms);
    =}
    reaction(a) {=
        auto elapsed_time = get_elapsed_logical_time();
        std::cout << "Action triggered at logical time " << elapsed_time << "  nsec after start." << std::endl;
    =}
}

target Python;
reactor Schedule {
    input x;
    logical action a;
    reaction(x) -> a {=
        a.schedule(MSEC(200))
    =}
    reaction(a) {=
        elapsed_time = lf.time.logical_elapsed()
        print(f"Action triggered at logical time {elapsed_time} nsec after start.")
    =}
}

target TypeScript
reactor Schedule {
    input x:number
    logical action a
    reaction(x) -> a {=
        actions.a.schedule(TimeValue.nsecs(200), null)
    =}
    reaction(a) {=
        console.log(`Action triggered at logical time ${util.getElapsedLogicalTime()} after start.`)
    =}
}

target Rust;
reactor Schedule {
    input x:u32;
    logical action a;
    reaction(x) -> a {=
        ctx.schedule(a, after!(200 ms));
    =}
    reaction(a) {=
        printf("
            Action triggered at logical time {} nsec after start.",
            ctx.get_elapsed_logical_time().as_nanos(),
        );
    =}
}

Here, the delay is specified in the call to schedule within the target language code. Notice that in the diagram, a logical action is shown as a triangle with an L. Logical actions are always scheduled within a reaction of the reactor that declares the action.

The time argument is required to be non-negative. If it is zero, then the action will be scheduled one microstep later. See Superdense Time.

Physical Actions

A physical action is used to schedule reactions at logical times determined by the local physical clock. If a physical action with delay d is scheduled at physical time T, then the logical time assigned to the event is T + d. For example, the following reactor schedules the physical action p to trigger at a logical time equal to the physical time at which the input x arrives:

target C;
reactor Physical {
    input x:int;
    physical action a;
    reaction(x) -> a {=
        lf_schedule(a, 0);
    =}
    reaction(a) {=
        interval_t elapsed_time = lf_time_logical_elapsed();
        printf("Action triggered at logical time %lld nsec after start.\n", elapsed_time);
    =}
}

target Cpp;

reactor Physical {
    input x:int;
    physical action a;

    reaction(x) -> a {=
        a.schedule(0ms);
    =}

    reaction(a) {=
        auto elapsed_time = get_elapsed_logical_time();
        std::cout << "Action triggered at logical time " << elapsed_time << " nsec after start." << std::endl;
    =}
}

target Python;
reactor Physical {
    input x;
    physical action a;
    reaction(x) -> a {=
        a.schedule(0)
    =}
    reaction(a) {=
        elapsed_time = lf.time.logical_elapsed()
        print(f"Action triggered at logical time {elapsed_time} nsec after start.")
    =}
}

target TypeScript
reactor Physical {
    input x:int
    physical action a
    reaction(x) -> a {=
        actions.a.schedule(TimeValue.zero(), null)
    =}
    reaction(a) {=
        console.log(`Action triggered at logical time ${util.getElapsedLogicalTime()} nsec after start.`)
    =}
}

target Rust;
reactor Physical {
    input x:u32;
    physical action a;
    reaction(x) -> a {=
        let phys_action = a.clone();
        ctx.spawn_physical_thread(move |link| {
            link.schedule(&phys_action, Asap).unwrap();
        });
    =}
    reaction(a) {=
        println!(
            "Action triggered at logical time {} nsec after start.",
            ctx.get_elapsed_logical_time().as_nanos(),
        );
    =}
}

If you drive this with a timer, using for example the following structure:

then running the program will yield an output something like this:

Action triggered at logical time 201491000 nsec after start.
Action triggered at logical time 403685000 nsec after start.
Action triggered at logical time 603669000 nsec after start.
...

Here, logical time is lagging physical time by a few milliseconds. Note that, unless the fast option is given, logical time t chases physical time T, so t < T. Hence, the event being scheduled in the reaction to input x is assured of being in the future in logical time.

Whereas logical actions are required to be scheduled within a reaction of the reactor that declares the action, physical actions can be scheduled by code that is outside the Lingua Franca system. For example, some other thread or a callback function may call schedule(), passing it a physical action. For example:

target C;
main reactor {
    preamble {=
        // Schedule an event roughly every 200 msec.
        void* external(void* a) {
            while (true) {
                lf_nanosleep(MSEC(200));
                lf_schedule(a, 0);
            }
        }
    =}
    state thread_id:lf_thread_t(0);
    physical action a(100 msec):int;

    reaction(startup) -> a {=
        // Start a thread to schedule physical actions.
        lf_thread_create(&self->thread_id, &external, a);
    =}

    reaction(a) {=
        interval_t elapsed_time = lf_time_logical_elapsed();
        printf("Action triggered at logical time %lld nsec after start.\n", elapsed_time);
    =}
}

target Cpp;
main reactor {
    private preamble {=
        #include <thread>
    =}

    state thread: std::thread;
    physical action a:int;

    reaction(startup) -> a {=
        // Start a thread to schedule physical actions.
        thread = std::thread([&]{
            while (true) {
                std::this_thread::sleep_for(200ms);
                // the value that we give it really doesn't matter
                // but we the action should is scheduled for 100ms into the future
                a.schedule(0, 100ms);
            }
        });
    =}

    reaction(a) {=
        auto elapsed_time = get_physical_time();
        std::cout << "Action triggered at logical time" << elapsed_time <<"nsec after start." << std::endl;
    =}
}

target Python;
main reactor {
    preamble {=
        import time
        import threading
        # Schedule an event roughly every 200 msec.
        def external(self, a):
            while (True):
                self.time.sleep(0.2)
                a.schedule(0)
    =}
    state thread;
    physical action a(100 msec);

    reaction(startup) -> a {=
        # Start a thread to schedule physical actions.
        self.thread = self.threading.Thread(target=self.external, args=(a,))
        self.thread.start()
    =}

    reaction(a) {=
        elapsed_time = lf.time.logical_elapsed()
        print(f"Action triggered at logical time {elapsed_time} nsec after start.")
    =}
}

target TypeScript
main reactor {

    physical action a(100 msec):number;

    reaction(startup) -> a {=
        // Have asynchronous callback schedule physical action.
        setTimeout(() => {
            actions.a.schedule(TimeValue.zero(), 0)
        }, 200)
    =}

    reaction(a) {=
        console.log(`Action triggered at logical time ${util.getElapsedLogicalTime()} nsec after start.`)
    =}
}

target Rust;
main reactor {
    state start_time:Instant({=Instant::now()=});
    physical action a(100 msec):u32;

    reaction(startup) -> a {=
        let phys_action = a.clone(); // clone to move it into other thread
        // Start a thread to schedule physical actions.
        ctx.spawn_physical_thread(move |link| {
            loop {
                std::thread::sleep(Duration::from_millis(200));
                link.schedule_physical(&phys_action, Asap).unwrap();
            }
        });
    =}

    reaction(a) {=
        let elapsed_time = self.start_time.elapsed();
        println!("Action triggered at logical time {} nsecs after start.", elapsed_time.as_nanos());
    =}
}

Physical actions are the mechanism for obtaining input from the outside world. Because they are assigned a logical time derived from the physical clock, their logical time can be interpreted as a measure of the time at which some external event occurred.

Triggering Time for Actions

An action will trigger at a logical time that depends on the arguments given to the schedule function, the <min_delay>, <min_spacing>, and <policy> arguments in the action declaration, and whether the action is physical or logical.

For a logical action a, the tag assigned to the event resulting from a call to schedule() is computed as follows. First, let t be the current logical time. For a logical action, t is just the logical time at which the reaction calling schedule() is called. The preliminary time of the action is then just t + <min_delay> + <offset>. This preliminary time may be further modified, as explained below.

For a physical action, the preliminary time is similar, except that t is replaced by the current physical time T when schedule() is called.

If a <min_spacing> has been declared, then it gives a minimum logical time interval between the tags of two subsequently scheduled events. If the preliminary time is closer than <min_spacing> to the time of the previously scheduled event (if there is one), then <policy> (if supported by the target) determines how the minimum spacing constraint is enforced.

Testing an Action for Presence

When a reaction is triggered by more than one action or by an action and an input, it may be necessary to test within the reaction whether the action is present. Just like for inputs, this can be done in the C target with a->is_present, where a is the name of the action. Just like for inputs, this can be done in the Python target with a.is_present, where a is the name of the action. Just like for inputs, this can be done in the C++ target with a.is_present(), where a is the name of the action. Just like for inputs, this can be done in the TypeScript target with a != undefined, where a is the name of the action. Just like for inputs, this can be done in the Rust target with ctx.is_present(a), where a is the name of the action.