[20706] Make reader get_first_untaken_info() coherent with read()/take()

[Mario-DL]

Description

This PR corrects the behavior of get_first_untaken_info() so that it retrieves the first valid cache change (checking whether the change is in the future or not), instead of just returning the first one in the instance (sorted by sourcetimestamp).
In the scenario of having multiple reliable writers and one reader with history size > 1 in the same topic, it can happen that get_first_untaken_info() returns OK (as it is not currently checking whether the change is in the future) but take() returns NO_DATA because the change is in the future.

In addition, a brief doxygen documentation is added to be aware that the method is meant to be followed by a read() or take() since it does not modify the status condition of the entity.

@Mergifyio backport 2.13.x 2.10.x 2.6.x

Fixes ros2/rmw_fastrtps#749

Contributor Checklist

• Commit messages follow the project guidelines.
• The code follows the style guidelines of this project.
• Tests that thoroughly check the new feature have been added/Regression tests checking the bug and its fix have been added; the added tests pass locally
• Any new/modified methods have been properly documented using Doxygen.
• Any new configuration API has an equivalent XML API (with the corresponding XSD extension)
• Changes are ABI compatible.
• Changes are API compatible.
• N/A New feature has been added to the versions.md file (if applicable).
• N/A New feature has been documented/Current behavior is correctly described in the documentation.
• Applicable backports have been included in the description.

Reviewer Checklist

• The PR has a milestone assigned.
• The title and description correctly express the PR's purpose.
• Check contributor checklist is correct.
• Check CI results: changes do not issue any warning.
• Check CI results: failing tests are unrelated with the changes.

[fujitatomoya]

lgtm! @Mario-DL thanks for the fix!

[MiguelCompany]

@richiprosima Please test this

[MiguelCompany]

Unrelated failures. Going in.

[MiguelCompany]

@Mergifyio backport 2.13.x 2.10.x 2.6.x

[mergify]

backport 2.13.x 2.10.x 2.6.x

✅ Backports have been created

• #4706 [20706] Make reader get_first_untaken_info() coherent with read()/take() (backport #4696) has been created for branch 2.13.x
• #4707 [20706] Make reader get_first_untaken_info() coherent with read()/take() (backport #4696) has been created for branch 2.10.x
• #4708 [20706] Make reader get_first_untaken_info() coherent with read()/take() (backport #4696) has been created for branch 2.6.x