 |
OpenSplice ISO C++ 2 DCPS
v7.x
ISO C++ 2 OpenSplice Data Distribution Service Data-Centric Publish-Subscribe API
|
|
OpenSplice ISO C++ 2 DCPS
v7.x
ISO C++ 2 OpenSplice Data Distribution Service Data-Centric Publish-Subscribe API
|
This QosPolicy allows the DataReader to define it's own set of keys on the data, potentially different from the keys defined on the topic. More...
#include "ProprietaryApi.hpp"
Public Member Functions | |
| SubscriptionKey () | |
| SubscriptionKey (bool use_key_list, const std::string &key) | |
| SubscriptionKey (bool use_key_list, const dds::core::StringSeq &keys) | |
| SubscriptionKey (const SubscriptionKey &other) | |
| SubscriptionKey & | key (const std::string &key) |
| SubscriptionKey & | key (const dds::core::StringSeq &keys) |
| const dds::core::StringSeq | key () const |
| bool | operator!= (const Value &other) const |
| D * | operator-> () |
| const D * | operator-> () const |
| bool | operator== (const Value &other) const |
| SubscriptionKey & | use_key_list (bool use_key_list) |
| bool | use_key_list () const |
This QosPolicy allows the DataReader to define it's own set of keys on the data, potentially different from the keys defined on the topic.
By using the SubscriptionKey QosPolicy, a DataReader can force its own key-list definition on data samples. The consequences are that the DataReader will internally keep track of instances based on its own key list, instead of the key list dictated by the Topic.
Operations that operate on instances or instance handles, such as lookup_instance or get_key_value, respect the alternative key-list and work as expected. However, since the mapping of writer instances to reader instances is no longer trivial (one writer instance may now map to more than one matching reader instance and vice versa), a writer instance will no longer be able to fully determine the lifecycle of its matching reader instance, nor the value its view_state and instance_state.
In fact, by diverting from the conceptual 1 – 1 mapping between writer instance and reader instance, the writer can no longer keep an (empty) reader instance ALIVE by just refusing to unregister its matching writer instance. That means that when a reader takes all samples from a particular reader instance, that reader instance will immediately be removed from the reader’s administration. Any subsequent reception of a message with the same keys will re-introduce the instance into the reader administration, setting its view_state back to NEW. Compare this to the default behaviour, where the reader instance will be kept alive as long as the writer does not unregister it. That causes the view_state in the reader instance to remain NOT_NEW, even if the reader has consumed all of its samples prior to receiving an update.
Another consequence of allowing an alternative keylist is that events that are communicated by invalid samples (i.e. samples that have only initialized their keyfields) may no longer be interpreted by the reader to avoid situations in which uninitialized non-keyfields are treated as keys in the alternative keylist. This effectively means that all invalid samples (e.g. unregister messages and both implicit and explicit dispose messages) will be skipped and can no longer affect the instance_state, which will therefore remain ALIVE. The only exceptions to this are the messages that are transmitted explicitly using the dds::pub::DataWriter::writedispose call, which always includes a full and valid sample and can therefore modify the instance_state to NOT_ALIVE_DISPOSED.
By default, the SubscriptionKeyQosPolicy is not used because use_key_list is set to FALSE.
This QosPolicy is applicable to a DataReader only, and cannot be changed after the DataReader is enabled.
Definition at line 879 of file ProprietaryApi.hpp.
| org::opensplice::core::policy::SubscriptionKey::SubscriptionKey | ( | ) |
Creates a SubscriptionKey QoS Policy instance
|
explicit |
Creates a SubscriptionKey QoS Policy instance
| use_key_list | use the key list or not |
| key | a single key |
|
explicit |
Creates a SubscriptionKey QoS Policy instance
| use_key_list | use the key list or not |
| keys | a sequence containing multiple keys |
| org::opensplice::core::policy::SubscriptionKey::SubscriptionKey | ( | const SubscriptionKey & | other | ) |
Copies a SubscriptionKey QoS Policy instance
| other | the SubscriptionKey QoS Policy instance to copy |
| SubscriptionKey& org::opensplice::core::policy::SubscriptionKey::key | ( | const std::string & | key | ) |
Sets the key
| key | the key |
| SubscriptionKey& org::opensplice::core::policy::SubscriptionKey::key | ( | const dds::core::StringSeq & | keys | ) |
Sets multiple keys
| names | a sequence containing multiple keys |
| const dds::core::StringSeq org::opensplice::core::policy::SubscriptionKey::key | ( | ) | const |
Gets the keys
|
inherited |
|
inherited |
The operator->() is provided to be able to directly invoke functions on the delegate.
The decision to provide direct access to the delegate was motivated by the need for providing a way that was not invasive with respect to the CXXDDS API and yet would allow for vendor-specific extension. Thus vendor-specific extensions can be invoked on the Value and on all its subclasses as follows:
|
inherited |
The operator->() is provided to be able to directly invoke functions on the delegate.
The decision to provide direct access to the delegate was motivated by the need for providing a way that was not invasive with respect to the CXXDDS API and yet would allow for vendor-specific extension. Thus vendor-specific extensions can be invoked on the Value and on all its subclasses as follows:
|
inherited |
| SubscriptionKey& org::opensplice::core::policy::SubscriptionKey::use_key_list | ( | bool | use_key_list | ) |
Sets use_key_list state
| use_key_list | state |
| bool org::opensplice::core::policy::SubscriptionKey::use_key_list | ( | ) | const |
Gets use_key_list state
1.8.13