reaction_macros.h File Reference

Macros providing an API for use in inline reaction bodies. More...

Go to the source code of this file.

Macros
#define	lf_set_present(out)
	Mark a port present.
#define	lf_set(out, val)
	Set the specified output (or input of a contained reactor) to the specified value.
#define	lf_set_array(out, val, len)
	Set the specified output (or input of a contained reactor) to the specified array with the given length.
#define	lf_set_token(out, newtoken)
	Set the specified output (or input of a contained reactor) to the specified token value.
#define	lf_set_destructor(out, dtor)
	Set the destructor associated with the specified port.
#define	lf_set_copy_constructor(out, cpy_ctor)
	Set the copy constructor associated with the specified port.
#define	lf_tag()
#define	lf_time_logical()
#define	lf_time_logical_elapsed()

Detailed Description

Macros providing an API for use in inline reaction bodies.

Author

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

Copyright

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

This set of macros is defined prior to each reaction body and undefined after the reaction body using the set_undef.h header file. If you wish to use these macros in external code, such as that implementing a bodiless reaction, then you can include this header file (and at least reactor.h, plus possibly a few other header files) in your code.

The purpose for these macros is to provide a semblance of polymorphism even though C does not support polymorphism. For example, lf_set(port, value) is a macro where the first argument is a specific port struct and the second type is a value with a type corresponding to the port's type. It is not possible in C to provide a function that can be called with a port struct and a value of any type.

Some of the macros are provided for convenience. For example, the macro can automatically provide common arguments such as the environment and can cast arguments to required base types to suppress warning.

Note for target language developers. This is one way of developing a target language where the C core runtime is adopted. This file is a translation layer that implements Lingua Franca APIs which interact with the internal APIs.

Macro Definition Documentation

lf_set

#define lf_set	(		out,
			val )

Value:

  do {                                                                                                                 \
    out->value = val;                                                                                                  \
    lf_set_present(out);                                                                                               \
    if (((token_template_t*)out)->token != NULL) {                                                                     \
      /* The cast "*((void**) &out->value)" is a hack to make the code */                                              \
      /* compile with non-token types where value is not a pointer. */                                                 \
      lf_token_t* token = _lf_initialize_token_with_value((token_template_t*)out, *((void**)&out->value), 1);          \
      out->token = token;                                                                                              \
    }                                                                                                                  \
  } while (0)

Set the specified output (or input of a contained reactor) to the specified value.

If the value argument is a primitive type such as int, double, etc. as well as the built-in types bool and string, the value is copied and therefore the variable carrying the value can be subsequently modified without changing the output. This also applies to structs with a type defined by a typedef so that the type designating string does not end in '*'.

If the value argument is a pointer to memory that the calling reaction has dynamically allocated, the memory will be automatically freed once all downstream reactions no longer need the value. If 'lf_set_destructor' is called on 'out', then that destructor will be used to free 'value'. Otherwise, the default void free(void*) function is used.

Parameters

out	The output port (by name) or input of a contained reactor in form input_name.port_name.
value	The value to insert into the self struct.

lf_set_array

#define lf_set_array	(		out,
			val,
			len )

Value:

  do {                                                                                                                 \
    lf_set_present(out);                                                                                               \
    lf_token_t* token = _lf_initialize_token_with_value((token_template_t*)out, val, len);                             \
    out->token = token;                                                                                                \
    out->value = token->value;                                                                                         \
    out->length = len;                                                                                                 \
  } while (0)

Set the specified output (or input of a contained reactor) to the specified array with the given length.

The array is assumed to be in dynamically allocated memory. The deallocation is delegated to downstream reactors, which automatically deallocate when the reference count drops to zero.

Parameters

out	The output port (by name).
val	The array to send (a pointer to the first element).
length	The length of the array to send.

lf_set_copy_constructor

#define lf_set_copy_constructor	(		out,
			cpy_ctor )

Value:

((token_type_t*)out)->copy_constructor = cpy_ctor

Set the copy constructor associated with the specified port.

The copy constructor will be used to copy any value sent through the specified port whenever a downstream user of the value declares a mutable input port or calls lf_writable_copy().

Parameters

out	The output port (by name) or input of a contained reactor in form reactor.port_name.
dtor	A pointer to a void function that takes a pointer argument (or NULL to use the default void memcpy() function.

lf_set_destructor

#define lf_set_destructor	(		out,
			dtor )

Value:

((token_type_t*)out)->destructor = dtor

Set the destructor associated with the specified port.

The destructor will be used to free any value sent through the specified port when all downstream users of the value are finished with it.

Parameters

out	The output port (by name) or input of a contained reactor in form reactor.port_name.
dtor	A pointer to a void function that takes a pointer argument (or NULL to use the default void free(void*) function.

lf_set_present

#define lf_set_present

(

out

)

Value:

lf_set_present((lf_port_base_t*)out)

Mark a port present.

This sets the is_present field of the specified output to true.

This macro is a thin wrapper around the lf_set_present() function. It simply casts the argument to lf_port_base_t* to suppress warnings.

Parameters

out	The output port (by name).

lf_set_token

#define lf_set_token	(		out,
			newtoken )

Value:

  do {                                                                                                                 \
    lf_set_present(out);                                                                                               \
    _lf_replace_template_token((token_template_t*)out, newtoken);                                                      \
    out->value = newtoken->value;                                                                                      \
    out->length = newtoken->length;                                                                                    \
  } while (0)

Set the specified output (or input of a contained reactor) to the specified token value.

Tokens in the C runtime wrap messages that are in dynamically allocated memory and perform reference counting to ensure that memory is not freed prematurely.

Parameters

out	The output port (by name).
token	A pointer to token obtained from an input, an action, or from lf_new_token().

lf_tag

#define lf_tag

(

)

Value:

lf_tag(self->base.environment)

Return the current tag of the environment invoking this reaction.

lf_time_logical

#define lf_time_logical

(

)

Value:

lf_time_logical(self->base.environment)

Return the current logical time in nanoseconds of the environment invoking this reaction.

lf_time_logical_elapsed

#define lf_time_logical_elapsed

(

)

Value:

lf_time_logical_elapsed(self->base.environment)

Return the current logical time of the environment invoking this reaction relative to the start time in nanoseconds.