<<extension>> DDS_FlowController and associated elements More...

Data Structures
struct	DDS_FlowControllerTokenBucketProperty_t
	DDS_FlowController uses the popular token bucket approach for open loop network flow control. The flow control characteristics are determined by the token bucket properties. More...

struct	DDS_FlowControllerProperty_t
	Determines the flow control characteristics of the DDS_FlowController. More...

Macros
#define	DDS_FlowControllerTokenBucketProperty_t_INITIALIZER
	Initializer for new property instances.

Typedefs
typedef struct DDS_FlowControllerImpl	DDS_FlowController
	<<interface>> A flow controller is the object responsible for shaping the network traffic by determining when attached asynchronous DDS_DataWriter instances are allowed to write data.

Enumerations
enum	DDS_FlowControllerSchedulingPolicy { DDS_RR_FLOW_CONTROLLER_SCHED_POLICY, DDS_EDF_FLOW_CONTROLLER_SCHED_POLICY, DDS_HPF_FLOW_CONTROLLER_SCHED_POLICY }
	Kinds of flow controller scheduling policy. More...

Functions
const char *	DDS_FlowController_get_name (DDS_FlowController *self)
	Returns the name of the DDS_FlowController.

DDS_DomainParticipant *	DDS_FlowController_get_participant (DDS_FlowController *self)
	Returns the DDS_DomainParticipant to which the DDS_FlowController belongs.

DDS_ReturnCode_t	DDS_FlowController_set_property (DDS_FlowController self, const struct DDS_FlowControllerProperty_t prop)
	Sets the DDS_FlowController property.

DDS_ReturnCode_t	DDS_FlowController_get_property (DDS_FlowController self, struct DDS_FlowControllerProperty_t prop)
	Gets the DDS_FlowController property.

DDS_ReturnCode_t	DDS_FlowController_trigger_flow (DDS_FlowController *self)
	Provides an external trigger to the DDS_FlowController.

Variables
char *	DDS_DEFAULT_FLOW_CONTROLLER_NAME
	[default] Special value of DDS_PublishModeQosPolicy::flow_controller_name that refers to the built-in default flow controller.

char *	DDS_FIXED_RATE_FLOW_CONTROLLER_NAME
	Special value of DDS_PublishModeQosPolicy::flow_controller_name that refers to the built-in fixed-rate flow controller.

char *	DDS_ON_DEMAND_FLOW_CONTROLLER_NAME
	Special value of DDS_PublishModeQosPolicy::flow_controller_name that refers to the built-in on-demand flow controller.

Detailed Description

<<extension>> DDS_FlowController and associated elements

DDS_FlowController provides the network traffic shaping capability to asynchronous DDS_DataWriter instances. For use cases and advantages of publishing asnychronously, please refer to DDS_PublishModeQosPolicy of DDS_DataWriterQos.

See Also: DDS_PublishModeQosPolicy; DDS_DataWriterQos::publish_mode; DDS_AsynchronousPublisherQosPolicy

Macro Definition Documentation

#define DDS_FlowControllerTokenBucketProperty_t_INITIALIZER

Initializer for new property instances.

New DDS_FlowControllerProperty_t instances stored on the stack should be initialized with this value before they are passed to any function. This step ensures that the contained property values are properly initialized. This does not allocate memory.

The simplest way to create a new property structure is to initialize it on the stack at the time of its creation:

struct DDS_FlowControllerProperty_t myProperty = DDS_FlowControllerProperty_t_INITIALIZER;

Note that the above assignment is not a substitute for calling DDS_DomainParticipant_get_default_flowcontroller_property.

See Also: DDS_DomainParticipant_get_default_flowcontroller_property

Typedef Documentation

typedef struct DDS_FlowControllerImpl DDS_FlowController

<<interface>> A flow controller is the object responsible for shaping the network traffic by determining when attached asynchronous DDS_DataWriter instances are allowed to write data.

QoS:: DDS_FlowControllerProperty_t

Enumeration Type Documentation

enum DDS_FlowControllerSchedulingPolicy

