The main purpose of a DomainParticipantFactory is to create and destroy DomainParticipants.
In C++ terms, this is a singleton class; that is, you will only have a single DomainParticipantFactory in an application—no matter how many DomainParticipants the application may create. Figure 3 shows how to instantiate a DomainParticipantFactory. Notice that there are no parameters to specify. Alternatively, in C++, C++/CLI, and C#, the predefined macro, DDSTheParticipantFactory,1In C, the macro is DDS_TheParticipantFactory. In Java, use the static class method DomainParticipantFactory.TheParticipantFactory. can also be used to retrieve the singleton factory.
Unlike the other Entities that you create, the DomainParticipantFactory does not have an associated Listener. However, it does have associated QosPolicies, see Setting DomainParticipantFactory QosPolicies. You can change them using the factory’s get_qos() and set_qos() operations. The DomainParticipantFactory also stores the default QoS settings that can be used when a DomainParticipant is created. These default settings can be changed as well, see Getting and Setting Default QoS for Child Entities.
Figure 3 Instantiating a DomainParticipantFactory
DDSDomainParticipantFactory* factory = NULL; factory = DDSDomainParticipantFactory::get_instance(); if (factory == NULL) { // ... error }
In the Modern C++ API, there isn’t a explicit DomainParticipantFactory. DomainParticipants are created using their constructors andare automatically destroyed as a reference type (See Creating and Deleting DDS Entities).
The operations to set and get the default DomainParticipantQos are static functions in DomainParticipant: DomainParticipant::default_participant_qos(). The operations to look up participants are freestanding functions in the dds::domain and rti::domain namespaces: dds::domain::find(), rti::domain::find_participant_by_name(), and rti::domain::find_participants(). The class QosProvider is responsible for managing QoS profiles (see How to Load XML-Specified QoS Settings).
There is a DomainParticipantFactoryQos, but it only contains the ENTITY_FACTORY to indicate if a DomainParticipant should be enabled in its constructor or by calling enable(), and SYSTEM_RESOURCE_LIMITS. The DomainParticipantFactoryQos getter and setter are static functions in DomainParticipant: DomainParticipant::participant_factory_qos().
Another static function in DomainParticipant allows finalizing the implicit DomainParticipantFactory singleton: DomainParticipant::finalize_participant_factory().
Once you have a DomainParticipantFactory, you can use it to perform the operations listed in Table 1 . The most important one is create_participant(), described in Creating a DomainParticipant. For more details on all operations, see the API Reference HTML documentation as well as the section of the manual listed in the Reference column.
Working with ... |
Operation |
Description |
Reference |
Domain-Participants |
create_participant |
Creates a DomainParticipant. |
|
create_participant_with_ |
Creates a DomainParticipant based on a QoS profile. |
||
delete_participant |
Deletes a DomainParticipant. |
||
get_default_participant_qos |
Gets the default QoS for DomainParticipants. |
||
get_participants |
Returns a sequence of pointers to all the DomainParticipants within the DomainParticipantFactory. |
||
lookup_participant |
Finds a specific DomainParticipant, based on a domain ID. |
||
lookup_participant_by_name |
Finds a specific DomainParticipant, based on a domain name. |
||
set_default_participant_qos |
Sets the default QoS for DomainParticipants. |
||
set_default_participant_qos_ |
Sets the default QoS for DomainParticipants based on a QoS profile. |
||
The Factory’s Instance |
get_instance |
Gets the singleton instance of this class. |
|
finalize_instance |
Destroys the singleton instance of this class. |
||
The Factory’s Own QoS |
get_qos |
Gets/sets the DomainParticipantFactory’s QoS. |
|
set_qos |
|||
equals |
Compares two DomainParticipantFactory’s QoS structures for equality. |
||
Threads |
set_thread_factory |
Specifies a ThreadFactory implementation that DomainParticipants will use to create and delete all threads. |
|
unregister_thread |
Frees all resources related to a thread. This function is intended to be used at the end of any user-created threads that invoke Connext DDS APIs (not all users will have this situation). The best approach is to call it immediately before exiting such a thread, after all Connext DDS APIs have been called. |
|
|
Profiles & Libraries |
get_default_library |
Gets the default library for a DomainParticipantFactory. |
Getting and Setting the DomainParticipantFactory’s Default QoS Profile and Library |
get_default_profile |
Gets the default QoS profile for a DomainParticipantFactory. |
||
get_default_profile_library |
Gets the library that contains the default QoS profile for a DomainParticipantFactory. |
||
get_<entity>_qos_from_profile |
Gets the <entity> QoS values associated with a specified QoS profile. <entity> may be topic, datareader, datawriter, subscriber, publisher, or participant. |
||
get_<entity>_qos_from_profile_w_topic_name |
Like get_<entity>_qos_from_profile(), but this operation allows you to specify a topic name associated with the entity. The topic filter expressions in the profile will be evaluated on the topic name. <entity> may be topic, datareader, or datawriter. |
||
get_qos_profiles |
Gets the names of all XML QoS profiles associated with a specified XML QoS profile library. |
||
get_qos_profile_libraries |
Gets the names of all XML QoS profile libraries associated with the DomainParticipantFactory. |
||
load_profiles |
Explicitly loads or reloads the QoS profiles. |
||
reload_profiles |
|||
set_default_profile |
Sets the default QoS profile for a DomainParticipantFactory. |
Getting and Setting the DomainParticipantFactory’s Default QoS Profile and Library |
|
set_default_library |
Sets the default library for a DomainParticipantFactory. |
||
unload_profiles |
Frees the resources associated with loading QoS profiles. |
© 2015 RTI