15.1 Creating and Deleting DDS Entities

• C, Traditional C++, Java, and .NET:

The factory design pattern is used in creating and deleting DDS Entities. Instead of declaring and constructing or destructing Entities directly, a factory object is used to create an Entity. Almost all Entity factories are objects that are also Entities. The only exception is the factory for a DomainParticipant. See Table 15.1 Entity Factories.

Table 15.1 Entity Factories

Entity	Created by
DomainParticipant	DomainParticipantFactory (a static singleton object provided by Connext)
Topic	DomainParticipant
Publisher
Subscriber
DataWriter
DataReader
DataWriter	Publisher
DataReader	Subscriber

All Entities that are factories have:

• Operations to create and delete child Entities. For example:

DDSPublisher::create_datawriter()

DDSDomainParticipant::delete_topic()

• Operations to get and set the default QoS values used when creating child Entities. For example:

DDSSubscriber::get_default_datareader_qos()

DDSDomainParticipantFactory::set_default_participant_qos()

• And 46.2 ENTITYFACTORY QosPolicy to specify whether or not the newly created child Entity should be automatically enabled upon creation.

DataWriters may be created by a DomainParticipant or a Publisher. Similarly, DataReaders may be created by a DomainParticipant or a Subscriber.

An entity that is a factory cannot be deleted until all the child Entities created by it have been deleted.

Each Entity obtained through create_<entity>() must eventually be deleted by calling delete_<entity>(), or by calling delete_contained_entities().

• Modern C++:

In the Modern C++ API the factory pattern is not explicit. Entities have constructors and destructors. The first argument to an Entity's constructor is its "factory" (except for the DomainParticipant). For example:

// Note: this example shows the simplest version of each Entity's constructor:
dds::domain::DomainParticipant participant(MY_DOMAIN_ID);
dds::topic::Topic<Foo> topic(participant, "Example Foo");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo> reader(subscriber, topic);
dds::pub::Publisher publisher(participant);
dds::pub::DataWriter<Foo> writer(publisher, topic);

Entities are reference types. In a reference type copy operations, such as copy-construction and copy-assignment are shallow. The reference types are modeled after shared pointers. Similar to pointers, it is important to distinguish between an entity and a reference (or handle) to it. A single entity may have multiple references. Copying a reference does not copy the entity it is referring to—creating additional references from the existing reference(s) is a relatively inexpensive operation.

The lifecycle of references and the entity they are referring to is not the same. In general, the entity lives as long as there is at least one reference to it. When the last reference to the entity ceases to exists, the entity it is referring to is destroyed.

Applications can override the automatic destruction of Entities. An Entity can be explicitly closed (by calling the method close()) or retained (by calling retain())

Closing an Entity destroys the underlying object and invalidates all references to it.

Retaining an Entity disables the automatic destruction when it loses all its reference. A retained Entity can be looked up (see 16.2.4 Looking Up DomainParticipants) and has to be explicitly destroyed with close().