Entity Use Cases

The following #includes are needed for the examples on this page

#include <dds/domain/ddsdomain.hpp>

Changing the QoS for an entity

The QoS for an entity can be specified at entity creation time. Once an entity has been created, its QoS can be manipulated as the following examples illustrate. A DataWriter is used in these examples, but the same can be applied to any <<reference-type>>, such as DomainParticipants, Subscribers, Publishers, DataReaders, and Topics.

• See QosProvider for examples on how to manage user-defined QoS profiles.
  
  
• See Qos Use Cases for examples on how to work with the Qos policy classes.
  
  
• Get an entity's QoS settings

      dds::pub::DataWriter<Foo> writer(dds::pub::Publisher(participant), a_topic); 
  
      // Get the DataWriter's QoS 
      dds::pub::qos::DataWriterQos writer_qos = writer.qos();

  
  
• Change the desired qos policy fields

      // Change the History QoS for the DataWriter using the History QoS's 
      // KeepAll named constructor
      writer_qos << dds::core::policy::History::KeepAll();

  
  
• Set the qos

      // Set the modified QoS for the DataWriter
      writer.qos(writer_qos);

Changing the listener and enabling/disabling statuses associated with it

The listener for an entity can be specified at the entity creation time. By default the listener is enabled for all the statuses supported by the entity.

Once an entity has been created, its listener and/or the statuses for which it is enabled can be manipulated as follows.

The following examples use a DomainParticipant but the same examples can be applied to all other entities (Subscribers, Publishers, DataReaders, DataWriters, and Topics)

• User defines entity listener methods

  class ExampleDomainParticipantListener : public dds::domain::NoOpDomainParticipantListener
  {
  public:
      ExampleDomainParticipantListener() {}
  public:
      void on_liveliness_lost(
         dds::pub::AnyDataWriter&,
         const::dds::core::status::LivelinessLostStatus&)
      {
          std::cout << "on_liveliness_lost" << std::endl;
      }
  
      void on_liveliness_changed(
         dds::sub::AnyDataReader&,
         const dds::core::status::LivelinessChangedStatus&)
      {
          std::cout << "on_liveliness_changed" << std::endl;
      }
  
      void on_inconsistent_topic(
         dds::topic::AnyTopic&,
         const dds::core::status::InconsistentTopicStatus&)
      {
          std::cout << "on_inconsistent_topic" << std::endl;
      }
  
      void on_data_on_readers(
         dds::sub::Subscriber&)
      {
          std::cout << "on_data_on_readers" << std::endl;
      }
  
      void on_offered_deadline_missed(
         dds::pub::AnyDataWriter&,
         const::dds::core::status::OfferedDeadlineMissedStatus&)
      {
          std::cout << "on_offered_deadline_missed" << std::endl;
      }
  
      void on_offered_incompatible_qos(
         dds::pub::AnyDataWriter&,
         const::dds::core::status::OfferedIncompatibleQosStatus&)
      {
          std::cout << "on_offered_incompatible_qos" << std::endl;
      }
  
      void on_publication_matched(
         dds::pub::AnyDataWriter&,
         const::dds::core::status::PublicationMatchedStatus&)
      {
          std::cout << "on_publication_matched" << std::endl;
      }
  
      void on_requested_deadline_missed(
         dds::sub::AnyDataReader&,
         const dds::core::status::RequestedDeadlineMissedStatus&)
      {
          std::cout << "on_requested_deadline_missed" << std::endl;
      }
  
      void on_requested_incompatible_qos(
         dds::sub::AnyDataReader&,
         const dds::core::status::RequestedIncompatibleQosStatus&)
      {
          std::cout << "on_requested_incompatible_qos" << std::endl;
      }
  
      void on_sample_lost(
         dds::sub::AnyDataReader&,
         const dds::core::status::SampleLostStatus&)
      {
          std::cout << "on_sample_lost" << std::endl;
      }
  
      void on_sample_rejected(
         dds::sub::AnyDataReader&,
         const dds::core::status::SampleRejectedStatus&)
      {
          std::cout << "on_sample_rejected" << std::endl;
      }
  
      void on_subscription_matched(
         dds::sub::AnyDataReader&,
         const dds::core::status::SubscriptionMatchedStatus&)
      {
          std::cout << "on_subscription_matched" << std::endl;
      }
  
      void on_data_available(
         dds::sub::AnyDataReader&)
      {
          std::cout << "on_data_available" << std::endl;
      }
  };

  
  
