[15169] Added Conditions C++ API reference.

docs/03-exports/aliases-api.include

@@ -14,10 +14,12 @@
 .. |DataReader::read_instance-api| replace:: :cpp:func:`DataReader::read_instance()<eprosima::fastdds::dds::DataReader::read_instance>`
 .. |DataReader::read_next_instance-api| replace:: :cpp:func:`DataReader::read_next_instance()<eprosima::fastdds::dds::DataReader::read_next_instance>`
 .. |DataReader::read_next_sample-api| replace:: :cpp:func:`DataReader::read_next_sample()<eprosima::fastdds::dds::DataReader::read_next_sample>`
+.. |DataReader::read_w_condition-api| replace:: :cpp:func:`DataReader::read_w_condition()<eprosima::fastdds::dds::DataReader::read_w_condition>`
 .. |DataReader::take-api| replace:: :cpp:func:`DataReader::take()<eprosima::fastdds::dds::DataReader::take>`
 .. |DataReader::take_instance-api| replace:: :cpp:func:`DataReader::take_instance()<eprosima::fastdds::dds::DataReader::take_instance>`
 .. |DataReader::take_next_instance-api| replace:: :cpp:func:`DataReader::take_next_instance()<eprosima::fastdds::dds::DataReader::take_next_instance>`
 .. |DataReader::take_next_sample-api| replace:: :cpp:func:`DataReader::take_next_sample()<eprosima::fastdds::dds::DataReader::take_next_sample>`
+.. |DataReader::take_w_condition-api| replace:: :cpp:func:`DataReader::take_w_condition()<eprosima::fastdds::dds::DataReader::take_w_condition>`
 .. |DataReader::return_loan-api| replace:: :cpp:func:`DataReader::return_loan()<eprosima::fastdds::dds::DataReader::return_loan>`
 .. |DataReaderListener-api| replace:: :cpp:class:`DataReaderListener <eprosima::fastdds::dds::DataReaderListener>`
 
@@ -218,10 +220,12 @@
 .. |QosPolicy-api| replace:: :cpp:class:`QosPolicy <eprosima::fastdds::dds::QosPolicy>`
 .. |StatusMask-api| replace:: :cpp:class:`StatusMask <eprosima::fastdds::dds::StatusMask>`
 .. |StatusMask::all-api| replace:: :cpp:func:`StatusMask::all()<eprosima::fastdds::dds::StatusMask::all>`
+.. |StatusMask::is_active-api| replace:: :cpp:func:`StatusMask::is_active()<eprosima::fastdds::dds::StatusMask::is_active>`
 .. |StatusMask::none-api| replace:: :cpp:func:`StatusMask::none()<eprosima::fastdds::dds::StatusMask::none>`
 .. |Subscriber-api| replace:: :cpp:class:`Subscriber <eprosima::fastdds::dds::Subscriber>`
 .. |Subscriber::get_qos-api| replace:: :cpp:func:`get_qos()<eprosima::fastdds::dds::Subscriber::get_qos>`
 .. |Subscriber::set_qos-api| replace:: :cpp:func:`Subscriber::set_qos()<eprosima::fastdds::dds::Subscriber::set_qos>`
+.. |Subscriber::get_datareaders-api| replace:: :cpp:func:`Subscriber::get_datareaders()<eprosima::fastdds::dds::Subscriber::get_datareaders>`
 .. |Subscriber::get_default_datareader_qos-api| replace:: :cpp:func:`get_default_datareader_qos()<eprosima::fastdds::dds::Subscriber::get_default_datareader_qos>`
 .. |Subscriber::set_default_datareader_qos-api| replace:: :cpp:func:`set_default_datareader_qos()<eprosima::fastdds::dds::Subscriber::set_default_datareader_qos>`
 .. |Subscriber::get_datareader_qos_from_profile| replace:: :cpp:func:`get_datareader_qos_from_profile()<eprosima::fastdds::dds::Subscriber::get_datareader_qos_from_profile>`
@@ -290,6 +294,7 @@
 
 .. |Entity-api| replace:: :cpp:class:`Entity<eprosima::fastdds::dds::Entity>`
 .. |Entity::get_instance_handle-api| replace:: :cpp:func:`get_instance_handle()<eprosima::fastdds::dds::Entity::get_instance_handle>`
