Functions for federated execution. More...

Files
file	clock-sync.h
	Utility functions for clock synchronization in federated Lingua Franca programs.
file	federate.h
	Data structures and functions for federated Lingua Franca programs.

Data Structures
struct	federate_instance_t
	Structure that a federate instance uses to keep track of its own state. More...
struct	federation_metadata_t
	Structure for federation metadata. More...
struct	lf_stat_ll
	Holds generic statistical data. More...
struct	socket_stat_t
	Statistics and state for clock synchronization over a socket connection. More...
struct	staa_t
	Structure for STAA (safe to assume absent). More...

Macros
#define	_LF_CLOCK_SYNC_ATTENUATION 10
	Runtime clock offset updates will be divided by this number.
#define	_LF_CLOCK_SYNC_COLLECT_STATS true
	By default, collect statistics on clock synchronization.
#define	_LF_CLOCK_SYNC_EXCHANGES_PER_INTERVAL 10
	Number of required clock sync T4 messages per synchronization interval.
#define	CLOCK_SYNC_GUARD_BAND USEC(100)
	Define a guard band to filter clock synchronization messages based on discrepancies in the network delay.
#define	LF_CLOCK_SYNC LF_CLOCK_SYNC_INIT
	Clock synchronization mode.
#define	LF_CLOCK_SYNC_INIT 2
	Indicator for clock synchronization to be turned on at initialization.
#define	LF_CLOCK_SYNC_OFF 1
	Indicator for clock synchronization to be turned off altogether.
#define	LF_CLOCK_SYNC_ON 3
	Indicator for clock synchronization to be turned on at initialization and runtime.

Typedefs
typedef struct federate_instance_t	federate_instance_t
	Structure that a federate instance uses to keep track of its own state.
typedef struct federation_metadata_t	federation_metadata_t
	Structure for federation metadata.
typedef struct lf_stat_ll	lf_stat_ll
	Holds generic statistical data.
typedef enum parse_rti_code_t	parse_rti_code_t
	Code returned by lf_parse_rti_addr().
typedef struct socket_stat_t	socket_stat_t
	Statistics and state for clock synchronization over a socket connection.
typedef struct staa_t	staa_t
	Structure for STAA (safe to assume absent).

Enumerations
enum	parse_rti_code_t { SUCCESS , INVALID_PORT , INVALID_HOST , INVALID_USER , FAILED_TO_PARSE }
	Code returned by lf_parse_rti_addr(). More...

Functions
void	clock_sync_add_offset (instant_t *t)
	Add the current clock synchronization offset to a specified timestamp.
void	clock_sync_set_constant_bias (interval_t offset)
	Set a fixed offset to the physical clock.
void	clock_sync_subtract_offset (instant_t *t)
	Subtract the clock synchronization offset from a timestamp.
int	create_clock_sync_thread (lf_thread_t *thread_id)
	Create the thread responsible for handling clock synchronization with the RTI if (runtime) clock synchronization is on.
int	handle_T1_clock_sync_message (unsigned char buffer, void socket_or_net, instant_t t2, socket_type_t socket_type)
	Handle a clock synchroninzation message T1 coming from the RTI.
void	handle_T4_clock_sync_message (unsigned char buffer, void socket_or_net, instant_t r4, socket_type_t socket_type)
	Handle a clock synchronization message T4 coming from the RTI.
void	lf_connect_to_federate (uint16_t remote_federate_id)
	Connect to the federate with the specified id.
void	lf_connect_to_rti (const char *hostname, int port_number)
	Connect to the RTI at the specified host and port.
void	lf_create_server (int specified_port)
	Create a server to listen to incoming P2P connections.
void	lf_enqueue_port_absent_reactions (environment_t *env)
	Enqueue port absent reactions.
interval_t	lf_get_fed_maxwait (void)
	Return the global maxwait for the current federate.
interval_t	lf_get_sta (void)
	Return the global STA (safe to advance) offset for federated execution.
void *	lf_handle_p2p_connections_from_federates (void *ignored)
	Thread to accept connections from other federates.
void	lf_latest_tag_confirmed (tag_t tag_to_send)
	Send a latest tag confirmed (LTC) signal to the RTI.
parse_rti_code_t	lf_parse_rti_addr (const char *rti_addr)
	Parse the address of the RTI and store them into the global federation_metadata struct.
