DDS_Listener Struct Reference
[Entity Support]
<<interface>> Abstract base class for all Listener interfaces.
More...
|
Data Fields |
void * | listener_data |
| A place for listener implementors to keep a pointer to data that may be needed by their listener.
|
Detailed Description
<<interface>> Abstract base class for all Listener interfaces.
- Entity:
- DDS_Entity
- QoS:
- QoS Policies
- Status:
- Status Kinds
All the supported kinds of concrete
DDS_Listener interfaces (one per concrete
DDS_Entity type) derive from this root and add functions whose prototype depends on the concrete Listener.
Listeners provide a way for RTI Data Distribution Service 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:
- For each communication status, there is a corresponding operation whose name is
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:
Hierarchical listener processing. The most specific relevant enabled listener is called.
- When the application attaches a listener on an entity, it must set a mask. The mask indicates to RTI Data Distribution Service which operations are enabled within the listener (cf. operation DDS_Entity set_listener() ).
- When a plain communication status changes, RTI Data Distribution Service triggers the most specific relevant listener operation that is enabled. In case the most specific relevant listener operation corresponds to an application-installed 'nil' listener the operation will be considered handled by a NO-OP operation that does not reset the communication status.
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
FooDataReader_read or
FooDataReader_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
FooDataReader_read or
FooDataReader_take on the related
DDS_DataReader).
Note that if DDS_SubscriberListener::on_data_on_readers is called, RTI Data Distribution Service 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 DDS_BOOLEAN_TRUE or DDS_BOOLEAN_FALSE, the following operations are not allowed:
-
Within any listener callback, deleting the entity to which the DDS_Listener is attached
-
Within a DDS_Topic listener callback, any operations on any subscribers, readers, publishers or writers
An attempt to call a disallowed function from within a callback will result in
DDS_RETCODE_ILLEGAL_OPERATION.
If DDS_ExclusiveAreaQosPolicy::use_shared_exclusive_area is set to DDS_BOOLEAN_FALSE, the setting which allows more concurrency among RTI Data Distribution Service threads, the following are not allowed:
An attempt to call a disallowed function from within a callback will result in
DDS_RETCODE_ILLEGAL_OPERATION.
The above limitations can be lifted by setting DDS_ExclusiveAreaQosPolicy::use_shared_exclusive_area to DDS_BOOLEAN_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.
- See also:
- EXCLUSIVE_AREA
Status Kinds
DDS_WaitSet, DDS_Condition
Field Documentation
A place for listener implementors to keep a pointer to data that may be needed by their listener.