Reference counting and the token type in the C target - lf-lang/lingua-franca GitHub Wiki

Define an output to be either an output port or the record on the self struct that records data sent to the input port of a contained reactor. If the output has a type of the form type* or type[], then it is said to have token type, and object of type lf_token_t will be created by the code generator to serve as a template for the data produced by this output. The struct for this output (a field of the self struct) will have a pointer to the template token at all times, though the actual object pointed to can change over time. The template token contains the following critical pieces of information:

  • value: a pointer to the payload for the token, which is either an array or a scalar.
  • element_size: the size of each array element (or the total size if not an array). This is determined by the type of the output.
  • length: the length of the array of objects of size element_size carried by the token or 1 if it is not an array.
  • num_destinations: the number of destination input ports that refer to this output.
  • ref_count: A count of the number of times this token is currently referenced by an event on the event queue, including events with the current tag, plus 1 if the token is a template token. As explained below, a token can be put on the event queue using the lf_schedule_token function.
  • destructor: a function that frees the memory of each element of size element_size.
  • copy_constructor: a function that copies an element of size element_size.

If no destructor is given, then free will be used. If no copy constructor is given, then elements will be copied using assignment =. A template token may become detached from an output (see below), at which time the num_destinations field will be set to 0.

When a reaction sets an output (or the input of a contained reactor) via lf_set(name, value), it attempts to just update the value (and maybe the length) of the template token. It can do this if and only if the ref_count is 1. If ref_count > 1, then the current reference token is detached, meaning that num_destinations is set to 0 and ref_count is decremented. A new token is allocated (or retrieved from the recycle bin, see below), replacing the old. It inherits the element_size, num_destinations, destructor, and copy_constructor of the previous template token. Its length is set to 1 and the value set to the value argument of lf_set.

FIXME:

Mutable inputs

Scheduling tokens

lf_new_array

recycling