<<interface>> <<cert>> Allows an application to wait until one or more of the attached DDSCondition objects has a trigger_value of DDS_BOOLEAN_TRUE or else until the timeout expires. More...

#include <dds_cpp_infrastructure.hxx>

Public Member Functions
DDS_ReturnCode_t	wait (DDSConditionSeq &active_conditions, const DDS_Duration_t &timeout)
	<<cert>> Allows an application thread to wait for the occurrence of certain conditions.
DDS_ReturnCode_t	attach_condition (DDSCondition *cond)
	<<cert>> Attaches a DDSCondition to the DDSWaitSet.
DDS_ReturnCode_t	detach_condition (DDSCondition *cond)
	Detaches a DDSCondition from the DDSWaitSet.
DDS_ReturnCode_t	get_conditions (DDSConditionSeq &attached_conditions)
	<<cert>> Retrieves the list of attached DDSCondition (s).

Detailed Description

<<interface>> <<cert>> Allows an application to wait until one or more of the attached DDSCondition objects has a trigger_value of DDS_BOOLEAN_TRUE or else until the timeout expires.

Usage

DDSCondition (s) (in conjunction with wait-sets) provide an alternative mechanism to allow the middleware to communicate communication status changes (including arrival of data) to the application.

This mechanism is wait-based. Its general use pattern is as follows:

The application indicates which relevant information it wants to get by creating DDSCondition objects (DDSStatusCondition) and attaching them to a DDSWaitSet.

It then waits on that DDSWaitSet until the trigger_value of one or several DDSCondition objects become DDS_BOOLEAN_TRUE.

It then uses the result of the wait (i.e., active_conditions, the list of DDSCondition objects with trigger_value == DDS_BOOLEAN_TRUE) to actually get the information:
- by calling DDSEntity::get_status_changes and then get_<communication_status>() on the relevant DDSEntity, if the condition is a DDSStatusCondition and the status changes, refer to plain communication status;
- by calling DDSEntity::get_status_changes and then FooDataReader::read() or FooDataReader::take on the relevant DDSDataReader, if the condition is a DDSStatusCondition and the status changes refers to DDS_DATA_AVAILABLE_STATUS;

Usually the first step is done in an initialization phase, while the others are put in the application main loop.

As there is no extra information passed from the middleware to the application when a wait returns (only the list of triggered DDSCondition objects), DDSCondition objects are meant to embed all that is needed to react properly when enabled. In particular, DDSEntity-related conditions are related to exactly one DDSEntity and cannot be shared.

The result of a DDSWaitSet::wait operation depends on the state of the DDSWaitSet, which in turn depends on whether at least one attached DDSCondition has a trigger_value of DDS_BOOLEAN_TRUE. If the wait operation is called on DDSWaitSet with state BLOCKED, it will block the calling thread. If wait is called on a DDSWaitSet with state UNBLOCKED, it will return immediately. In addition, when the DDSWaitSet transitions from BLOCKED to UNBLOCKED it wakes up any threads that had called wait on it.

A key aspect of the DDSCondition/DDSWaitSet mechanism is the setting of the trigger_value of each DDSCondition.

Trigger State of a ::DDSStatusCondition

The trigger_value of a DDSStatusCondition is the boolean OR of the ChangedStatusFlag of all the communication statuses (see Status Kinds) to which it is sensitive. That is, trigger_value == DDS_BOOLEAN_FALSE only if all the values of the ChangedStatusFlags are DDS_BOOLEAN_FALSE.

The sensitivity of the DDSStatusCondition to a particular communication status is controlled by the list of enabled_statuses set on the condition by means of the DDSStatusCondition::set_enabled_statuses operation.

Trigger State of a ::DDSGuardCondition

The trigger_value of a DDSGuardCondition is completely controlled by the application via the operation DDSGuardCondition::set_trigger_value.

See also:: Status Kinds; DDSStatusCondition, DDSGuardCondition; DDSListener

Member Function Documentation

DDS_ReturnCode_t DDSWaitSet::wait	(	DDSConditionSeq &	active_conditions,
		const DDS_Duration_t &	timeout
	)

<<cert>> Allows an application thread to wait for the occurrence of certain conditions.

If none of the conditions attached to the DDSWaitSet have a trigger_value of DDS_BOOLEAN_TRUE, the wait operation will block suspending the calling thread.

The result of the wait operation is the list of all the attached conditions that have a trigger_value of DDS_BOOLEAN_TRUE (i.e., the conditions that unblocked the wait).

Note: The resolution of the timeout period is constrained by the resolution of the system clock.

The wait operation takes a timeout argument that specifies the maximum duration for the wait. If this duration is exceeded and none of the attached DDSCondition objects is DDS_BOOLEAN_TRUE, wait will return with the return code DDS_RETCODE_TIMEOUT. In this case, the resulting list of conditions will be empty.

Note: The resolution of the timeout period is constrained by the resolution of the system clock.

DDS_RETCODE_TIMEOUT will not be returned when the timeout duration is exceeded if attached DDSCondition objects are DDS_BOOLEAN_TRUE, or in the case of a DDSWaitSet waiting for more than one trigger event, if one or more trigger events have occurred.

It is not allowable for for more than one application thread to be waiting on the same DDSWaitSet. If the wait operation is invoked on a DDSWaitSet that already has a thread blocking on it, the operation will return immediately with the value DDS_RETCODE_PRECONDITION_NOT_MET.

Parameters:

active_conditions <<inout>> a valid non-NULL DDSConditionSeq object. Note that RTI Connext DDS Micro will not allocate a new object if active_conditions is NULL; the method will return DDS_RETCODE_PRECONDITION_NOT_MET.

Parameters:

timeout <<in>> a wait timeout

Returns:: One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_TIMEOUT.

DDS_ReturnCode_t DDSWaitSet::attach_condition ( DDSCondition * cond )

<<cert>> Attaches a DDSCondition to the DDSWaitSet.

It is possible to attach a DDSCondition on a DDSWaitSet that is currently being waited upon (via the wait operation). In this case, if the DDSCondition has a trigger_value of DDS_BOOLEAN_TRUE, then attaching the condition will unblock the DDSWaitSet.

Parameters:

cond	<<in>> Contition to be attached.

Returns:: One of the Standard Return Codes, or DDS_RETCODE_OUT_OF_RESOURCES.

DDS_ReturnCode_t DDSWaitSet::detach_condition ( DDSCondition * cond )

Detaches a DDSCondition from the DDSWaitSet.

If the DDSCondition was not attached to the DDSWaitSet the operation will return DDS_RETCODE_BAD_PARAMETER.

Parameters:

cond	<<in>> Condition to be detached.

Returns:: One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

DDS_ReturnCode_t DDSWaitSet::get_conditions ( DDSConditionSeq & attached_conditions )

<<cert>> Retrieves the list of attached DDSCondition (s).

Parameters:

attached_conditions <<inout>> a DDSConditionSeq object where the list of attached conditions will be returned

Returns:: One of the Standard Return Codes, or DDS_RETCODE_OUT_OF_RESOURCES.

Public Member Functions

Detailed Description

Usage

Trigger State of a ::DDSStatusCondition

Trigger State of a ::DDSGuardCondition

Member Function Documentation