+.. |Entity::get_status_changes-api| replace:: :cpp:func:`get_status_changes()<eprosima::fastdds::dds::Entity::get_status_changes>`
 
 .. |DestinationOrderQosPolicyKind-api| replace:: :cpp:enum:`DestinationOrderQosPolicyKind<eprosima::fastdds::dds::DestinationOrderQosPolicyKind>`
 .. |BY_RECEPTION_TIMESTAMP| replace:: :cpp:enumerator:`BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS<eprosima::fastdds::dds::DestinationOrderQosPolicyKind::BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS>`
@@ -745,6 +750,12 @@
 .. |REJECTED_BY_SAMPLES_LIMIT| replace:: :cpp:enumerator:`REJECTED_BY_SAMPLES_LIMIT<eprosima::fastdds::dds::SampleRejectedStatusKind::REJECTED_BY_SAMPLES_LIMIT>`
 .. |REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT| replace:: :cpp:enumerator:`REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT<eprosima::fastdds::dds::SampleRejectedStatusKind::REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT>`
 
+.. |GuardCondition::set_trigger_value-api| replace:: :cpp:func:`set_trigger_value()<eprosima::fastdds::dds::GuardCondition::set_trigger_value>`
+.. |StatusCondition::set_enabled_statuses-api| replace:: :cpp:func:`set_enabled_statuses()<eprosima::fastdds::dds::StatusCondition::set_enabled_statuses>`
+.. |WaitSet::attach_condition-api| replace:: :cpp:func:`attach_condition()<eprosima::fastdds::dds::WaitSet::attach_condition>`
+.. |WaitSet::detach_condition-api| replace:: :cpp:func:`detach_condition()<eprosima::fastdds::dds::WaitSet::detach_condition>`
+.. |WaitSet::wait-api| replace:: :cpp:func:`wait()<eprosima::fastdds::dds::WaitSet::wait>`
+
 .. |SubscriptionMatchedStatus-api| replace:: :cpp:struct:`SubscriptionMatchedStatus<eprosima::fastdds::dds::SubscriptionMatchedStatus>`
 .. |SubscriptionMatchedStatus::last_publication_handle-api| replace:: :cpp:member:`last_publication_handle<eprosima::fastdds::dds::SubscriptionMatchedStatus::last_publication_handle>`
 

docs/fastdds/api_reference/dds_pim/core/condition/basecondition.rst

@@ -0,0 +1,10 @@
+Condition
+=========
+
+.. toctree::
+
+    /fastdds/api_reference/dds_pim/core/condition/condition.rst
+    /fastdds/api_reference/dds_pim/core/condition/conditionseq.rst
+    /fastdds/api_reference/dds_pim/core/condition/guardcondition.rst
+    /fastdds/api_reference/dds_pim/core/condition/statuscondition.rst
+    /fastdds/api_reference/dds_pim/core/condition/waitset.rst

docs/fastdds/api_reference/dds_pim/core/condition/condition.rst

@@ -0,0 +1,10 @@
+.. _api_pim_condition:
+
+.. rst-class:: api-ref
+
+Condition
+---------
+
+.. doxygenclass:: eprosima::fastdds::dds::Condition
+    :project: FastDDS
+    :members:

docs/fastdds/api_reference/dds_pim/core/condition/conditionseq.rst

@@ -0,0 +1,9 @@
+.. _api_pim_conditionseq:
+
+.. rst-class:: api-ref
+
+ConditionSeq
+------------
+
+.. doxygentypedef:: eprosima::fastdds::dds::ConditionSeq
+    :project: FastDDS

docs/fastdds/api_reference/dds_pim/core/condition/guardcondition.rst

@@ -0,0 +1,10 @@
+.. _api_pim_guardcondition:
+
+.. rst-class:: api-ref
+
+GuardCondition
+--------------
+
+.. doxygenclass:: eprosima::fastdds::dds::GuardCondition
+    :project: FastDDS
+    :members:

docs/fastdds/api_reference/dds_pim/core/condition/statuscondition.rst

@@ -0,0 +1,10 @@
+.. _api_pim_statuscondition:
+
+.. rst-class:: api-ref
+
+StatusCondition
+---------------
+
+.. doxygenclass:: eprosima::fastdds::dds::StatusCondition
+    :project: FastDDS
+    :members:

docs/fastdds/api_reference/dds_pim/core/condition/waitset.rst

