46.2 ENTITYFACTORY QosPolicy

This QosPolicy controls whether or not child Entities are created in the enabled state.

This QosPolicy applies to the DomainParticipantFactory, DomainParticipants, Publishers, and Subscribers, which act as ‘factories’ for the creation of subordinate Entities. A DomainParticipantFactory is used to create DomainParticipants. A DomainParticipant is used to create both Publishers and Subscribers. A Publisher is used to create DataWriters, similarly a Subscriber is used to create DataReaders.

Entities can be created either in an ‘enabled’ or ‘disabled’ state. An enabled entity can actively participate in communication. A disabled entity cannot be discovered or take part in communication until it is explicitly enabled. For example, Connext will not send data if the write() operation is called on a disabled DataWriter, nor will Connext deliver data to a disabled DataReader. You can only enable a disabled entity. Once an entity is enabled, you cannot disable it, see 15.2 Enabling DDS Entities about the enable() method.

The ENTITYFACTORY contains only one member, as illustrated in Table 46.2 DDS_EntityFactoryQosPolicy.

The ENTITYFACTORY QosPolicy controls whether the Entities created from the factory are automatically enabled upon creation or are left disabled. For example, if a Publisher is configured to auto-enable created Entities, then all DataWriters created from that Publisher will be automatically enabled.

Note: If an entity is disabled, then all of the child Entities it creates are also created in a disabled state, regardless of the setting of this QosPolicy. However, enabling a disabled entity will enable all of its children if this QosPolicy is set to autoenable child Entities.

Note: An entity can only be enabled; it cannot be disabled after it has been enabled.

See 46.2.1 Example for an example of how to set this policy.

There are various reasons why you may want to create Entities in the disabled state:

• To get around a “chicken and egg”-type issue. Where you need to have an entity in order to modify it, but you don’t want the entity to be used by Connext until it has been modified.

For example, if you create a DomainParticipant in the enabled state, it will immediately start sending packets to other nodes trying to discover if other Connext applications exist. However, you may want to configure the built-in topic reader listener before discovery occurs. To do this, you need to create a DomainParticipant in the disabled state because once enabled, discovery will occur. If you set up the built-in topic reader listener after the DomainParticipant is enabled, you may miss some discovery traffic.

• You may want to create Entities without having them automatically start to work. This especially pertains to DataReaders. If you create a DataReader in an enabled state and you are using DataReaderListeners, Connext will immediately search for matching DataWriters and callback the listener as soon as data is published. This may not be what you want to happen if your application is still in the middle of initialization when data arrives.

So typically, you would create all Entities in a disabled state, and then when all parts of the application have been initialized, one would enable all Entities at the same time using the enable() operation on the DomainParticipant, see 15.2 Enabling DDS Entities.

• An entity’s existence is not advertised to other participants in the network until the entity is enabled. Instead of sending an individual declaration packet to other applications announcing the existence of the entity, Connext can be more efficient in bundling multiple declarations into a single packet when you enable all Entities at the same time.

See 15.2 Enabling DDS Entities for more information about enabled/disabled Entities.

46.2.1 Example

The code in Figure 46.1: Configuring a Publisher so that New DataWriters are Disabled illustrates how to use the ENTITYFACTORY QoS.

Note:

• In C, you must initialize the QoS structures before they are used, see 42.2 Special QosPolicy Handling Considerations for C.

DDS_PublisherQos publisher_qos;
// topic, publisher, writer_listener already created
if (publisher->get_qos(publisher_qos) != DDS_RETCODE_OK) {
    // handle error
}
publisher_qos.entity_factory.autoenable_created_entities 
    = DDS_BOOLEAN_FALSE;
if (publisher->set_qos(publisher_qos) != DDS_RETCODE_OK) {
    // handle error
}
// Subsequently created DataWriters are created disabled and
// must be explicitly enabled by the user-code
DDSDataWriter* writer = publisher->create_datawriter(topic,
    DDS_DATAWRITER_QOS_DEFAULT, writer_listener, DDS_STATUS_MASK_ALL);
// now do other initialization
// Now explicitly enable the DataWriter, this will allow other
// applications to discover the DataWriter and for this application
// to send data when the DataWriter’s write() method is called
writer->enable();

46.2.2 Properties

This QosPolicy can be modified at any time.

It can be set differently on the publishing and subscribing sides.

46.2.3 Related QosPolicies

This QosPolicy does not interact with any other policies.

46.2.4 Applicable DDS Entities

• 16.2 DomainParticipantFactory
• 16.3 DomainParticipants
• Chapter 30 Publishers
• Chapter 39 Subscribers

46.2.5 System Resource Considerations

This QosPolicy does not significantly impact the use of system resources.