RTI Connext Modern C++ API  Version 6.1.0
rti::pub::FlowControllerTokenBucketProperty Class Reference

<<extension>> <<value-type>> Configures a FlowController based on a tocken-bucket mechanism More...

#include <FlowController.hpp>

Inherits rti::core::NativeValueType< T, NATIVE_T, ADAPTER >.

Public Member Functions

 FlowControllerTokenBucketProperty (int32_t max_tokens=dds::core::LENGTH_UNLIMITED, int32_t tokens_added_per_period=dds::core::LENGTH_UNLIMITED, int32_t tokens_leaked_per_period=0, const dds::core::Duration &period=dds::core::Duration(1, 0), int32_t bytes_per_token=dds::core::LENGTH_UNLIMITED)
 Initializes the properties. More...
 
int32_t max_tokens () const
 Gets the max_tokens. More...
 
FlowControllerTokenBucketPropertymax_tokens (int32_t value)
 Sets the maximum number of tokens that can accumulate in the token bucket. More...
 
int32_t tokens_added_per_period () const
 Gets the tokens_added_per_period. More...
 
FlowControllerTokenBucketPropertytokens_added_per_period (int32_t value)
 Sets the number of tokens added to the token bucket per specified period. More...
 
int32_t tokens_leaked_per_period () const
 Gets the tokens_leaked_per_period. More...
 
FlowControllerTokenBucketPropertytokens_leaked_per_period (int32_t value)
 Sets the number of tokens removed from the token bucket per specified period. More...
 
dds::core::Duration period () const
 Gets the period. More...
 
FlowControllerTokenBucketPropertyperiod (const dds::core::Duration &value)
 Sets the period for adding tokens to and removing tokens from the bucket. More...
 
int32_t bytes_per_token () const
 Gets the bytes_per_token. More...
 
FlowControllerTokenBucketPropertybytes_per_token (int32_t value)
 Sets the maximum number of bytes allowed to send for each token available. More...
 

Detailed Description

<<extension>> <<value-type>> Configures a FlowController based on a tocken-bucket mechanism

rti::pub::FlowController uses the popular token bucket approach for open loop network flow control. The flow control characteristics are determined by the token bucket properties.

Asynchronously published samples are queued up and transmitted based on the token bucket flow control scheme. The token bucket contains tokens, each of which represents a number of bytes. Samples can be sent only when there are sufficient tokens in the bucket. As samples are sent, tokens are consumed. The number of tokens consumed is proportional to the size of the data being sent. Tokens are replenished on a periodic basis.

The rate at which tokens become available and other token bucket properties determine the network traffic flow.

Note that if the same sample must be sent to multiple destinations, separate tokens are required for each destination. Only when multiple samples are destined to the same destination will they be co-alesced and sent using the same token(s). In other words, each token can only contribute to a single network packet.

Entity:
rti::pub::FlowController
Properties:
RxO = N/A

Changeable = YES. However, the special value of dds::core::Duration::infinite() as FlowControllerTokenBucketProperty::period is strictly used to create an on-demand rti::pub::FlowController. The token period cannot toggle from an infinite to finite value (or vice versa). It can, however, change from one finite value to another.

Constructor & Destructor Documentation

◆ FlowControllerTokenBucketProperty()

rti::pub::FlowControllerTokenBucketProperty::FlowControllerTokenBucketProperty ( int32_t  max_tokens = dds::core::LENGTH_UNLIMITED,
int32_t  tokens_added_per_period = dds::core::LENGTH_UNLIMITED,
int32_t  tokens_leaked_per_period = 0,
const dds::core::Duration period = dds::core::Duration(1, 0),
int32_t  bytes_per_token = dds::core::LENGTH_UNLIMITED 
)

Initializes the properties.

Member Function Documentation

◆ max_tokens() [1/2]

int32_t rti::pub::FlowControllerTokenBucketProperty::max_tokens ( ) const

Gets the max_tokens.

See also
max_tokens(int32_t)

◆ max_tokens() [2/2]

FlowControllerTokenBucketProperty& rti::pub::FlowControllerTokenBucketProperty::max_tokens ( int32_t  value)

Sets the maximum number of tokens that can accumulate in the token bucket.

The number of tokens in the bucket will never exceed this value. Any excess tokens are discarded. This property value, combined with FlowControllerTokenBucketProperty::bytes_per_token, determines the maximum allowable data burst.

Use dds::core::LENGTH_UNLIMITED to allow accumulation of an unlimited amount of tokens (and therefore potentially an unlimited burst size).

[default] dds::core::LENGTH_UNLIMITED

