[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