FlowController Use Cases
[Programming How-To's]

Working with flow controllers. More...

Creating a flow controller

Set up participant

Create a flow controller

    DDS.FlowController controller = null;
    DDS.FlowControllerProperty_t property = new DDS.FlowControllerProperty_t();
    
    try {
       participant.get_default_flowcontroller_property(property);
   } catch (DDS.Exception) {
        System.Console.WriteLine(
            "***Error: failed to get default flow controller property");
    }
    
    // optionally modify flow controller property values
    
    controller = participant.create_flowcontroller(
        "my flow controller name", property);
    
    if (controller == null) {
        System.Console.WriteLine(
            "***Error: failed to create flow controller");
    }

Flow controlling a data writer

Set up participant

Create flow controller

Create an asynchronous data writer, FooDataWriter, of user data type Foo:

    DataWriterQos writer_qos = new DataWriterQos();

    // MyWriterListener is user defined and 
    // extends DataWriterListener
    MyWriterListener writer_listener = new MyWriterListener(); // or = null

    try {
        publisher.get_default_datawriter_qos(writer_qos);
    } catch (DDS.Exception) {
        // ... error 
    }

    // Change the writer QoS to publish asnychronously
    writer_qos.publish_mode.kind =
        PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS;

    // Setup to use the previously created flow controller
    writer_qos.publish_mode.flow_controller_name = 
        "my flow controller name";

    // Samples queued for asynchronous write are subject to the History Qos policy
    writer_qos.history.kind = HistoryQosPolicyKind.KEEP_ALL_HISTORY_QOS;

    FooDataWriter writer = (FooDataWriter) publisher.create_datawriter(
                                                     topic,
                                                     writer_qos, 
                                                     writer_listener,
                             STATUS_MASK_ALL);
    if (writer == null) {
        // ... error 
    }

    // Send data asynchronously...
    
    // Wait for asynchronous send completes, if desired
    try {
        writer.wait_for_asynchronous_publishing(timout);
    } catch (DDS.Exception) {
        System.Console.WriteLine(
            "***Error: failed to wait for asynchronous publishing");
    }

Using the built-in flow controllers

RTI Data Distribution Service provides several built-in flow controllers.

The DDS::DEFAULT_FLOW_CONTROLLER_NAME built-in flow controller provides the basic asynchronous writer behavior. When calling DDS::TypedDataWriter::write, the call signals the DDS::Publisher asynchronous publishing thread (DDS::PublisherQos::asynchronous_publisher) to send the actual data. As with any DDS::PublishModeQosPolicyKind::ASYNCHRONOUS_PUBLISH_MODE_QOS DDS::DataWriter, the DDS::TypedDataWriter::write call returns immediately afterwards. The data is sent immediately in the context of the DDS::Publisher asynchronous publishing thread.

When using the DDS::FIXED_RATE_FLOW_CONTROLLER_NAME flow controller, data is also sent in the context of the DDS::Publisher asynchronous publishing thread, but at a regular fixed interval. The thread accumulates samples from different DDS::DataWriter instances and generates data on the wire only once per DDS::FlowControllerTokenBucketProperty_t::period.

In contrast, the DDS::ON_DEMAND_FLOW_CONTROLLER_NAME flow controller permits flow only when DDS::FlowController::trigger_flow is called. The data is still sent in the context of the DDS::Publisher asynchronous publishing thread. The thread accumulates samples from different DDS::DataWriter instances (across any DDS::Publisher) and sends all data since the previous trigger.

The properties of the built-in DDS::FlowController instances can be adjusted.

Set up participant

Lookup built-in flow controller

    FlowController controller = null;

    controller = participant.lookup_flowcontroller(
        FlowController.DEFAULT_FLOW_CONTROLLER_NAME);

    // This should never happen, built-in flow controllers are always created
    if (controller == null) {
        System.Console.WriteLine("***Error: failed to lookup flow controller");
    }

Change property of built-in flow controller, if desired

    DDS.FlowControllerProperty_t property = new DDS.FlowControllerProperty_t();

    // Get the property of the flow controller
    try {
        controller.get_property(property);
    } catch (DDS.Exception) {
        System.Console.WriteLine(
            "***Error: failed to get flow controller property");
    }

    // Change the property value as desired
    property.token_bucket.period.sec = 2;
    property.token_bucket.period.nanosec = 0;

    // Update the flow controller property
    try {
       controller.set_property(property);
    } catch (DDS.Exception) {
        System.Console.WriteLine(
            "***Error: failed to set flow controller property");
    }

Create a data writer using the correct flow controller name

Shaping the network traffic for a particular transport

Set up participant

Create the transports

Create a separate flow controller for each transport

Configure DDS::DataWriter instances to only use a single transport

Associate all data writers using the same transport to the corresponding flow controller

For each transport, the corresponding flow controller limits the network traffic based on the token bucket properties

Coalescing multiple samples in a single network packet

Set up participant

Create a flow controller with a desired token bucket period

Associate the data writer with the flow controller