Function dds_waitset_wait

Function Documentation

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