[range] [1,dds::core::LENGTH_UNLIMITED]

Returns
*this

◆ tokens_added_per_period() [1/2]

int32_t rti::pub::FlowControllerTokenBucketProperty::tokens_added_per_period ( ) const

Gets the tokens_added_per_period.

See also
tokens_added_per_period(int32_t)

◆ tokens_added_per_period() [2/2]

FlowControllerTokenBucketProperty& rti::pub::FlowControllerTokenBucketProperty::tokens_added_per_period ( int32_t  value)

Sets the number of tokens added to the token bucket per specified period.

rti::pub::FlowController transmits data only when tokens are available. Tokens are periodically replenished. This field determines the number of tokens added to the token bucket with each periodic replenishment.

Available tokens are distributed to associated dds::pub::DataWriter instances based on the rti::pub::FlowControllerProperty::scheduling_policy.

Use dds::core::LENGTH_UNLIMITED to add the maximum number of tokens allowed by FlowControllerTokenBucketProperty::max_tokens.

[default] dds::core::LENGTH_UNLIMITED

[range] [1,dds::core::LENGTH_UNLIMITED]

Returns
*this

◆ tokens_leaked_per_period() [1/2]

int32_t rti::pub::FlowControllerTokenBucketProperty::tokens_leaked_per_period ( ) const

Gets the tokens_leaked_per_period.

See also
tokens_leaked_per_period(int32_t)

◆ tokens_leaked_per_period() [2/2]

FlowControllerTokenBucketProperty& rti::pub::FlowControllerTokenBucketProperty::tokens_leaked_per_period ( int32_t  value)

Sets the number of tokens removed from the token bucket per specified period.

rti::pub::FlowController transmits data only when tokens are available. When tokens are replenished and there are sufficient tokens to send all samples in the queue, this property determines whether any or all of the leftover tokens remain in the bucket.

Use dds::core::LENGTH_UNLIMITED to remove all excess tokens from the token bucket once all samples have been sent. In other words, no token accumulation is allowed. When new samples are written after tokens were purged, the earliest point in time at which they can be sent is at the next periodic replenishment.

[default] 0

[range] [0,dds::core::LENGTH_UNLIMITED]

Returns
*this

◆ period() [1/2]

dds::core::Duration rti::pub::FlowControllerTokenBucketProperty::period ( ) const

Gets the period.

See also
period(const dds::core::Duration&)

◆ period() [2/2]

FlowControllerTokenBucketProperty& rti::pub::FlowControllerTokenBucketProperty::period ( const dds::core::Duration value)

Sets the period for adding tokens to and removing tokens from the bucket.

rti::pub::FlowController transmits data only when tokens are available. This field determines the period by which tokens are added or removed from the token bucket.

The special value dds::core::Duration::infinite() can be used to create an on-demand rti::pub::FlowController, for which tokens are no longer replenished periodically. Instead, tokens must be added explicitly by calling rti::pub::FlowController::trigger_flow. This external trigger adds FlowControllerTokenBucketProperty::tokens_added_per_period tokens each time it is called (subject to the other property settings).

[default] 1 second

[range] [1 nanosec, 1 year] or dds::core::Duration::infinite()

Returns
*this

◆ bytes_per_token() [1/2]

int32_t rti::pub::FlowControllerTokenBucketProperty::bytes_per_token ( ) const

Gets the bytes_per_token.

See also
bytes_per_token(int32_t)

◆ bytes_per_token() [2/2]

FlowControllerTokenBucketProperty& rti::pub::FlowControllerTokenBucketProperty::bytes_per_token ( int32_t  value)

Sets the maximum number of bytes allowed to send for each token available.

rti::pub::FlowController transmits data only when tokens are available. This field determines the number of bytes that can actually be transmitted based on the number of tokens.

Tokens are always consumed in whole by each dds::pub::DataWriter. That is, in cases where FlowControllerTokenBucketProperty::bytes_per_token is greater than the sample size, multiple samples may be sent to the same destination using a single token (regardless of rti::pub::FlowControllerProperty::scheduling_policy).

Where fragmentation is required, the fragment size will be FlowControllerTokenBucketProperty::bytes_per_token or the minimum largest message size across all transports installed with the dds::pub::DataWriter, whichever is less.

Use dds::core::LENGTH_UNLIMITED to indicate that an unlimited number of bytes can be transmitted per token. In other words, a single token allows the recipient dds::pub::DataWriter to transmit all its queued samples to a single destination. A separate token is required to send to each additional destination.

[default] dds::core::LENGTH_UNLIMITED

[range] [1024,dds::core::LENGTH_UNLIMITED]

Returns
*this