Skip to main content
Version: Nightly 🚧

Async and Await

This article has examples in the following target languages:

note

lf_async and lf_await are supported in the C and Python targets, and only with the threaded runtime using the default (NP) or GEDF_NP scheduler.

A reaction normally runs to completion at a single tag. Its body cannot wait for anything: if it makes a blocking call, such as reading from a socket or waiting for keyboard input, the whole program stalls, because logical time cannot advance while a reaction is executing. And if a reaction needs a result that another reactor will produce, the reaction has to end, and a second reaction has to pick up the result when it arrives. Anything the first reaction wants to use later must be copied into state variables, a pattern sometimes called stack ripping.

Two mechanisms let a reaction suspend in the middle of its body and continue later, at a later tag, while logical time advances and other reactions execute:

  • lf_async invokes a function that may block or run for a long time and suspends the reaction until the function returns. While the function is running, logical time advances and other reactions execute. The reaction continues at a tag determined by an action that you choose.
  • lf_await suspends the reaction until the specified input arrives. The reaction continues at the tag of that input.

In both cases, local variables that were on the stack before the call are still there afterward, so nothing needs to be copied into state variables.

Waiting for an Input with lf_await​

The following program sends a request to another reactor and waits, in the same reaction, for the result to come back:

target C {
  timeout: 1 s
}

reactor RequestWork {
  input result: int
  output request: int
  timer t(0, 200 ms)
  state count: int = 1

  reaction(t, result) -> request {=
    lf_print("Request work at logical time " PRINTF_TIME, lf_time_logical_elapsed());
    lf_set(request, self->count++);
    lf_await(result);
    lf_print("Result %d received at logical time " PRINTF_TIME, result->value, lf_time_logical_elapsed());
  =}
}

reactor DoWork {
  input request: int
  output result: int

  reaction(request) -> result {=
    lf_print("Do work starting at logical time " PRINTF_TIME, lf_time_logical_elapsed());
    lf_set(result, request->value * 2);
  =}
}

main reactor {
  request_work = new RequestWork()
  process_work = new DoWork()
  request_work.request -> process_work.request
  process_work.result -> request_work.result after 100 ms
}
Lingua Franca diagram: AwaitLETAwaitLETRequestWork(0, 200 ms)resultrequestDoWorkrequestresult100 ms

RequestWork has one reaction that, when triggered by the timer, sets the request output, calls lf_await on result, blocks until an event arrives on result, and then prints the result. Because the feedback connection has an after delay of 100 ms, the result arrives exactly 100 ms after the request in logical time, so the output looks like this:

Request work at logical time 0
Do work starting at logical time 0
Result 2 received at logical time 100000000
Request work at logical time 200000000
Do work starting at logical time 200000000
Result 4 received at logical time 300000000
...

Each request takes 100 ms of logical time to be answered. In effect, the DoWork reactor has a logical execution time (LET) of 100 ms, and the requesting reaction is written as if it simply called DoWork and waited for the answer.

Notice three things about how lf_await is used:

  1. The input port passed to lf_await is listed as a trigger for the reaction. It could alternatively be listed as a source (put result between the triggers and the ->), in which case, arrivals on the port will not trigger the reaction if it is not already suspended.
  2. Reaction order is preserved. If other reactions are enabled at the same tag at which the suspended reaction resumes, they will execute in the lexical order of the reactions, including the resumed one.
  3. When lf_await returns, the current tag becomes the tag of the input. The value of the input, (result->value)(result.value), will be the newly arrived value. Any outputs set after lf_await returns are produced at that new tag.

Outputs set before lf_await are produced at the tag at which they were set. In the example, request is produced at the tag of the timer, before logical time advances, which is what allows DoWork to respond at that tag.

If several reactions of a reactor are suspended on the same input port, a single event on that port resumes all of them.

