I tried to tighten much of the text. I am not 100% sure it belongs here.
Maybe it should be a package-level doc comment for runtime/race. Will
leave that decision for adg.

File doc/articles/race_detector.html (right):

doc/articles/race_detector.html:9: Data races are one of the most common
and hardest to debug types of bugs in concurrent systems. A data race
occurs when two goroutines access the same variable without proper
synchronization and at least one of the accesses is write. See the <a
href="/ref/mem">The Go Memory Model</a> for details.
s/without proper synchronization/concurrently/

doc/articles/race_detector.html:13: Here is an example of a data race on
map variable that can lead to crashes and memory corruptions:
s/on map variable //

doc/articles/race_detector.html:35: Fortunately, Go includes a built-in
data race detector. The usage is very simple -- you just need to add
-race flag to the go command:
s/The usage.*/To use it, add the -race flag to the go command:

doc/articles/race_detector.html:48: When the race detector finds a data
race in the program, it prints an informative report. The report
contains stack traces for conflicting accesses, as well as stacks where
the involved goroutines were created. You may see an example below:
s/an informative/a/
s/You may see an example below/For example/

doc/articles/race_detector.html:89: You can pass some options to the
race detector by means of <code>GORACE</code> environment variable. The
format is:
The GORACE environment variable sets race detector options.
The format is:

doc/articles/race_detector.html:99: <li> log_path: Tells race detector
to write reports to 'log_path.pid' file. The special values are
'stdout' and 'stderr'. The default is 'stderr'.</li>
log_path (default stderr): The race detector writes its report to a file
named log_path.pid. The special names stdout and stderr cause reports to
be written to standard output and standard error, respectively.

doc/articles/race_detector.html:100: <li> exitcode: Override exit status
of the process if something was reported. Default value is 66.</li>
exitcode (default 66): The exit status to use when exiting after a
detected race.

doc/articles/race_detector.html:101: <li> strip_path_prefix: Allows to
strip beginnings of file paths in reports to make them more
strip_path_prefix (default ""): Strip this prefix from all reported file
paths, to make reports more concise.

doc/articles/race_detector.html:102: <li> history_size: Per-goroutine
history size, controls how many previous memory accesses are remembered
per goroutine. Possible values are [0..7]. history_size=0 amounts to
32K memory accesses. Each next value doubles the amount of memory
accesses, up to history_size=7 that amounts to 4M memory accesses. The
default value is 1 (64K memory accesses). Try to increase this value
when you see "failed to restore the stack" in reports. However, it can
significantly increase memory consumption.</li>
history_size (default 1): The per-goroutine memory access history is 32K
* 2**history_size elements. Increasing this value can avoid a "failed to
restore the stack" error in reports, but at the cost of increased memory

doc/articles/race_detector.html:115: You may start with just running
your tests under the race detector (<code>go test -race</code>).
However sometimes tests have limited coverage, especially with respect
to concurrency. The race detector finds only races that actually happen
in the execution, it can't find races in code paths that were not
executed. So it may be beneficial to run the whole program built with
-race under a realistic workload, frequently it discovers much more bugs
than tests.
To start, run your tests using the race detector (go test -race).
The race detector only finds races that happen at runtime, so it can't
find races
in code paths that are not executed. If your tests have incomplete
you may find more races by running a binary built with -race under a
realistic workload.

doc/articles/race_detector.html:121: Here are some examples of typical
data races. All of them can be automatically detected with the race
s/examples of //
s/automatically //

doc/articles/race_detector.html:141: Closures capture variables by
reference rather than by value, so the reads of the <code>i</code>
variable in the goroutines race with <code>i</code> increment in the
loop statement. Such program typically outputs 55555 instead of
expected 01234. The program can be fixed by explicitly making a copy of
the loop counter:
The variable i in the function literal is the same variable used by the
loop, so the read in the goroutine races with the loop increment. (This
program typically prints 55555, not 01234.) The program can be fixed by
making a copy of the variable:

doc/articles/race_detector.html:191: The fix is simple, one just needs
to introduce new variables in the goroutines (note <code>:=</code>):
The fix is to introduce new ...

doc/articles/race_detector.html:203: If the following code is called
from several goroutines, it leads to bad races on the
<code>services</code> map.
Concurrent reads and writes of a map are not safe:

doc/articles/race_detector.html:213: func GetService(name string)
net.Addr {

doc/articles/race_detector.html:219: It can be fixed by protecting the
accesses with a mutex:
To make the code safe, protect the accesses with a mutex:

doc/articles/race_detector.html:232: func GetService(name string)
net.Addr {

doc/articles/race_detector.html:267: Even such "innocent" data races can
lead to hard to debug problems caused by (1) non-atomicity of the memory
accesses, (2) interference with compiler optimizations and (3) processor
memory access reordering issues.

doc/articles/race_detector.html:271: To fix such data race one can use
(aside from <code>chan</code> and <code>sync.Mutex</code>) package <a
href="/pkg/sync/atomic"><code>sync/atomic</code></a>, which provides
atomic operations on primitive types. <a
href="/pkg/sync/atomic"><code>sync/atomic</code></a> functions solve all
of the above issues.
A typical fix for this race is to use a channel or a mutex.
To preserve the lock-free behavior, one can also use the sync/atomic

doc/articles/race_detector.html:294: <h2>Supported Platforms</h2>

doc/articles/race_detector.html:297: Supported platforms are
darwin/amd64, linux/amd64 and windows/amd64.
The race detector runs on darwin/amd64, linux/amd64, and windows/amd64.

doc/articles/race_detector.html:300: <h2>Runtime Overheads</h2>

doc/articles/race_detector.html:303: The data race detector
significantly increases both memory consumption and execution time. The
concrete numbers are highly dependent on the particular program, but
some reference numbers would be: memory consumption ~5-10x, execution
time ~2-20x.
The cost of race detection varies by program, but for a typical program,
memory usage may increase by 5-10x and execution time by 2-20x.


Search Discussions

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupgolang-dev @
postedDec 17, '12 at 1:10a
activeDec 24, '12 at 8:34a



site design / logo © 2022 Grokbase