Function rmw_borrow_loaned_message

• Defined in File rmw.h

Function Documentation

rmw_ret_t rmw_borrow_loaned_message(const rmw_publisher_t *publisher, const rosidl_message_type_support_t *type_support, void **ros_message)

Borrow a loaned ROS message.

This ROS message is owned by the middleware, that will keep it alive (i.e. in valid memory space) until the caller publishes it using rmw_publish_loaned_message() or returns it using rmw_return_loaned_message_from_publisher().

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

[1] implementation defined, check implementation documentation.

Runtime behavior

To borrow 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).

Memory allocation

It is implementation defined whether memory will be allocated on borrow or not. Check the implementation documentation to learn about memory allocation guarantees when using ROS message loaning support.

Thread-safety

Publishers are thread-safe objects, and so are all operations on them except for finalization. Therefore, it is safe to borrow ROS messages from the same publisher concurrently.

Parameters:

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

• type_support – [in] Message type support of the loaned ROS message.

• ros_message – [out] Pointer to type erased ROS message loaned by the middleware.

Pre:

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

Pre:

Given type_support must be a valid rosidl message type support, matching the one registered with the publisher on creation.

Returns:

RMW_RET_OK if successful, or

Returns:

RMW_RET_BAD_ALLOC if memory allocation fails, or

Returns:

RMW_RET_INVALID_ARGUMENT if publisher is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if type_support is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if ros_message is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if *ros_message is not NULL (to prevent leaks), 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 occured.