void	lf_reset_status_fields_on_input_port_triggers (void)
	Reset the status fields on network input ports to unknown or absent.
int	lf_send_message (int message_type, unsigned short port, unsigned short federate, const char next_destination_str, size_t length, unsigned char message)
	Send a message to another federate.
void	lf_send_neighbor_structure_to_RTI (net_abstraction_t)
	Send information about connections to the RTI.
tag_t	lf_send_next_event_tag (environment_t *env, tag_t tag, bool wait_for_reply)
	Send a next event tag (NET) signal.
void	lf_send_port_absent_to_federate (environment_t *env, interval_t additional_delay, unsigned short port_ID, unsigned short fed_ID)
	Send a port absent message.
int	lf_send_stop_request_to_rti (tag_t stop_tag)
	Send a MSG_TYPE_STOP_REQUEST message to the RTI.
int	lf_send_tagged_message (environment_t env, interval_t additional_delay, int message_type, unsigned short port, unsigned short federate, const char next_destination_str, size_t length, unsigned char *message)
	Send a tagged message to the specified port of the specified federate.
void	lf_set_fed_maxwait (interval_t offset)
	Set the global maxwait for the current federate.
void	lf_set_federation_id (const char *fid)
	Set the federation_id of this federate.
void	lf_set_sta (interval_t offset)
	Set the global STA (safe to advance) offset for federated execution.
void	lf_spawn_staa_thread (void)
	Spawn a thread to iterate through STAA structs.
void	lf_stall_advance_level_federation (environment_t *env, size_t level)
	Wait until inputs statuses are known up to and including the specified level.
void	lf_stall_advance_level_federation_locked (size_t level)
	Version of lf_stall_advance_level_federation() that assumes the caller holds the mutex lock.
void	lf_synchronize_with_other_federates (void)
	Synchronize the start with other federates via the RTI.
bool	lf_update_max_level (tag_t tag, bool is_provisional)
	Update the max level allowed to advance (MLAA).
instant_t	lf_wait_until_time (tag_t tag)
	Return the physical time that we should wait until before advancing to the specified tag.
void	reset_socket_stat (struct socket_stat_t *socket_stat)
	Reset statistics on the socket.
uint16_t	setup_clock_synchronization_with_rti (void)
	Setup necessary functionalities to synchronize clock with the RTI.
void	synchronize_initial_physical_clock_with_rti (net_abstraction_t rti_net)
	Synchronize the initial physical clock with the RTI.
void	tracepoint_federate_from_federate (trace_event_t event_type, int fed_id, int partner_id, tag_t *tag)
	Trace federate receiving a message from another federate.
void	tracepoint_federate_from_rti (trace_event_t event_type, int fed_id, tag_t *tag)
	Trace federate receiving a message from the RTI.
void	tracepoint_federate_to_federate (trace_event_t event_type, int fed_id, int partner_id, tag_t *tag)
	Trace federate sending a message to another federate.
void	tracepoint_federate_to_rti (trace_event_t event_type, int fed_id, tag_t *tag)
	Trace federate sending a message to the RTI.

Variables
lf_mutex_t	lf_outbound_net_mutex
	Mutex lock held while performing outbound network abstraction write and close operations.
lf_cond_t	lf_port_status_changed
	Condition variable for blocking on unkonwn federate input ports.

Detailed Description

Functions for federated execution.

This group contains functions for federated execution. The message types and protocols are defined in net_common.h.

Macro Definition Documentation

◆ _LF_CLOCK_SYNC_ATTENUATION

#define _LF_CLOCK_SYNC_ATTENUATION 10

#include <clock-sync.h>

Runtime clock offset updates will be divided by this number.

◆ _LF_CLOCK_SYNC_COLLECT_STATS

#define _LF_CLOCK_SYNC_COLLECT_STATS true

#include <clock-sync.h>

By default, collect statistics on clock synchronization.

◆ _LF_CLOCK_SYNC_EXCHANGES_PER_INTERVAL

#define _LF_CLOCK_SYNC_EXCHANGES_PER_INTERVAL 10

#include <clock-sync.h>

Number of required clock sync T4 messages per synchronization interval.

The offset to the clock will not be adjusted until this number of T4 clock synchronization messages have been received.

