Function rcl_subscription_set_on_new_message_callback

Function Documentation

rcl_ret_t rcl_subscription_set_on_new_message_callback(const rcl_subscription_t *subscription, rcl_event_callback_t callback, const void *user_data)

Set the on new message callback function for the subscription.

This API sets the callback function to be called whenever the subscription is notified about a new message.

Since this callback is called from the middleware, you should aim to make it fast and not blocking. This callback is intended to implement an event driven executor and not process data directly.

See also

rmw_subscription_set_on_new_message_callback for details about this function.

Doing work in this callback can cause delays, deadlocks, or latency due to cross thread waiting as this process runs on middleware managed threads and is meant only to notify the executor that new data is available in the middleware queue.

Attribute

Adherence

Allocates Memory

No

Thread-Safe

Yes

Uses Atomics

Maybe [1]

Lock-Free

Maybe [1]

[1] rmw implementation defined

Parameters:

  • subscription – [in] The subscription on which to set the callback

  • callback – [in] The callback to be called when new messages arrive, may be NULL

  • user_data – [in] Given to the callback when called later, may be NULL

Returns:

RCL_RET_OK if successful, or

Returns:

RCL_RET_INVALID_ARGUMENT if subscription is NULL, or

Returns:

RCL_RET_UNSUPPORTED if the API is not supported by the middleware