Add declaration for function to check QoS profile compatibility

[jacobperron]

Currently, users who are creating a publisher or subscription can receive 'QoS incompatibility'
events from the RMW if an incompatible endpoint is discovered. While this is useful, we
currently don't have a nice way for application to generally check if two QoS profiles are
compatible. For example, it would be nice if tooling could query the communication graph and
report any detected QoS incompatibilities.

In order to reduce code duplication, I think an API for checking QoS compatibilty should live
in a common place. I've opted for rmw (over a place like rcl) since it's possible QoS
compatiblity rules may vary per RMW vendor. Since rules for all DDS implementations should be
the same, we could put that common logic in rmw_dds_common.

---

The motivation for this API is to add features to tooling like rqt_graph and ros2doctor to help diagnose QoS compatibility issues. E.g. it would be useful to change how incompatible links in the ROS graph are rendered in rqt_graph.

---

Connected PRs:

• rmw_dds_common (implementation): Add function for checking QoS profile compatibility rmw_dds_common#45
• rmw_cyclonedds: Add RMW function to check QoS compatibility rmw_cyclonedds#286
• rmw_fastrtps: Add RMW function to check QoS compatibility rmw_fastrtps#511
• rmw_connext: Add RMW function to check QoS compatibility rmw_connext#488
• rmw_implementation: Add function for checking QoS profile compatibility rmw_implementation#180
• rmw_connextdds: TODO

CI for connected PRs listed above:

• Linux
• Linux-aarch64
• macOS
• Windows

[jacobperron]

I've refactored the proposed API. Two major changes:

1. Now instead of a bool, it outputs the compatibility result as an enum type parameter. The return code is reserved for other errors not related to compatibility.
   The compatibility can have one of three states:

   • "OK": the profiles are compatible
   • "WARNING": because one or more policies was set to "system default", we don't actually know if the profiles are compatible.
   • "ERROR": the profiles are incompatible.

2. Added a string buffer (and size) parameter for setting the reason for an incompatibility or warning.
   The user should provide a pre-allocated array so that memory management is completely in their hands.

@mjeronimo @gbiggs PTAL

[jacobperron]

Oh, and I also renamed the function on a whim.

[mjeronimo]

I agree with the name change given the change in the return type.

Looks good to me, although I would've preferred a definitive yes/no answer, which would, of course, require a way to query the underlying implementation for its QoS system defaults.

[gbiggs]

Some documentation improvements are needed.

[wjwwood]

Added a string buffer (and size) parameter for setting the reason for an incompatibility or warning.
The user should provide a pre-allocated array so that memory management is completely in their hands.

👍 like this even more than what we talked about.

[jacobperron]

I've opened a PR with the implementation for DDS RMWs here: ros2/rmw_dds_common#45

[jacobperron]

Thanks for the feedback! I've updated this PR and opened a bunch of connected PRs that implement this for our supported RMWs (see the updated description for a list). The common implementation lives in rmw_dds_common, so this one could use the most scrutiny: ros2/rmw_dds_common#45

[mjeronimo]

Use 'nullptr's here instead of NULLs?

[ivanpauno]

nullptr is cpp only AFAIK

[ivanpauno]

Pending discussion in another PR ros2/rmw_dds_common#45 (comment)

[jacobperron]

Updated 93e9aa2

Unknown values now result in a compatibility warning instead of an error.

[fujitatomoya]

lgtm

[jacobperron]

Thanks for all the feedback so far!

I'm just waiting for ci.ros2.org to come back online and then I'll trigger CI and get this merged/released.

[asorbini]

I noticed this new API from a new test failure in test_rmw_implementation, and added support for it to rmw_connextdds in 91753dc.

I also noticed that these changes have not yet made it to the Rolling Debian binaries, and I had to build the tree from source in order to validate them. What is the period with which those packages are usually regenerated?

[ivanpauno]

I think that releasing rmw_implementation is pending, but IIUC @jacobperron already released up to rmw.

I also noticed that these changes have not yet made it to the Rolling Debian binaries, and I had to build the tree from source in order to validate them. What is the period with which those packages are usually regenerated?

IIUC the packages used by build.ros2.org for testing will be updated almost right away (delay of some hours), but the public ones (the ones you download when apt install ...) will only get updated after a sync.
I guess there will be a sync in about May as ROS 2 Galactic will be released for that date, though IDK.

[jacobperron]

@ivanpauno is correct. If you switch to the testing repo (see instructions), then you should see these changes already released there. Syncs to main happen periodically (roughly every three weeks), though I don't think there has been one for a couple months now.

@nuclearsandwich what do you think about doing a Rolling sync in the near future?