◆ CLOCK_SYNC_GUARD_BAND

#define CLOCK_SYNC_GUARD_BAND USEC(100)

#include <clock-sync.h>

Define a guard band to filter clock synchronization messages based on discrepancies in the network delay.

See also: Coded probes in Geng, Yilong, et al. "Exploiting a natural network effect for scalable, fine-grained clock synchronization."

◆ LF_CLOCK_SYNC

#define LF_CLOCK_SYNC LF_CLOCK_SYNC_INIT

#include <clock-sync.h>

Clock synchronization mode.

This is one of LF_CLOCK_SYNC_OFF, LF_CLOCK_SYNC_INIT, or LF_CLOCK_SYNC_ON. The default is LF_CLOCK_SYNC_INIT, which indicates that clock synchronization is performed only at initialization.

Note: This is a compile-time option.

◆ LF_CLOCK_SYNC_INIT

#define LF_CLOCK_SYNC_INIT 2

#include <clock-sync.h>

Indicator for clock synchronization to be turned on at initialization.

◆ LF_CLOCK_SYNC_OFF

#define LF_CLOCK_SYNC_OFF 1

#include <clock-sync.h>

Indicator for clock synchronization to be turned off altogether.

◆ LF_CLOCK_SYNC_ON

#define LF_CLOCK_SYNC_ON 3

#include <clock-sync.h>

Indicator for clock synchronization to be turned on at initialization and runtime.

Typedef Documentation

◆ federate_instance_t

typedef struct federate_instance_t federate_instance_t

#include <federate.h>

Structure that a federate instance uses to keep track of its own state.

◆ federation_metadata_t

typedef struct federation_metadata_t federation_metadata_t

#include <federate.h>

Structure for federation metadata.

◆ lf_stat_ll

typedef struct lf_stat_ll lf_stat_ll

#include <clock-sync.h>

Holds generic statistical data.

◆ parse_rti_code_t

typedef enum parse_rti_code_t parse_rti_code_t

#include <federate.h>

Code returned by lf_parse_rti_addr().

◆ socket_stat_t

typedef struct socket_stat_t socket_stat_t

#include <clock-sync.h>

Statistics and state for clock synchronization over a socket connection.

This struct maintains the state and statistics needed for clock synchronization between a federate and the RTI using a variant of the Precision Time Protocol (PTP). The synchronization process involves four timestamps (T1-T4) to estimate network delays and clock offsets:

T1: RTI's physical time when sending sync message
T2: Federate's physical time when receiving T1
T3: Federate's physical time when sending reply
T4: RTI's physical time when receiving reply

The round trip delay is estimated as: (T4 - T1) - (T3 - T2) The clock offset can be estimated as: ((T2 - T1) + (T3 - T4)) / 2

◆ staa_t

typedef struct staa_t staa_t

#include <federate.h>

Structure for STAA (safe to assume absent).

Enumeration Type Documentation

◆ parse_rti_code_t

enum parse_rti_code_t

#include <federate.h>

Code returned by lf_parse_rti_addr().

Enumerator
SUCCESS
INVALID_PORT
INVALID_HOST
INVALID_USER
FAILED_TO_PARSE

Function Documentation

◆ clock_sync_add_offset()

void clock_sync_add_offset ( instant_t * t )

#include <clock-sync.h>

Add the current clock synchronization offset to a specified timestamp.

Parameters

t	Pointer to the timestamp to which to add the offset.

◆ clock_sync_set_constant_bias()

void clock_sync_set_constant_bias ( interval_t offset )

#include <clock-sync.h>

Set a fixed offset to the physical clock.

After calling this, the value returned by lf_time_physical(void) and get_elpased_physical_time(void) will have this specified offset added to what it would have returned before the call.

◆ clock_sync_subtract_offset()

void clock_sync_subtract_offset ( instant_t * t )

#include <clock-sync.h>

Subtract the clock synchronization offset from a timestamp.

Parameters

t	The timestamp from which to subtract the current clock sync offset.

◆ create_clock_sync_thread()

int create_clock_sync_thread ( lf_thread_t * thread_id )

#include <clock-sync.h>

Create the thread responsible for handling clock synchronization with the RTI if (runtime) clock synchronization is on.

