DDSDomainParticipantFactory Class Reference

<<singleton>> <<interface>> <<cert>> Allows creation and destruction of DDSDomainParticipant objects. More...

List of all members.

Public Member Functions
virtual DDSDomainParticipant *	create_participant (DDS_DomainId_t domainId, const DDS_DomainParticipantQos &qos, DDSDomainParticipantListener *listener, DDS_StatusMask mask)=0
	<<cert>> Creates a new DDSDomainParticipant object.
virtual DDS_ReturnCode_t	delete_participant (DDSDomainParticipant *a_participant)=0
	Deletes an existing DDSDomainParticipant.
virtual DDSDomainParticipant *	lookup_participant (DDS_DomainId_t domainId)=0
	<<cert>> Locates an existing DDSDomainParticipant.
virtual DDS_ReturnCode_t	set_default_participant_qos (const DDS_DomainParticipantQos &qos)=0
	Sets the default DDS_DomainParticipantQos values for this domain participant factory.
virtual DDS_ReturnCode_t	get_default_participant_qos (DDS_DomainParticipantQos &qos)=0
	Initializes the DDS_DomainParticipantQos instance with default values.
virtual DDS_ReturnCode_t	get_qos (DDS_DomainParticipantFactoryQos &qos)=0
	<<cert>> Gets the value for participant factory QoS.
virtual DDS_ReturnCode_t	set_qos (const DDS_DomainParticipantFactoryQos &qos)=0
	<<cert>> Sets the value for a participant factory QoS.
virtual RTRegistry *	get_registry ()=0
	<<cert>> Retrieves the singleton registry instance associated with the factory.

Static Public Member Functions
static DDSDomainParticipantFactory *	get_instance ()
	<<cert>> Gets the singleton instance of this class.
static DDS_ReturnCode_t	finalize_instance ()
	<<eXtension>> Destroys the singleton instance of this class.

---

Detailed Description

<<singleton>> <<interface>> <<cert>> Allows creation and destruction of DDSDomainParticipant objects.

The sole purpose of this class is to allow the creation and destruction of DDSDomainParticipant objects. This class itself is a <<singleton>>, and accessed via the get_instance() method, and destroyed with finalize_instance() method.

A single application can participate in multiple domains by instantiating multiple DDSDomainParticipant objects.

An application may even instantiate multiple participants in the same domain. Participants in the same domain exchange data in the same way regardless of whether they are in the same application or different applications or on the same node or different nodes; their location is transparent.

There are two important caveats:

• With multiple participants in the same domain on the same node (in the same application or different applications), each participant must be assigned its own receive ports. The receive ports are calculated based on the domain ID and the participant index set in the DDS_WireProtocolQosPolicy. The default index (-1) causes the participant to automatically search for the next available index, starting at 0, when it is created. If an index larger or equal to 0 is assigned then only that value will be used. If another participant with the same index already exists the participant creation will fail.

  NOTE: An exception to this rule is multicast ports. Multicast ports are shared between between participants in the same domain on the same host). Thus, the index value is ignored.

• You cannot mix entities from different participants. For example, you cannot delete a topic on a different participant than you created it from, and you cannot ask a subscriber to create a reader for a topic created from a participant different than the subscriber's own participant. (Note that it is permissable for an application built on top of RTI Connext Micro to know about entities from different participants. For example, an application could keep references to a reader from one domain and a writer from another and then bridge the domains by writing the data received in the reader callback.)

See also:

DDSDomainParticipant

---

Member Function Documentation

static DDSDomainParticipantFactory* DDSDomainParticipantFactory::get_instance ( )

static

<<cert>> Gets the singleton instance of this class.

Returns:

the DDSDomainParticipantFactory instance.

MT Safety:

UNSAFE on the FIRST call to DDSDomainParticipantFactory::get_instance(). It is not safe for two threads to simultaneously make the first call to get an instance of the factory. Subsequent calls are thread safe.

DDSTheParticipantFactory can be used as an alias for the singleton factory returned by this operation.

DDSDomainParticipantFactory::get_instance also initializes the RTI Connext Micro library and should be called before any other API, unless the API is explicitly mentioned as safe to call before DDSDomainParticipantFactory::get_instance.

Returns:

the singleton DDSDomainParticipantFactory instance.

ARINC 653 API Restriction:

This function must only be called before a partition enters NORMAL mode.

See also:

DDSTheParticipantFactory

static DDS_ReturnCode_t DDSDomainParticipantFactory::finalize_instance ( )

static

<<eXtension>> Destroys the singleton instance of this class.

Only necessary to explicitly reclaim resources used by the participant factory singleton. Note that on many OSes, these resources are automatically reclaimed by the OS when the program terminates. Some memory checker tools still flag these as unreclaimed however. So this method provides a way to clean up memory used by the participant factory.

Precondition:

All participants created from the factory have been deleted.

Postcondition:

All resources belonging to the factory reclaimed. Another call to DDSDomainParticipantFactory::get_instance will return a new lifecycle of the singleton.

MT Safety:

UNSAFE for two threads to simultaneously call DDSDomainParticipantFactory::finalize_instance() or DDSDomainParticipantFactory::get_instance() at the same time.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET

virtual DDSDomainParticipant* DDSDomainParticipantFactory::create_participant ( DDS_DomainId_t  domainId, const DDS_DomainParticipantQos &  qos, DDSDomainParticipantListener *  listener, DDS_StatusMask  mask  )

pure virtual

<<cert>> Creates a new DDSDomainParticipant object.

Precondition:

The specified QoS policies must be consistent, or the operation will fail and no DDSDomainParticipant will be created.

If you want to create multiple participants on a given host in the same domain, make sure each one has a different participant index (set in the DDS_WireProtocolQosPolicy). This in turn will ensure each participant uses a different port number (since the unicast port numbers are calculated from the participant index and the domain ID).

Note that if there is a single participant per host in a given domain, the participant index can be left at the default value (-1).

Parameters:

domainId	<<in>> ID of the domain that the application intends to join. [range] [>=0], and does not violate guidelines stated in DDS_RtpsWellKnownPorts_t.
qos	<<in>> the domain participant's QoS. The special value DDS_PARTICIPANT_QOS_DEFAULT can be used to indicate that the DDSDomainParticipant should be created with the default DDS_DomainParticipantQos set in the DDSDomainParticipantFactory.
listener	<<in>> the domain participant's listener.
mask	<<in>> Changes of communication status to be invoked on the listener.

Returns:

domain participant or NULL on failure

MT Safety:

This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

ARINC 653 API Restriction:

This function must only be called before a partition enters NORMAL mode.

See also:

Specifying QoS on entities for information on setting QoS before entity creation

DDS_DomainParticipantQos for rules on consistency among QoS

DDS_PARTICIPANT_QOS_DEFAULT

virtual DDS_ReturnCode_t DDSDomainParticipantFactory::delete_participant ( DDSDomainParticipant *  a_participant )

pure virtual

Deletes an existing DDSDomainParticipant.

Precondition:

All domain entities belonging to the participant must have already been deleted. Otherwise it fails with the error DDS_RETCODE_PRECONDITION_NOT_MET.

Postcondition:

Listener installed on the DDSDomainParticipant will not be called after this method returns successfully.

Parameters:

a_participant

<<in>> DDSDomainParticipant to be deleted.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

virtual DDSDomainParticipant* DDSDomainParticipantFactory::lookup_participant ( DDS_DomainId_t  domainId )

pure virtual

<<cert>> Locates an existing DDSDomainParticipant.

If no such DDSDomainParticipant exists, the operation will return NULL value.

If multiple DDSDomainParticipant entities belonging to that domainId exist, then the operation will return one of them. It is not specified which one.

Parameters:

domainId

<<in>> ID of the domain participant to lookup.

Returns:

domain participant if it exists, or NULL

MT Safety:

This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

virtual DDS_ReturnCode_t DDSDomainParticipantFactory::set_default_participant_qos ( const DDS_DomainParticipantQos &  qos )

pure virtual

Sets the default DDS_DomainParticipantQos values for this domain participant factory.

This method may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters:

qos

<<inout>> Qos to be used by the DDSDomainParticipant. The special value DDS_PARTICIPANT_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would used if DDSDomainParticipantFactory::set_default_participant_qos had never been called.

Returns:

One of the Standard Return Codes

See also:

DDS_PARTICIPANT_QOS_DEFAULT

DDSDomainParticipantFactory::create_participant

virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_default_participant_qos ( DDS_DomainParticipantQos &  qos )

pure virtual

Initializes the DDS_DomainParticipantQos instance with default values.

The retrieved qos will match the set of values specified on the last successful call to DDSDomainParticipantFactory::set_default_participant_qos, or else, if the call was never made, the default values listed in DDS_DomainParticipantQos.

This method may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters:

qos	<<out>> the domain participant's QoS

Returns:

One of the Standard Return Codes

See also:

DDS_PARTICIPANT_QOS_DEFAULT

DDSDomainParticipantFactory::create_participant

virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_qos ( DDS_DomainParticipantFactoryQos &  qos )

pure virtual

<<cert>> Gets the value for participant factory QoS.

Parameters:

qos	<<inout>> QoS to be filled up.

Returns:

One of the Standard Return Codes

MT Safety:

This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

virtual DDS_ReturnCode_t DDSDomainParticipantFactory::set_qos ( const DDS_DomainParticipantFactoryQos &  qos )

pure virtual

<<cert>> Sets the value for a participant factory QoS.

The DDS_DomainParticipantFactoryQos::entity_factory can be changed. The other policies are immutable.

Note that despite having QoS, the DDSDomainParticipantFactory is not an DDSEntity.

Note that this function may cause RTI Connext Micro to free and reallocate memory, depending on the QoS policies that are changed.

Parameters:

qos	<<in>> Set of policies to be applied to DDSDomainParticipantFactory. Policies must be consistent. Immutable policies can only be changed before calling any other RTI Connext Micro methods except for DDSDomainParticipantFactory::get_qos

Returns:

One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY if immutable policy is changed, or DDS_RETCODE_INCONSISTENT_POLICY if policies are inconsistent

MT Safety:

This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

See also:

DDS_DomainParticipantFactoryQos for rules on consistency among QoS

virtual RTRegistry* DDSDomainParticipantFactory::get_registry ( )

pure virtual

<<cert>> Retrieves the singleton registry instance associated with the factory.

Returns:

the registry instance or NULL on failure.

MT Safety:

This operation is thread safe.