RTI Connext Modern C++ API  Version 7.0.0
dds::pub::CoherentSet Class Reference

<<value-type>> A publishing application can request that a set of DDS data-sample changes be propagated in such a way that they are interpreted at the receivers' side as a cohesive set of modifications. More...

#include "dds/pub/CoherentSet.hpp"

Public Member Functions

 CoherentSet (const dds::pub::Publisher &pub)
 Creating a CoherentSet object indicates that the application will begin a coherent set of modifications using dds::pub::DataWriter objects attached to the dds::pub::Publisher. More...
 
void end ()
 Explicitly terminate a coherent set initiated by the CoherentSet constructor. More...
 
 ~CoherentSet ()
 Implicitly terminate a coherent set. More...
 

Detailed Description

<<value-type>> A publishing application can request that a set of DDS data-sample changes be propagated in such a way that they are interpreted at the receivers' side as a cohesive set of modifications.

In this case, the receiver will only be able to access the data after all the modifications in the set are available at the subscribing end.

Constructor & Destructor Documentation

◆ CoherentSet()

dds::pub::CoherentSet::CoherentSet ( const dds::pub::Publisher pub)
inlineexplicit

Creating a CoherentSet object indicates that the application will begin a coherent set of modifications using dds::pub::DataWriter objects attached to the dds::pub::Publisher.

A 'coherent set' is a set of modifications that must be propagated in such a way that they are interpreted at the receiver's side as a consistent set of modifications; that is, the receiver will only be able to access the data after all the modifications in the set are available at the receiver end.

A connectivity change may occur in the middle of a set of coherent changes; for example, the set of partitions used by the dds::pub::Publisher or one of its subscribers (dds::sub::Subscriber) may change, a late-joining dds::sub::DataReader may appear on the network, or a communication failure may occur. In the event that such a change prevents an entity from receiving the entire set of coherent changes, that entity must behave as if it had received none of the set.

These calls can be nested. In that case, the coherent set terminates only with the last call to dds::pub::CoherentSet::end(). Publisher's samples (samples published by any of the DataWriters within the Publisher) that are not published within a begin_coherent_changes/end_coherent_changes block will not be provided to the DataReaders as a set.

The support for coherent changes enables a publishing application to change the value of several data-instances that could belong to the same or different topics and have those changes be seen atomically by the readers. This is useful in cases where the values are inter-related (for example, if there are two data-instances representing the altitude and velocity vector of the same aircraft and both are changed, it may be useful to communicate those values in a way the reader can see both together; otherwise, it may, e.g., erroneously interpret that the aircraft is on a collision course).

Note
Coherent sets don't apply to Topic Queries. If a rti::sub::TopicQuery selects only a subset of samples that was published as a coherent set, the subscribing application will receive them regardless of their membership to the coherent set.
Exceptions
Oneof the Standard Exceptions or dds::core::NotEnabledError.
See also
dds::core::policy::Presentation
Parameters
pubThe Publisher

◆ ~CoherentSet()

dds::pub::CoherentSet::~CoherentSet ( )
inline

Implicitly terminate a coherent set.

See also
end()

Member Function Documentation

◆ end()

void dds::pub::CoherentSet::end ( )
inline

Explicitly terminate a coherent set initiated by the CoherentSet constructor.

Precondition
If there is no matching call to dds::pub::CoherentSet::CoherentSet the operation will fail with dds::core::PreconditionNotMetError.
Exceptions
Oneof the Standard Exceptions, dds::core::PreconditionNotMetError or dds::core::NotEnabledError.