RMW interface documentation about rmw

[wjwwood]

Hi @astralien3000, that cool that you're working on a new rmw implementation! I'm sorry that the rmw interface is not better documented at the moment, but we've had to pick and choose what to spend time on and we wanted to instead focus on the rcl API which is used to implement new client libraries (in different languages like C++ and Python).

Also, we've been wanting to improve the rmw API for a while now, but we've not had the time to do it. For example, we think the way we manage allocation in rcl is better than the original approach used in rmw and we'd like to update rmw to use the other style. This and other items have discouraged us from spending time on documenting the functions in great details because we knew they were going to change.

The best I can do is point you to code surrounding the rmw functions. For example, have a look at rcl_take which are basically thin wrappers around rmw_take_with_info at the moment and have decent docs:

rcl_take (there's also a hosted version, but it is not as up-to-date)

You can also look at how rcl calls rmw, for example:

• https://github.com/ros2/rcl/blob/88888fb672b88e3de41ce3f6dc67e05299d6a304/rcl/src/rcl/subscription.c#L140

Or how one of our rmw implementations implement it, like:

• https://github.com/ros2/rmw_connext/blob/master/rmw_connext_cpp/src/functions.cpp#L784-L828
• https://github.com/ros2/rmw_fastrtps/blob/master/rmw_fastrtps_cpp/src/functions.cpp#L1183-L1213

For the higher level integration into rclcpp there's also a lack of design documentation up online. But basically rmw_wait is used by rclcpp's Executor class to know when a subscription has data available, and then the Executor class will choose whether or not to take data from the ready subscriptions, and if it does it will do so with rmw_take* via rcl_take.

For more specific details, just ask directly.

Also, I'm going to close this issue for now. You might want to direct future high level questions to our discourse list:

https://discourse.ros.org/c/ng-ros

I can reopen this if needed.