RTI Connext C++ API  Version 5.0.0
Flow Controllers

<<eXtension>> DDSFlowController and associated elements More...

Classes

struct  DDS_FlowControllerTokenBucketProperty_t
 DDSFlowController 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 DDSFlowController. More...
 
class  DDSFlowController
 <<interface>> A flow controller is the object responsible for shaping the network traffic by determining when attached asynchronous DDSDataWriter instances are allowed to write data. More...
 

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

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>> DDSFlowController and associated elements

DDSFlowController provides the network traffic shaping capability to asynchronous DDSDataWriter 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

Enumeration Type Documentation

Kinds of flow controller scheduling policy.

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

Each DDSFlowController maintains a separate FIFO queue for each unique destination (remote application). Samples written by asynchronous DDSDataWriter 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 DDSFlowController 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 DDSFlowController 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 DDSDataWriter in-order data delivery guarantee.

[default] for DDSDataWriter

DDS_HPF_FLOW_CONTROLLER_SCHED_POLICY 

Indicates /o flow control in an highest-priority-first fashion.

Determines the next destination queue to service as determined by the publication priority of the DDSDataWriter, 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 DDSFlowController 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 DDSDataWriter in-order data delivery guarantee.

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 DDSFlowController for use with an asynchronous DDSDataWriter. 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 DDSDataWriter.

Essentially, this is equivalent to a user-created DDSFlowController 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
DDSPublisher::create_datawriter
DDSDomainParticipant::lookup_flowcontroller
DDSFlowController::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 DDSFlowController for use with an asynchronous DDSDataWriter. 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 DDSFlowController 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
DDSPublisher::create_datawriter
DDSDomainParticipant::lookup_flowcontroller
DDSFlowController::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 DDSFlowController for use with an asynchronous DDSDataWriter. 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 DDSFlowController::trigger_flow. With each trigger, all accumulated data since the previous trigger is sent (across all DDSPublisher or DDSDataWriter 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 DDSFlowController 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

See Also
DDSPublisher::create_datawriter
DDSDomainParticipant::lookup_flowcontroller
DDSFlowController::trigger_flow
DDSFlowController::set_property
DDS_PublishModeQosPolicy
DDS_AsynchronousPublisherQosPolicy

RTI Connext C++ API Version 5.0.0 Copyright © Thu Aug 30 2012 Real-Time Innovations, Inc