DDS::FlowControllerTokenBucketProperty_t Struct Reference

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

#include <managed_flowcontroller.h>

Public Attributes
System::Int32	max_tokens
	Maximum number of tokens than can accumulate in the token bucket. More...
System::Int32	tokens_added_per_period
	The number of tokens added to the token bucket per specified period. More...
System::Int32	tokens_leaked_per_period
	The number of tokens removed from the token bucket per specified period. More...
Duration_t	period
	Period for adding tokens to and removing tokens from the bucket. More...
System::Int32	bytes_per_token
	Maximum number of bytes allowed to send for each token available. More...

Detailed Description

DDS::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:

DDS::FlowController

Properties:

RxO = N/A

Changeable = YES. However, the special value of DDS::Duration_t::DURATION_INFINITE as DDS::FlowControllerTokenBucketProperty_t::period is strictly used to create an on-demand DDS::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.

Member Data Documentation

max_tokens

System::Int32 DDS::FlowControllerTokenBucketProperty_t::max_tokens

Maximum number of tokens than 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 DDS::FlowControllerTokenBucketProperty_t::bytes_per_token, determines the maximum allowable data burst.

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

[default] DDS::ResourceLimitsQosPolicy::LENGTH_UNLIMITED

[range] [1,DDS::ResourceLimitsQosPolicy::LENGTH_UNLIMITED]

tokens_added_per_period

System::Int32 DDS::FlowControllerTokenBucketProperty_t::tokens_added_per_period

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

DDS::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::DataWriter instances based on the DDS::FlowControllerProperty_t::scheduling_policy.

Use DDS::ResourceLimitsQosPolicy::LENGTH_UNLIMITED to add the maximum number of tokens allowed by DDS::FlowControllerTokenBucketProperty_t::max_tokens.

[default] DDS::ResourceLimitsQosPolicy::LENGTH_UNLIMITED

[range] [1,DDS::ResourceLimitsQosPolicy::LENGTH_UNLIMITED]

tokens_leaked_per_period

System::Int32 DDS::FlowControllerTokenBucketProperty_t::tokens_leaked_per_period

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

DDS::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::ResourceLimitsQosPolicy::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::ResourceLimitsQosPolicy::LENGTH_UNLIMITED]

period

Duration_t DDS::FlowControllerTokenBucketProperty_t::period

Period for adding tokens to and removing tokens from the bucket.

DDS::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::Duration_t::DURATION_INFINITE can be used to create an on-demand DDS::FlowController, for which tokens are no longer replenished periodically. Instead, tokens must be added explicitly by calling DDS::FlowController::trigger_flow. This external trigger adds DDS::FlowControllerTokenBucketProperty_t::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::Duration_t::DURATION_INFINITE

bytes_per_token

System::Int32 DDS::FlowControllerTokenBucketProperty_t::bytes_per_token

Maximum number of bytes allowed to send for each token available.

DDS::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::DataWriter. That is, in cases where DDS::FlowControllerTokenBucketProperty_t::bytes_per_token is greater than the sample size, multiple samples may be sent to the same destination using a single token (regardless of DDS::FlowControllerProperty_t::scheduling_policy).

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

Use DDS::ResourceLimitsQosPolicy::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::DataWriter to transmit all its queued samples to a single destination. A separate token is required to send to each additional destination.

[default] DDS::ResourceLimitsQosPolicy::LENGTH_UNLIMITED

[range] [1024,DDS::ResourceLimitsQosPolicy::LENGTH_UNLIMITED]