Function rcl_publish

Function Documentation

rcl_ret_t rcl_publish(const rcl_publisher_t *publisher, const void *ros_message, rmw_publisher_allocation_t *allocation)

Publish a ROS message on a topic using a publisher.

It is the job of the caller to ensure that the type of the ros_message parameter and the type associate with the publisher (via the type support) match. Passing a different type to publish produces undefined behavior and cannot be checked by this function and therefore no deliberate error will occur.

Todo:

TODO(wjwwood): The blocking behavior of publish is a still a point of dispute. This section should be updated once the behavior is clearly defined. See: https://github.com/ros2/ros2/issues/255

Calling rcl_publish() is a potentially blocking call. When called rcl_publish() will immediately do any publishing related work, including, but not limited to, converting the message into a different type, serializing the message, collecting publish statistics, etc. The last thing it will do is call the underlying middleware’s publish function which may or may not block based on the quality of service settings given via the publisher options in rcl_publisher_init(). For example, if the reliability is set to reliable, then a publish may block until space in the publish queue is available, but if the reliability is set to best effort then it should not block.

The ROS message given by the ros_message void pointer is always owned by the calling code, but should remain constant during publish.

This function is thread safe so long as access to both the publisher and the ros_message is synchronized. That means that calling rcl_publish() from multiple threads is allowed, but calling rcl_publish() at the same time as non-thread safe publisher functions is not, e.g. calling rcl_publish() and rcl_publisher_fini() concurrently is not allowed. Before calling rcl_publish() the message can change and after calling rcl_publish() the message can change, but it cannot be changed during the publish call. The same ros_message, however, can be passed to multiple calls of rcl_publish() simultaneously, even if the publishers differ. The ros_message is unmodified by rcl_publish().

Attribute

Adherence

Allocates Memory

No

Thread-Safe

Yes [1]

Uses Atomics

No

Lock-Free

Yes

[1] for unique pairs of publishers and messages, see above for more

Parameters:

  • publisher – [in] handle to the publisher which will do the publishing

  • ros_message – [in] type-erased pointer to the ROS message

  • allocation – [in] structure pointer, used for memory preallocation (may be NULL)

Returns:

RCL_RET_OK if the message was published successfully, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_PUBLISHER_INVALID if the publisher is invalid, or

Returns:

RCL_RET_ERROR if an unspecified error occurs.