FAQ
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.



https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html
File doc/articles/race_detector.html (right):

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode9
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/

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode13
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 //

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode35
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:

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode48
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/

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode89
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:

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode99
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.

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode100
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.

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

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode102
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
usage.

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode115
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
coverage,
you may find more races by running a binary built with -race under a
realistic workload.

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode121
doc/articles/race_detector.html:121: Here are some examples of typical
data races. All of them can be automatically detected with the race
detector.
s/examples of //
s/automatically //

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode141
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:

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode191
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 ...

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode203
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:

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode213
doc/articles/race_detector.html:213: func GetService(name string)
net.Addr {
s/Get/Lookup/

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode219
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:

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode232
doc/articles/race_detector.html:232: func GetService(name string)
net.Addr {
s/Get/Lookup/

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode267
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.
&ldquo;innocent&rdquo;

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode271
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
pcakage.

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode294
doc/articles/race_detector.html:294: <h2>Supported Platforms</h2>
s/Platforms/Systems/

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode297
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.

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode300
doc/articles/race_detector.html:300: <h2>Runtime Overheads</h2>
s/Overheads/Overhead/

https://codereview.appspot.com/6948043/diff/6003/doc/articles/race_detector.html#newcode303
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.

https://codereview.appspot.com/6948043/

Search Discussions

Related Discussions

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

People

Translate

site design / logo © 2022 Grokbase