Conditions and WaitSets

DDS_Condition and DDS_WaitSet and related items. More...

Typedefs
typedef struct DDS_ConditionImpl	DDS_Condition
	<<interface>> <<cert>> Root class for all the conditions that may be attached to a DDS_WaitSet.
typedef struct DDS_GuardConditionImpl	DDS_GuardCondition
	<<interface>> <<cert>> A specific DDS_Condition whose trigger_value is completely under the control of the application.
typedef struct DDS_StatusConditionImpl	DDS_StatusCondition
	<<interface>> <<cert>> A specific DDS_Condition that is associated with each DDS_Entity.
typedef struct DDS_WaitSetImpl	DDS_WaitSet
	<<interface>> <<cert>> Allows an application to wait until one or more of the attached DDS_Condition objects has a trigger_value of DDS_BOOLEAN_TRUE or else until the timeout expires.

Functions
DDS_Boolean	DDS_Condition_get_trigger_value (DDS_Condition *self)
	<<cert>> Retrieve the trigger_value.
DDS_Condition *	DDS_GuardCondition_as_condition (DDS_GuardCondition *guard_cond)
	<<cert>> Access a DDS_GuardCondition's supertype instance.
DDS_GuardCondition *	DDS_GuardCondition_new (void)
	<<cert>> No argument constructor.
DDS_ReturnCode_t	DDS_GuardCondition_delete (DDS_GuardCondition *self)
	Destructor.
DDS_ReturnCode_t	DDS_GuardCondition_set_trigger_value (DDS_GuardCondition *self, DDS_Boolean value)
	<<cert>> Set the guard condition trigger value.
DDS_Condition *	DDS_StatusCondition_as_condition (DDS_StatusCondition *statusCondition)
	<<cert>> Access a DDS_StatusCondition's supertype instance.
DDS_StatusMask	DDS_StatusCondition_get_enabled_statuses (DDS_StatusCondition *self)
	<<cert>> Get the list of statuses enabled on an DDS_Entity.
DDS_ReturnCode_t	DDS_StatusCondition_set_enabled_statuses (DDS_StatusCondition *self, DDS_StatusMask mask)
	<<cert>> This operation defines the list of communication statuses that determine the trigger_value of the DDS_StatusCondition.
DDS_Entity *	DDS_StatusCondition_get_entity (DDS_StatusCondition *self)
	<<cert>> Get the DDS_Entity associated with the DDS_StatusCondition.
DDS_WaitSet *	DDS_WaitSet_new (void)
	<<cert>> Create a new, empty waitset.
DDS_ReturnCode_t	DDS_WaitSet_wait (DDS_WaitSet *self, struct DDS_ConditionSeq *active_conditions, const struct DDS_Duration_t *timeout)
	<<cert>> Allows an application thread to wait for the occurrence of certain conditions.
DDS_ReturnCode_t	DDS_WaitSet_attach_condition (DDS_WaitSet *self, DDS_Condition *cond)
	<<cert>> Attaches a DDS_Condition to the DDS_WaitSet.
DDS_ReturnCode_t	DDS_WaitSet_delete (DDS_WaitSet *self)
	Destructor.
DDS_ReturnCode_t	DDS_WaitSet_detach_condition (DDS_WaitSet *self, DDS_Condition *cond)
	Detaches a DDS_Condition from the DDS_WaitSet.
DDS_ReturnCode_t	DDS_WaitSet_get_conditions (DDS_WaitSet *self, struct DDS_ConditionSeq *attached_conditions)
	<<cert>> Retrieves the list of attached DDS_Condition (s).

---

Detailed Description

DDS_Condition and DDS_WaitSet and related items.

---

Typedef Documentation

typedef struct DDS_ConditionImpl DDS_Condition

<<interface>> <<cert>> Root class for all the conditions that may be attached to a DDS_WaitSet.

This basic class is specialised in two classes:

DDS_GuardCondition and DDS_StatusCondition.

A DDS_Condition has a trigger_value that can be DDS_BOOLEAN_TRUE or DDS_BOOLEAN_FALSE and is set automatically by RTI Connext Micro.

See also:

DDS_WaitSet

typedef struct DDS_GuardConditionImpl DDS_GuardCondition

<<interface>> <<cert>> A specific DDS_Condition whose trigger_value is completely under the control of the application.