• Get an entity's listener

      ExampleDomainParticipantListener *listener = new ExampleDomainParticipantListener;
      dds::domain::DomainParticipant participant(
         0, dds::domain::qos::DomainParticipantQos(), listener);
  
      dds::domain::DomainParticipantListener *retrieved_listener = participant.listener();

  
  
• Enable statuses for the listener

      // The default constructor creates an empty StatusMask
      dds::core::status::StatusMask enabled_status_list; 
  
      // ...
  
      // Add more statuses to the enabled_status_list
      enabled_status_list |= dds::core::status::StatusMask::liveliness_changed() |
          dds::core::status::StatusMask::offered_incompatible_qos();

  
  
• Disable a status for the listener

      enabled_status_list &= ~dds::core::status::StatusMask::offered_incompatible_qos();

  
  
• Set an entity's listener and only enable the listener for the statuses specified by the enabled_status_list.

      participant.listener(listener, enabled_status_list);

Enabling/Disabling statuses associated with a status condition

Upon entity creation, by default, all the statuses are enabled for the DDS_StatusCondition associated with the entity.

Once an entity has been created, the list of statuses for which the DDS_StatusCondition is triggered can be manipulated as follows.

• Given an entity and the associated status_condition

      ExampleDomainParticipantListener *listener = new ExampleDomainParticipantListener;
      dds::domain::DomainParticipant participant(
         0, dds::domain::qos::DomainParticipantQos(), listener);
  
      dds::core::cond::StatusCondition status_condition(participant);

  
  
• Get the list of statuses enabled for the status_condition

      dds::core::status::StatusMask enabled_status_list = status_condition.enabled_statuses();

  
  
• Check if a given status is enabled for the status_condition

      // StatusMask inherits from std::bitset. You can use std::bitset's any() 
      // method to check if a given status is enabled
      if ((enabled_status_list & dds::core::status::StatusMask::data_on_readers()).any()) {
          // Do something to handle the on_data_on_readers status...
      }

  
  
• Enable statuses for the status_condition

      status_condition.enabled_statuses(
         dds::core::status::StatusMask::inconsistent_topic() | 
         dds::core::status::StatusMask::sample_rejected());

  
  
• Disable statuses for the status_condition

      status_condition.enabled_statuses(
         ~dds::core::status::StatusMask::inconsistent_topic());

Ignoring Entities

A Topic is used in this example, but each of the other entities (DomainParticipants, Publishers, Subscribers, and DataWriters) also have an ignore() method which takes the DomainParticipant and InstanceHandle(s) of the entities that are to be ignored

• Ignore Topics

      dds::domain::DomainParticipant participant(0);
      dds::topic::Topic<Foo> topic1(participant, "Topic1");
      dds::topic::Topic<Foo> topic2(participant, "Topic2");
      dds::topic::Topic<Foo> topic3(participant, "Topic3");
  
      // This participant will now ignore this topic
      dds::topic::ignore(participant, topic1.instance_handle());
  
      dds::core::InstanceHandleSeq handles;
      handles.push_back(topic2.instance_handle());
      handles.push_back(topic3.instance_handle());
  
      // This participant will now ignore the other two topics too
      dds::topic::ignore(participant, handles.begin(), handles.end());

Tearing Down An Entity

The following examples use a DomainParticipant to show the various patterns which exist to tear down an entity, but the same examples can also be applied when shutting down Subscribers, Publishers, DataReaders, DataWriters, and Topics

