Go Race Detector User Manual

The tool works for linux amd64. No portability guarantees at the moment.

Everything is currently in a the fork of the original Go repository: http://code.google.com/r/mpimenov-go1-tsan/. The version of the original repo is 12771:fbc982f5aff1 (Mar 20, 2012) which is very close to Go 1. Any program compatible with Go 1 should be compatible with our toolchain. If it is not, please file an issue.

1. You need to download ThreadSanitizer first:

export TSAN_PATH=/home/$USER/tsan
svn checkout http://data-race-test.googlecode.com/svn/trunk/ $TSAN_PATH
cd $TSAN_PATH/go
DEBUG=1 make
sudo make install

2. Download the modified compiler from the forked repository:

export GOROOT=/home/$USER/go_race
export GOBIN=$GOROOT/bin
export PATH=$GOBIN:$PATH

hg clone -r 998b7e5d75c0 https://mpimenov%40google.com@code.google.com/r/mpimenov-go1-tsan/ $GOROOT

Copy the tsan shared library to the package dir:

cp $TSAN_PATH/go/libtsan_go64.so $GOROOT/src/pkg/gotsan

3. Build the tree.

cd $GOROOT/src
./make.bash

4. Test that the package is installed correctly:

cd $GOROOT/src/pkg/gotsan
go install -a -race
go run -race testtsan.go

Around 80% of tests should pass.

5. A simple Go program containing a data race may be found at $GOROOT/src/pkg/gotsan/race.go. To run it and see the report use the following command:

go run -race race.go

The output you should see looks like this:

==22257== INFO: Allocating 256Mb (32 * 8M) for Segments.
==22257== INFO: Will allocate up to 640Mb for 'previous' stack traces.
 sizeof(CacheLine) = 568
==22257== INFO: T0 is program's main thread
==22257== INFO: T1 has been created by T0. Use --announce-threads to see the creation stack.
==22257== WARNING: Possible data race during write of size 1 at 0xf840000000: {{{
==22257==    T1 (L{}):
==22257==     #0  main._func_001 ~/go/src/pkg/gotsan/race.go:10
==22257==     #1  runtime.goexit ~/go/src/pkg/runtime/proc.c:266
==22257==   Concurrent write(s) happened at (OR AFTER) these points:
==22257==    T0 (L{}):
==22257==     #0  main.main ~/go/src/pkg/gotsan/race.go:13
==22257==     #1  runtime.main ~/go/src/pkg/runtime/proc.c:238
==22257==    Race verifier data: 0x400da1,0x400caf
==22257== }}}

ThreadSanitizer has received 24 events
1 READs
6 WRITEs
1 SIGNALs
1 WAITs
3 RTN_CALLs
3 RTN_EXITs

6. Your package’s tests can be run with race detection enabled too. We will test src/pkg/image as an example.

cd $GOROOT/src/pkg/image
go install -a -race
go test -race

The output should contain lines like these:

INFO: Allocating 256Mb (32 * 8M) for Segments.
INFO: Will allocate up to 640Mb for 'previous' stack traces.
sizeof(CacheLine) = 568
PASS

ThreadSanitizer has received 17302207 events
7 THR_STARTs
6958 READs
125096 WRITEs
248 SIGNALs
254 WAITs
8470034 RTN_CALLs
8470034 RTN_EXITs
97471 MALLOCs
56 FREEs


ThreadSanitizer summary: reported 0 warning(s) (0 race(s))
ok  	image	10.257s

Looks like there are no races in this package and its tests!

7. Some races found by ThreadSanitizer can be observed in Go issue list: http://code.google.com/p/go/issues/list?can=1&q=label%3AThreadSanitizer

8. The slowdown imposed by the tool may be 20x and higher, so please be patient when running your programs. Also, please file an issue if you program crashes because of the tool.