Function rmw_wait

Function Documentation

rmw_ret_t rmw_wait(rmw_subscriptions_t *subscriptions, rmw_guard_conditions_t *guard_conditions, rmw_services_t *services, rmw_clients_t *clients, rmw_events_t *events, rmw_wait_set_t *wait_set, const rmw_time_t *wait_timeout)

Waits on sets of different entities and returns when one is ready.

This function adds middleware-specific conditions to the wait set and waits until one or more become ready, or until the timeout is reached.

Arrays contain type-erased, middleware-specific conditions associated with waitable entities, which this function casts and adds to the wait set. NULL entries in arrays prior to wait are considered invalid. When the wait is over, entries in each array that correspond to conditions that were not triggered are set to NULL.

Remark

Elapsed time should be measured using a monotonic clock, though rmw implementations could use a different one. Timeout granularity is thus bound to that of the clock used by the underlying implementation, and to the platform-specific APIs used to sleep and/or wait.

Remark

The amount of time this function actually waits may be either above or below the specified timeout.

Attribute

Adherence

Allocates Memory

Maybe [1]

Thread-Safe

No

Uses Atomics

Maybe [1]

Lock-Free

Maybe [1]

[1] rmw implementation defined, check the implementation documentation

Remark

Arrays’ memory management is external to this function.

Thread-safety

To wait is a reentrant procedure, but:

  • It is not safe to use the same wait set to wait in two or more threads concurrently.

  • It is not safe to wait for the same entity using different wait sets in two or more threads concurrently.

  • Access to the given timeout is read-only but it is not synchronized. Concurrent wait_timeout reads are safe, but concurrent reads and writes are not.

Parameters:

  • subscriptions – [inout] Array of subscriptions to wait on. Can be NULL if there are no subscriptions to wait on.

  • guard_conditions – [inout] Array of guard conditions to wait on Can be NULL if there are no guard conditions to wait on.

  • services – [inout] Array of services to wait on. Can be NULL if there are no services to wait on.

  • clients – [inout] Array of clients to wait on. Can be NULL if there are no clients to wait on.

  • events – [inout] Array of events to wait on. Can be NULL if there are no events to wait on.

  • wait_set – [in] Wait set to use for waiting.

  • wait_timeout – [in] If NULL, block indefinitely until an entity becomes ready. If zero, do not block — check only for immediately available entities. Else, this represents the maximum amount of time to wait for an entity to become ready.

Pre:

Given wait_set must be a valid wait set, as returned by rmw_create_wait_set().

Pre:

All given entities must be associated with nodes that, in turn, were registered with the same context the given wait_set was registered with on creation.

Returns:

RMW_RET_OK if successful, or

Returns:

RMW_RET_TIMEOUT if wait timed out, or

Returns:

RMW_RET_INVALID_ARGUMENT if wait_set is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if an array entry is NULL, or

Returns:

RMW_RET_INCORRECT_RMW_IMPLEMENTATION if the wait_set implementation identifier does not match this implementation, or

Returns:

RMW_RET_ERROR if an unspecified error occurs.