Documentation for Wait for Acknowledgements

[fujitatomoya]

Overview

add the following wait_for_all_acked documentation with using examples.

• Client APIs

  • https://github.com/ros2/rclcpp/blob/rolling/rclcpp/include/rclcpp/publisher_base.hpp#L235-L259
  • https://github.com/ros2/rclpy/blob/f8606f03d900bbd2387f51178ae5bdf5c5d7b443/rclpy/rclpy/publisher.py#L113-L131

• Examples

  • https://github.com/ros2/examples/blob/rolling/rclcpp/topics/minimal_publisher/member_function_with_wait_for_all_acked.cpp
  • rclpy does not have example, but we can add.

Description

This operation blocks the calling thread until either all data written by the reliable DataWriter entities is acknowledged by all matched reliable DataReader entities, or else the duration specified by the max_wait parameter elapses, whichever happens first.
A return value of OK indicates that all the samples written have been acknowledged by all reliable matched data readers; a return value of TIMEOUT indicates that max_wait elapsed before all the data was acknowledged.

This is really useful for the following use cases.

• safety-critical applications (e.g., autonomous vehicles, industrial automation, medical devices), ensuring data has been received before proceeding is crucial to avoid failures.
• Useful in distributed systems where state synchronization is required before the next action can occur.
• In systems where data integrity and order matter, waiting for an acknowledgment ensures that messages are not lost due to network issues.

[fujitatomoya]

@christophebedard @kscottz @mjcarroll what do you think? if you guys feel this is good to go, i can take this.