Otherwise, do nothing and return 0.

Returns: On success, returns 0; On error, it returns an error number.

◆ handle_T1_clock_sync_message()

int handle_T1_clock_sync_message	(	unsigned char *	buffer,
		void *	socket_or_net,
		instant_t	t2,
		socket_type_t	socket_type )

#include <clock-sync.h>

Handle a clock synchroninzation message T1 coming from the RTI.

T1 is the first message in a PTP exchange. This replies to the RTI with a T3 message. It also measures the time it takes between when the method is called and the reply has been sent.

Parameters

buffer	The buffer containing the message, including the message type.
net_abstraction_t	The pointer to the network abstraction.
t2	The physical time at which the T1 message was received.
socket_type	The socket type (TCP or UDP).

Returns: 0 if T3 reply is successfully sent, -1 otherwise.

◆ handle_T4_clock_sync_message()

void handle_T4_clock_sync_message	(	unsigned char *	buffer,
		void *	socket_or_net,
		instant_t	r4,
		socket_type_t	socket_type )

#include <clock-sync.h>

Handle a clock synchronization message T4 coming from the RTI.

If the socket_or_net is a network abstraction, then assume we are in the initial clock synchronization phase and set the clock offset based on the estimated clock synchronization error. Otherwise, if the socket_or_net is UDP socket, then this looks also for a subsequent "coded probe" message on the socket. If the delay between the T4 and the coded probe message is not as expected, then reject this clock synchronization round. If it is not rejected, then make an adjustment to the clock offset based on the estimated error. This function does not acquire the net_mutex lock. The caller should acquire it unless it is sure there is only one thread running.

Parameters

buffer	The buffer containing the message, including the message type.
net_abstraction_t	The pointer to the network abstraction.
r4	The physical time at which this T4 message was received.\
socket_type	The socket type (TCP or UDP).

◆ lf_connect_to_federate()

void lf_connect_to_federate ( uint16_t remote_federate_id )

#include <federate.h>

Connect to the federate with the specified id.

The established connection will then be used in functions such as lf_send_tagged_message() to send messages directly to the specified federate. This function first sends an MSG_TYPE_ADDRESS_QUERY message to the RTI to obtain the IP address and port number of the specified federate. It then attempts to establish a network abstraction connection to the specified federate. If this fails, the program exits. If it succeeds, it sets element [id] of the _fed.net_for_outbound_p2p_connections global array to refer to the network abstraction for communicating directly with the federate.

Parameters

remote_federate_id The ID of the remote federate.

◆ lf_connect_to_rti()

void lf_connect_to_rti	(	const char *	hostname,
		int	port_number )

#include <federate.h>

Connect to the RTI at the specified host and port.

This will return the network abstraction for the connection. If port_number is 0, then start at DEFAULT_PORT and increment the port number on each attempt. If an attempt fails, wait CONNECT_RETRY_INTERVAL and try again. If it fails after CONNECT_TIMEOUT, the program exits. If it succeeds, it sets the _fed.net_to_RTI global variable to refer to the network abstraction for communicating with the RTI.

Parameters

hostname	A hostname, such as "localhost".
port_number	A port number or 0 to start with the default.

◆ lf_create_server()

void lf_create_server ( int specified_port )

#include <federate.h>

Create a server to listen to incoming P2P connections.

Such connections are used for physical connections or any connection if using decentralized coordination. This function only handles the creation of the server network abstraction. The bound port for the server network abstraction is then sent to the RTI by sending an MSG_TYPE_ADDRESS_ADVERTISEMENT message (

See also: net_common.h). This function expects no response from the RTI.

If a port is specified by the user, that will be used. Otherwise, a random port will be assigned. If the bind fails, it will retry after PORT_BIND_RETRY_INTERVAL until it has tried PORT_BIND_RETRY_LIMIT times. Then it will fail.

Parameters

specified_port The port specified by the user or 0 to use a random port.

◆ lf_enqueue_port_absent_reactions()

void lf_enqueue_port_absent_reactions ( environment_t * env )

#include <federate.h>

Enqueue port absent reactions.

These reactions will send a MSG_TYPE_PORT_ABSENT message to downstream federates if a given network output port is not present.

Parameters

env	The environment of the federate

◆ lf_get_fed_maxwait()