The DDS_GuardCondition provides a way for an application to manually wake up a DDS_WaitSet. This is accomplished by attaching the DDS_GuardCondition to the DDS_WaitSet and then setting the trigger_value by means of the DDS_GuardCondition_set_trigger_value operation.

See also:

DDS_WaitSet

typedef struct DDS_StatusConditionImpl DDS_StatusCondition

<<interface>> <<cert>> A specific DDS_Condition that is associated with each DDS_Entity.

The trigger_value of the DDS_StatusCondition depends on the communication status of that entity (e.g., arrival of data, loss of information, etc.), 'filtered' by the set of enabled_statuses on the DDS_StatusCondition.

See also:

Status Kinds

DDS_WaitSet, DDS_Condition

DDS_Listener

typedef struct DDS_WaitSetImpl DDS_WaitSet

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

Usage

DDS_Condition (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 DDS_Condition objects (DDS_StatusCondition) and attaching them to a DDS_WaitSet.

• It then waits on that DDS_WaitSet until the trigger_value of one or several DDS_Condition objects become DDS_BOOLEAN_TRUE.

• It then uses the result of the wait (i.e., active_conditions, the list of DDS_Condition objects with trigger_value == DDS_BOOLEAN_TRUE) to actually get the information:

  • by calling DDS_Entity_get_status_changes and then get_<communication_status>() on the relevant DDS_Entity, if the condition is a DDS_StatusCondition and the status changes, refer to plain communication status;

  • by calling DDS_Entity_get_status_changes and then FooDataReader_read() or FooDataReader_take on the relevant DDS_DataReader, if the condition is a DDS_StatusCondition 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 DDS_Condition objects), DDS_Condition objects are meant to embed all that is needed to react properly when enabled. In particular, DDS_Entity-related conditions are related to exactly one DDS_Entity and cannot be shared.

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

A key aspect of the DDS_Condition/DDS_WaitSet mechanism is the setting of the trigger_value of each DDS_Condition.

Trigger State of a ::DDS_StatusCondition

The trigger_value of a DDS_StatusCondition 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 DDS_StatusCondition to a particular communication status is controlled by the list of enabled_statuses set on the condition by means of the DDS_StatusCondition_set_enabled_statuses operation.

Trigger State of a ::DDS_GuardCondition

The trigger_value of a DDS_GuardCondition is completely controlled by the application via the operation DDS_GuardCondition_set_trigger_value.

See also:

Status Kinds

DDS_StatusCondition, DDS_GuardCondition

DDS_Listener

---

Function Documentation

DDS_Boolean DDS_Condition_get_trigger_value

(

DDS_Condition *

self

)

<<cert>> Retrieve the trigger_value.

Parameters:

self	<<in>> Cannot be NULL.

Returns:

the trigger value.

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.

DDS_Condition* DDS_GuardCondition_as_condition

(

DDS_GuardCondition *

guard_cond

)

<<cert>> Access a DDS_GuardCondition's supertype instance.

Parameters:

guard_cond

<<in>> Cannot be NULL.

DDS_GuardCondition* DDS_GuardCondition_new

(

void

)

<<cert>> No argument constructor.

Construct a new guard condition on the heap.

Returns:

A new condition with trigger value DDS_BOOLEAN_FALSE, or NULL if a condition could not be allocated.

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.

API Restriction:

This function must only be called after DDS_DomainParticipantFactory_get_instance.

ARINC 653 API Restriction:

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

DDS_ReturnCode_t DDS_GuardCondition_delete

(

DDS_GuardCondition *

self

)

Destructor.

Releases the resources associated with this object.

Deleting a NULL condition is safe and has no effect.

Parameters:

self	<<in>> Cannot be NULL.

DDS_ReturnCode_t DDS_GuardCondition_set_trigger_value	(	DDS_GuardCondition *	self,
		DDS_Boolean	value
	)

<<cert>> Set the guard condition trigger value.

Parameters:

self	<<in>> Cannot be NULL.
value	<<in>> the new trigger value.

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.

DDS_Condition* DDS_StatusCondition_as_condition

(

DDS_StatusCondition *

statusCondition

)

<<cert>> Access a DDS_StatusCondition's supertype instance.

Parameters:

statusCondition

<<in>> Cannot be NULL.

DDS_StatusMask DDS_StatusCondition_get_enabled_statuses

(

DDS_StatusCondition *

self

)

<<cert>> Get the list of statuses enabled on an DDS_Entity.

