diff options
Diffstat (limited to 'doc/articles')
| -rw-r--r-- | doc/articles/godoc_documenting_go_code.html | 14 | ||||
| -rw-r--r-- | doc/articles/image_package.html | 4 | ||||
| -rw-r--r-- | doc/articles/race_detector.html | 54 |
3 files changed, 44 insertions, 28 deletions
diff --git a/doc/articles/godoc_documenting_go_code.html b/doc/articles/godoc_documenting_go_code.html index 18a3ee953..3f4e3228c 100644 --- a/doc/articles/godoc_documenting_go_code.html +++ b/doc/articles/godoc_documenting_go_code.html @@ -83,18 +83,20 @@ godoc's output, with one notable exception. Top-level comments that begin with the word <code>"BUG(who)"</code> are recognized as known bugs, and included in the "Bugs" section of the package documentation. The "who" part should be the user name of someone who could provide more information. For example, this is a -known issue from the <a href="/pkg/bytes/#pkg-bugs"><code>bytes</code></a> package: +known issue from the <a href="/pkg/sync/atomic/#pkg-note-BUG"><code>sync/atomic</code></a> package: </p> <pre> -// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly. +// BUG(rsc): On x86-32, the 64-bit functions use instructions +// unavailable before the Pentium MMX. On both ARM and x86-32, it is the +// caller's responsibility to arrange for 64-bit alignment of 64-bit +// words accessed atomically. </pre> <p> -Godoc treats executable commands somewhat differently. Instead of inspecting the -command source code, it looks for a Go source file belonging to the special -package "documentation". The comment on the "package documentation" clause is -used as the command's documentation. For example, see the +Godoc treats executable commands in the same way. It looks for a comment on +package main, which is sometimes put in a separate file called <code>doc.go</code>. +For example, see the <a href="/cmd/godoc/">godoc documentation</a> and its corresponding <a href="/src/cmd/godoc/doc.go">doc.go</a> file. </p> diff --git a/doc/articles/image_package.html b/doc/articles/image_package.html index ebe92a1ca..39a93ccda 100644 --- a/doc/articles/image_package.html +++ b/doc/articles/image_package.html @@ -130,7 +130,7 @@ much easier to type. A <code>Rectangle</code> is inclusive at the top-left and exclusive at the bottom-right. For a <code>Point p</code> and a <code>Rectangle r</code>, <code>p.In(r)</code> if and only if -<code>r.Min.X <= p.X && p.X < r.Max.X</code>, and similarly for <code>Y</code>. This is analagous to how +<code>r.Min.X <= p.X && p.X < r.Max.X</code>, and similarly for <code>Y</code>. This is analogous to how a slice <code>s[i0:i1]</code> is inclusive at the low end and exclusive at the high end. (Unlike arrays and slices, a <code>Rectangle</code> often has a non-zero origin.) @@ -236,7 +236,7 @@ more complicated, to access these struct type's <code>Pix</code> field directly. The slice-based <code>Image</code> implementations also provide a <code>SubImage</code> method, which returns an <code>Image</code> backed by the same array. Modifying the pixels of a sub-image will affect the pixels of the -original image, analagous to how modifying the contents of a sub-slice +original image, analogous to how modifying the contents of a sub-slice <code>s[i0:i1]</code> will affect the contents of the original slice <code>s</code>. </p> diff --git a/doc/articles/race_detector.html b/doc/articles/race_detector.html index 400d96b19..2d36f616e 100644 --- a/doc/articles/race_detector.html +++ b/doc/articles/race_detector.html @@ -6,7 +6,9 @@ <h2 id="Introduction">Introduction</h2> <p> -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 concurrently and at least one of the accesses is a write. See the <a href="/ref/mem/">The Go Memory Model</a> for details. +Data races are among the most common and hardest to debug types of bugs in concurrent systems. +A data race occurs when two goroutines access the same variable concurrently and at least one of the accesses is a write. +See the <a href="/ref/mem/">The Go Memory Model</a> for details. </p> <p> @@ -32,7 +34,8 @@ func main() { <h2 id="Usage">Usage</h2> <p> -Fortunately, Go includes a built-in data race detector. To use it, add the <code>-race</code> flag to the go command: +To help diagnose such bugs, Go includes a built-in data race detector. +To use it, add the <code>-race</code> flag to the go command: </p> <pre> @@ -45,7 +48,9 @@ $ go install -race mypkg // to install the package <h2 id="Report_Format">Report Format</h2> <p> -When the race detector finds a data race in the program, it prints a report. The report contains stack traces for conflicting accesses, as well as stacks where the involved goroutines were created. For example: +When the race detector finds a data race in the program, it prints a report. +The report contains stack traces for conflicting accesses, as well as stacks where the involved goroutines were created. +Here is an example: </p> <pre> @@ -86,7 +91,8 @@ Goroutine 184 (running) created at: <h2 id="Options">Options</h2> <p> -The <code>GORACE</code> environment variable sets race detector options. The format is: +The <code>GORACE</code> environment variable sets race detector options. +The format is: </p> <pre> @@ -100,7 +106,8 @@ The options are: <ul> <li> <code>log_path</code> (default <code>stderr</code>): The race detector writes -its report to a file named log_path.pid. The special names <code>stdout</code> +its report to a file named <code>log_path.<em>pid</em></code>. +The special names <code>stdout</code> and <code>stderr</code> cause reports to be written to standard output and standard error, respectively. </li> @@ -117,8 +124,8 @@ from all reported file paths, to make reports more concise. <li> <code>history_size</code> (default <code>1</code>): The per-goroutine memory -access history is <code>32K * 2**history_size elements</code>. Increasing this -value can avoid a "failed to restore the stack" error in reports, but at the +access history is <code>32K * 2**history_size elements</code>. +Increasing this value can avoid a "failed to restore the stack" error in reports, at the cost of increased memory usage. </li> </ul> @@ -134,9 +141,10 @@ $ GORACE="log_path=/tmp/race/report strip_path_prefix=/my/go/sources/" go test - <h2 id="Excluding_Tests">Excluding Tests</h2> <p> -When you build with <code>-race</code> flag, go command defines additional -<a href="/pkg/go/build/#Build_Constraints">build tag</a> <code>race</code>. -You can use it to exclude some code/tests under the race detector. For example: +When you build with <code>-race</code> flag, the <code>go</code> command defines additional +<a href="/pkg/go/build/#hdr-Build_Constraints">build tag</a> <code>race</code>. +You can use the tag to exclude some code and tests when running the race detector. +Some examples: </p> <pre> @@ -165,7 +173,8 @@ func TestBaz(t *testing.T) { <p> To start, run your tests using the race detector (<code>go test -race</code>). 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, +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 <code>-race</code> under a realistic workload. </p> @@ -194,9 +203,9 @@ func main() { <p> The variable <code>i</code> 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: +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: </p> <pre> @@ -246,7 +255,7 @@ func ParallelWrite(data []byte) chan error { </pre> <p> -The fix is to introduce new variables in the goroutines (note <code>:=</code>): +The fix is to introduce new variables in the goroutines (note the use of <code>:=</code>): </p> <pre> @@ -260,8 +269,8 @@ The fix is to introduce new variables in the goroutines (note <code>:=</code>): <h3 id="Unprotected_global_variable">Unprotected global variable</h3> <p> -If the following code is called from several goroutines, it leads to bad races on the <code>service</code> map. -Concurrent reads and writes of a map are not safe: +If the following code is called from several goroutines, it leads to races on the <code>service</code> map. +Concurrent reads and writes of the same map are not safe: </p> <pre> @@ -302,7 +311,8 @@ func LookupService(name string) net.Addr { <h3 id="Primitive_unprotected_variable">Primitive unprotected variable</h3> <p> -Data races can happen on variables of primitive types as well (<code>bool</code>, <code>int</code>, <code>int64</code>, etc.), like in the following example: +Data races can happen on variables of primitive types as well (<code>bool</code>, <code>int</code>, <code>int64</code>, etc.), +as in this example: </p> <pre> @@ -327,12 +337,16 @@ func (w *Watchdog) Start() { </pre> <p> -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. +Even such "innocent" data races can lead to hard-to-debug problems caused by +non-atomicity of the memory accesses, +interference with compiler optimizations, +or reordering issues accessing processor memory . </p> <p> 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 <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> package. +To preserve the lock-free behavior, one can also use the +<a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> package. </p> <pre> |