Function rmw_return_loaned_message_from_publisher

• Defined in File rmw.h

Function Documentation

rmw_ret_t rmw_return_loaned_message_from_publisher(const rmw_publisher_t *publisher, void *loaned_message)

Return a loaned message previously borrowed from a publisher.

Tells the middleware that a borrowed ROS message is no longer needed by the caller. Ownership of the ROS message is given back 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 returning it.

Attribute	Adherence
Allocates Memory	No
Thread-Safe	Yes
Uses Atomics	Maybe [1]
Lock-Free	Maybe [1]

[1] implementation defined, check implementation documentation.

Runtime behavior

To return a ROS message is a synchronous operation. It is also non-blocking, but it is not guaranteed to be lock-free. Generally speaking, implementations may synchronize access to internal resources using locks but are not allowed to wait for events with no guaranteed time bound (barring the effects of starvation due to OS scheduling).

Thread-safety

Publishers are thread-safe objects, and so are all operations on them except for finalization. Therefore, it is safe to return borrowed ROS messages to the same publisher concurrently. However, since ownership of the loaned ROS message is given back to the middleware and this transfer is not synchronized, it is not safe to return the same loaned ROS message concurrently.

Parameters:

• publisher – [in] Publisher to which the loaned ROS message is associated.

• loaned_message – [in] Type erased loaned ROS message to be returned.

Pre:

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

Pre:

Given loaned_message must have been previously borrowed from the same publisher using rmw_borrow_loaned_message().

Returns:

RMW_RET_OK if successful, or

Returns:

RMW_RET_INVALID_ARGUMENT if publisher is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if loaned_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 and no message can be initialized.