Function rmw_publish_serialized_message

Function Documentation

rmw_ret_t rmw_publish_serialized_message(const rmw_publisher_t *publisher, const rmw_serialized_message_t *serialized_message, rmw_publisher_allocation_t *allocation)

Publish a ROS message as a byte stream.

Send a ROS message serialized as a byte stream to all subscriptions with matching QoS policies using the given publisher. A ROS message can be serialized manually using rmw_serialize().

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. However, asynchronous implementations are not allowed to access the given byte stream 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. Even if a publisher allocation is provided, an implementation may ignore it. Check the implementation documentation to learn about memory allocation guarantees when publishing serialized 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 serialized ROS messages:

  • Access to the byte stream is read-only but it is not synchronized. Concurrent serialized_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.

  • serialized_message – [in] Serialized 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 serialized_message must be a valid serialized message, initialized by rmw_serialized_message_init() and containing the serialization of a ROS 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 serialized_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.