RTI Connext Modern C++ API  Version 5.3.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
dds::core::Entity Class Reference

<<reference-type>> This is the abstract base class for all the DDS objects that support QoS policies, a listener and a status condition. More...

#include <dds/core/Entity.hpp>

Inheritance diagram for dds::core::Entity:
dds::sub::DataReader< ReplyType > dds::sub::DataReader< RequestType > dds::pub::DataWriter< dds::core::xtypes::DynamicData > dds::pub::DataWriter< ReplyType > dds::pub::DataWriter< RequestType > dds::domain::DomainParticipant dds::pub::DataWriter< T > dds::pub::Publisher dds::sub::DataReader< T > dds::sub::Subscriber dds::topic::TopicDescription< T >

Public Member Functions

void enable ()
 Enables this entity (if it was created disabled)
 
const dds::core::status::StatusMask status_changes ()
 Retrieves the list of communication statuses that are triggered.
 
const dds::core::InstanceHandle instance_handle () const
 Get the instance handle that represents this entity.
 
void close ()
 Forces the destruction of this entity.
 
void retain ()
 Disables the automatic destruction of this entity.
 

Related Functions

(Note that these are not member functions.)

template<typename TO , typename FROM >
TO polymorphic_cast (FROM &from)
 Downcasts an Entity to a subclass.
 

Detailed Description

<<reference-type>> This is the abstract base class for all the DDS objects that support QoS policies, a listener and a status condition.

See Also
Reference types for operations that all reference types provide.
Entity Use Cases

All operations except for set_qos(), get_qos(), set_listener(), get_listener() and enable(), may return the value dds::core::NotEnabledError.

QoS:
QoS Policies
Status:
Status Kinds
Listener:
Listener

Abstract operations

Each derived entity provides the following operations specific to its role in RTI Connext. Note that these are not member functions of dds::core::Entity, but members of each of the derived classes.

set_qos (abstract)

This operation sets the QoS policies of the dds::core::Entity.

Precondition
Certain policies are immutable (see QoS Policies): they can only be set at dds::core::Entity creation time or before the entity is enabled. If set_qos() is invoked after the dds::core::Entity is enabled and it attempts to change the value of an immutable policy, the operation will fail and return dds::core::ImmutablePolicyError.
Certain values of QoS policies can be incompatible with the settings of the other policies. The set_qos() operation will also fail if it specifies a set of values that, once combined with the existing values, would result in an inconsistent set of policies. In this case, the operation will fail and return dds::core::InconsistentPolicyError.
If the application supplies a non-default value for a QoS policy that is not supported by the implementation of the service, the set_qos operation will fail and return dds::core::UnsupportedError.
Postcondition
The existing set of policies is only changed if the set_qos() operation succeeds.

Possible exceptions thrown in addition to Standard Exceptions : dds::core::ImmutablePolicyError, dds::core::InconsistentPolicyError.

Default QoS

When you create an Entity the Qos parameter is optional. When you don't specify it the default QoS applies.

Applications can set that default in a number of ways:

If the application does nothing explicit to specify the default QoS, the default RTI Connext values will be used whenever an entity is created. Each of the QoS policies and their defaults can be found here: QoS Policies.

// Create a participant with default QoS
dds::domain::DomainParticipant dp_default_qos(0);
// Create a participant with specific QoS
// Set some values in participant_qos
...
dds::domain::DomainParticipant dp_cusotm_qos(0, participant_qos);

Applications can modify the default Qos via XML configuration files accessed through dds::core::QosProvider::Default() (see Configuring QoS Profiles with XML). The default QosProvider is a singleton, meaning that any change made to it will affect the creation of all entities in an application. The rti::core::QosProviderParams for the default QosProvider will determine which XML configuration files are loaded and used during entity creation.