@@ -0,0 +1,10 @@
+.. _api_pim_waitset:
+
+.. rst-class:: api-ref
+
+Wait-set
+--------
+
+.. doxygenclass:: eprosima::fastdds::dds::WaitSet
+    :project: FastDDS
+    :members:

docs/fastdds/api_reference/dds_pim/core/core.rst

@@ -7,6 +7,7 @@ Core
    /fastdds/api_reference/dds_pim/core/domainentity.rst
    /fastdds/api_reference/dds_pim/core/policy/policy.rst
    /fastdds/api_reference/dds_pim/core/status/status.rst
+   /fastdds/api_reference/dds_pim/core/condition/basecondition.rst
    /fastdds/api_reference/dds_pim/core/loanablearray.rst
    /fastdds/api_reference/dds_pim/core/loanablecollection.rst
    /fastdds/api_reference/dds_pim/core/loanablesequence.rst

docs/fastdds/api_reference/dds_pim/subscriber/readcondition.rst

@@ -0,0 +1,10 @@
+.. _api_pim_readcondition:
+
+.. rst-class:: api-ref
+
+ReadCondition
+--------------
+
+.. doxygenclass:: eprosima::fastdds::dds::ReadCondition
+    :project: FastDDS
+    :members:

docs/fastdds/api_reference/dds_pim/subscriber/subscriber.rst

@@ -7,6 +7,7 @@ Subscriber
    /fastdds/api_reference/dds_pim/subscriber/datareaderlistener.rst
    /fastdds/api_reference/dds_pim/subscriber/datareaderqos.rst
    /fastdds/api_reference/dds_pim/subscriber/instancestatekind.rst
+   /fastdds/api_reference/dds_pim/subscriber/readcondition.rst
    /fastdds/api_reference/dds_pim/subscriber/readerresourcelimitsqos.rst
    /fastdds/api_reference/dds_pim/subscriber/rtpsreliablereaderqos.rst
    /fastdds/api_reference/dds_pim/subscriber/sampleinfo.rst

docs/fastdds/api_reference/spelling_wordlist.txt

@@ -96,6 +96,7 @@ nullptr
 Num
 OfferedDeadlineMissedStatus
 OfferedIncompatibleQosStatus
+ok
 OStream
 OwnershipQosPolicy
 OwnershipStrengthQosPolicy
@@ -114,6 +115,7 @@ PublisherListener
 qos
 QosPolicyCount
 rdata
+ReadCondition
 ReceiverResource
 ReliabilityQosPolicy
 ReplyPubSubType
@@ -179,6 +181,7 @@ unregistration
 untaken
 untyped
 UserAllocatedSequence
+wakeup
 wdata
 WLPListener
 xml

docs/fastdds/dds_layer/core/waitsets/waitsets.rst

@@ -11,22 +11,27 @@ to notify communication status changes (including arrival of data) to the applic
 
 This mechanism is wait-based. Its general use pattern is as follows:
 