Kinds of flow controller scheduling policy.

Samples written by an asynchronous DDS_DataWriter are not sent in the context of the FooDataWriter_write call. Instead, the middleware puts the samples in a queue for future processing. The DDS_FlowController associated with each asynchronous DataWriter instance determines when the samples are actually sent.

Each DDS_FlowController maintains a separate FIFO queue for each unique destination (remote application). Samples written by asynchronous DDS_DataWriter instances associated with the flow controller, are placed in the queues that correspond to the intended destinations of the sample.

When tokens become available, a flow controller must decide which queue(s) to grant tokens first. This is determined by the flow controller's scheduling policy. Once a queue has been granted tokens, it is serviced by the asynchronous publishing thread. The queued up samples will be coalesced and sent to the corresponding destination. The number of samples sent depends on the data size and the number of tokens granted.

QoS:: DDS_FlowControllerProperty_t

Enumerator:

DDS_RR_FLOW_CONTROLLER_SCHED_POLICY

Indicates to flow control in a round-robin fashion.

Whenever tokens become available, the flow controller distributes the tokens uniformly across all of its (non-empty) destination queues. No destinations are prioritized. Instead, all destinations are treated equally and are serviced in a round-robin fashion.

DDS_EDF_FLOW_CONTROLLER_SCHED_POLICY

Indicates to flow control in an earliest-deadline-first fashion.

A sample's deadline is determined by the time it was written plus the latency budget of the DataWriter at the time of the write call (as specified in the DDS_LatencyBudgetQosPolicy). The relative priority of a flow controller's destination queue is determined by the earliest deadline across all samples it contains.

When tokens become available, the DDS_FlowController distributes tokens to the destination queues in order of their deadline priority. In other words, the queue containing the sample with the earliest deadline is serviced first. The number of tokens granted equals the number of tokens required to send the first sample in the queue. Note that the priority of a queue may change as samples are sent (i.e. removed from the queue). If a sample must be sent to multiple destinations or two samples have an equal deadline value, the corresponding destination queues are serviced in a round-robin fashion.

Hence, under the default DDS_LatencyBudgetQosPolicy::duration setting, an EDF_FLOW_CONTROLLER_SCHED_POLICY DDS_FlowController preserves the order in which the user calls FooDataWriter_write across the DataWriters associated with the flow controller.

Since the DDS_LatencyBudgetQosPolicy is mutable, a sample written second may contain an earlier deadline than the sample written first if the DDS_LatencyBudgetQosPolicy::duration value is sufficiently decreased in between writing the two samples. In that case, if the first sample is not yet written (still in queue waiting for its turn), it inherits the priority corresponding to the (earlier) deadline from the second sample.

In other words, the priority of a destination queue is always determined by the earliest deadline among all samples contained in the queue. This priority inheritance approach is required in order to both honor the updated DDS_LatencyBudgetQosPolicy::duration and adhere to the DDS_DataWriter in-order data delivery guarantee.

[default] for DDS_DataWriter

DDS_HPF_FLOW_CONTROLLER_SCHED_POLICY

Indicates to flow control in a highest-priority-first fashion.

Determines the next destination queue to service as determined by the publication priority of the DDS_DataWriter, channel of multi-channel DataWriter, or individual sample.

The relative priority of a flow controller's destination queue is determined by the highest publication priority of all samples it contains.

When tokens become available, the DDS_FlowController distributes tokens to the destination queues in order of their publication priority. In other words, the queue containing the sample with the highest publication priority is serviced first. The number of tokens granted equals the number of tokens required to send the first sample in the queue. Note that the priority of a queue may change as samples are sent (i.e. removed from the queue). If a sample must be sent to multiple destinations or two samples have an equal publication priority, the corresponding destination queues are serviced in a round-robin fashion.

This priority inheritance approach is required in order to both honor the designated publication priority and adhere to the DDS_DataWriter in-order data delivery guarantee.

Function Documentation

const char* DDS_FlowController_get_name ( DDS_FlowController * self )

Returns the name of the DDS_FlowController.

Parameters

self	<<in>> Cannot be NULL.