// Configure the Default QosProvider to load an XML configuration file from
// a specific location
params.url_profile(dds::core::StringSeq(1, "/path/to/an/xml/configuration/file.xml"));
// Set the Default QosProvider's params
// This participant will be created with the QoS values from /path/to/an/xml/configuration/file.xml
// if there is a profile marked with the 'is_default_qos=true' attribute
dds::domain::DomainParticipant dp_default_qos(0);

If left unchanged, RTI Connext will load the default locations and files described by Configuring QoS Profiles with XML. Otherwise, an application can configure the default QosProvider to load files from other locations and to use specific libraries and profiles within those locations as the default.

// Assuming we have set the Default QosProvider's QosProviderParams as
// in the above code snippet, we can set the default profile that will be
// used when creating entities
dds::core::QosProvider::Default()->default_profile("ALibrary::ANewDefaultProfile");
// Setting the default profile could have also been accomplished by setting the default library
// and then the default profile separately:
// dds::core::QosProvider::Default()->default_library("ALibrary");
// dds::core::QosProvider::Default()->default_profile("ANewDefaultProfile");
// This participant will be created with the QoS values from /path/to/an/xml/configuration/file.xml
// from the QoS profile "ALibrary::ANewDefaultProfile"
dds::domain::DomainParticipant dp_new_default_profile(0);

In addition, for each entity, there are default_*_qos APIs that allow an application to set the default QoS values for all entities that are created from that entity. For example, the dds::domain::DomainParticipant::default_subscriber_qos API sets the default SubscriberQos that will be used for each dds::sub::Subscriber that is created from that DomainParticipant. The QoS values that are set using the default_*_qos() APIs on an entity take precedence over the default values that are maintained by the default QosProvider. Therefore, the values returned from the default_*_qos() APIs on the default QosProvider are only representative of the default QoS values if the corresponding default_*_qos() setter of an entity has not be used.

// Set the default qos for any subscriber that is created from this participant
// Set some values in the subscriber_qos
...
// Previous to the following call, dds::core::QosProvider::Default().subscriber_qos()
// would return the SubscriberQos that would be used to create Subscribers when
// no QoS object was provided to the constructor. After the following call, this
// will no longer be the case.
participant.default_subscriber_qos(subscriber_qos);

Calling the default_*_qos() getters on an entity will always return the default values that will be used when creating an entity when the QoS parameter of the constructor is not specified.

get_qos (abstract)

This operation allows access to the existing set of QoS policies for the dds::core::Entity.

set_listener (abstract)

This operation installs a Listener on the dds::core::Entity. The listener will only be invoked on the changes of communication status indicated by the specified mask.

There are two components involved when setting up listeners: the listener itself and the mask. Both of these can be NULL.

Listeners for some Entities derive from the Connext DDS Listeners for related Entities. This means that the derived Listener has all of the methods of its parent class. You can install Listeners at all levels of the object hierarchy. At the top is the DomainParticipantListener; only one can be installed in a DomainParticipant. Then every Subscriber and Publisher can have their own Listener. Finally, each Topic, DataReader and DataWriter can have their own listeners. All are optional.

Suppose, however, that an Entity does not install a Listener, or installs a Listener that does not have particular communication status selected in the bitmask. In this case, if/when that particular status changes for that Entity, the corresponding Listener for that Entity’s parent is called. Status changes are “propagated” from child Entity to parent Entity until a Listener is found that is registered for that status. Connext DDS will give up and drop the status-change event only if no Listeners have been installed in the object hierarchy to be called back for the specific status.

The following table describes the effect of different combinations of Listeners and Status Bit Masks considering the hierarchical processing.

Effect of Different Combinations of Listeners and Status Bit Masks
No Bits Set in Mask Some/All Bits Set in Mask
Listener is Specified Connext DDS finds the next most relevant listener for the changed status For the statuses that are enabled in the mask, the most relevant listener will be called. The 'statusChangedFlag' for the relevant status is reset
Listener is NULL Connext DDS behaves as if the listener is not installed and finds the next most relevant listener for that status Connext DDS behaves as if the listener is installed, but the callback is doing nothing. This is called a ‘nil’ listener
Postcondition
Only one listener can be attached to each dds::core::Entity. If a listener was already set, the operation set_listener() will replace it with the new one. Consequently, if the value NULL is passed for the listener parameter to the set_listener operation, any existing listener will be removed.
An entity with a listener is automatically retained and won't be destroyed when all its references go out of scope. To destroy an Entity with a listener, you need to unset the listener or explicitly call close(). To simplify this process you can use the utility rti::core::ListenerBinder.

