Function rmw_publish

Function Documentation

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

Publish a ROS message.

Send a ROS message to all subscriptions with matching QoS policies using the given 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

It is implementation defined whether to publish a ROS message is a synchronous or asynchronous, blocking or non-blocking operation. However, asynchronous implementations are not allowed to access the given ROS message after this function returns. 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 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 regular ROS messages:

  • Access to the ROS message is read-only but it is not synchronized. Concurrent ros_message reads are safe, but concurrent reads and writes are not.

  • 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] 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, whose type matches the message type support the publisher was registered with on creation.

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_ERROR if an unexpected error occurs.