RTI Connext .Net APIs
Version 5.0.0
|
<<interface>> Abstract base class for all Listener interfaces. More...
#include <managed_infrastructure.h>
<<interface>> Abstract base class for all Listener interfaces.
All the supported kinds of concrete DDS::Listener interfaces (one per concrete DDS::Entity type) derive from this root and add methods whose prototype depends on the concrete Listener.
Listeners provide a way for RTI Connext to asynchronously alert the application when there are relevant status changes.
Almost every application will have to implement listener interfaces.
Each dedicated listener presents a list of operations that correspond to the relevant communication status changes to which an application may respond.
The same DDS::Listener instance may be shared among multiple entities if you so desire. Consequently, the provided parameter contains a reference to the concerned DDS::Entity.
The general mapping between the plain communication statuses (see Status Kinds) and the listeners' operations is as follows:
on_<communication_status>
(), which takes a parameter of type <communication_status>
as listed in Status Kinds. on_<communication_status>
is available on the relevant DDS::Entity as well as those that embed it, as expressed in the following figure: This behavior allows the application to set a default behavior (e.g., in the listener associated with the DDS::DomainParticipant) and to set dedicated behaviors only where needed.
The two statuses related to data arrival are treated slightly differently. Since they constitute the core purpose of the Data Distribution Service, there is no need to provide a default mechanism (as is done for the plain communication statuses above).
The rule is as follows. Each time the read communication status changes:
The rationale is that either the application is interested in relations among data arrivals and it must use the first option (and then get the corresponding DDS::DataReader objects by calling DDS::Subscriber::get_datareaders on the related DDS::Subscriber and then get the data by calling DDS::TypedDataReader::read or DDS::TypedDataReader::take on the returned DDS::DataReader objects), or it wants to treat each DDS::DataReader independently and it may choose the second option (and then get the data by calling DDS::TypedDataReader::read or DDS::TypedDataReader::take on the related DDS::DataReader).
Note that if DDS::SubscriberListener::on_data_on_readers is called, RTI Connext will not try to call DDS::DataReaderListener::on_data_available. However, an application can force a call to the DDS::DataReader objects that have data by calling DDS::Subscriber::notify_datareaders.
The operations that are allowed in DDS::Listener callbacks depend on the DDS::ExclusiveAreaQosPolicy QoS policy of the DDS::Entity to which the DDS::Listener is attached – or in the case of a DDS::DataWriter of DDS::DataReader listener, on the DDS::ExclusiveAreaQosPolicy QoS of the parent DDS::Publisher or DDS::Subscriber. For instance, the DDS::ExclusiveAreaQosPolicy settings of a DDS::Subscriber will determine which operations are allowed within the callbacks of the listeners associated with all the DataReaders created through that DDS::Subscriber.
Note: these restrictions do not apply to builtin topic listener callbacks.
Regardless of whether DDS::ExclusiveAreaQosPolicy::use_shared_exclusive_area is set to true or false, the following operations are not allowed:
An attempt to call a disallowed method from within a callback will result in DDS::Retcode_IllegalOperation.
If DDS::ExclusiveAreaQosPolicy::use_shared_exclusive_area is set to false, the setting which allows more concurrency among RTI Connext threads, the following are not allowed:
An attempt to call a disallowed method from within a callback will result in DDS::Retcode_IllegalOperation.
The above limitations can be lifted by setting DDS::ExclusiveAreaQosPolicy::use_shared_exclusive_area to true on the DDS::Publisher or DDS::Subscriber (or on the DDS::Publisher/ DDS::Subscriber of the DDS::DataWriter/DDS::DataReader) to which the listener is attached. However, the application will pay the cost of reduced concurrency between the affected publishers and subscribers.