WaitSets and Conditions

group waitset

Typedefs

typedef intptr_t dds_attach_t

Waitset attachment argument.

Every entity that is attached to the waitset can be accompanied by such an attachment argument. When the waitset wait is unblocked because of an entity that triggered, then the returning array will be populated with these attachment arguments that are related to the triggered entity.

Functions

dds_entity_t dds_create_waitset(dds_entity_t owner)

Create a waitset and allocate the resources required

A WaitSet object allows an application to wait until one or more of the conditions of the attached entities evaluates to TRUE or until the timeout expires.

Parameters

  • owner – [in] Domain participant which the WaitSet contains.

Return values

  • >=0 – A valid waitset handle.

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A valid waitset handle or an error code.

dds_return_t dds_waitset_get_entities(dds_entity_t waitset, dds_entity_t *entities, size_t size)

Acquire previously attached entities.

This functions takes a pre-allocated list to put the entities in and will return the number of found entities. It is possible that the given size of the list is not the same as the number of found entities. If less entities are found, then the last few entries in the list are untouched. When more entities are found, then only ‘size’ number of entries are inserted into the list, but still the complete count of the found entities is returned. Which entities are returned in the latter case is undefined.

Parameters

  • waitset – [in] Waitset from which to get its attached entities.

  • entities – [out] Pre-allocated array to contain the found entities.

  • size – [in] Size of the pre-allocated entities’ list.

Return values

  • >=0 – Number of children found (can be larger than ‘size’).

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_BAD_PARAMETER – The entities parameter is NULL, while a size is provided.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The waitset has already been deleted.

Returns

A dds_return_t with the number of children or an error code.

dds_return_t dds_waitset_attach(dds_entity_t waitset, dds_entity_t entity, dds_attach_t x)

This operation attaches an Entity to the WaitSet.

This operation attaches an Entity to the WaitSet. The dds_waitset_wait() will block when none of the attached entities are triggered. ‘Triggered’ (dds_triggered()) doesn’t mean the same for every entity:

  • Reader/Writer/Publisher/Subscriber/Topic/Participant

    • These are triggered when their status changed.

  • WaitSet

    • Triggered when trigger value was set to true by the application. It stays triggered until application sets the trigger value to false (dds_waitset_set_trigger()). This can be used to wake up an waitset for different reasons (f.i. termination) than the ‘normal’ status change (like new data).

  • ReadCondition/QueryCondition

    • Triggered when data is available on the related Reader that matches the Condition.

Multiple entities can be attached to a single waitset. A particular entity can be attached to multiple waitsets. However, a particular entity can not be attached to a particular waitset multiple times.

Parameters

  • waitset – [in] The waitset to attach the given entity to.

  • entity – [in] The entity to attach.

  • x – [in] Blob that will be supplied when the waitset wait is triggered by the given entity.

Return values

  • DDS_RETCODE_OK – Entity attached.

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_BAD_PARAMETER – The given waitset or entity are not valid.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The waitset has already been deleted.

  • DDS_RETCODE_PRECONDITION_NOT_MET – The entity was already attached.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_waitset_detach(dds_entity_t waitset, dds_entity_t entity)

This operation detaches an Entity from the WaitSet.

Parameters

  • waitset – [in] The waitset to detach the given entity from.

  • entity – [in] The entity to detach.

Return values

  • DDS_RETCODE_OK – Entity detached.

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_BAD_PARAMETER – The given waitset or entity are not valid.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The waitset has already been deleted.

  • DDS_RETCODE_PRECONDITION_NOT_MET – The entity is not attached.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_waitset_set_trigger(dds_entity_t waitset, bool trigger)

Sets the trigger_value associated with a waitset.

When the waitset is attached to itself and the trigger value is set to ‘true’, then the waitset will wake up just like with an other status change of the attached entities.

This can be used to forcefully wake up a waitset, for instance when the application wants to shut down. So, when the trigger value is true, the waitset will wake up or not wait at all.

The trigger value will remain true until the application sets it false again deliberately.

Parameters

  • waitset – [in] The waitset to set the trigger value on.

  • trigger – [in] The trigger value to set.

Return values

  • DDS_RETCODE_OK – Trigger value set.

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_BAD_PARAMETER – The given waitset is not valid.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The waitset has already been deleted.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_waitset_wait(dds_entity_t waitset, dds_attach_t *xs, size_t nxs, dds_duration_t reltimeout)

This operation allows an application thread to wait for the a status change or other trigger on (one of) the entities that are attached to the WaitSet.

The dds_waitset_wait() operation blocks until the some of the attached entities have triggered or “reltimeout” has elapsed. ‘Triggered’ (dds_triggered()) doesn’t mean the same for every entity:

  • Reader/Writer/Publisher/Subscriber/Topic/Participant

    • These are triggered when their status changed.

  • WaitSet

    • Triggered when trigger value was set to true by the application. It stays triggered until application sets the trigger value to false (dds_waitset_set_trigger()). This can be used to wake up an waitset for different reasons (f.i. termination) than the ‘normal’ status change (like new data).

  • ReadCondition/QueryCondition

    • Triggered when data is available on the related Reader that matches the Condition.