Parameters:

self	<<in>> Cannot be NULL.

Returns:

list of enabled statuses.

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.

DDS_ReturnCode_t DDS_StatusCondition_set_enabled_statuses	(	DDS_StatusCondition *	self,
		DDS_StatusMask	mask
	)

<<cert>> This operation defines the list of communication statuses that determine the trigger_value of the DDS_StatusCondition.

This operation may change the trigger_value of the DDS_StatusCondition.

DDS_WaitSet objects' behavior depends on the changes of the trigger_value of their attached conditions. Therefore, any DDS_WaitSet to which the DDS_StatusCondition is attached is potentially affected by this operation.

If this function is not invoked, the default list of enabled statuses includes all the statuses.

Parameters:

self	<<in>> Cannot be NULL.
mask	<<in>> the list of enables statuses (see Status Kinds)

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.

DDS_Entity* DDS_StatusCondition_get_entity

(

DDS_StatusCondition *

self

)

<<cert>> Get the DDS_Entity associated with the DDS_StatusCondition.

There is exactly one DDS_Entity associated with each DDS_StatusCondition.

Parameters:

self	<<in>> Cannot be NULL.

Returns:

DDS_Entity associated with the DDS_StatusCondition.

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.

DDS_WaitSet* DDS_WaitSet_new

(

void

)

<<cert>> Create a new, empty waitset.

Create a new waitset. The waitset does not have a factory, so for this reason the waitset is allocated from the heap. A waitset maintains a list of conditions that have been attached with DDS_WaitSet_attach.

Returns:

A new, empty waitset on success 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.

API Restriction:

This function must only be called after DDS_DomainParticipantFactory_get_instance.

ARINC 653 API Restriction:

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

DDS_ReturnCode_t DDS_WaitSet_wait	(	DDS_WaitSet *	self,
		struct DDS_ConditionSeq *	active_conditions,
		const struct 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 DDS_WaitSet 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 DDS_Condition 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 DDS_Condition objects are DDS_BOOLEAN_TRUE, or in the case of a DDS_WaitSet 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 DDS_WaitSet. If the wait operation is invoked on a DDS_WaitSet 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 DDS_ConditionSeq object. Note that RTI Connext Micro will not allocate a new object if active_conditions is NULL; the function will return DDS_RETCODE_PRECONDITION_NOT_MET.
self	<<in>> Cannot be NULL.
timeout	<<in>> a wait timeout

Returns:

One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_TIMEOUT.

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.

DDS_ReturnCode_t DDS_WaitSet_attach_condition	(	DDS_WaitSet *	self,
		DDS_Condition *	cond
	)

<<cert>> Attaches a DDS_Condition to the DDS_WaitSet.

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

Parameters:

self	<<in>> Cannot be NULL.
cond	<<in>> Contition to be attached.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_OUT_OF_RESOURCES.

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.

DDS_ReturnCode_t DDS_WaitSet_delete

(

DDS_WaitSet *

self

)

Destructor.

Releases the resources asociated with this DDS_WaitSet. This function is not thread-safe. Only one thread should be deleting a DDS_WaitSet. If a thread is blocked on a DDS_WaitSet that is being deleted the blocked thread will be unblocked and DDS_WaitSet_wait will return DDS_RETCODE_ALREADY_DELETED.

Freeing a null pointer is safe and does nothing.

Parameters:

self	<<in>> Cannot be NULL.

API Restriction:

This function must only be called after DDS_DomainParticipantFactory_get_instance.

DDS_ReturnCode_t DDS_WaitSet_detach_condition	(	DDS_WaitSet *	self,
		DDS_Condition *	cond
	)

Detaches a DDS_Condition from the DDS_WaitSet.

If the DDS_Condition was not attached to the DDS_WaitSet the operation will return DDS_RETCODE_BAD_PARAMETER.

Parameters:

self	<<in>> Cannot be NULL.
cond	<<in>> Condition to be detached.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

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.

DDS_ReturnCode_t DDS_WaitSet_get_conditions	(	DDS_WaitSet *	self,
		struct DDS_ConditionSeq *	attached_conditions
	)

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

Parameters:

self	<<in>> Cannot be NULL.
attached_conditions	<<inout>> a DDS_ConditionSeq object where the list of attached conditions will be returned

Returns:

One of the Standard Return Codes, or DDS_RETCODE_OUT_OF_RESOURCES.

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.