<<extension>> Allows a dds::pub::DataWriter to batch multiple samples into a single network packet to increase throughput. More...

#include <rti/core/policy/CorePolicy.hpp>

Public Member Functions
	Batch ()
	Creates the default policy (batching is disabled) More...

Batch &	enable (bool the_enable)
	Enables or disables batching. More...

bool	enable () const
	Returns whether batching is enabled or not. More...

Batch &	max_data_bytes (int32_t the_max_data_bytes)
	Sets the maximum cumulative length of all serialized samples in a batch. More...

int32_t	max_data_bytes () const
	Getter (see setter with the same name) More...

Batch &	max_samples (int32_t the_max_samples)
	Sets the maximum number of samples in a batch. More...

int32_t	max_samples () const
	Getter (see setter with the same name) More...

Batch &	max_flush_delay (const dds::core::Duration &the_max_flush_delay)
	Sets the maximum delay after which a batch is flushed. More...

dds::core::Duration	max_flush_delay () const
	Getter (see setter with the same name) More...

Batch &	source_timestamp_resolution (const dds::core::Duration &the_source_timestamp_resolution)
	Sets the timestamp resolution of the samples in a batch. More...

dds::core::Duration	source_timestamp_resolution () const
	Getter (see setter with the same name) More...

Batch &	thread_safe_write (bool the_thread_safe_write)
	Indicates if the write operation needs to be thread-safe. More...

bool	thread_safe_write () const
	Getter (see setter with the same name) More...

Static Public Member Functions
static Batch	Enabled ()
	Returns an instance that enables batching with the default max_samples() and max_data_bytes(). More...

static Batch	Disabled ()
	Returns an instance that disables batching. More...

static Batch	EnabledWithMaxDataBytes (int32_t the_max_bytes)
	Returns an instance that enables batching with max_data_bytes() More...

static Batch	EnabledWithMaxSamples (int32_t the_max_samples)
	Returns an instance that enables batching with max_samples() More...

Detailed Description

<<extension>> Allows a dds::pub::DataWriter to batch multiple samples into a single network packet to increase throughput.

This QoS policy configures the ability of the middleware to collect multiple user data samples to be sent in a single network packet, to take advantage of the efficiency of sending larger packets and thus increase effective throughput.

This QoS policy can be used to dramatically increase effective throughput for small data samples. Usually, throughput for small samples (size < 2048 bytes) is limited by CPU capacity and not by network bandwidth. Batching many smaller samples to be sent in a single large packet will increase network utilization, and thus throughput, in terms of samples per second.

Entity:: dds::pub::DataWriter

Properties:: RxO = NO
Changeable = UNTIL ENABLE

Constructor & Destructor Documentation

◆ Batch()

rti::core::policy::Batch::Batch ( )

inline

Creates the default policy (batching is disabled)

Member Function Documentation

◆ Enabled()

static Batch rti::core::policy::Batch::Enabled ( )

inlinestatic

Returns an instance that enables batching with the default max_samples() and max_data_bytes().

◆ Disabled()

static Batch rti::core::policy::Batch::Disabled ( )

inlinestatic

Returns an instance that disables batching.

◆ EnabledWithMaxDataBytes()

static Batch rti::core::policy::Batch::EnabledWithMaxDataBytes ( int32_t the_max_bytes )

inlinestatic

Returns an instance that enables batching with max_data_bytes()

For example:

using namespace rti::core::policy;
 
writer_qos << Batch::EnabledWithMaxDataBytes(2048);

◆ EnabledWithMaxSamples()

static Batch rti::core::policy::Batch::EnabledWithMaxSamples ( int32_t the_max_samples )

inlinestatic

Returns an instance that enables batching with max_samples()

◆ enable() [1/2]

Batch & rti::core::policy::Batch::enable ( bool the_enable )

Enables or disables batching.

Referenced by max_data_bytes(), and max_flush_delay().

◆ enable() [2/2]

bool rti::core::policy::Batch::enable ( ) const

Returns whether batching is enabled or not.

◆ max_data_bytes() [1/2]

Batch & rti::core::policy::Batch::max_data_bytes ( int32_t the_max_data_bytes )

Sets the maximum cumulative length of all serialized samples in a batch.

A batch is flushed automatically when this maximum is reached.

max_data_bytes does not include the meta data associated with the batch samples. Each sample has at least 8 bytes of meta data containing information such as the timestamp and sequence number. The meta data can be as large as 52 bytes for keyed topics and 20 bytes for unkeyed topics.

Note: Batches must contain whole samples. If a new batch is started and its initial sample causes the serialized size to exceed max_data_bytes, RTI Connext will send the sample in a single batch.

[default] 1024

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

Consistency

The setting of rti::core::policy::Batch::max_data_bytes must be consistent with rti::core::policy::Batch::max_samples. For these two values to be consistent, they cannot be both dds::core::LENGTH_UNLIMITED.

