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

Data Fields
DDS_Long	max_tokens
	Maximum number of tokens than can accumulate in the token bucket.
DDS_Long	tokens_added_per_period
	The number of tokens added to the token bucket per specified period.
DDS_Long	tokens_leaked_per_period
	The number of tokens removed from the token bucket per specified period.
struct DDS_Duration_t	period
	Period for adding tokens to and removing tokens from the bucket.
DDS_Long	bytes_per_token
	Maximum number of bytes allowed to send for each token available.

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

Field Documentation

DDS_Long 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_LENGTH_UNLIMITED to allow accumulation of an unlimited amount of tokens (and therefore potentially an unlimited burst size).

[default] DDS_LENGTH_UNLIMITED

DDS_Long 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_LENGTH_UNLIMITED to add the maximum number of tokens allowed by DDS_FlowControllerTokenBucketProperty_t::max_tokens.

[default] DDS_LENGTH_UNLIMITED

DDS_Long 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_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

struct DDS_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_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] [0,1 year] or DDS_DURATION_INFINITE

DDS_Long 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_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_LENGTH_UNLIMITED

[range] [1024,DDS_LENGTH_UNLIMITED]