expose getUnreadCount from history in subscriber

[dirk-thomas]

This PR is trying to address the problem described in ros2/rclcpp#280. The problem is best described in this comment but I will summarize it here and give a example what the exact problem is.

Consider a use case where a publisher publishes 100 messages and the subscriber has a history depth of 10. Additionally assume that the subscriber hasn't started processing any incoming message.

In ROS 2 we use a SubscriberListener to get notified about new data. onNewDataMessage is being triggered for every incoming message (so 100 times in this example). The custom listener keeps track of the count internally and every time a sample has been taken from the subscriber using takeNextData that counter is decremented. In the example the messages which exceed the queue size are still contributing to the count but can never be taken. So when the subscriber history is empty (after taken 10 samples) the internal count of the listener is still 90 but no sample can be taken anymore. That is the reason why in the referenced issue ROS starts to busy-spin since it keeps trying to take samples without succeeding - the count is never reduced in that case so this keeps going forever.

We have considered multiple options to address the problem each with different pros / cons:

1. The first option is based on the patch provided in this PR. By exposing the unread count from the history through the subscriber API the listener mentioned above doesn't need to keep its own count (which might get out of sync) but can just retrieve the actual count from the history.
   (+) The advantage is that the count is always "correct" and can never diverge.
   (-) The downside is that it requires this patch.

2. The second option would be to always decrement the internal count variable even when takeNextData fails.
   (+) Doable without requiring changes to FastRTPS.
   (--) After takeNextData failed because the unread history count is actually zero a new message might arrive asynchronously before it is attempted to decrement the counter. This might lead to never waiking up again since the counter is back to zero even though a sample is available to be taken.
   (-) ROS would need to "try" 90 times to step by step get the counter back to 0 which seems wasteful.

3. The third option is similar to the second but in case of takeNextData returning false it resets the counter to zero.
   (+) Doable without requiring changes to FastRTPS.
   (-) Same race condition as for the second option.
   (-) ROS would still need to "try" one time to get the counter back to 0 which seems unnecessary and potentially surprising when the user notices an event which then doesn't do anything.

The question now is if the proposed patch can be merged since it is the "cleanest" solution to the problem? Or is there another option how to use the existing API of FastRTPS to resolve the problem?

[richiware]

Could be useful the functionality you exposed for other users. It also solves your problem :). Thanks for your contribution.