Referenced by max_flush_delay().

◆ max_data_bytes() [2/2]

int32_t rti::core::policy::Batch::max_data_bytes ( ) const

Getter (see setter with the same name)

References enable().

◆ max_samples() [1/2]

Batch & rti::core::policy::Batch::max_samples ( int32_t the_max_samples )

Sets the maximum number of samples in a batch.

A batch is flushed automatically when this maximum is reached.

[default] dds::core::LENGTH_UNLIMITED

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

Consistency

The setting of rti::core::policy::Batch::max_samples must be consistent with rti::core::policy::Batch::max_data_bytes. For these two values to be consistent, they cannot be both dds::core::LENGTH_UNLIMITED.

◆ max_samples() [2/2]

int32_t rti::core::policy::Batch::max_samples ( ) const

Getter (see setter with the same name)

◆ max_flush_delay() [1/2]

Batch & rti::core::policy::Batch::max_flush_delay ( const dds::core::Duration & the_max_flush_delay )

Sets the maximum delay after which a batch is flushed.

A batch is flushed automatically after the delay specified by this parameter.

The delay is measured from the time the first sample in the batch is written by the application.

[default] dds::core::Duration::infinite()

[range] [0,dds::core::Duration::infinite()]

Consistency

The setting of rti::core::policy::Batch::max_flush_delay must be consistent with rti::core::policy::AsynchronousPublisher::disable_asynchronous_batch and rti::core::policy::Batch::thread_safe_write. If the delay is different than dds::core::Duration::infinite(), rti::core::policy::AsynchronousPublisher::disable_asynchronous_batch must be set to false and rti::core::policy::Batch::thread_safe_write must be set to true.

References enable(), and max_data_bytes().

◆ max_flush_delay() [2/2]

dds::core::Duration rti::core::policy::Batch::max_flush_delay ( ) const

Getter (see setter with the same name)

◆ source_timestamp_resolution() [1/2]

Batch & rti::core::policy::Batch::source_timestamp_resolution ( const dds::core::Duration & the_source_timestamp_resolution )

Sets the timestamp resolution of the samples in a batch.

The value of this field determines how the source timestamp is associated with the samples in a batch.

A sample written with timestamp 't' inherits the source timestamp 't2' associated with the previous sample unless ('t' - 't2') > source_timestamp_resolution.

If source_timestamp_resolution is set to dds::core::Duration::infinite(), every sample in the batch will share the source timestamp associated with the first sample.

If source_timestamp_resolution is set to zero, every sample in the batch will contain its own source timestamp corresponding to the moment when the sample was written.

The performance of the batching process is better when source_timestamp_resolution is set to dds::core::Duration::infinite().

[default] dds::core::Duration::infinite()

[range] [0,dds::core::Duration::infinite()]

Consistency

The setting of rti::core::policy::Batch::source_timestamp_resolution must be consistent with rti::core::policy::Batch::thread_safe_write. If rti::core::policy::Batch::thread_safe_write is set to false, rti::core::policy::Batch::source_timestamp_resolution must be set to dds::core::Duration::infinite().

◆ source_timestamp_resolution() [2/2]

dds::core::Duration rti::core::policy::Batch::source_timestamp_resolution ( ) const

Getter (see setter with the same name)

◆ thread_safe_write() [1/2]

Batch & rti::core::policy::Batch::thread_safe_write ( bool the_thread_safe_write )

Indicates if the write operation needs to be thread-safe.

If this parameter is set to true, multiple threads can call write on the dds::pub::DataWriter concurrently.

[default] true

Consistency

The setting of rti::core::policy::Batch::thread_safe_write must be consistent with rti::core::policy::Batch::source_timestamp_resolution. If rti::core::policy::Batch::thread_safe_write is set to false, rti::core::policy::Batch::source_timestamp_resolution must be set to dds::core::Duration::infinite().

◆ thread_safe_write() [2/2]

bool rti::core::policy::Batch::thread_safe_write ( ) const

Getter (see setter with the same name)

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Batch()

Member Function Documentation

◆ Enabled()

◆ Disabled()

◆ EnabledWithMaxDataBytes()

◆ EnabledWithMaxSamples()

◆ enable() [1/2]

◆ enable() [2/2]

◆ max_data_bytes() [1/2]

Consistency

◆ max_data_bytes() [2/2]

◆ max_samples() [1/2]

Consistency

◆ max_samples() [2/2]

◆ max_flush_delay() [1/2]

Consistency

◆ max_flush_delay() [2/2]

◆ source_timestamp_resolution() [1/2]

Consistency

◆ source_timestamp_resolution() [2/2]

◆ thread_safe_write() [1/2]

Consistency

◆ thread_safe_write() [2/2]