get_listener (abstract)

This operation allows access to the existing Listener attached to the dds::core::Entity.

If no listener is installed on the dds::core::Entity, this operation will return NULL.

Member Function Documentation

void dds::core::Entity::enable ( )
inline

Enables this entity (if it was created disabled)

This operation enables the Entity. Entity objects can be created either enabled or disabled. This is controlled by the value of the ENTITY_FACTORY QoS policy on the corresponding factory for the dds::core::Entity.

By default, ENTITY_FACTORY is set so that it is not necessary to explicitly call dds::core::Entity::enable on newly created entities.

The dds::core::Entity::enable operation is idempotent. Calling enable on an already enabled Entity returns OK and has no effect.

If a dds::core::Entity has not yet been enabled, the following kinds of operations may be invoked on it:

Other operations may explicitly state that they may be called on disabled entities; those that do not will return the error dds::core::NotEnabledError.

It is legal to delete an dds::core::Entity that has not been enabled .

Entities created from a factory Entity that is disabled are created disabled, regardless of the setting of the dds::core::policy::EntityFactory.

Calling enable on an Entity whose factory Entity is not enabled will fail and return dds::core::PreconditionNotMetError.

If dds::core::policy::EntityFactory::autoenable_created_entities is TRUE, the enable operation on a factory will automatically enable all entities created from that factory (for example, enabling a dds::pub::Publisher will enable all its contained dds::pub::DataWriter objects)

Listeners associated with an entity are not called until the entity is enabled.

Conditions associated with a disabled entity are "inactive," that is, they have a trigger_value == FALSE.

Exceptions
Oneof the Standard Exceptions, Standard Exceptions or dds::core::PreconditionNotMetError.
const dds::core::status::StatusMask dds::core::Entity::status_changes ( )
inline

Retrieves the list of communication statuses that are triggered.

That is, the list of statuses whose value has changed since the last time the application read the status using the get_*_status() method.

When the entity is first created or if the entity is not enabled, all communication statuses are in the "untriggered" state so the list returned by the get_status_changes operation will be empty.

The list of statuses returned by the get_status_changes operation refers to the status that are triggered on the Entity itself and does not include statuses that apply to contained entities.

Returns
list of communication statuses in the dds::core::Entity that are triggered.
See Also
Status Kinds
const dds::core::InstanceHandle dds::core::Entity::instance_handle ( ) const
inline

Get the instance handle that represents this entity.

This operation returns the dds::core::InstanceHandle that represents the dds::core::Entity.

Returns
the instance handle associated with this entity.
void dds::core::Entity::close ( )
inline

Forces the destruction of this entity.

MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
See Also
Reference types
void dds::core::Entity::retain ( )
inline

Disables the automatic destruction of this entity.

See Also
Reference types

Friends And Related Function Documentation

template<typename TO , typename FROM >
TO polymorphic_cast ( FROM &  from)
related

Downcasts an Entity to a subclass.

Template Parameters
TOThe type to cast to
FROMThe type to cast from
Parameters
fromThe object to cast to type TO
Returns
A reference to the same object from, but cast to the type TO. Both objects share ownership of the underlying entity.

For example:

using namespace dds::core;
using namespace dds::domain;
DomainParticipant participant(0);
Entity entity = participant; // Assignment to base
assert (participant == participant2); // Same reference
See Also
Reference types

RTI Connext Modern C++ API Version 5.3.0 Copyright © Sun Jun 25 2017 Real-Time Innovations, Inc