Returns: The name of the DDS_FlowController.

DDS_DomainParticipant* DDS_FlowController_get_participant ( DDS_FlowController * self )

Returns the DDS_DomainParticipant to which the DDS_FlowController belongs.

Parameters

self	<<in>> Cannot be NULL.

Returns: The DDS_DomainParticipant to which the DDS_FlowController belongs.

DDS_ReturnCode_t DDS_FlowController_set_property	(	DDS_FlowController *	self,
		const struct DDS_FlowControllerProperty_t *	prop
	)

Sets the DDS_FlowController property.

This operation modifies the property of the DDS_FlowController.

Once a DDS_FlowController has been instantiated, only the DDS_FlowControllerProperty_t::token_bucket can be changed. The DDS_FlowControllerProperty_t::scheduling_policy is immutable.

A new DDS_FlowControllerTokenBucketProperty_t::period only takes effect at the next scheduled token distribution time (as determined by its previous value).

Parameters

self <<in>> Cannot be NULL.

prop <<in>> The new DDS_FlowControllerProperty_t. Property must be consistent. Immutable fields cannot be changed after DDS_FlowController has been created. The special value DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT can be used to indicate that the property of the DDS_FlowController should be changed to match the current default DDS_FlowControllerProperty_t set in the DDS_DomainParticipant. Cannot be NULL.

Returns: One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY, or DDS_RETCODE_INCONSISTENT_POLICY.

See Also: DDS_FlowControllerProperty_t for rules on consistency among property values.

DDS_ReturnCode_t DDS_FlowController_get_property	(	DDS_FlowController *	self,
		struct DDS_FlowControllerProperty_t *	prop
	)

Gets the DDS_FlowController property.

Parameters

self	<<in>> Cannot be NULL.
prop	<<in>> DDS_FlowController to be filled in. Cannot be NULL.

Returns: One of the Standard Return Codes

DDS_ReturnCode_t DDS_FlowController_trigger_flow ( DDS_FlowController * self )

Provides an external trigger to the DDS_FlowController.

Typically, a DDS_FlowController uses an internal trigger to periodically replenish its tokens. The period by which this trigger is called is determined by the DDS_FlowControllerTokenBucketProperty_t::period property setting.

This function provides an additional, external trigger to the DDS_FlowController. This trigger adds DDS_FlowControllerTokenBucketProperty_t::tokens_added_per_period tokens each time it is called (subject to the other property settings of the DDS_FlowController).

An on-demand DDS_FlowController can be created with a DDS_DURATION_INFINITE as DDS_FlowControllerTokenBucketProperty_t::period, in which case the only trigger source is external (i.e. the FlowController is solely triggered by the user on demand).

DDS_FlowController_trigger_flow can be called on both strict on-demand FlowController and hybrid FlowController (internally and externally triggered).

Parameters

self	<<in>> Cannot be NULL.

Returns: One of the Standard Return Codes

Variable Documentation

char* DDS_DEFAULT_FLOW_CONTROLLER_NAME

[default] Special value of DDS_PublishModeQosPolicy::flow_controller_name that refers to the built-in default flow controller.

RTI Connext provides several built-in DDS_FlowController for use with an asynchronous DDS_DataWriter. The user can choose to use the built-in flow controllers and optionally modify their properties or can create a custom flow controller.

By default, flow control is disabled. That is, the built-in DDS_DEFAULT_FLOW_CONTROLLER_NAME flow controller does not apply any flow control. Instead, it allows data to be sent asynchronously as soon as it is written by the DDS_DataWriter.

Essentially, this is equivalent to a user-created DDS_FlowController with the following DDS_FlowControllerProperty_t settings:

- DDS_FlowControllerProperty_t::scheduling_policy = DDS_EDF_FLOW_CONTROLLER_SCHED_POLICY

- DDS_FlowControllerProperty_t::token_bucket max_tokens = DDS_LENGTH_UNLIMITED

- DDS_FlowControllerProperty_t::token_bucket tokens_added_per_period = DDS_LENGTH_UNLIMITED

