Function rmw_publish_loaned_message

Function Documentation

rmw_ret_t rmw_publish_loaned_message(const rmw_publisher_t *publisher, void *ros_message, rmw_publisher_allocation_t *allocation)

Publish a loaned ROS message.

Send a previously borrowed ROS message to all subscriptions with matching QoS policies using the given publisher, then return ROS message ownership to the middleware.

If this function fails early due to a logical error, such as an invalid argument, the loaned ROS message will be left unchanged. Otherwise, ownership of the ROS message will be given back to the middleware. It is up to the middleware what will be made of the returned ROS message. It is undefined behavior to use a loaned ROS message after publishing it.

Attribute

Adherence

Allocates Memory

Maybe

Thread-Safe

Yes

Uses Atomics

Maybe [1]

Lock-Free

Maybe [1]

[1] implementation defined, check the implementation documentation.

Runtime behavior

It is implementation defined whether to publish a loaned ROS message is a synchronous or asynchronous, blocking or non-blocking operation. Check the implementation documentation to learn about publish behavior.

Memory allocation

It is implementation defined whether memory will be allocated on publish or not. For instance, implementations that serialize ROS messages to send it over the wire may need to perform additional memory allocations when dealing with unbounded (dynamically-sized) fields. A publisher allocation, if provided, may or may not be used. Check the implementation documentation to learn about memory allocation guarantees when publishing loaned ROS messages with and without publisher allocations.

Thread-safety

Publishers are thread-safe objects, and so are all operations on them except for finalization. Therefore, it is safe to publish using the same publisher concurrently. However, when publishing loaned ROS messages:

  • Ownership of the loaned ROS message is given back to the middleware. This transfer is not synchronized, and thus it is not safe to publish the same loaned ROS message concurrently.

  • Access to the publisher allocation is not synchronized, unless specifically stated otherwise by the implementation. Thus, it is generally not safe to read or write allocation while rmw_publish() uses it. Check the implementation documentation to learn about publisher allocations’ thread-safety.

Parameters:

  • publisher – [in] Publisher to be used to send message.

  • ros_message – [in] Loaned type erased ROS message to be sent.

  • allocation – [in] Pre-allocated memory to be used. May be NULL.

Pre:

Given publisher must be a valid publisher, as returned by rmw_create_publisher().

Pre:

Given ros_message must be a valid message, borrowed from the same publisher using rmw_borrow_loaned_message().

Pre:

If not NULL, given allocation must be a valid publisher allocation, initialized with rmw_publisher_allocation_init() with a message type support that matches the one registered with publisher on creation.

Returns:

RMW_RET_OK if successful, or

Returns:

RMW_RET_INVALID_ARGUMENT if publisher is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if ros_message is NULL, or

Returns:

RMW_RET_INCORRECT_RMW_IMPLEMENTATION if publisher implementation identifier does not match this implementation, or

Returns:

RMW_RET_UNSUPPORTED if the implementation does not support ROS message loaning, or

Returns:

RMW_RET_ERROR if an unexpected error occurs.