-* The application indicates which relevant information it wants to get, by means of Condition
-  objects (GuardCondition, StatusCondition, or ReadCondition) and attaching them to a wait-set.
-* It then waits on that wait-set until the trigger value of one or several Condition objects become
-  true.
-* It then uses the result of the wait (i.e., the list of Condition objects with
+* The application indicates which relevant information it wants to get, by means of :ref:`api_pim_condition`
+  objects (:ref:`api_pim_guardcondition`, :ref:`api_pim_statuscondition`, or :ref:`api_pim_readcondition`)
+  and attaching them to a :ref:`api_pim_waitset` via the |WaitSet::attach_condition-api| call.
+* It then waits on that :ref:`api_pim_waitset` via the |WaitSet::wait-api|
+  call until the trigger value of one or several :ref:`api_pim_condition` objects become true.
+* It then uses the result of the |WaitSet::wait-api| (i.e., the list of :ref:`api_pim_condition` objects with
   trigger_value == true) to actually get the information by calling:
 
-  * get_status_changes and then get_<communication_status> on the relevant Entity, when the
-    condition is a StatusCondition and the status changes refer to plain communication status.
-  * get_status_changes and then get_datareaders on the relevant Subscriber, when the condition is a
+  * |Entity::get_status_changes-api|, then checking if any of the changes is relevant using the |StatusMask::is_active-api|
+    method on the result and finally calling get_<communication_status> on the relevant Entity, when the condition is a StatusCondition and the status changes refer to plain communication status.
+    Refer to :ref:`dds_layer_core_status` for additional information on the different statuses that can be queried.
+  * |Entity::get_status_changes-api| and then |Subscriber::get_datareaders-api| on the relevant Subscriber, when the condition is a
     StatusCondition and the status changes refer to DataOnReaders.
-  * get_status_changes and then read/take on the relevant DataReader, when the condition is a
+  * |Entity::get_status_changes-api| and then |DataReader::read-api|/|DataReader::take-api| on the relevant DataReader, when the condition is a
     StatusCondition and the status changes refer to DataAvailable.
-  * Directly read_w_condition/take_w_condition on the DataReader with the Condition as a parameter,
+  * Directly |DataReader::read_w_condition-api|/|DataReader::take_w_condition-api| on the DataReader with the :ref:`api_pim_condition` as a parameter,
     when it is a ReadCondition
 
+* When a Condition is no longer relevant it can be detached from a :ref:`api_pim_waitset` via the
+  |WaitSet::detach_condition-api| call.
+
 The first step is usually done in an initialization phase, while the others are put in the
 application main loop.
 
@@ -36,22 +41,22 @@ application main loop.
    :end-before: //!
    :dedent: 4
 
-Calling the wait operation on the wait-set will block the calling thread if the trigger value of
-all the conditions attached to it are false.
-The thread will wake up, and the wait operation will return OK, whenever the trigger value of any
+Calling the |WaitSet::wait-api| operation on the :ref:`api_pim_waitset` will block the calling thread
+if the trigger value of all the conditions attached to it are false.
+The thread will wake up, and the |WaitSet::wait-api| operation will return RETCODE_OK, whenever the trigger value of any
 of the attached conditions becomes true.
 
 GuardCondition
 --------------
 A condition for which the trigger value is completely controlled by the application via its
-set_trigger_value operation.
+|GuardCondition::set_trigger_value-api| operation.
 
 StatusCondition
 ---------------
 A condition that triggers whenever there are changes on the communication statuses of an Entity.
 
-The sensitivity of the StatusCondition to a particular communication status is controlled by the
-list of enabled_statuses set on the condition by means of the set_enabled_statuses operation.
+The sensitivity of the :ref:`api_pim_statuscondition` to a particular communication status is controlled by the
+list of enabled_statuses set on the condition by means of the |StatusCondition::set_enabled_statuses-api| operation.
 
 ReadCondition
 -------------
@@ -65,12 +70,14 @@ For example, if all samples are taken, any ReadCondition associated with the Dat
 triggered before, will see their trigger value changed to false.
 Note that this does not guarantee that WaitSet objects that were separately attached to those
 conditions will not be woken up.
-Once we have trigger_value == true on a condition, it may wake up the attached wait-set.
-The condition transitioning to trigger_value == false does not necessarily ‘unwakeup’ the wait-set,
+Once we have trigger_value == true on a condition, it may wake up the attached :ref:`api_pim_waitset`.
+The condition transitioning to trigger_value == false does not necessarily ‘unwakeup’ the :ref:`api_pim_waitset`,
 as ‘unwakening’ may not be possible in general.
-The consequence is that an application blocked on a wait-set may return from the wait with a list
+The consequence is that an application blocked on a :ref:`api_pim_waitset` may return from the wait with a list
 of conditions, some of which are no longer triggered.
-This is unavoidable if multiple threads are concurrently waiting on separate wait-set objects and
+This also may be the consequence of user actions.
+A user manually calling |GuardCondition::set_trigger_value-api| could potentially trigger the same behavior.
+This is unavoidable if multiple threads are concurrently waiting on separate :ref:`api_pim_waitset` objects and
 taking data associated with the same DataReader entity.
 
 To elaborate further, consider the following example:
@@ -82,3 +89,4 @@ However, if the same ReadCondition had a sample_state_mask = {READ, NOT_READ}, t
 trigger_value would only become false once all the newly-arrived samples are taken (it is not
 sufficient to read them as that would only change the SampleState to READ which overlaps the mask
 on the ReadCondition).
+

docs/spelling_wordlist.txt

@@ -171,6 +171,7 @@ reconnection
 redistributable
 replier
 repos
+RETCODE_OK
 retransmission
 roadmap
 rosbag