In C, lf_await is a macro that must be used within a reaction body. The macros fill in the reactor pointer where the runtime needs it. To use this mechanism in a reaction body defined in a separate file, you must name the self pointer variable self in your reaction definitions and include the macro definition as follows:

#include "../include/api/reaction_macros.h"

Making a Blocking Call with lf_async​

warning

lf_async requires compiler features provided by GCC and Clang, but not by MSVC, so Windows is not supported.

lf_async is for calling a function that may block or execute for an unpredictable time. In C, that function is an ordinary C function.In Python, that function is an ordinary Python callable, not a coroutine. The following program reads lines from the keyboard, which blocks until the user presses return, and yet a timer-driven reaction continues to run every five seconds while the program waits:

target C {
  keepalive: true
}

reactor UserInput {
  preamble {=
    #include <stdio.h>
    #include <stdlib.h>

    // Read a line from stdin into dynamically allocated memory, dropping the
    // trailing newline. The caller must free the result. Returns 0 on EOF or error.
    size_t read_string(char** result) {
      char* buffer = NULL;
      size_t capacity = 0;
      ssize_t nread = getline(&buffer, &capacity, stdin);
      if (nread < 0) {
        free(buffer);
        return 0;
      }
      if (nread > 0 && buffer[nread - 1] == '\n') {
        buffer[nread - 1] = '\0';
      }
      *result = buffer;
      return nread;
    }
  =}
  timer t(0, 5 s)
  output out: char*
  state count: int
  physical action awake

  reaction(startup, awake) -> out, awake {=
    while (true) {
      char* line = NULL;
      int nread = lf_async(awake, read_string, &line);
      if (nread == 0) {
        lf_request_stop();
        break;
      }
      // The logical time is now the physical time at which the line was read.
      lf_set(out, line);
    }
  =}

  reaction(t) -> out {=
    char* prompt = NULL;
    asprintf(&prompt, "%d: Waiting for input...", self->count++);
    lf_set(out, prompt);
  =}
}

main reactor {
  user_input = new UserInput()

  reaction(user_input.out) {=
    lf_print("At logical time " PRINTF_TIME ", Line: %s", lf_time_logical_elapsed(), user_input.out->value);
  =}
}
Lingua Franca diagram: AsyncUserInputAsyncUserInputUserInput(0, 5 s)12Pout

The call

int nread = lf_async(awake, read_string, &line);

invokes read_string(&line) and yields whatever read_string returns. The function must return a value; functions returning void are not supported. The additional arguments are passed through to the function.

The first argument, awake, is an action of the reactor that determines the tag at which the reaction continues. The calling reaction lists awake as a trigger and an effect so that it is in scope. Strictly speaking, it is not necessary to list awake as both a trigger and an effect, but doing so makes it clearer that the reaction both schedules the action and resumes when the action is triggered.

Here awake is a physical action. When read_string returns, lf_async schedules awake at the current physical time, and the reaction resumes at that tag. The logical time after the call is therefore the physical time at which the user typed the line, which is exactly what a program reading real-world input wants. Running the program and typing a few lines produces output like this:

At logical time 0, Line: 0: Waiting for input...
hello
At logical time 2314876000, Line: hello
At logical time 5000000000, Line: 1: Waiting for input...
world
At logical time 7102351000, Line: world

In C, lf_async is a macro that must be used within a reaction body. The macro fills in the reactor pointer where the runtime needs it. To use this mechanism in a reaction body defined in a separate file, you must name the self pointer variable self in your reaction definitions and include the macro definition as follows:

#include "../include/api/reaction_macros.h"

Logical Actions​

The action passed to lf_async may instead be a logical action. A logical action is scheduled when lf_async is called, at the current tag plus the action's minimum delay (or one microstep later if it has no minimum delay), rather than when the function returns. This gives the blocking call a fixed logical duration:

reactor Blocker {
  logical action done(200 ms)

  reaction(startup, done) -> done {=
    int result = lf_async(done, slow, 50);
    // Logical time is now exactly 200 ms, regardless of how long slow() took.
  =}
}

If the function returns before the 200 ms have elapsed, the reaction continues at 200 ms. If the function is still running when logical time reaches 200 ms, the reaction calling lf_async resumes at logical time 200 ms and then blocks until the function returns, holding logical time at 200 ms. Either way, the reaction continues at exactly 200 ms. This is useful when the rest of the program must not see results earlier than some fixed delay, or when the timing of the program should not depend on how long the call takes.

A physical action must be dedicated to no more than one reaction calling lf_async. The same reaction may call lf_async on it repeatedly, as UserInput does in its loop, but a second reaction using the same physical action is a runtime error. Give each such reaction its own physical action.

How It Works​

When a reaction calls lf_async or lf_await, the following happens:

  1. Any outputs set so far are propagated at the current tag, so downstream reactions see them at the tag at which they were set.
  2. The worker thread executing the reaction leaves the pool of worker threads. If no previously added thread is free, a new worker thread is added to the pool to replace it. The remaining workers can therefore advance logical time and execute other reactions as if the calling reaction had completed.
  3. For lf_async, the specified function is invoked. For lf_await, nothing is invoked.
  4. When the reaction calling lf_async or lf_await resumes, the suspended thread rejoins the pool and continues executing the reaction at the new current tag.

Worker threads added this way persist until the program terminates, so the number of them is the maximum number of calls that were suspended at the same time. Repeated calls from one reaction, like the loop in UserInput, reuse a single added thread. The function lf_added_worker_thread_count() returns the number of threads that have been added.The method self.lf_added_worker_thread_count() returns the number of threads that have been added.

In the Python target, the binding releases the interpreter lock around the parts of the call that can block inside the runtime. The callable passed to self.lf_async itself runs with the lock held.

Caveats​

Reaction order. If more than one reaction is enabled at the tag at which a suspended reaction resumes, the order in which they execute is the lexical order of the reactions. That is, the resumption will occur in the expected order relative to other reactions belonging to the same reactor.

State variables. Other reactions of the same reactor may execute while a reaction is suspended, and they may modify state variables. Do not assume that a state variable has the same value after lf_async or lf_await returns that it had before. Local variables, on the other hand, are preserved.

Re-triggering. A suspended reaction still counts as executing. If one of its triggers fires at an intervening tag, that triggering is dropped. In AwaitLET, the timer period of 200 ms is longer than the 100 ms round trip, so no timer events are lost. Had the period been shorter than the round trip, the intervening timer events would have been ignored.

Mutual exclusion. Reactions belonging to the same reactor are normally mutually exclusive. With a call to lf_async, however, the invoked function may execute concurrently with other reactions of the same reactor. Hence, that function must not access shared state variables or call other functions that do.

Termination. If the program stops before a suspended reaction is resumed, lf_async or lf_await returns at the stop tag, after the shutdown reactions have executed, so that the reaction can complete. If a reaction calls lf_async or lf_await while the program is already stopping, the call does not suspend: lf_async invokes the function and returns, and lf_await returns immediately.

Modal models. Using lf_async or lf_await in a modal model can lead to peculiar behavior, particularly if the resume occurs after that mode that issued the call has become inactive. As a consequence, it is not recommended to use lf_async or lf_await in a modal model.

The interpreter lock. The callable passed to self.lf_async holds Python's global interpreter lock while it runs. Other Python reactions make progress during that call only when the callable releases the lock. input() and time.sleep, for example, do release the lock. A stretch of pure Python does not, so other Python reactions wait until it returns.

Portability. Both mechanisms require the threaded runtime, which is the default, with the NP or GEDF_NP scheduler. They are not available with the single-threaded runtime or the adaptive scheduler. In C, lf_async uses GCC and Clang extensions (statement expressions and __typeof__) to return the function's value with its own type.