interval_t lf_get_fed_maxwait ( void )

#include <reactor.h>

Return the global maxwait for the current federate.

◆ lf_get_sta()

interval_t lf_get_sta ( void )

#include <reactor.h>

Return the global STA (safe to advance) offset for federated execution.

◆ lf_handle_p2p_connections_from_federates()

void * lf_handle_p2p_connections_from_federates ( void * ignored )

#include <federate.h>

Thread to accept connections from other federates.

This thread accepts connections from federates that send messages directly to this one (not through the RTI). This thread starts a thread for each accepted network abstraction connection to read messages and, once it has opened all expected network abstractions, exits.

Parameters

ignored No argument needed for this thread.

◆ lf_latest_tag_confirmed()

void lf_latest_tag_confirmed ( tag_t tag_to_send )

#include <federate.h>

Send a latest tag confirmed (LTC) signal to the RTI.

This avoids the send if an equal or later LTC has previously been sent.

This function assumes the caller holds the mutex lock on the top-level environment.

Parameters

tag_to_send The tag to send.

◆ lf_parse_rti_addr()

parse_rti_code_t lf_parse_rti_addr ( const char * rti_addr )

#include <federate.h>

Parse the address of the RTI and store them into the global federation_metadata struct.

Returns: a parse_rti_code_t indicating the result of the parse.

◆ lf_reset_status_fields_on_input_port_triggers()

void lf_reset_status_fields_on_input_port_triggers ( void )

#include <federate.h>

Reset the status fields on network input ports to unknown or absent.

This will reset to absent if the last_known_status_tag field of the port is greater than or equal to the current tag of the top-level environment. This should be overriden to present if an event gets scheduled. Otherwise, set the status to unknown.

Note: This function must be called at the beginning of each logical time.

◆ lf_send_message()

int lf_send_message	(	int	message_type,
		unsigned short	port,
		unsigned short	federate,
		const char *	next_destination_str,
		size_t	length,
		unsigned char *	message )

#include <federate.h>

Send a message to another federate.

This function is used for physical connections between federates. If the connection to the remote federate or the RTI has been broken, then this returns -1 without sending. Otherwise, it returns 0.

This method assumes that the caller does not hold the lf_outbound_net_mutex lock, which it acquires to perform the send.

Parameters

message_type	The type of the message being sent (currently only MSG_TYPE_P2P_MESSAGE).
port	The ID of the destination port.
federate	The ID of the destination federate.
next_destination_str	The name of the next destination in string format (for reporting).
length	The message length.
message	The message.

Returns: 0 if the message has been sent, -1 otherwise.

◆ lf_send_neighbor_structure_to_RTI()

void lf_send_neighbor_structure_to_RTI ( net_abstraction_t )

#include <federate.h>

Send information about connections to the RTI.

This is a generated function that sends information about connections between this federate and other federates where messages are routed through the RTI. Currently, this only includes logical connections when the coordination is centralized. This information is needed for the RTI to perform the centralized coordination.

See also: MSG_TYPE_NEIGHBOR_STRUCTURE in net_common.h

Parameters

socket_TCP_RTI The socket descriptor for the connection to the RTI.

◆ lf_send_next_event_tag()

tag_t lf_send_next_event_tag	(	environment_t *	env,
		tag_t	tag,
		bool	wait_for_reply )

#include <federate.h>

Send a next event tag (NET) signal.

If this federate depends on upstream federates or sends data to downstream federates, then send to the RTI a NET, which will give the tag of the earliest event on the event queue, or, if the queue is empty, the timeout time, or, if there is no timeout, FOREVER.

If there are network outputs that depend on physical actions, then insert a dummy event to ensure this federate advances its tag so that downstream federates can make progress.

A NET is a promise saying that, absent network inputs, this federate will not produce an output message with tag earlier than the NET value.