This functions takes a pre-allocated list to put the “xs” blobs in (that were provided during the attach of the related entities) and will return the number of triggered entities. It is possible that the given size of the list is not the same as the number of triggered entities. If less entities were triggered, then the last few entries in the list are untouched. When more entities are triggered, then only ‘size’ number of entries are inserted into the list, but still the complete count of the triggered entities is returned. Which “xs” blobs are returned in the latter case is undefined.

In case of a time out, the return value is 0.

Deleting the waitset while the application is blocked results in an error code (i.e. < 0) returned by “wait”.

Multiple threads may block on a single waitset at the same time; the calls are entirely independent.

An empty waitset never triggers (i.e., dds_waitset_wait on an empty waitset is essentially equivalent to a sleep).

The “dds_waitset_wait_until” operation is the same as the “dds_waitset_wait” except that it takes an absolute timeout.

Parameters

  • waitset – [in] The waitset to set the trigger value on.

  • xs – [out] Pre-allocated list to store the ‘blobs’ that were provided during the attach of the triggered entities.

  • nxs – [in] The size of the pre-allocated blobs list.

  • reltimeout – [in] Relative timeout

Return values

  • >0 – Number of entities triggered.

  • 0 – Time out (no entities were triggered).

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_BAD_PARAMETER – The given waitset is not valid.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The waitset has already been deleted.

Returns

A dds_return_t with the number of entities triggered or an error code

dds_return_t dds_waitset_wait_until(dds_entity_t waitset, dds_attach_t *xs, size_t nxs, dds_time_t abstimeout)

This operation allows an application thread to wait for the a status change or other trigger on (one of) the entities that are attached to the WaitSet.

The dds_waitset_wait() operation blocks until the some of the attached entities have triggered or “abstimeout” has been reached. ‘Triggered’ (dds_triggered()) doesn’t mean the same for every entity:

  • Reader/Writer/Publisher/Subscriber/Topic/Participant

    • These are triggered when their status changed.

  • WaitSet

    • Triggered when trigger value was set to true by the application. It stays triggered until application sets the trigger value to false (dds_waitset_set_trigger()). This can be used to wake up an waitset for different reasons (f.i. termination) than the ‘normal’ status change (like new data).

  • ReadCondition/QueryCondition

    • Triggered when data is available on the related Reader that matches the Condition.

This functions takes a pre-allocated list to put the “xs” blobs in (that were provided during the attach of the related entities) and will return the number of triggered entities. It is possible that the given size of the list is not the same as the number of triggered entities. If less entities were triggered, then the last few entries in the list are untouched. When more entities are triggered, then only ‘size’ number of entries are inserted into the list, but still the complete count of the triggered entities is returned. Which “xs” blobs are returned in the latter case is undefined.

In case of a time out, the return value is 0.

Deleting the waitset while the application is blocked results in an error code (i.e. < 0) returned by “wait”.

Multiple threads may block on a single waitset at the same time; the calls are entirely independent.

An empty waitset never triggers (i.e., dds_waitset_wait on an empty waitset is essentially equivalent to a sleep).

The “dds_waitset_wait” operation is the same as the “dds_waitset_wait_until” except that it takes an relative timeout.

The “dds_waitset_wait” operation is the same as the “dds_wait” except that it takes an absolute timeout.

Parameters

  • waitset – [in] The waitset to set the trigger value on.

  • xs – [out] Pre-allocated list to store the ‘blobs’ that were provided during the attach of the triggered entities.

  • nxs – [in] The size of the pre-allocated blobs list.

  • abstimeout – [in] Absolute timeout

Return values

  • >0 – Number of entities triggered.

  • 0 – Time out (no entities were triggered).

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_BAD_PARAMETER – The given waitset is not valid.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The waitset has already been deleted.

Returns

A dds_return_t with the number of entities triggered or an error code.

Conditions

group condition

Conditions allow you to express conditional interest in samples, to be used in read/take operations or attach to Waitsets.

Functions

dds_return_t dds_get_mask(dds_entity_t condition, uint32_t *mask)

Get the mask of a condition.

This operation returns the mask that was used to create the given condition.

Parameters

  • condition – [in] Read or Query condition that has a mask.

  • mask – [out] Where to store the mask of the condition.

Return values

  • DDS_RETCODE_OK – Success (given mask is set).

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_BAD_PARAMETER – The mask arg is NULL.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

group reading_masks

Masks for read condition, read, take: there is only one mask here, which combines the sample, view and instance states.

Defines

DDS_READ_SAMPLE_STATE 1u

Samples that were already returned once by a read/take operation.

DDS_NOT_READ_SAMPLE_STATE 2u

Samples that have not been returned by a read/take operation yet.

DDS_ANY_SAMPLE_STATE (1u | 2u)

Samples DDS_READ_SAMPLE_STATE or DDS_NOT_READ_SAMPLE_STATE.

DDS_NEW_VIEW_STATE 4u

Samples that belong to a new instance (unique key value)