- DDS_FlowControllerProperty_t::token_bucket tokens_leaked_per_period = 0

- DDS_FlowControllerProperty_t::token_bucket period = 1 second

- DDS_FlowControllerProperty_t::token_bucket bytes_per_token = DDS_LENGTH_UNLIMITED

See Also: DDS_Publisher_create_datawriter; DDS_DomainParticipant_lookup_flowcontroller; DDS_FlowController_set_property; DDS_PublishModeQosPolicy; DDS_AsynchronousPublisherQosPolicy

char* DDS_FIXED_RATE_FLOW_CONTROLLER_NAME

Special value of DDS_PublishModeQosPolicy::flow_controller_name that refers to the built-in fixed-rate flow controller.

RTI Connext provides several builtin DDS_FlowController for use with an asynchronous DDS_DataWriter. The user can choose to use the built-in flow controllers and optionally modify their properties or can create a custom flow controller.

The built-in DDS_FIXED_RATE_FLOW_CONTROLLER_NAME flow controller shapes the network traffic by allowing data to be sent only once every second. Any accumulated samples destined for the same destination are coalesced into as few network packets as possible.

Essentially, this is equivalent to a user-created DDS_FlowController with the following DDS_FlowControllerProperty_t settings:

- DDS_FlowControllerProperty_t::scheduling_policy = DDS_EDF_FLOW_CONTROLLER_SCHED_POLICY

- DDS_FlowControllerProperty_t::token_bucket max_tokens = DDS_LENGTH_UNLIMITED

- DDS_FlowControllerProperty_t::token_bucket tokens_added_per_period = DDS_LENGTH_UNLIMITED

- DDS_FlowControllerProperty_t::token_bucket tokens_leaked_per_period = DDS_LENGTH_UNLIMITED

- DDS_FlowControllerProperty_t::token_bucket period = 1 second

- DDS_FlowControllerProperty_t::token_bucket bytes_per_token = DDS_LENGTH_UNLIMITED

See Also: DDS_Publisher_create_datawriter; DDS_DomainParticipant_lookup_flowcontroller; DDS_FlowController_set_property; DDS_PublishModeQosPolicy; DDS_AsynchronousPublisherQosPolicy

char* DDS_ON_DEMAND_FLOW_CONTROLLER_NAME

Special value of DDS_PublishModeQosPolicy::flow_controller_name that refers to the built-in on-demand flow controller.

RTI Connext provides several builtin DDS_FlowController for use with an asynchronous DDS_DataWriter. The user can choose to use the built-in flow controllers and optionally modify their properties or can create a custom flow controller.

The built-in DDS_ON_DEMAND_FLOW_CONTROLLER_NAME allows data to be sent only when the user calls DDS_FlowController_trigger_flow. With each trigger, all accumulated data since the previous trigger is sent (across all DDS_Publisher or DDS_DataWriter instances). In other words, the network traffic shape is fully controlled by the user. Any accumulated samples destined for the same destination are coalesced into as few network packets as possible.

This external trigger source is ideal for users who want to implement some form of closed-loop flow control or who want to only put data on the wire every so many samples (e.g. with the number of samples based on NDDS_Transport_Property_t::gather_send_buffer_count_max).

Essentially, this is equivalent to a user-created DDS_FlowController with the following DDS_FlowControllerProperty_t settings:

- DDS_FlowControllerProperty_t::scheduling_policy = DDS_EDF_FLOW_CONTROLLER_SCHED_POLICY

- DDS_FlowControllerProperty_t::token_bucket max_tokens = DDS_LENGTH_UNLIMITED

- DDS_FlowControllerProperty_t::token_bucket tokens_added_per_period = DDS_LENGTH_UNLIMITED

- DDS_FlowControllerProperty_t::token_bucket tokens_leaked_per_period = DDS_LENGTH_UNLIMITED

- DDS_FlowControllerProperty_t::token_bucket period = DDS_DURATION_INFINITE

- DDS_FlowControllerProperty_t::token_bucket bytes_per_token = DDS_LENGTH_UNLIMITED