If there are upstream federates, then after sending a NET, this will block until either the RTI grants the advance to the requested time or the wait for the response from the RTI is interrupted by a change in the event queue (e.g., a physical action triggered or a network message arrived). If there are no upstream federates, then it will not wait for a TAG (which won't be forthcoming anyway) and returns the earliest tag on the event queue.

If the federate has neither upstream nor downstream federates, then this returns the specified tag immediately without sending anything to the RTI.

If there is at least one physical action somewhere in the federate that can trigger an output to a downstream federate, then the NET is required to be less than the current physical time. If physical time is less than the earliest event in the event queue (or the event queue is empty), then this function will insert a dummy event with a tag equal to the current physical time (and a microstep of 0). This will enforce advancement of tag for this federate and causes a NET message to be sent repeatedly as physical time advances with the time interval between messages controlled by the target parameter coordination-options: {advance-message-interval timevalue}. It will stop creating dummy events if and when its event queue has an event with a timestamp less than physical time.

If wait_for_reply is false, then this function will simply send the specified tag and return that tag immediately. This is useful when a federate is shutting down and will not be sending any more messages at all.

In all cases, this returns either the specified tag or another tag when it is safe to advance logical time to the returned tag. The returned tag may be less than the specified tag if there are upstream federates and either the RTI responds with a lesser tag or the wait for a response from the RTI is interrupted by a change in the event queue.

This function is used in centralized coordination only.

This function assumes the caller holds the mutex lock.

Parameters

env	The environment of the federate
tag	The tag.
wait_for_reply	If true, wait for a reply.

◆ lf_send_port_absent_to_federate()

void lf_send_port_absent_to_federate	(	environment_t *	env,
		interval_t	additional_delay,
		unsigned short	port_ID,
		unsigned short	fed_ID )

#include <federate.h>

Send a port absent message.

This informs the remote federate that it will not receive a message with tag less than the current tag of the specified environment delayed by the additional_delay.

Parameters

env	The environment from which to get the current tag.
additional_delay	The after delay of the connection or NEVER if none.
port_ID	The ID of the receiving port.
fed_ID	The fed ID of the receiving federate.

◆ lf_send_stop_request_to_rti()

int lf_send_stop_request_to_rti ( tag_t stop_tag )

#include <federate.h>

Send a MSG_TYPE_STOP_REQUEST message to the RTI.

The payload is the specified tag plus one microstep. If this federate has previously received a stop request from the RTI, then do not send the message and return 1. Return -1 if the network abstraction is disconnected. Otherwise, return 0.

Returns: 0 if the message is sent.

◆ lf_send_tagged_message()

int lf_send_tagged_message	(	environment_t *	env,
		interval_t	additional_delay,
		int	message_type,
		unsigned short	port,
		unsigned short	federate,
		const char *	next_destination_str,
		size_t	length,
		unsigned char *	message )

#include <federate.h>

Send a tagged message to the specified port of the specified federate.

The tag will be the current tag of the specified environment delayed by the specified additional_delay. If the delayed tag falls after the timeout time, then the message is not sent and -1 is returned. The caller can reuse or free the memory storing the message after this returns.

If the message fails to send (e.g. the network abstraction connection is broken), then the response depends on the message_type. For MSG_TYPE_TAGGED_MESSAGE, the message is supposed to go via the RTI, and failure to communicate with the RTI is a critical failure. In this case, the program will exit with an error message. If the message type is MSG_TYPE_P2P_TAGGED_MESSAGE, then the failure is not critical. It may be due to the remote federate having exited, for example, because its safe-to-process offset led it to believe that there were no messages forthcoming. In this case, on failure to send the message, this function returns -11.

This method assumes that the caller does not hold the lf_outbound_net_mutex lock, which it acquires to perform the send.

Parameters

env	The environment from which to get the current tag.
additional_delay	The after delay on the connection or NEVER is there is none.
message_type	The type of the message being sent. Currently can be MSG_TYPE_TAGGED_MESSAGE for messages sent via the RTI or MSG_TYPE_P2P_TAGGED_MESSAGE for messages sent directly between federates.
port	The ID of the destination port.
federate	The ID of the destination federate.
next_destination_str	The next destination in string format (RTI or federate) (used for reporting errors).
length	The message length.
message	The message.

Returns: 0 if the message has been sent, 1 otherwise.

◆ lf_set_fed_maxwait()

void lf_set_fed_maxwait ( interval_t offset )

#include <reactor.h>

Set the global maxwait for the current federate.

Parameters

offset A non-negative time value to be applied as the maxwait.

◆ lf_set_federation_id()

void lf_set_federation_id ( const char * fid )

#include <federate.h>

Set the federation_id of this federate.

Parameters

fid	The federation ID.

◆ lf_set_sta()

void lf_set_sta ( interval_t offset )

#include <reactor.h>

Set the global STA (safe to advance) offset for federated execution.

Parameters

offset A non-negative time value to be applied as the STA offset.

◆ lf_spawn_staa_thread()

void lf_spawn_staa_thread ( void )

#include <federate.h>

Spawn a thread to iterate through STAA structs.

This will set their associated ports absent at an offset if the port is not present with a value by a certain physical time.

◆ lf_stall_advance_level_federation()

void lf_stall_advance_level_federation	(	environment_t *	env,
		size_t	level )

#include <federate.h>

Wait until inputs statuses are known up to and including the specified level.

Specifically, wait until the specified level is less that the max level allowed to advance (MLAA). This function does nothing if the environment is not the top-level environment.

Parameters

env	The environment (which should always be the top-level environment).
level	The level to which we would like to advance.

◆ lf_stall_advance_level_federation_locked()

void lf_stall_advance_level_federation_locked ( size_t level )

#include <federate.h>

Version of lf_stall_advance_level_federation() that assumes the caller holds the mutex lock.

Parameters

level The level to which we would like to advance.

◆ lf_synchronize_with_other_federates()

void lf_synchronize_with_other_federates ( void )

#include <federate.h>

Synchronize the start with other federates via the RTI.

This assumes that a connection to the RTI is already made and net_to_RTI is valid. It then sends the current logical time to the RTI and waits for the RTI to respond with a specified time. It starts a thread to listen for messages from the RTI.

◆ lf_update_max_level()

bool lf_update_max_level	(	tag_t	tag,
		bool	is_provisional )

#include <federate.h>

Update the max level allowed to advance (MLAA).

If the specified tag is greater than the current_tag of the top-level environment (or equal and is_provisional is false), then set the MLAA to INT_MAX and return. This removes any barriers on execution at the current tag due to network inputs. Otherwise, set the MLAA to the minimum level over all (non-physical) network input ports where the status of the input port is not known at that current_tag.

This function assumes that the caller holds the mutex.

Parameters

tag	The latest TAG or PTAG received by this federate.
is_provisional	Whether the tag was provisional.

Returns: True if the MLAA changed.

◆ lf_wait_until_time()

instant_t lf_wait_until_time ( tag_t tag )

#include <federate.h>

Return the physical time that we should wait until before advancing to the specified tag.

This function adds the STA offset (STP_offset parameter) to the time of the specified tag unless the tag is the starting tag (it is always safe to advance to the starting tag). It also avoids adding the STA offset if all network input ports are known at least up to one microstep earlier than the specified tag.

This function assumes that the caller holds the environment mutex.

Parameters

time	The specified time.

◆ reset_socket_stat()

void reset_socket_stat ( struct socket_stat_t * socket_stat )

#include <clock-sync.h>

Reset statistics on the socket.

Parameters

socket_stat The socket_stat_t struct that keeps track of stats for a given connection

◆ setup_clock_synchronization_with_rti()

uint16_t setup_clock_synchronization_with_rti ( void )

#include <clock-sync.h>

Setup necessary functionalities to synchronize clock with the RTI.

Returns: port number to be sent to the RTI. If clock synchronization is off compeltely, USHRT_MAX is returned. If clock synchronization is set to initial, 0 is sent. If clock synchronization is set to on, a reserved UDP port number will be sent.

◆ synchronize_initial_physical_clock_with_rti()

void synchronize_initial_physical_clock_with_rti ( net_abstraction_t rti_net )

#include <clock-sync.h>

Synchronize the initial physical clock with the RTI.

A call to this function is inserted into the startup sequence by the code generator if initial clock synchronization is required.

This is a blocking function that expects to read a MSG_TYPE_CLOCK_SYNC_T1 from the RTI network abstraction. It will then follow the PTP protocol to synchronize the local physical clock with the RTI. Failing to complete this protocol is treated as a catastrophic error that causes the federate to exit.

Parameters

rti_net Pointer to the RTI's network abstraction.

◆ tracepoint_federate_from_federate()

void tracepoint_federate_from_federate	(	trace_event_t	event_type,
		int	fed_id,
		int	partner_id,
		tag_t *	tag )

#include <tracepoint.h>

Trace federate receiving a message from another federate.

Parameters

event_type	The type of event. Possible values are:
fed_id	The federate identifier.
partner_id	The partner federate identifier.
tag	Pointer to the tag that has been received, or NULL.

◆ tracepoint_federate_from_rti()

void tracepoint_federate_from_rti	(	trace_event_t	event_type,
		int	fed_id,
		tag_t *	tag )

#include <tracepoint.h>

Trace federate receiving a message from the RTI.

Parameters

event_type	The type of event. Possible values are:
fed_id	The federate identifier.
tag	Pointer to the tag that has been received, or NULL.

◆ tracepoint_federate_to_federate()

void tracepoint_federate_to_federate	(	trace_event_t	event_type,
		int	fed_id,
		int	partner_id,
		tag_t *	tag )

#include <tracepoint.h>

Trace federate sending a message to another federate.

Parameters

event_type	The type of event. Possible values are:
fed_id	The federate identifier.
partner_id	The partner federate identifier.
tag	Pointer to the tag that has been sent, or NULL.

◆ tracepoint_federate_to_rti()

void tracepoint_federate_to_rti	(	trace_event_t	event_type,
		int	fed_id,
		tag_t *	tag )

#include <tracepoint.h>

Trace federate sending a message to the RTI.

Parameters

event_type	The type of event. Possible values are:
fed_id	The federate identifier.
tag	Pointer to the tag that has been sent, or NULL.

Variable Documentation

◆ lf_outbound_net_mutex

lf_mutex_t lf_outbound_net_mutex

extern

#include <federate.h>

Mutex lock held while performing outbound network abstraction write and close operations.

◆ lf_port_status_changed

lf_cond_t lf_port_status_changed

extern

#include <federate.h>

Condition variable for blocking on unkonwn federate input ports.

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ _LF_CLOCK_SYNC_ATTENUATION

◆ _LF_CLOCK_SYNC_COLLECT_STATS

◆ _LF_CLOCK_SYNC_EXCHANGES_PER_INTERVAL

◆ CLOCK_SYNC_GUARD_BAND

◆ LF_CLOCK_SYNC

◆ LF_CLOCK_SYNC_INIT

◆ LF_CLOCK_SYNC_OFF

◆ LF_CLOCK_SYNC_ON

Typedef Documentation

◆ federate_instance_t

◆ federation_metadata_t

◆ lf_stat_ll

◆ parse_rti_code_t

◆ socket_stat_t

◆ staa_t

Enumeration Type Documentation

◆ parse_rti_code_t

Function Documentation

◆ clock_sync_add_offset()

◆ clock_sync_set_constant_bias()

◆ clock_sync_subtract_offset()

◆ create_clock_sync_thread()

◆ handle_T1_clock_sync_message()

◆ handle_T4_clock_sync_message()

◆ lf_connect_to_federate()

◆ lf_connect_to_rti()

◆ lf_create_server()

◆ lf_enqueue_port_absent_reactions()

◆ lf_get_fed_maxwait()

◆ lf_get_sta()

◆ lf_handle_p2p_connections_from_federates()

◆ lf_latest_tag_confirmed()

◆ lf_parse_rti_addr()

◆ lf_reset_status_fields_on_input_port_triggers()

◆ lf_send_message()

◆ lf_send_neighbor_structure_to_RTI()

◆ lf_send_next_event_tag()

◆ lf_send_port_absent_to_federate()

◆ lf_send_stop_request_to_rti()

◆ lf_send_tagged_message()

◆ lf_set_fed_maxwait()

◆ lf_set_federation_id()

◆ lf_set_sta()

◆ lf_spawn_staa_thread()

◆ lf_stall_advance_level_federation()

◆ lf_stall_advance_level_federation_locked()

◆ lf_synchronize_with_other_federates()

◆ lf_update_max_level()

◆ lf_wait_until_time()

◆ reset_socket_stat()

◆ setup_clock_synchronization_with_rti()

◆ synchronize_initial_physical_clock_with_rti()

◆ tracepoint_federate_from_federate()

◆ tracepoint_federate_from_rti()

◆ tracepoint_federate_to_federate()

◆ tracepoint_federate_to_rti()

Variable Documentation

◆ lf_outbound_net_mutex

◆ lf_port_status_changed