Documentation on runtime flags

[GoogleCodeExporter]

ThreadSanitizer has more runtime flags than documented on
http://code.google.com/p/thread-sanitizer/wiki/Flags

Missing flags include suppress_equal_stacks, suppress_equal_addresses,
report_atomic_races, which are useful not only for those, who read
TSan's sources.

Could you, please, add documentation on missing flags to the wiki?

Original issue reported on code.google.com by yegor.de...@gmail.com on 15 Nov 2013 at 8:04

[GoogleCodeExporter]

We may want to document some more flags, but I certainly don't want to document 
all
of them because some are internal only an may change w/o a notice. 

Original comment by konstant...@gmail.com on 16 Nov 2013 at 3:38

[GoogleCodeExporter]

Hi,

We intentionally do not document most of the flags. Some of them are intended 
for tsan tests only, some of them are used in very narrow situations by us. Not 
enough thought is put into most of them to make them stable public interface.
Please describe the problem you want to solve, then we can think about adding 
new flags or exposing some existing flags (but this time realizing that it 
becomes a part of public stable interface).

Original comment by dvyu...@google.com on 19 Nov 2013 at 6:29

• Changed state: WaitingForReply
• Added labels: Type-Enhancement
• Removed labels: Type-Defect

[GoogleCodeExporter]

Hi,

I will rather mention a real use case. I advertised ThreadSanitizer to a
developer. The developer tried to use it on a real project. A couple of
data races were reported, in an algorithm which was known to be racy.
However, this algorithm was run several times throughout the execution,
and the next question to me was: why are there so few races reported?

Since I read TSan's sources, I could answer. But I could not even give a
link to a webpage, where one could read about the flags controlling
suppressions, so that the developer could try them out and see that all
races are actually detected. So, I ended up copy-pasting documentation
on suppress_equal_{stacks,addresses} flags from tsan_flags.h.

Since there is one person who needed to know about them, there is likely
more of them, and not all of them like to read sources.

Concerning the other flags, I do not have a strong opinion whether they
should be documented. (I tried setting report_atomic_races=1 for some
research-related purposes, so I am not sure whether this is useful for
general public.)

Original comment by yegor.de...@gmail.com on 19 Nov 2013 at 3:12

[GoogleCodeExporter]

It does not sound like compelling enough argument for 
suppress_equal_{stacks,addresses} flags.

First, data race is undefined behavior. So after the first data race report all 
bets are mostly off. The program may just crash, or do not what you expect. The 
principal distinction is "clean run" vs "run with one or more data races". 
There is no principal distinction between one or N races.

Second, this behavior is added on a purpose. Exactly because of the case you 
describe. If a program processes 10^9 elements, and processing of each element 
produces 10 race reports; it's not wise to print 10^10 race reports. Equivalent 
reports does not add significant value.

Original comment by dvyu...@google.com on 21 Nov 2013 at 12:39

[GoogleCodeExporter]

Hi,

> First, data race is undefined behavior. So after the first data race
> report all bets are mostly off.

Data race is an undefined behavior _in C++_. Some APIs (e.g. GASPI)
define data race semantics in an interleaving fashion. It is sometimes a
sufficient guarantee for a developer, and it relies on it, writing racy,
but correct (and fast!), code.

Essentially, one talks here about guarantees like "two concurrent
memcpy-s with the same destinations will write an interleaving of source
data as the result and will not burn your computer on the way".

I do not see why one would like to artificially limit TSan's
applicability to pure C++-way correct programs, while it already can
handle correct racy programs (with the help of one or two annotations/
suppressions).

> it's not wise to print 10^10 race reports.
I let myself quote Martin Kuhn, a developer from Fraunhofer ITWM:

---- cut ----
Main reason is that in general the number of races gives a hint on the
source of the problem. Knowing that a specific race occurs once or
hundreds of time gives me a good hint if I'm looking at an quite exotic
event or at a quite common event.

Specifically for the suppress_equal_stacks consider the following
example. Let's say you define a simple function that e.g. increases a
variable. If you use this function at hundred different places in the 
source code the first appearance will mask all the others. So how do I
know if the function itself is buggy and will cause a race every time I
call it or if it is buggy only in specific contexts, i.e. when I call it
on certain variables.

Similar argument goes for the suppress_equal_addresses flag. If I have
hundred functions that touch a certain memory area, the first race would
mask all the others. So how do I know if the first race is the only one 
and should be examined carefully or if it is only the tip of the ice berg.
---- cut ----

Original comment by yegor.de...@gmail.com on 21 Nov 2013 at 3:33