37.3 FlowControllers (DDS Extension)

This section does not apply when using the separate add-on product, Ada Language Support, which does not support FlowControllers.

A FlowController is the object responsible for shaping the network traffic by determining when attached asynchronous DataWriters are allowed to write data. To configure a DataWriter to be asynchronous, see 59.20 PUBLISH_MODE QosPolicy (DDS Extension).

You can use one of the built-in FlowControllers (and optionally modify their properties), create a custom FlowController by using the DomainParticipant’s create_flowcontroller() operation (see 37.3.6 Creating and Deleting FlowControllers), or create a custom FlowController by using the DomainParticipant's 59.19 PROPERTY QosPolicy (DDS Extension) ; see 37.3.5 Creating and Configuring Custom FlowControllers with Property QoS.

To use a FlowController, you provide its name in the DataWriter’s 59.20 PUBLISH_MODE QosPolicy (DDS Extension).

• DDS_DEFAULT_FLOW_CONTROLLER_NAME

  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 DataWriter.

• DDS_FIXED_RATE_FLOW_CONTROLLER_NAME

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

• DDS_ON_DEMAND_FLOW_CONTROLLER_NAME

  The ON_DEMAND flow controller allows data to be sent only when you call the FlowController’s trigger_flow() operation. With each trigger, all accumulated data since the previous trigger is sent (across all Publishers or DataWriters). In other words, the network traffic shape is fully controlled by the user. Any accumulated DDS 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 DDS samples (e.g., with the number of DDS samples based on NDDS_Transport_Property_t’s gather_send_buffer_count_max).

The default property settings for the built-in FlowControllers are described in the API Reference HTML documentation.

DDS samples written by an asynchronous DataWriter are not sent in the context of the write() call. Instead, Connext puts the DDS samples in a queue for future processing and they are sent in the asynchronous publishing thread. (See 58.1 ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension).) The FlowController associated with each asynchronous DataWriter determines when the DDS samples are actually sent.

Each FlowController maintains a separate FIFO queue for each unique destination (remote application). DDS samples written by asynchronous DataWriters associated with the FlowController are placed in the queues that correspond to the intended destinations of the DDS sample.

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

Table 37.2 DDS_FlowControllerProperty_t lists the properties for a FlowController.

Table 37.2 DDS_FlowControllerProperty_t

Type	Field Name	Description
DDS_FlowControllerSchedulingPolicy	scheduling_policy	Round robin, earliest deadline first, or highest priority first. See 37.3.1 Flow Controller Scheduling Policies.
DDS_FlowControllerTokenBucketProperty_t	token_bucket	See 37.3.3 Token Bucket Properties.

Table 37.3 FlowController Operations lists the operations available for a FlowController.

Table 37.3 FlowController Operations

Operation	Description	Reference
get_property	Get and Set the FlowController properties.	37.3.8 Getting/Setting Properties for a Specific FlowController
set_property
trigger_flow	Provides an external trigger to the FlowController.	37.3.9 Adding an External Trigger
get_name	Returns the name of the FlowController.	37.3.10 Other FlowController Operations
get_participant	Returns the DomainParticipant to which the FlowController belongs.