From efcc50dfdc94c82ee0292bf71992ecb7c0123061 Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Tue, 14 May 2013 18:39:35 +0200 Subject: Imported Upstream version 1.1 --- doc/articles/godoc_documenting_go_code.html | 14 ++++---- doc/articles/image_package.html | 4 +-- doc/articles/race_detector.html | 54 ++++++++++++++++++----------- 3 files changed, 44 insertions(+), 28 deletions(-) (limited to 'doc/articles') 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 "BUG(who)" 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 bytes package: +known issue from the sync/atomic package: 

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

-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 doc.go. +For example, see the godoc documentation and its corresponding doc.go file.

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 Rectangle is inclusive at the top-left and exclusive at the bottom-right. For a Point p and a Rectangle r, p.In(r) if and only if -r.Min.X <= p.X && p.X < r.Max.X, and similarly for Y. This is analagous to how +r.Min.X <= p.X && p.X < r.Max.X, and similarly for Y. This is analogous to how a slice s[i0:i1] is inclusive at the low end and exclusive at the high end. (Unlike arrays and slices, a Rectangle often has a non-zero origin.) @@ -236,7 +236,7 @@ more complicated, to access these struct type's Pix field directly. The slice-based Image implementations also provide a SubImage method, which returns an Image 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 s[i0:i1] will affect the contents of the original slice s.

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 @@

Introduction

-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 The Go Memory Model 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 The Go Memory Model for details.

@@ -32,7 +34,8 @@ func main() {

Usage

-Fortunately, Go includes a built-in data race detector. To use it, add the -race flag to the go command: +To help diagnose such bugs, Go includes a built-in data race detector. +To use it, add the -race flag to the go command: 

@@ -45,7 +48,9 @@ $ go install -race mypkg // to install the package
 
Report Format

 
 

-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:
 

 
 
@@ -86,7 +91,8 @@ Goroutine 184 (running) created at:
 
Options

 
 

-The GORACE environment variable sets race detector options.  The format is:
+The GORACE environment variable sets race detector options.
+The format is:
 

 
 
@@ -100,7 +106,8 @@ The options are:
 
    
 
  • 
 log_path (default stderr): The race detector writes
-its report to a file named log_path.pid.  The special names stdout
+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.
 
    • 
@@ -117,8 +124,8 @@ from all reported file paths, to make reports more concise.
 
 
  • 
 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
+access history is 32K * 2**history_size elements.
+Increasing this value can avoid a "failed to restore the stack" error in reports, at the
 cost of increased memory usage.
 
    • 
 

@@ -134,9 +141,10 @@ $ GORACE="log_path=/tmp/race/report strip_path_prefix=/my/go/sources/" go test -
 
Excluding Tests

 
 

-When you build with -race flag, go command defines additional
-build tag race.
-You can use it to exclude some code/tests under the race detector. For example:
+When you build with -race flag, the go command defines additional
+build tag race.
+You can use the tag to exclude some code and tests when running the race detector.
+Some examples:
 

 
 
@@ -165,7 +173,8 @@ func TestBaz(t *testing.T) {
 

 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,
+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.
 

@@ -194,9 +203,9 @@ func main() {
 
 

 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:
+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:
 

 
 
@@ -246,7 +255,7 @@ func ParallelWrite(data []byte) chan error {
 

 
 

-The fix is to introduce new variables in the goroutines (note :=):
+The fix is to introduce new variables in the goroutines (note the use of :=):
 

 
 
@@ -260,8 +269,8 @@ The fix is to introduce new variables in the goroutines (note :=):
 
Unprotected global variable

 
 

-If the following code is called from several goroutines, it leads to bad races on the service 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 service map.
+Concurrent reads and writes of the same map are not safe:
 

 
 
@@ -302,7 +311,8 @@ func LookupService(name string) net.Addr {
 
Primitive unprotected variable

 
 

-Data races can happen on variables of primitive types as well (bool, int, int64, etc.), like in the following example:
+Data races can happen on variables of primitive types as well (bool, int, int64, etc.),
+as in this example:
 

 
 
@@ -327,12 +337,16 @@ func (w *Watchdog) Start() {
 

 
 

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

 
 

 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 package.
+To preserve the lock-free behavior, one can also use the
+sync/atomic package.
 

 
 
-- 
cgit v1.2.3