• Let all references to a given entity go out-of-scope and let the destructor take care of entity clean up

  {
      {
          // Create a participant on domain 0
          dds::domain::DomainParticipant participant(0);
          
          // ...
      } // participant destroyed here
  
      // found_participant will equal dds::core::null because the participant's
      // destructor was called when the only reference to it went out of scope
      dds::domain::DomainParticipant found_participant = dds::domain::find(0);
  }

  
  
• Explicitly call close() on one of the existing references to an Entity

      // Create a participant on domain 0
      dds::domain::DomainParticipant participant(0);
  
      // All Entities are Reference types, meaning that the assignment operator
      // will not make a copy of the participant, but instead will just create 
      // another reference to the previously created participant 
      dds::domain::DomainParticipant same_participant = participant;
  
      // Call close() on same_participant to explicitly destroy the participant.
      // Both references (participant and same_participant) are now invalid.
      same_participant.close();
  
      try {
          // Any attempt to use the closed participant, will cause a 
          // dds::core::AlreadyClosedError exception
          participant.enable();
      }
      catch (dds::core::AlreadyClosedError& ex) {
          std::cout << "Expected AlreadyClosedError: " << ex.what() << std::endl;
      }

  
  
• Assigning dds::core::null to a variable has the same effect as if the reference went ouf of scope. Assigning dds::core::null to the last reference destroys the underlying object.

      // Create a reference to a null participant
      dds::domain::DomainParticipant participant1(dds::core::null);
  
      // Now create a participant on domain 0
      dds::domain::DomainParticipant participant2(0);
  
      // Assign participant1 to this valid participant
      participant1 = participant2;
  
      // Assign dds::core:null to participant2. The participant will not be 
      // destroyed because participant1 is still a valid reference
      participant2 = dds::core::null;
  
      // We can still use the participant because participant1 is still a 
      // valid reference
      dds::domain::qos::DomainParticipantQos qos = 
          participant1.default_participant_qos();
  
      // Assigning dds::core::null to the only remaining reference to the 
      // participant will now cause its destructor to be called
      participant1 = dds::core::null;
  
      // found_participant will equal dds::core::null because the previous
      // assignment to dds::core::null caused the participant to be destroyed
      dds::domain::DomainParticipant found_participant = dds::domain::find(0);

  
  
• Retaining and then destroying an Entity

  void howto_teardown_retain()
  {
      // To prevent participant destruction when all references go out of scope 
      // you can call retain().
      const uint32_t domain_id_0 = 0;
      const uint32_t domain_id_1 = 1;
  
      create_and_retain_participant(domain_id_0, false);
      create_and_retain_participant(domain_id_1, true);
  
      // We did not retain the participant with domain_id_0, so the following 
      // will result in participant0 == dds::core::null
      dds::domain::DomainParticipant participant0 = dds::domain::find(domain_id_0);
  
      // We can recover the participant with domain_id_1 using find() because we 
      // retained it. participant1 will be a valid reference to 
      // the participant that was created on domain 1
      dds::domain::DomainParticipant participant1 = dds::domain::find(domain_id_1);
  
      // Because we called retain on the participant, the only way to destroy
      // the participant is to explicitly call close() on a reference to the
      // participant. Any attempt to use the participant after calling 
      // close will cause a dds::core::AlreadyClosedError exception to be thrown
  
      // Destroy the participant
      participant1.close();
  
      try {
          // This call will cause a dds::core::AlreadyClosedError exception
          participant1.enable();
      }
      catch (dds::core::AlreadyClosedError& ex) {
          std::cout << "Expected AlreadyClosedError: " << ex.what() << std::endl;
      }
       
  }
  
  void create_and_retain_participant(const uint32_t domain_id, bool retain)
  {
      // Create and retain a participant. If retained, the participant will not 
      // be destroyed when it goes out of scope and can be retrieved again
      dds::domain::DomainParticipant participant(domain_id);
      if (retain) {
          participant.retain();
      }
  }