RTI Connext Modern C++ API  Version 6.0.1
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
rti::pub::FlowController Class Reference

<<extension>> <<reference-type>> A flow controller is the object responsible for shaping the network traffic by determining when attached asynchronous dds::pub::DataWriter instances are allowed to write data. More...

#include <FlowController.hpp>

Inheritance diagram for rti::pub::FlowController:
dds::core::Reference< FlowControllerImpl >

Public Member Functions

 FlowController (dds::domain::DomainParticipant the_participant, const std::string &the_name, const FlowControllerProperty &the_property=FlowControllerProperty())
 Creates a FlowController with specific properties.
 
std::string name () const
 Gets the name of this FlowController.
 
dds::domain::DomainParticipant participant () const
 Gets the participant associated to this FlowController.
 
FlowControllerProperty property () const
 Gets the configuration of this FlowController.
 
void property (const FlowControllerProperty &prop) const
 Gets the configuration of this FlowController.
 
void trigger_flow ()
 Provides an external way to trigger a FlowController.
 
void retain ()
 Disables the automatic destruction of this object.
 
void close ()
 Manually destroys this object.
 
bool closed () const
 Returns true if this FlowController has been closed.
 

Static Public Attributes

static
OMG_DDS_API_CLASS_VARIABLE
const std::string 
DEFAULT_NAME
 Name that identifies the built-in default FlowController.
 
static
OMG_DDS_API_CLASS_VARIABLE
const std::string 
FIXED_RATE_NAME
 Name that identifies the built-in fixed-rate FlowController.
 
static
OMG_DDS_API_CLASS_VARIABLE
const std::string 
ON_DEMAND_NAME
 Name that identifies the built-in on-demand FlowController.
 

Related Functions

(Note that these are not member functions.)

FlowController find_flow_controller (dds::domain::DomainParticipant participant, const std::string &name)
 Retrieves an existing FlowController.
 

Detailed Description

<<extension>> <<reference-type>> A flow controller is the object responsible for shaping the network traffic by determining when attached asynchronous dds::pub::DataWriter instances are allowed to write data.

Note
A FlowController provides all the functions of a <<reference-type>>, including close() and retain().

Constructor & Destructor Documentation

rti::pub::FlowController::FlowController ( dds::domain::DomainParticipant  the_participant,
const std::string &  the_name,
const FlowControllerProperty the_property = FlowControllerProperty() 
)
inline

Creates a FlowController with specific properties.

Parameters
the_participantThe DomainParticipant where this FlowController exists
the_nameName to refer to this FlowController
the_propertyDetermines how to shape the network traffic

The created rti::pub::FlowController is associated with a dds::pub::DataWriter via rti::core::policy::PublishMode::flow_controller_name. A single FlowController may service multiple DataWriters instances, even if they belong to a different dds::pub::Publisher. The property determines how the FlowController shapes the network traffic.

Precondition
The specified property must be consistent, or the operation will fail and no rti::pub::FlowController will be created.
See Also
rti::pub::FlowControllerProperty for rules on consistency among property

Member Function Documentation

std::string rti::pub::FlowController::name ( ) const
inline

Gets the name of this FlowController.

dds::domain::DomainParticipant rti::pub::FlowController::participant ( ) const
inline

Gets the participant associated to this FlowController.

FlowControllerProperty rti::pub::FlowController::property ( ) const
inline

Gets the configuration of this FlowController.

void rti::pub::FlowController::property ( const FlowControllerProperty prop) const
inline

Gets the configuration of this FlowController.

This operation modifies the property of the rti::pub::FlowController.

Once a rti::pub::FlowController has been instantiated, only the rti::pub::FlowControllerProperty::token_bucket can be changed. The rti::pub::FlowControllerProperty::scheduling_policy is immutable.

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

Parameters
prop<<in>> The new rti::pub::FlowControllerProperty. Property must be consistent. Immutable fields cannot be changed after rti::pub::FlowController has been created.
Exceptions
Oneof the Standard Exceptions, dds::core::ImmutablePolicyError, or dds::core::InconsistentPolicyError.
See Also
rti::pub::FlowControllerProperty for rules on consistency among property values.
void rti::pub::FlowController::trigger_flow ( )
inline

Provides an external way to trigger a FlowController.

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

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

An on-demand rti::pub::FlowController can be created with a dds::core::Duration::infinite() as FlowControllerTokenBucketProperty::period, in which case the only trigger source is external (i.e. the FlowController is solely triggered by the user on demand).

rti::pub::FlowController::trigger_flow can be called on both strict on-demand FlowController and hybrid FlowController (internally and externally triggered).

Exceptions
Oneof the Standard Exceptions
void rti::pub::FlowController::retain ( )
inline

Disables the automatic destruction of this object.

Disables the automatic destruction of the underlying FlowController when when there are no more references to it. After that it can be looked up using rti::pub::lookup_flow_controller

To delete a retained object, manually call close()

void rti::pub::FlowController::close ( )
inline

Manually destroys this object.

Destroys the object referenced by this FlowController reference.

After closing it, any calls to this object through this or other references throw dds::core::AlreadyClosedError.

See Also
retain()
bool rti::pub::FlowController::closed ( ) const
inline

Returns true if this FlowController has been closed.

The FlowController may have been closed either by calling close() or by closing the related DomainParticipant.

Friends And Related Function Documentation

FlowController find_flow_controller ( dds::domain::DomainParticipant  participant,
const std::string &  name 
)
related

Retrieves an existing FlowController.

Parameters
participantThe DomainParticipant associated to the FlowController
nameThe name used to create the FlowController or the name of one of the built-in FlowControllers (FlowController::DEFAULT_NAME, FlowController::FIXED_RATE_NAME, FlowController::ON_DEMAND_NAME)
Returns
The flow controller with that name in that participant or an empty reference (equals to dds::core::null) if it doesn't exist
See Also
FlowController::retain()

RTI Connext Modern C++ API Version 6.0.1 Copyright © Sat Nov 23 2019 Real-Time Innovations, Inc