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

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)
lf_token_t * _lf_initialize_token_with_value(token_template_t *tmplt, void *value, size_t length)
Definition lf_token.c:282
Definition lf_token.h:94
Base type for ports (lf_port_base_t) and actions (trigger_t), which can carry tokens....
Definition lf_token.h:121
lf_token_t * token
Definition lf_token.h:124

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
outThe output port (by name) or input of a contained reactor in form input_name.port_name.
valueThe value to insert into the self struct.

◆ lf_set_array

#define lf_set_array ( out,
val,
len )
Value:
do { \
lf_set_present(out); \
out->token = token; \
out->value = token->value; \
out->length = len; \
} while (0)
void * value
Definition lf_token.h:96

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
outThe output port (by name).
valThe array to send (a pointer to the first element).
lengthThe 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
Type information for tokens. Specifically, this struct contains the fields needed to support token ty...
Definition lf_token.h:67

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
outThe output port (by name) or input of a contained reactor in form reactor.port_name.
dtorA 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
outThe output port (by name) or input of a contained reactor in form reactor.port_name.
dtorA 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:
#define lf_set_present(out)
Mark a port present.
Definition reaction_macros.h:48
Base type for ports. Port structs are customized types because their payloads are type specific....
Definition lf_token.h:140

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
outThe 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
outThe output port (by name).
tokenA 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)
#define lf_tag()
Definition reaction_macros.h:189

Return the current tag of the environment invoking this reaction.

◆ lf_time_logical

#define lf_time_logical ( )
Value:
lf_time_logical(self->base.environment)
#define lf_time_logical()
Definition reaction_macros.h:194

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)
#define lf_time_logical_elapsed()
Definition reaction_macros.h:200

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