[TSAN] Lack of Documentation for __tsan_acquire and __tsan_release Annotations

[alvarillo89]

Dear Maintainers,

We have observed that Thread Sanitizer (TSan) is unable to detect when a variable is protected by a standalone memory barrier. As a result, it is necessary to annotate the memory addresses with __tsan_acquire and/or __tsan_release.

However, we have encountered instances where these annotations do not suffice to eliminate already fixed data races. Unfortunately, these annotations are not documented, and we could only find a brief comment in the code:

// __tsan_release establishes a happens-before relation with a preceding
// __tsan_acquire on the same address.
void SANITIZER_CDECL __tsan_acquire(void *addr);
void SANITIZER_CDECL __tsan_release(void *addr);

Could you please provide an official explanation and/or document their usage in the official documentation? This would be extremely helpful for developers relying on TSan.

Thank you for your attention to this matter.

Best regards,
Alvaro

[dfaure-kdab]

I agree. One thing that the documentation for those functions should state, for instance, is whether they establish an acquire/release fence from the "C++ abstract machine" point of view, or only in TSAN's own understanding.
This matters, for instance, when considering to replace a std::atomic_thread_fence (which leads to warnings under TSAN for lack of implementation) with __tsan_acquire / __tsan_release calls when building under TSAN. Is that OK, or does that introduce data races?

Similarly, please document what __tsan_atomic_thread_fence is.