DDS_NOT_NEW_VIEW_STATE 8u

Samples that belong to an existing instance (previously received key value)

DDS_ANY_VIEW_STATE (4u | 8u)

Samples DDS_NEW_VIEW_STATE or DDS_NOT_NEW_VIEW_STATE.

DDS_ALIVE_INSTANCE_STATE 16u

Samples that belong to a write.

DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE 32u

Samples that belong to a (write)dispose.

DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE 64u

Samples that belong a writer that is gone.

DDS_ANY_INSTANCE_STATE (16u | 32u | 64u)

Samples DDS_ALIVE_INSTANCE_STATE, DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE or DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE.

DDS_ANY_STATE (DDS_ANY_SAMPLE_STATE | DDS_ANY_VIEW_STATE | DDS_ANY_INSTANCE_STATE)

Any and all samples Equivalen to DDS_ANY_SAMPLE_STATE | DDS_ANY_VIEW_STATE | DDS_ANY_INSTANCE_STATE.

ReadCondition

group readcondition

Functions

dds_entity_t dds_create_readcondition(dds_entity_t reader, uint32_t mask)

Creates a readcondition associated to the given reader.

The readcondition allows specifying which samples are of interest in a data reader’s history, by means of a mask. The mask is or’d with the flags that are dds_sample_state_t, dds_view_state_t and dds_instance_state_t.

Based on the mask value set, the readcondition gets triggered when data is available on the reader.

Waitsets allow waiting for an event on some of any set of entities. This means that the readcondition can be used to wake up a waitset when data is in the reader history with states that matches the given mask.

Note

The parent reader and every of its associated conditions (whether they are readconditions or queryconditions) share the same resources. This means that one of these entities reads or takes data, the states of the data will change for other entities automatically. For instance, if one reads a sample, then the sample state will become ‘read’ for all associated reader/conditions. Or if one takes a sample, then it’s not available to any other associated reader/condition.

Parameters

  • reader – [in] Reader to associate the condition to.

  • mask – [in] Interest (dds_sample_state_t|dds_view_state_t|dds_instance_state_t).

Return values

  • >0 – A valid condition handle

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A valid condition handle or an error code.

QueryCondition

group querycondition

Typedefs

typedef bool (*dds_querycondition_filter_fn)(const void *sample)

Function signature for a querycondition filter.

Functions

dds_entity_t dds_create_querycondition(dds_entity_t reader, uint32_t mask, dds_querycondition_filter_fn filter)

Creates a queryondition associated to the given reader.

The queryondition allows specifying which samples are of interest in a data reader’s history, by means of a mask and a filter. The mask is or’d with the flags that are dds_sample_state_t, dds_view_state_t and dds_instance_state_t.

Based on the mask value set and data that matches the filter, the querycondition gets triggered when data is available on the reader.

Waitsets allow waiting for an event on some of any set of entities. This means that the querycondition can be used to wake up a waitset when data is in the reader history with states that matches the given mask and filter.

Note

The parent reader and every of its associated conditions (whether they are readconditions or queryconditions) share the same resources. This means that one of these entities reads or takes data, the states of the data will change for other entities automatically. For instance, if one reads a sample, then the sample state will become ‘read’ for all associated reader/conditions. Or if one takes a sample, then it’s not available to any other associated reader/condition.

Parameters

  • reader – [in] Reader to associate the condition to.

  • mask – [in] Interest (dds_sample_state_t|dds_view_state_t|dds_instance_state_t).

  • filter – [in] Callback that the application can use to filter specific samples.

Return values

  • >=0 – A valid condition handle.

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A valid condition handle or an error code

GuardCondition

group guardcondition

Functions

dds_entity_t dds_create_guardcondition(dds_entity_t owner)

Creates a guardcondition.

Waitsets allow waiting for an event on some of any set of entities. This means that the guardcondition can be used to wake up a waitset when data is in the reader history with states that matches the given mask.

Parameters

  • owner – [in] Participant on which to create the guardcondition.

Return values

  • >0 – A valid condition handle

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A valid condition handle or an error code.

dds_return_t dds_set_guardcondition(dds_entity_t guardcond, bool triggered)

Sets the trigger status of a guardcondition.

Parameters

  • guardcond – [in] Guard condition to set the trigger status of.

  • triggered – [in] The triggered status to set.

Return values

  • DDS_RETCODE_OK – Operation successful

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

dds_return_t dds_read_guardcondition(dds_entity_t guardcond, bool *triggered)

Reads the trigger status of a guardcondition.

Parameters

  • guardcond – [in] Guard condition to read the trigger status of.

  • triggered – [out] The triggered status read from the guard condition.

Return values

  • DDS_RETCODE_OK – Operation successful

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

dds_return_t dds_take_guardcondition(dds_entity_t guardcond, bool *triggered)

Reads and resets the trigger status of a guardcondition.

Parameters

  • guardcond – [in] Guard condition to read and reset the trigger status of.

  • triggered – [out] The triggered status read from the guard condition.

Return values

  • DDS_RETCODE_OK – Operation successful

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.