Feature request

Feature description

Often, though not consistently, ROS 2 APIs explicitly state their thread (un)safety. These binary statements, when not qualified by a footnote (and even then), are quite unspecific. There's no mention as to:

• whether a function can be called concurrently with itself or not (re-entrancy),
• whether a function can be called concurrently with other functions in a given group or not,
• whether a function can be called concurrently on the same input and/or output argument or not.
• whether a function can be called concurrently on different (but potentially shared) input and/or output argument or not.

As a result, we have a vague qualifier for authors, reviewers, and users.

There have been some exchanges in the past, but still it creeps up every now and then. I think we should sit and unambiguously standardize how we document thread-safety.

Implementation considerations

It's worth exploring how other software standards and libraries do this.

For POSIX:

MT-Safe or Thread-Safe functions are safe to call in the presence of other threads.

Being MT-Safe does not imply a function is atomic, nor that it uses any of the memory synchronization mechanisms POSIX exposes to users. It is even possible that calling MT-Safe functions in sequence does not yield an MT-Safe combination.

Functions like memset or free are tagged as MT-Safe -- that is, no guarantees are made when using these functions' arguments concurrently with the same functions or others.

For Qt:

A thread-safe function can be called simultaneously from multiple threads, even when the invocations use shared data, because all references to the shared data are serialized.

A reentrant function can also be called simultaneously from multiple threads, but only if each invocation uses its own data.

Perhaps we should talk about reentrant functions and thread-safe data structures? Maybe we should state if reads or writes are to be expected on any given argument?