diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 32 | ||||
| -rw-r--r-- | doc/articles/race_detector.html | 388 | ||||
| -rw-r--r-- | doc/articles/wiki/Makefile | 10 | ||||
| -rw-r--r-- | doc/articles/wiki/final.go | 23 | ||||
| -rw-r--r-- | doc/articles/wiki/index.html | 2 | ||||
| -rwxr-xr-x | doc/articles/wiki/test.bash | 26 | ||||
| -rw-r--r-- | doc/asm.html | 11 | ||||
| -rw-r--r-- | doc/codewalk/sharemem.xml | 2 | ||||
| -rw-r--r-- | doc/contrib.html | 42 | ||||
| -rw-r--r-- | doc/contribute.html | 92 | ||||
| -rw-r--r-- | doc/debugging_with_gdb.html | 21 | ||||
| -rw-r--r-- | doc/devel/release.html | 36 | ||||
| -rw-r--r-- | doc/docs.html | 7 | ||||
| -rw-r--r-- | doc/effective_go.html | 99 | ||||
| -rw-r--r-- | doc/gccgo_install.html | 4 | ||||
| -rw-r--r-- | doc/go1.3.html | 599 | ||||
| -rw-r--r-- | doc/go1.html | 2 | ||||
| -rw-r--r-- | doc/go_faq.html | 39 | ||||
| -rw-r--r-- | doc/go_mem.html | 37 | ||||
| -rw-r--r-- | doc/go_spec.html | 511 | ||||
| -rw-r--r-- | doc/gopher/README | 3 | ||||
| -rw-r--r-- | doc/help.html | 2 | ||||
| -rw-r--r-- | doc/install-source.html | 25 | ||||
| -rw-r--r-- | doc/install.html | 33 | ||||
| -rw-r--r-- | doc/root.html | 1 |
25 files changed, 1667 insertions, 380 deletions
diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index 23262da94..000000000 --- a/doc/Makefile +++ /dev/null @@ -1,32 +0,0 @@ -# Copyright 2009 The Go Authors. All rights reserved. -# Use of this source code is governed by a BSD-style -# license that can be found in the LICENSE file. - -RAWHTML=\ - articles/defer_panic_recover.rawhtml\ - articles/error_handling.rawhtml\ - articles/slices_usage_and_internals.rawhtml\ - articles/laws_of_reflection.rawhtml\ - articles/c_go_cgo.rawhtml\ - articles/concurrency_patterns.rawhtml\ - articles/godoc_documenting_go_code.rawhtml\ - articles/gobs_of_data.rawhtml\ - articles/json_and_go.rawhtml\ - articles/json_rpc_tale_of_interfaces.rawhtml\ - articles/image_draw.rawhtml\ - articles/image_package.rawhtml\ - effective_go.rawhtml\ - go1.rawhtml\ - -all: $(RAWHTML) - -%.rawhtml: %.html - godoc -url /doc/$< >$@ - -clean: - rm -f $(RAWHTML) - -compare: - for i in $(RAWHTML); do \ - godoc -url /doc/$${i/.rawhtml/.html} | diff -u $$i -; \ - done diff --git a/doc/articles/race_detector.html b/doc/articles/race_detector.html new file mode 100644 index 000000000..282db8ba4 --- /dev/null +++ b/doc/articles/race_detector.html @@ -0,0 +1,388 @@ +<!--{ + "Title": "Data Race Detector", + "Template": true +}--> + +<h2 id="Introduction">Introduction</h2> + +<p> +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> +Here is an example of a data race that can lead to crashes and memory corruption: +</p> + +<pre> +func main() { + c := make(chan bool) + m := make(map[string]string) + go func() { + m["1"] = "a" // First conflicting access. + c <- true + }() + m["2"] = "b" // Second conflicting access. + <-c + for k, v := range m { + fmt.Println(k, v) + } +} +</pre> + +<h2 id="Usage">Usage</h2> + +<p> +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> +$ go test -race mypkg // to test the package +$ go run -race mysrc.go // to run the source file +$ go build -race mycmd // to build the command +$ go install -race mypkg // to install the package +</pre> + +<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. +Here is an example: +</p> + +<pre> +WARNING: DATA RACE +Read by goroutine 185: + net.(*pollServer).AddFD() + src/pkg/net/fd_unix.go:89 +0x398 + net.(*pollServer).WaitWrite() + src/pkg/net/fd_unix.go:247 +0x45 + net.(*netFD).Write() + src/pkg/net/fd_unix.go:540 +0x4d4 + net.(*conn).Write() + src/pkg/net/net.go:129 +0x101 + net.func·060() + src/pkg/net/timeout_test.go:603 +0xaf + +Previous write by goroutine 184: + net.setWriteDeadline() + src/pkg/net/sockopt_posix.go:135 +0xdf + net.setDeadline() + src/pkg/net/sockopt_posix.go:144 +0x9c + net.(*conn).SetDeadline() + src/pkg/net/net.go:161 +0xe3 + net.func·061() + src/pkg/net/timeout_test.go:616 +0x3ed + +Goroutine 185 (running) created at: + net.func·061() + src/pkg/net/timeout_test.go:609 +0x288 + +Goroutine 184 (running) created at: + net.TestProlongTimeout() + src/pkg/net/timeout_test.go:618 +0x298 + testing.tRunner() + src/pkg/testing/testing.go:301 +0xe8 +</pre> + +<h2 id="Options">Options</h2> + +<p> +The <code>GORACE</code> environment variable sets race detector options. +The format is: +</p> + +<pre> +GORACE="option1=val1 option2=val2" +</pre> + +<p> +The options are: +</p> + +<ul> +<li> +<code>log_path</code> (default <code>stderr</code>): The race detector writes +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> + +<li> +<code>exitcode</code> (default <code>66</code>): The exit status to use when +exiting after a detected race. +</li> + +<li> +<code>strip_path_prefix</code> (default <code>""</code>): Strip this prefix +from all reported file paths, to make reports more concise. +</li> + +<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, at the +cost of increased memory usage. +</li> + +<li> +<code>halt_on_error</code> (default <code>0</code>): Controls whether the program +exits after reporting first data race. +</li> +</ul> + +<p> +Example: +</p> + +<pre> +$ GORACE="log_path=/tmp/race/report strip_path_prefix=/my/go/sources/" go test -race +</pre> + +<h2 id="Excluding_Tests">Excluding Tests</h2> + +<p> +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> +// +build !race + +package foo + +// The test contains a data race. See issue 123. +func TestFoo(t *testing.T) { + // ... +} + +// The test fails under the race detector due to timeouts. +func TestBar(t *testing.T) { + // ... +} + +// The test takes too long under the race detector. +func TestBaz(t *testing.T) { + // ... +} +</pre> + +<h2 id="How_To_Use">How To Use</h2> + +<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, +you may find more races by running a binary built with <code>-race</code> under a realistic +workload. +</p> + +<h2 id="Typical_Data_Races">Typical Data Races</h2> + +<p> +Here are some typical data races. All of them can be detected with the race detector. +</p> + +<h3 id="Race_on_loop_counter">Race on loop counter</h3> + +<pre> +func main() { + var wg sync.WaitGroup + wg.Add(5) + for i := 0; i < 5; i++ { + go func() { + fmt.Println(i) // Not the 'i' you are looking for. + wg.Done() + }() + } + wg.Wait() +} +</pre> + +<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: +</p> + +<pre> +func main() { + var wg sync.WaitGroup + wg.Add(5) + for i := 0; i < 5; i++ { + go func(j int) { + fmt.Println(j) // Good. Read local copy of the loop counter. + wg.Done() + }(i) + } + wg.Wait() +} +</pre> + +<h3 id="Accidentally_shared_variable">Accidentally shared variable</h3> + +<pre> +// ParallelWrite writes data to file1 and file2, returns the errors. +func ParallelWrite(data []byte) chan error { + res := make(chan error, 2) + f1, err := os.Create("file1") + if err != nil { + res <- err + } else { + go func() { + // This err is shared with the main goroutine, + // so the write races with the write below. + _, err = f1.Write(data) + res <- err + f1.Close() + }() + } + f2, err := os.Create("file2") // The second conflicting write to err. + if err != nil { + res <- err + } else { + go func() { + _, err = f2.Write(data) + res <- err + f2.Close() + }() + } + return res +} +</pre> + +<p> +The fix is to introduce new variables in the goroutines (note the use of <code>:=</code>): +</p> + +<pre> + ... + _, err := f1.Write(data) + ... + _, err := f2.Write(data) + ... +</pre> + +<h3 id="Unprotected_global_variable">Unprotected global variable</h3> + +<p> +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> +var service map[string]net.Addr + +func RegisterService(name string, addr net.Addr) { + service[name] = addr +} + +func LookupService(name string) net.Addr { + return service[name] +} +</pre> + +<p> +To make the code safe, protect the accesses with a mutex: +</p> + +<pre> +var ( + service map[string]net.Addr + serviceMu sync.Mutex +) + +func RegisterService(name string, addr net.Addr) { + serviceMu.Lock() + defer serviceMu.Unlock() + service[name] = addr +} + +func LookupService(name string) net.Addr { + serviceMu.Lock() + defer serviceMu.Unlock() + return service[name] +} +</pre> + +<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.), +as in this example: +</p> + +<pre> +type Watchdog struct{ last int64 } + +func (w *Watchdog) KeepAlive() { + w.last = time.Now().UnixNano() // First conflicting access. +} + +func (w *Watchdog) Start() { + go func() { + for { + time.Sleep(time.Second) + // Second conflicting access. + if w.last < time.Now().Add(-10*time.Second).UnixNano() { + fmt.Println("No keepalives for 10 seconds. Dying.") + os.Exit(1) + } + } + }() +} +</pre> + +<p> +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. +</p> + +<pre> +type Watchdog struct{ last int64 } + +func (w *Watchdog) KeepAlive() { + atomic.StoreInt64(&w.last, time.Now().UnixNano()) +} + +func (w *Watchdog) Start() { + go func() { + for { + time.Sleep(time.Second) + if atomic.LoadInt64(&w.last) < time.Now().Add(-10*time.Second).UnixNano() { + fmt.Println("No keepalives for 10 seconds. Dying.") + os.Exit(1) + } + } + }() +} +</pre> + +<h2 id="Supported_Systems">Supported Systems</h2> + +<p> +The race detector runs on <code>darwin/amd64</code>, <code>linux/amd64</code>, and <code>windows/amd64</code>. +</p> + +<h2 id="Runtime_Overheads">Runtime Overhead</h2> + +<p> +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. +</p> diff --git a/doc/articles/wiki/Makefile b/doc/articles/wiki/Makefile deleted file mode 100644 index e40b1311e..000000000 --- a/doc/articles/wiki/Makefile +++ /dev/null @@ -1,10 +0,0 @@ -# Copyright 2010 The Go Authors. All rights reserved. -# Use of this source code is governed by a BSD-style -# license that can be found in the LICENSE file. - -all: index.html - -CLEANFILES:=get.bin final-test.bin a.out - -clean: - rm -f $(CLEANFILES) diff --git a/doc/articles/wiki/final.go b/doc/articles/wiki/final.go index f15794d66..d84c1ffb2 100644 --- a/doc/articles/wiki/final.go +++ b/doc/articles/wiki/final.go @@ -5,12 +5,19 @@ package main import ( + "flag" "html/template" "io/ioutil" + "log" + "net" "net/http" "regexp" ) +var ( + addr = flag.Bool("addr", false, "find open address and print to final-port.txt") +) + type Page struct { Title string Body []byte @@ -81,8 +88,24 @@ func makeHandler(fn func(http.ResponseWriter, *http.Request, string)) http.Handl } func main() { + flag.Parse() http.HandleFunc("/view/", makeHandler(viewHandler)) http.HandleFunc("/edit/", makeHandler(editHandler)) http.HandleFunc("/save/", makeHandler(saveHandler)) + + if *addr { + l, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + log.Fatal(err) + } + err = ioutil.WriteFile("final-port.txt", []byte(l.Addr().String()), 0644) + if err != nil { + log.Fatal(err) + } + s := &http.Server{} + s.Serve(l) + return + } + http.ListenAndServe(":8080", nil) } diff --git a/doc/articles/wiki/index.html b/doc/articles/wiki/index.html index 7bf7213e8..b6b080df9 100644 --- a/doc/articles/wiki/index.html +++ b/doc/articles/wiki/index.html @@ -466,7 +466,7 @@ header to the HTTP response. <p> The function <code>saveHandler</code> will handle the submission of forms located on the edit pages. After uncommenting the related line in -<code>main</code>, let's implement the the handler: +<code>main</code>, let's implement the handler: </p> {{code "doc/articles/wiki/final-template.go" `/^func saveHandler/` `/^}/`}} diff --git a/doc/articles/wiki/test.bash b/doc/articles/wiki/test.bash index 54a632c30..2997f1680 100755 --- a/doc/articles/wiki/test.bash +++ b/doc/articles/wiki/test.bash @@ -7,10 +7,12 @@ set -e wiki_pid= cleanup() { kill $wiki_pid - rm -f test_*.out Test.txt final-test.bin final-test.go a.out get.bin + rm -f test_*.out Test.txt final.bin final-port.txt a.out get.bin } trap cleanup 0 INT +rm -f get.bin final.bin a.out + # If called with -all, check that all code snippets compile. if [ "$1" == "-all" ]; then for fn in *.go; do @@ -19,13 +21,25 @@ if [ "$1" == "-all" ]; then fi go build -o get.bin get.go -addr=$(./get.bin -addr) -sed s/:8080/$addr/ < final.go > final-test.go -go build -o final-test.bin final-test.go -(./final-test.bin) & +go build -o final.bin final.go +(./final.bin --addr) & wiki_pid=$! -./get.bin --wait_for_port=5s http://$addr/edit/Test > test_edit.out +l=0 +while [ ! -f ./final-port.txt ] +do + l=$(($l+1)) + if [ "$l" -gt 5 ] + then + echo "port not available within 5 seconds" + exit 1 + break + fi + sleep 1 +done + +addr=$(cat final-port.txt) +./get.bin http://$addr/edit/Test > test_edit.out diff -u test_edit.out test_edit.good ./get.bin -post=body=some%20content http://$addr/save/Test > test_save.out diff -u test_save.out test_view.good # should be the same as viewing diff --git a/doc/asm.html b/doc/asm.html index b855b9ef7..d44cb799d 100644 --- a/doc/asm.html +++ b/doc/asm.html @@ -8,7 +8,11 @@ <p> This document is a quick outline of the unusual form of assembly language used by the <code>gc</code> suite of Go compilers (<code>6g</code>, <code>8g</code>, etc.). -It is based on the input to the Plan 9 assemblers, which is documented in detail +The document is not comprehensive. +</p> + +<p> +The assembler is based on the input to the Plan 9 assemblers, which is documented in detail <a href="http://plan9.bell-labs.com/sys/doc/asm.html">on the Plan 9 site</a>. If you plan to write assembly language, you should read that document although much of it is Plan 9-specific. This document provides a summary of the syntax and @@ -70,6 +74,8 @@ The <code>FUNCDATA</code> and <code>PCDATA</code> directives contain information for use by the garbage collector; they are introduced by the compiler. </p> +<!-- Commenting out because the feature is gone but it's popular and may come back. + <p> To see what gets put in the binary after linking, add the <code>-a</code> flag to the linker: </p> @@ -98,6 +104,7 @@ codeblk [0x2000,0x1d059) at offset 0x1000 ... </pre> +--> <h3 id="symbols">Symbols</h3> @@ -194,7 +201,7 @@ TEXT runtime·profileloop(SB),NOSPLIT,$8 <p> In the general case, the frame size is followed by an argument size, separated by a minus sign. -(It's not an subtraction, just idiosyncratic syntax.) +(It's not a subtraction, just idiosyncratic syntax.) The frame size <code>$24-8</code> states that the function has a 24-byte frame and is called with 8 bytes of argument, which live on the caller's frame. If <code>NOSPLIT</code> is not specified for the <code>TEXT</code>, diff --git a/doc/codewalk/sharemem.xml b/doc/codewalk/sharemem.xml index d443e176e..8b47f12b7 100644 --- a/doc/codewalk/sharemem.xml +++ b/doc/codewalk/sharemem.xml @@ -171,7 +171,7 @@ and/or writes to a shared map. <step title="Conclusion" src="doc/codewalk/urlpoll.go"> In this codewalk we have explored a simple example of using Go's concurrency -primitives to share memory through commmunication. +primitives to share memory through communication. <br/><br/> This should provide a starting point from which to explore the ways in which goroutines and channels can be used to write expressive and concise concurrent diff --git a/doc/contrib.html b/doc/contrib.html index 048a5d97f..6529c91d5 100644 --- a/doc/contrib.html +++ b/doc/contrib.html @@ -37,16 +37,13 @@ We encourage all Go users to subscribe to A guide for updating your code to work with Go 1. </p> -<h4 id="go1.1notes"><a href="/doc/go1.1">Go 1.1 Release Notes</a></h4> +<h4 id="release notes"><a href="/doc/go1.1">Go 1.1 Release Notes</a></h4> <p> -A list of significant changes in Go 1.1, with instructions for updating your -code where necessary. -</p> - -<h4 id="go1.2notes"><a href="/doc/go1.2">Go 1.2 Release Notes</a></h4> -<p> -A list of significant changes in Go 1.2, with instructions for updating your -code where necessary. +A list of significant changes in Go 1.1, with instructions for updating +your code where necessary. +Each point release includes a similar document appropriate for that +release: <a href="/doc/go1.2">Go 1.2</a>, <a href="/doc/go1.3">Go 1.3</a>, +and so on. </p> <h3 id="go1compat"><a href="/doc/go1compat">Go 1 and the Future of Go Programs</a></h3> @@ -61,15 +58,22 @@ Go 1 matures. <h3 id="source"><a href="https://code.google.com/p/go/source">Source Code</a></h3> <p>Check out the Go source code.</p> -<h3 id="golang-dev"><a href="http://groups.google.com/group/golang-dev">Developer Mailing List</a></h3> -<p>The <a href="http://groups.google.com/group/golang-dev">golang-dev</a> -mailing list is for discussing and reviewing code for the Go project.</p> +<h3 id="golang-dev"><a href="https://groups.google.com/group/golang-dev">Developer</a> and +<a href="https://groups.google.com/group/golang-codereviews">Code Review Mailing List</a></h3> +<p>The <a href="https://groups.google.com/group/golang-dev">golang-dev</a> +mailing list is for discussing code changes to the Go project. +The <a href="https://groups.google.com/group/golang-codereviews">golang-codereviews</a> +mailing list is for actual reviewing of the code changes (CLs).</p> + <p>For general discussion of Go programming, see <a -href="http://groups.google.com/group/golang-nuts">golang-nuts</a>.</p> +href="https://groups.google.com/group/golang-nuts">golang-nuts</a>.</p> -<h3 id="golang-checkins"><a href="http://groups.google.com/group/golang-checkins">Checkins Mailing List</a></h3> +<h3 id="golang-checkins"><a href="https://groups.google.com/group/golang-checkins">Checkins Mailing List</a></h3> <p>A mailing list that receives a message summarizing each checkin to the Go repository.</p> +<h3 id="golang-bugs"><a href="https://groups.google.com/group/golang-bugs">Bugs Mailing List</a></h3> +<p>A mailing list that receives each update to the Go <a href="http://golang.org/issue">issue tracker</a>.</p> + <h3 id="build_status"><a href="http://build.golang.org/">Build Status</a></h3> <p>View the status of Go builds across the supported operating systems and architectures.</p> @@ -77,13 +81,13 @@ systems and architectures.</p> <h2 id="howto">How you can help</h2> -<h3><a href="http://code.google.com/p/go/issues">Reporting issues</a></h3> +<h3><a href="https://code.google.com/p/go/issues">Reporting issues</a></h3> <p> If you spot bugs, mistakes, or inconsistencies in the Go project's code or documentation, please let us know by -<a href="http://code.google.com/p/go/issues/entry">filing a ticket</a> -on our <a href="http://code.google.com/p/go/issues">issue tracker</a>. +<a href="https://code.google.com/p/go/issues/entry">filing a ticket</a> +on our <a href="https://code.google.com/p/go/issues">issue tracker</a>. (Of course, you should check it's not an existing issue before creating a new one.) </p> @@ -102,8 +106,8 @@ To get started, read these <a href="/doc/contribute.html">contribution guidelines</a> for information on design, testing, and our code review process. </p> <p> -Check <a href="http://code.google.com/p/go/issues">the tracker</a> for +Check <a href="https://code.google.com/p/go/issues">the tracker</a> for open issues that interest you. Those labeled -<a href="http://code.google.com/p/go/issues/list?q=status=HelpWanted">HelpWanted</a> +<a href="https://code.google.com/p/go/issues/list?q=status=HelpWanted">HelpWanted</a> are particularly in need of outside help. </p> diff --git a/doc/contribute.html b/doc/contribute.html index 716a1849e..392734985 100644 --- a/doc/contribute.html +++ b/doc/contribute.html @@ -22,7 +22,7 @@ you're working on if you want it to become part of the main repository. <p> Before undertaking to write something new for the Go project, send -mail to the <a href="http://groups.google.com/group/golang-nuts">mailing +mail to the <a href="https://groups.google.com/group/golang-nuts">mailing list</a> to discuss what you plan to do. This gives everyone a chance to validate the design, helps prevent duplication of effort, and ensures that the idea fits inside the goals for the language @@ -45,11 +45,15 @@ tree to make sure the changes don't break other packages or programs: </p> <pre> -cd $GOROOT/src -./all.bash # On Windows, run all.bat +$ cd go/src +$ ./all.bash </pre> <p> +(To build under Windows use <code>all.bat</code>.) +</p> + +<p> After running for a while, the command should print "<code>ALL TESTS PASSED</code>". </p> @@ -95,11 +99,11 @@ command. <h3>Configure the extension</h3> -<p>Edit <code>$GOROOT/.hg/hgrc</code> to add:</p> +<p>Edit <code>.hg/hgrc</code> in the root of your Go checkout to add:</p> <pre> [extensions] -codereview = $GOROOT/lib/codereview/codereview.py +codereview = /path/to/go/lib/codereview/codereview.py [ui] username = Your Name <you@server.dom> @@ -110,6 +114,16 @@ The <code>username</code> information will not be used unless you are a committer (see below), but Mercurial complains if it is missing. </p> +<p> +As the codereview extension is only enabled for your Go checkout, the remainder of this document assumes you +are inside the go directory when issuing commands. +</p> + +<p>To contribute to subrepositories, edit the <code>.hg/hgrc</code> for each +subrepository in the same way. For example, add the codereview extension to +<code>code.google.com/p/go.tools/.hg/hgrc</code>. +</p> + <h3>Understanding the extension</h3> <p>After adding the code review extension, you can run</p> @@ -126,16 +140,10 @@ $ hg help change </pre> <p> -As the codereview extension is only enabled for your checkout -in <code>$GOROOT</code>, the remainder of this document assumes you -are inside <code>$GOROOT</code> when issuing commands. -</p> - -<p> -Windows users may need to perform extra steps to get the code review +Windows users may need to perform extra steps to get the code review extension working. See the -<a href="https://code.google.com/p/go-wiki/wiki/CodeReview">CodeReview page</a> -on the <a href="http://code.google.com/p/go-wiki/wiki">Go Wiki</a> for details. +<a href="https://code.google.com/p/go-wiki/wiki/CodeReview">CodeReview page</a> +on the <a href="https://code.google.com/p/go-wiki/wiki">Go Wiki</a> for details. </p> <h3>Log in to the code review site.</h3> @@ -146,7 +154,7 @@ The code review server uses a Google Account to authenticate. <a href="https://www.google.com/accounts/Login?hl=en&continue=http://www.google.com/">sign in at google.com</a>, you can use it to sign in to the code review server.) The email address you use on the Code Review site -will be recorded in the <a href="http://code.google.com/p/go/source/list">Mercurial change log</a> +will be recorded in the <a href="https://code.google.com/p/go/source/list">Mercurial change log</a> and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file. You can <a href="https://www.google.com/accounts/NewAccount">create a Google Account</a> associated with any address where you receive email. @@ -155,7 +163,6 @@ application-specific password and use that when prompted for a password. </p> <pre> -$ cd $GOROOT $ hg code-login Email (login for uploading to codereview.appspot.com): rsc@golang.org Password for rsc@golang.org: @@ -165,7 +172,7 @@ Saving authentication cookies to /Users/rsc/.codereview_upload_cookies_coderevie <h3>Configure your account settings.</h3> -<p>Edit your <a href="http://codereview.appspot.com/settings">code review settings</a>. +<p>Edit your <a href="https://codereview.appspot.com/settings">code review settings</a>. Grab a nickname. Many people prefer to set the Context option to “Whole file” to see more context when reviewing changes. @@ -240,7 +247,7 @@ These can be code review nicknames or arbitrary email addresses. Unless explicitly told otherwise, such as in the discussion leading up to sending in the change list, leave the reviewer field blank. This means that the -<a href="http://groups.google.com/group/golang-dev">golang-dev@googlegroups.com</a> +<a href="https://groups.google.com/group/golang-codereviews">golang-codereviews@googlegroups.com</a> mailing list will be used as the reviewer. </p> @@ -270,7 +277,7 @@ After editing, the template might now read: # Lines beginning with # are ignored. # Multi-line values should be indented. -Reviewer: golang-dev@googlegroups.com +Reviewer: golang-codereviews@googlegroups.com CC: math-nuts@swtch.com Description: @@ -286,11 +293,11 @@ Files: <p> The special sentence “Fixes issue 159.” associates -the change with issue 159 in the <a href="http://code.google.com/p/go/issues/list">Go issue tracker</a>. +the change with issue 159 in the <a href="https://code.google.com/p/go/issues/list">Go issue tracker</a>. When this change is eventually submitted, the issue tracker will automatically mark the issue as fixed. (These conventions are described in detail by the -<a href="http://code.google.com/p/support/wiki/IssueTracker#Integration_with_version_control">Google Project Hosting Issue Tracker documentation</a>.) +<a href="https://code.google.com/p/support/wiki/IssueTracker#Integration_with_version_control">Google Project Hosting Issue Tracker documentation</a>.) </p> <p> @@ -302,7 +309,7 @@ which <code>hg change</code> will print, something like: </p> <pre> -CL created: http://codereview.appspot.com/99999 +CL created: https://codereview.appspot.com/99999 </pre> <h3>Adding or removing files from an existing change</h3> @@ -448,7 +455,7 @@ lines blank and then run: </p> <pre> -$ hg mail -r golang-dev@googlegroups.com --cc math-nuts@swtch.com 99999 +$ hg mail -r golang-codereviews@googlegroups.com --cc math-nuts@swtch.com 99999 </pre> <p>to achieve the same effect.</p> @@ -473,31 +480,33 @@ to send comments back. <h3>Revise and upload</h3> <p> -You will probably revise your code in response to the reviewer comments. When -you have done this, you can upload your change to the code review server -without sending a notification by running <code>hg upload</code> using the change -list number assigned during <code>hg change</code> +When you have revised the code and are ready for another round of review, +you can upload your change and send mail asking the reviewers to +please take another look (<code>PTAL</code>). Use the change list number +assigned during <code>hg change</code> </p> <pre> -$ hg upload 99999 +$ hg mail 99999 </pre> + <p> -When you have revised the code and are ready for another round of review, run +Or to upload your change without sending a notification, run </p> <pre> -$ hg mail 99999 +$ hg upload 99999 </pre> -<p>again to upload the latest copy and send mail asking the reviewers to please take another look -(<code>PTAL</code>). +<p> +You will probably revise your code in response to the reviewer comments. You might also visit the code review web page and reply to the comments, letting the reviewer know that you've addressed them or explain why you haven't. When you're done replying, click “Publish and Mail comments” to send the line-by-line replies and any other comments. </p> + <p> The reviewer can comment on the new copy, and the process repeats. The reviewer approves the change by replying with a mail that says @@ -597,11 +606,18 @@ $ hg submit 99999 local repository out of date; must sync before submit </pre> +<h3>More information</h3> + +<p> +In addition to the information here, the Go community maintains a <a href="https://code.google.com/p/go-wiki/wiki/CodeReview">CodeReview</a> wiki page. +Feel free to contribute to this page as you learn the review process. +</p> + <h2 id="copyright">Copyright</h2> <p>Files in the Go repository don't list author names, both to avoid clutter and to avoid having to keep the lists up to date. -Instead, your name will appear in the <a href="http://code.google.com/p/go/source/list">Mercurial change log</a> +Instead, your name will appear in the <a href="https://code.google.com/p/go/source/list">Mercurial change log</a> and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file and perhaps the <a href="/AUTHORS"><code>AUTHORS</code></a> file. </p> @@ -616,13 +632,15 @@ In order for them to do that, you need to have completed one of the contributor license agreements: <ul> <li> -If you are the copyright holder, you will need to agree to -the <a href="http://code.google.com/legal/individual-cla-v1.0.html">individual +If you are the copyright holder, you will need to agree to the +<a href="https://developers.google.com/open-source/cla/individual">individual contributor license agreement</a>, which can be completed online. </li> <li> If your organization is the copyright holder, the organization -will need to agree to the <a href="http://code.google.com/legal/corporate-cla-v1.0.html">corporate contributor license agreement</a>. +will need to agree to the +<a href="https://developers.google.com/open-source/cla/corporate">corporate +contributor license agreement</a>. (If the copyright holder for your code has already completed the agreement in connection with another Google open source project, it does not need to be completed again.) @@ -636,7 +654,7 @@ This rigmarole needs to be done only for your first submission. <p>Code that you contribute should use the standard copyright header:</p> <pre> -// Copyright 2013 The Go Authors. All rights reserved. +// Copyright 2014 The Go Authors. All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. </pre> diff --git a/doc/debugging_with_gdb.html b/doc/debugging_with_gdb.html index b893f931a..afaedf74c 100644 --- a/doc/debugging_with_gdb.html +++ b/doc/debugging_with_gdb.html @@ -9,6 +9,23 @@ Besides this overview you might want to consult the <a href="http://sourceware.org/gdb/current/onlinedocs/gdb/">GDB manual</a>. </i></p> +<p> +GDB does not understand Go programs well. +The stack management, threading, and runtime contain aspects that differ +enough from the execution model GDB expects that they can confuse +the debugger, even when the program is compiled with gccgo. +As a consequence, although GDB can be useful in some situations, it is +not a reliable debugger for Go programs, particularly heavily concurrent ones. +Moreover, it is not a priority for the Go project to address these issues, which +are difficult. +In short, the instructions below should be taken only as a guide to how +to use GDB when it works, not as a guarantee of success. +</p> + +<p> +In time, a more Go-centric debugging architecture may be required. +</p> + <h2 id="Introduction">Introduction</h2> <p> @@ -19,8 +36,8 @@ use to inspect a live process or a core dump. </p> <p> -Pass the <code>'-s'</code> flag to the linker to omit the debug information -(for example, <code>go build -ldflags "-s" prog.go</code>). +Pass the <code>'-w'</code> flag to the linker to omit the debug information +(for example, <code>go build -ldflags "-w" prog.go</code>). </p> <p> diff --git a/doc/devel/release.html b/doc/devel/release.html index 5511db71b..3a3d5bc13 100644 --- a/doc/devel/release.html +++ b/doc/devel/release.html @@ -13,12 +13,38 @@ hg pull hg update <i>tag</i> </pre> +<h2 id="go1.3">go1.3 (released 2014/06/18)</h2> + +<p> +Go 1.3 is a major release of Go. +Read the <a href="/doc/go1.3">Go 1.3 Release Notes</a> for more information. +</p> + +<h2 id="go1.2">go1.2 (released 2013/12/01)</h2> + +<p> +Go 1.2 is a major release of Go. +Read the <a href="/doc/go1.2">Go 1.2 Release Notes</a> for more information. +</p> + +<h3 id="go1.2.minor">Minor revisions</h3> + +<p> +go1.2.1 (released 2014/03/02) includes bug fixes to the <code>runtime</code>, <code>net</code>, and <code>database/sql</code> packages. +See the <a href="https://code.google.com/p/go/source/list?name=release-branch.go1.2&r=7ada9e760ce34e78aee5b476c9621556d0fa5d31">change history</a> for details. +</p> + +<p> +go1.2.2 (released 2014/05/05) includes a +<a href="https://code.google.com/p/go/source/detail?r=bda3619e7a2c&repo=tools">security fix</a> +that affects the tour binary included in the binary distributions (thanks to Guillaume T). +</p> + <h2 id="go1.1">go1.1 (released 2013/05/13)</h2> <p> Go 1.1 is a major release of Go. -Read the <a href="/doc/go1.1.html">Go 1.1 Release Notes</a> for -more information. +Read the <a href="/doc/go1.1">Go 1.1 Release Notes</a> for more information. </p> <h3 id="go1.1.minor">Minor revisions</h3> @@ -363,12 +389,6 @@ variable to build and install your own code and external libraries outside of the Go tree (and avoid writing Makefiles). </p> -<h3 id="go1.2.minor">Minor revisions</h3> - -<p> -go1.2.1 (released 2014/03/02) includes bug fixes to the <code>runtime</code>, <code>net</code>, and <code>database/sql</code> packages. -See the <a href="https://code.google.com/p/go/source/list?name=release-branch.go1.2&r=7ada9e760ce34e78aee5b476c9621556d0fa5d31">change history</a> for details. -</p> <h3 id="r58.minor">Minor revisions</h3> diff --git a/doc/docs.html b/doc/docs.html index 7aad8dadf..bb2d52dcb 100644 --- a/doc/docs.html +++ b/doc/docs.html @@ -97,6 +97,9 @@ one goroutine can be guaranteed to observe values produced by writes to the same variable in a different goroutine. </p> +<h3 id="release"><a href="/doc/devel/release.html">Release History</a></h3> +<p>A summary of the changes between Go releases.</p> + <h2 id="articles">Articles</h2> @@ -143,7 +146,9 @@ Guided tours of Go programs. <li><a href="/doc/gdb">Debugging Go Code with GDB</a></li> <li><a href="/blog/godoc-documenting-go-code">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li> <li><a href="/blog/profiling-go-programs">Profiling Go Programs</a></li> -<li><a href="/blog/race-detector">Data Race Detector</a> - testing Go programs for race conditions.</li> +<li><a href="/doc/articles/race_detector.html">Data Race Detector</a> - a manual for the data race detector.</li> +<li><a href="/blog/race-detector">Introducing the Go Race Detector</a> - an introduction to the race detector. +<li><a href="/doc/asm">A Quick Guide to Go's Assembler</a> - an introduction to the assembler used by Go. </ul> <h4 id="articles_more">More</h4> diff --git a/doc/effective_go.html b/doc/effective_go.html index f9199511a..25266d6ab 100644 --- a/doc/effective_go.html +++ b/doc/effective_go.html @@ -214,7 +214,7 @@ not be used. One adjustment <code>godoc</code> does do is to display indented text in a fixed-width font, suitable for program snippets. The package comment for the -<a href="http://golang.org/pkg/fmt/"><code>fmt</code> package</a> uses this to good effect. +<a href="/pkg/fmt/"><code>fmt</code> package</a> uses this to good effect. </p> <p> @@ -288,7 +288,7 @@ var ( </pre> <p> -Even for private names, grouping can also indicate relationships between items, +Grouping can also indicate relationships between items, such as the fact that a set of variables is protected by a mutex. </p> @@ -350,7 +350,7 @@ not <code>encoding_base64</code> and not <code>encodingBase64</code>. </p> <p> -The importer of a package will use the name to refer to its contents. +The importer of a package will use the name to refer to its contents, so exported names in the package can use that fact to avoid stutter. (Don't use the <code>import .</code> notation, which can simplify @@ -701,6 +701,7 @@ for _, value := range array { <p> The blank identifier has many uses, as described in <a href="#blank">a later section</a>. +</p> <p> For strings, the <code>range</code> does more work for you, breaking out individual @@ -709,7 +710,7 @@ Erroneous encodings consume one byte and produce the replacement rune U+FFFD. (The name (with associated builtin type) <code>rune</code> is Go terminology for a single Unicode code point. -See <a href="http://golang.org/ref/spec#Rune_literals">the language specification</a> +See <a href="/ref/spec#Rune_literals">the language specification</a> for details.) The loop </p> @@ -849,7 +850,7 @@ func Compare(a, b []byte) int { } </pre> -<h2 id="type_switch">Type switch</h2> +<h3 id="type_switch">Type switch</h3> <p> A switch can also be used to discover the dynamic type of an interface @@ -1385,8 +1386,9 @@ func (file *File) Read(buf []byte) (n int, err error) </pre> <p> The method returns the number of bytes read and an error value, if -any. To read into the first 32 bytes of a larger buffer -<code>b</code>, <i>slice</i> (here used as a verb) the buffer. +any. +To read into the first 32 bytes of a larger buffer +<code>buf</code>, <i>slice</i> (here used as a verb) the buffer. </p> <pre> n, err := f.Read(buf[0:32]) @@ -1487,7 +1489,7 @@ If the slices might grow or shrink, they should be allocated independently to avoid overwriting the next line; if not, it can be more efficient to construct the object with a single allocation. For reference, here are sketches of the two methods. -First, a line a time: +First, a line at a time: </p> <pre> @@ -2054,10 +2056,22 @@ We pass the address of a <code>ByteSlice</code> because only <code>*ByteSlice</code> satisfies <code>io.Writer</code>. The rule about pointers vs. values for receivers is that value methods can be invoked on pointers and values, but pointer methods can only be -invoked on pointers. This is because pointer methods can modify the -receiver; invoking them on a copy of the value would cause those -modifications to be discarded. +invoked on pointers. </p> + +<p> +This rule arises because pointer methods can modify the receiver; invoking +them on a value would cause the method to receive a copy of the value, so +any modifications would be discarded. +The language therefore disallows this mistake. +There is a handy exception, though. When the value is addressable, the +language takes care of the common case of invoking a pointer method on a +value by inserting the address operator automatically. +In our example, the variable <code>b</code> is addressable, so we can call +its <code>Write</code> method with just <code>b.Write</code>. The compiler +will rewrite that to <code>(&b).Write</code> for us. +</p> + <p> By the way, the idea of using <code>Write</code> on a slice of bytes is central to the implementation of <code>bytes.Buffer</code>. @@ -2173,6 +2187,7 @@ A one-case type switch would do, but so would a <em>type assertion</em>. A type assertion takes an interface value and extracts from it a value of the specified explicit type. The syntax borrows from the clause opening a type switch, but with an explicit type rather than the <code>type</code> keyword: +</p> <pre> value.(typeName) @@ -2463,6 +2478,8 @@ It has uses beyond those we've seen already. <p> The use of a blank identifier in a <code>for</code> <code>range</code> loop is a special case of a general situation: multiple assignment. +</p> + <p> If an assignment requires multiple values on the left side, but one of the values will not be used by the program, @@ -2937,26 +2954,19 @@ means waiting until some receiver has retrieved a value. <p> A buffered channel can be used like a semaphore, for instance to limit throughput. In this example, incoming requests are passed -to <code>handle</code>, which receives a value from the channel, processes -the request, and then sends a value back to the channel -to ready the "semaphore" for the next consumer. +to <code>handle</code>, which sends a value into the channel, processes +the request, and then receives a value from the channel +to ready the “semaphore” for the next consumer. The capacity of the channel buffer limits the number of -simultaneous calls to <code>process</code>, -so during initialization we prime the channel by filling it to capacity. +simultaneous calls to <code>process</code>. </p> <pre> var sem = make(chan int, MaxOutstanding) func handle(r *Request) { - <-sem // Wait for active queue to drain. - process(r) // May take a long time. - sem <- 1 // Done; enable next request to run. -} - -func init() { - for i := 0; i < MaxOutstanding; i++ { - sem <- 1 - } + sem <- 1 // Wait for active queue to drain. + process(r) // May take a long time. + <-sem // Done; enable next request to run. } func Serve(queue chan *Request) { @@ -2968,10 +2978,9 @@ func Serve(queue chan *Request) { </pre> <p> -Because data synchronization occurs on a receive from a channel -(that is, the send "happens before" the receive; see -<a href="/ref/mem">The Go Memory Model</a>), -acquisition of the semaphore must be on a channel receive, not a send. +Once <code>MaxOutstanding</code> handlers are executing <code>process</code>, +any more will block trying to send into the filled channel buffer, +until one of the existing handlers finishes and receives from the buffer. </p> <p> @@ -2988,10 +2997,10 @@ Here's an obvious solution, but beware it has a bug we'll fix subsequently: <pre> func Serve(queue chan *Request) { for req := range queue { - <-sem + sem <- 1 go func() { process(req) // Buggy; see explanation below. - sem <- 1 + <-sem }() } }</pre> @@ -3009,10 +3018,10 @@ to the closure in the goroutine: <pre> func Serve(queue chan *Request) { for req := range queue { - <-sem + sem <- 1 go func(req *Request) { process(req) - sem <- 1 + <-sem }(req) } }</pre> @@ -3027,11 +3036,11 @@ name, as in this example: <pre> func Serve(queue chan *Request) { for req := range queue { - <-sem req := req // Create new instance of req for the goroutine. + sem <- 1 go func() { process(req) - sem <- 1 + <-sem }() } }</pre> @@ -3278,9 +3287,18 @@ the garbage collector for bookkeeping. <p> Library routines must often return some sort of error indication to -the caller. As mentioned earlier, Go's multivalue return makes it +the caller. +As mentioned earlier, Go's multivalue return makes it easy to return a detailed error description alongside the normal -return value. By convention, errors have type <code>error</code>, +return value. +It is good style to use this feature to provide detailed error information. +For example, as we'll see, <code>os.Open</code> doesn't +just return a <code>nil</code> pointer on failure, it also returns an +error value that describes what went wrong. +</p> + +<p> +By convention, errors have type <code>error</code>, a simple built-in interface. </p> <pre> @@ -3292,7 +3310,12 @@ type error interface { A library writer is free to implement this interface with a richer model under the covers, making it possible not only to see the error but also to provide some context. -For example, <code>os.Open</code> returns an <code>os.PathError</code>. +As mentioned, alongside the usual <code>*os.File</code> +return value, <code>os.Open</code> also returns an +error value. +If the file is opened successfully, the error will be <code>nil</code>, +but when there is a problem, it will hold an +<code>os.PathError</code>: </p> <pre> // PathError records an error and the operation and diff --git a/doc/gccgo_install.html b/doc/gccgo_install.html index eef5ac220..4c1a8c2f5 100644 --- a/doc/gccgo_install.html +++ b/doc/gccgo_install.html @@ -291,9 +291,9 @@ first one that it finds. <ul> <li><code><var>FILE</var>.gox</code> -<li><code><var>FILE</var>.o</code> <li><code>lib<var>FILE</var>.so</code> <li><code>lib<var>FILE</var>.a</code> +<li><code><var>FILE</var>.o</code> </ul> <p> @@ -522,4 +522,4 @@ port is for x86. The goal is to extend the port to most of the <a href="http://www.rtems.org/wiki/index.php/SupportedCPUs"> architectures supported by <code>RTEMS</code></a>. For more information on the port, as well as instructions on how to install it, please see this -<a href="http://www.rtems.com/wiki/index.php/GCCGoRTEMS"><code>RTEMS</code> Wiki page</a>. +<a href="http://www.rtems.org/wiki/index.php/GCCGoRTEMS"><code>RTEMS</code> Wiki page</a>. diff --git a/doc/go1.3.html b/doc/go1.3.html new file mode 100644 index 000000000..ae5c02598 --- /dev/null +++ b/doc/go1.3.html @@ -0,0 +1,599 @@ +<!--{ + "Title": "Go 1.3 Release Notes", + "Path": "/doc/go1.3", + "Template": true +}--> + +<h2 id="introduction">Introduction to Go 1.3</h2> + +<p> +The latest Go release, version 1.3, arrives six months after 1.2, +and contains no language changes. +It focuses primarily on implementation work, providing +precise garbage collection, +a major refactoring of the compiler tool chain that results in +faster builds, especially for large projects, +significant performance improvements across the board, +and support for DragonFly BSD, Solaris, Plan 9 and Google's Native Client architecture (NaCl). +It also has an important refinement to the memory model regarding synchronization. +As always, Go 1.3 keeps the <a href="/doc/go1compat.html">promise +of compatibility</a>, +and almost everything +will continue to compile and run without change when moved to 1.3. +</p> + +<h2 id="os">Changes to the supported operating systems and architectures</h2> + +<h3 id="win2000">Removal of support for Windows 2000</h3> + +<p> +Microsoft stopped supporting Windows 2000 in 2010. +Since it has <a href="https://codereview.appspot.com/74790043">implementation difficulties</a> +regarding exception handling (signals in Unix terminology), +as of Go 1.3 it is not supported by Go either. +</p> + +<h3 id="dragonfly">Support for DragonFly BSD</h3> + +<p> +Go 1.3 now includes experimental support for DragonFly BSD on the <code>amd64</code> (64-bit x86) and <code>386</code> (32-bit x86) architectures. +It uses DragonFly BSD 3.6 or above. +</p> + +<h3 id="freebsd">Support for FreeBSD</h3> + +<p> +It was not announced at the time, but since the release of Go 1.2, support for Go on FreeBSD +requires FreeBSD 8 or above. +</p> + +<p> +As of Go 1.3, support for Go on FreeBSD requires that the kernel be compiled with the +<code>COMPAT_FREEBSD32</code> flag configured. +</p> + +<p> +In concert with the switch to EABI syscalls for ARM platforms, Go 1.3 will run only on FreeBSD 10. +The x86 platforms, 386 and amd64, are unaffected. +</p> + +<h3 id="nacl">Support for Native Client</h3> + +<p> +Support for the Native Client virtual machine architecture has returned to Go with the 1.3 release. +It runs on the 32-bit Intel architectures (<code>GOARCH=386</code>) and also on 64-bit Intel, but using +32-bit pointers (<code>GOARCH=amd64p32</code>). +There is not yet support for Native Client on ARM. +Note that this is Native Client (NaCl), not Portable Native Client (PNaCl). +Details about Native Client are <a href="https://developers.google.com/native-client/dev/">here</a>; +how to set up the Go version is described <a href="http://golang.org/wiki/NativeClient">here</a>. +</p> + +<h3 id="netbsd">Support for NetBSD</h3> + +<p> +As of Go 1.3, support for Go on NetBSD requires NetBSD 6.0 or above. +</p> + +<h3 id="openbsd">Support for OpenBSD</h3> + +<p> +As of Go 1.3, support for Go on OpenBSD requires OpenBSD 5.5 or above. +</p> + +<h3 id="plan9">Support for Plan 9</h3> + +<p> +Go 1.3 now includes experimental support for Plan 9 on the <code>386</code> (32-bit x86) architecture. +It requires the <code>Tsemacquire</code> syscall, which has been in Plan 9 since June, 2012. +</p> + +<h3 id="solaris">Support for Solaris</h3> + +<p> +Go 1.3 now includes experimental support for Solaris on the <code>amd64</code> (64-bit x86) architecture. +It requires illumos, Solaris 11 or above. +</p> + +<h2 id="memory">Changes to the memory model</h2> + +<p> +The Go 1.3 memory model <a href="https://codereview.appspot.com/75130045">adds a new rule</a> +concerning sending and receiving on buffered channels, +to make explicit that a buffered channel can be used as a simple +semaphore, using a send into the +channel to acquire and a receive from the channel to release. +This is not a language change, just a clarification about an expected property of communication. +</p> + +<h2 id="impl">Changes to the implementations and tools</h2> + +<h3 id="stacks">Stack</h3> + +<p> +Go 1.3 has changed the implementation of goroutine stacks away from the old, +"segmented" model to a contiguous model. +When a goroutine needs more stack +than is available, its stack is transferred to a larger single block of memory. +The overhead of this transfer operation amortizes well and eliminates the old "hot spot" +problem when a calculation repeatedly steps across a segment boundary. +Details including performance numbers are in this +<a href="http://golang.org/s/contigstacks">design document</a>. +</p> + +<h3 id="garbage_collector">Changes to the garbage collector</h3> + +<p> +For a while now, the garbage collector has been <em>precise</em> when examining +values in the heap; the Go 1.3 release adds equivalent precision to values on the stack. +This means that a non-pointer Go value such as an integer will never be mistaken for a +pointer and prevent unused memory from being reclaimed. +</p> + +<p> +Starting with Go 1.3, the runtime assumes that values with pointer type +contain pointers and other values do not. +This assumption is fundamental to the precise behavior of both stack expansion +and garbage collection. +Programs that use <a href="/pkg/unsafe/">package unsafe</a> +to store integers in pointer-typed values are illegal and will crash if the runtime detects the behavior. +Programs that use <a href="/pkg/unsafe/">package unsafe</a> to store pointers +in integer-typed values are also illegal but more difficult to diagnose during execution. +Because the pointers are hidden from the runtime, a stack expansion or garbage collection +may reclaim the memory they point at, creating +<a href="http://en.wikipedia.org/wiki/Dangling_pointer">dangling pointers</a>. +</p> + +<p> +<em>Updating</em>: Code that uses <code>unsafe.Pointer</code> to convert +an integer-typed value held in memory into a pointer is illegal and must be rewritten. +Such code can be identified by <code>go vet</code>. +</p> + +<h3 id="map">Map iteration</h3> + +<p> +Iterations over small maps no longer happen in a consistent order. +Go 1 defines that “<a href="http://golang.org/ref/spec#For_statements">The iteration order over maps +is not specified and is not guaranteed to be the same from one iteration to the next.</a>” +To keep code from depending on map iteration order, +Go 1.0 started each map iteration at a random index in the map. +A new map implementation introduced in Go 1.1 neglected to randomize +iteration for maps with eight or fewer entries, although the iteration order +can still vary from system to system. +This has allowed people to write Go 1.1 and Go 1.2 programs that +depend on small map iteration order and therefore only work reliably on certain systems. +Go 1.3 reintroduces random iteration for small maps in order to flush out these bugs. +</p> + +<p> +<em>Updating</em>: If code assumes a fixed iteration order for small maps, +it will break and must be rewritten not to make that assumption. +Because only small maps are affected, the problem arises most often in tests. +</p> + +<h3 id="liblink">The linker</h3> + +<p> +As part of the general <a href="http://golang.org/s/go13linker">overhaul</a> to +the Go linker, the compilers and linkers have been refactored. +The linker is still a C program, but now the instruction selection phase that +was part of the linker has been moved to the compiler through the creation of a new +library called <code>liblink</code>. +By doing instruction selection only once, when the package is first compiled, +this can speed up compilation of large projects significantly. +</p> + +<p> +<em>Updating</em>: Although this is a major internal change, it should have no +effect on programs. +</p> + +<h3 id="gccgo">Status of gccgo</h3> + +<p> +GCC release 4.9 will contain the Go 1.2 (not 1.3) version of gccgo. +The release schedules for the GCC and Go projects do not coincide, +which means that 1.3 will be available in the development branch but +that the next GCC release, 4.10, will likely have the Go 1.4 version of gccgo. +</p> + +<h3 id="gocmd">Changes to the go command</h3> + +<p> +The <a href="/cmd/go/"><code>cmd/go</code></a> command has several new +features. +The <a href="/cmd/go/"><code>go run</code></a> and +<a href="/cmd/go/"><code>go test</code></a> subcommands +support a new <code>-exec</code> option to specify an alternate +way to run the resulting binary. +Its immediate purpose is to support NaCl. +</p> + +<p> +The test coverage support of the <a href="/cmd/go/"><code>go test</code></a> +subcommand now automatically sets the coverage mode to <code>-atomic</code> +when the race detector is enabled, to eliminate false reports about unsafe +access to coverage counters. +</p> + +<p> +The <a href="/cmd/go/"><code>go test</code></a> subcommand +now always builds the package, even if it has no test files. +Previously, it would do nothing if no test files were present. +</p> + +<p> +The <a href="/cmd/go/"><code>go build</code></a> subcommand +supports a new <code>-i</code> option to install dependencies +of the specified target, but not the target itself. +</p> + +<p> +Cross compiling with <a href="/cmd/cgo/"><code>cgo</code></a> enabled +is now supported. +The CC_FOR_TARGET and CXX_FOR_TARGET environment +variables are used when running all.bash to specify the cross compilers +for C and C++ code, respectively. +</p> + +<p> +Finally, the go command now supports packages that import Objective-C +files (suffixed <code>.m</code>) through cgo. +</p> + +<h3 id="cgo">Changes to cgo</h3> + +<p> +The <a href="/cmd/cgo/"><code>cmd/cgo</code></a> command, +which processes <code>import "C"</code> declarations in Go packages, +has corrected a serious bug that may cause some packages to stop compiling. +Previously, all pointers to incomplete struct types translated to the Go type <code>*[0]byte</code>, +with the effect that the Go compiler could not diagnose passing one kind of struct pointer +to a function expecting another. +Go 1.3 corrects this mistake by translating each different +incomplete struct to a different named type. +</p> + +<p> +Given the C declaration <code>typedef struct S T</code> for an incomplete <code>struct S</code>, +some Go code used this bug to refer to the types <code>C.struct_S</code> and <code>C.T</code> interchangeably. +Cgo now explicitly allows this use, even for completed struct types. +However, some Go code also used this bug to pass (for example) a <code>*C.FILE</code> +from one package to another. +This is not legal and no longer works: in general Go packages +should avoid exposing C types and names in their APIs. +</p> + +<p> +<em>Updating</em>: Code confusing pointers to incomplete types or +passing them across package boundaries will no longer compile +and must be rewritten. +If the conversion is correct and must be preserved, +use an explicit conversion via <a href="/pkg/unsafe/#Pointer"><code>unsafe.Pointer</code></a>. +</p> + +<h3 id="swig">SWIG 3.0 required for programs that use SWIG</h3> + +<p> +For Go programs that use SWIG, SWIG version 3.0 is now required. +The <a href="/cmd/go"><code>cmd/go</code></a> command will now link the +SWIG generated object files directly into the binary, rather than +building and linking with a shared library. +</p> + +<h3 id="gc_flag">Command-line flag parsing</h3> + +<p> +In the gc tool chain, the assemblers now use the +same command-line flag parsing rules as the Go flag package, a departure +from the traditional Unix flag parsing. +This may affect scripts that invoke the tool directly. +For example, +<code>go tool 6a -SDfoo</code> must now be written +<code>go tool 6a -S -D foo</code>. +(The same change was made to the compilers and linkers in <a href="/doc/go1.1#gc_flag">Go 1.1</a>.) +</p> + +<h3 id="godoc">Changes to godoc</h3> +<p> +When invoked with the <code>-analysis</code> flag, +<a href="http://godoc.org/code.google.com/p/go.tools/cmd/godoc">godoc</a> +now performs sophisticated <a href="/lib/godoc/analysis/help.html">static +analysis</a> of the code it indexes. +The results of analysis are presented in both the source view and the +package documentation view, and include the call graph of each package +and the relationships between +definitions and references, +types and their methods, +interfaces and their implementations, +send and receive operations on channels, +functions and their callers, and +call sites and their callees. +</p> + +<h3 id="misc">Miscellany</h3> + +<p> +The program <code>misc/benchcmp</code> that compares +performance across benchmarking runs has been rewritten. +Once a shell and awk script in the main repository, it is now a Go program in the <code>go.tools</code> repo. +Documentation is <a href="http://godoc.org/code.google.com/p/go.tools/cmd/benchcmp">here</a>. +</p> + +<p> +For the few of us that build Go distributions, the tool <code>misc/dist</code> has been +moved and renamed; it now lives in <code>misc/makerelease</code>, still in the main repository. +</p> + +<h2 id="performance">Performance</h2> + +<p> +The performance of Go binaries for this release has improved in many cases due to changes +in the runtime and garbage collection, plus some changes to libraries. +Significant instances include: +</p> + +<ul> + +<li> +The runtime handles defers more efficiently, reducing the memory footprint by about two kilobytes +per goroutine that calls defer. +</li> + +<li> +The garbage collector has been sped up, using a concurrent sweep algorithm, +better parallelization, and larger pages. +The cumulative effect can be a 50-70% reduction in collector pause time. +</li> + +<li> +The race detector (see <a href="/doc/articles/race_detector.html">this guide</a>) +is now about 40% faster. +</li> + +<li> +The regular expression package <a href="/pkg/regexp/"><code>regexp</code></a> +is now significantly faster for certain simple expressions due to the implementation of +a second, one-pass execution engine. +The choice of which engine to use is automatic; +the details are hidden from the user. +</li> + +</ul> + +<p> +Also, the runtime now includes in stack dumps how long a goroutine has been blocked, +which can be useful information when debugging deadlocks or performance issues. +</p> + +<h2 id="library">Changes to the standard library</h2> + +<h3 id="new_packages">New packages</h3> + +<p> +A new package <a href="/pkg/debug/plan9obj/"><code>debug/plan9obj</code></a> was added to the standard library. +It implements access to Plan 9 <a href="http://plan9.bell-labs.com/magic/man2html/6/a.out">a.out</a> object files. +</p> + +<h3 id="major_library_changes">Major changes to the library</h3> + +<p> +A previous bug in <a href="/pkg/crypto/tls/"><code>crypto/tls</code></a> +made it possible to skip verification in TLS inadvertently. +In Go 1.3, the bug is fixed: one must specify either ServerName or +InsecureSkipVerify, and if ServerName is specified it is enforced. +This may break existing code that incorrectly depended on insecure +behavior. +</p> + +<p> +There is an important new type added to the standard library: <a href="/pkg/sync/#Pool"><code>sync.Pool</code></a>. +It provides an efficient mechanism for implementing certain types of caches whose memory +can be reclaimed automatically by the system. +</p> + +<p> +The <a href="/pkg/testing/"><code>testing</code></a> package's benchmarking helper, +<a href="/pkg/testing/#B"><code>B</code></a>, now has a +<a href="/pkg/testing/#B.RunParallel"><code>RunParallel</code></a> method +to make it easier to run benchmarks that exercise multiple CPUs. +</p> + +<p> +<em>Updating</em>: The crypto/tls fix may break existing code, but such +code was erroneous and should be updated. +</p> + +<h3 id="minor_library_changes">Minor changes to the library</h3> + +<p> +The following list summarizes a number of minor changes to the library, mostly additions. +See the relevant package documentation for more information about each change. +</p> + +<ul> + +<li> In the <a href="/pkg/crypto/tls/"><code>crypto/tls</code></a> package, +a new <a href="/pkg/crypto/tls/#DialWithDialer"><code>DialWithDialer</code></a> +function lets one establish a TLS connection using an existing dialer, making it easier +to control dial options such as timeouts. +The package also now reports the TLS version used by the connection in the +<a href="/pkg/crypto/tls/#ConnectionState"><code>ConnectionState</code></a> +struct. +</li> + +<li> The <a href="/pkg/crypto/x509/#CreateCertificate"><code>CreateCertificate</code></a> +function of the <a href="/pkg/crypto/tls/"><code>crypto/tls</code></a> package +now supports parsing (and elsewhere, serialization) of PKCS #10 certificate +signature requests. +</li> + +<li> +The formatted print functions of the <code>fmt</code> package now define <code>%F</code> +as a synonym for <code>%f</code> when printing floating-point values. +</li> + +<li> +The <a href="/pkg/math/big/"><code>math/big</code></a> package's +<a href="/pkg/math/big/#Int"><code>Int</code></a> and +<a href="/pkg/math/big/#Rat"><code>Rat</code></a> types +now implement +<a href="/pkg/encoding/#TextMarshaler"><code>encoding.TextMarshaler</code></a> and +<a href="/pkg/encoding/#TextUnmarshaler"><code>encoding.TextUnmarshaler</code></a>. +</li> + +<li> +The complex power function, <a href="/pkg/math/cmplx/#Pow"><code>Pow</code></a>, +now specifies the behavior when the first argument is zero. +It was undefined before. +The details are in the <a href="/pkg/math/cmplx/#Pow">documentation for the function</a>. +</li> + +<li> +The <a href="/pkg/net/http/"><code>net/http</code></a> package now exposes the +properties of a TLS connection used to make a client request in the new +<a href="/pkg/net/http/#Response"><code>Response.TLS</code></a> field. +</li> + +<li> +The <a href="/pkg/net/http/"><code>net/http</code></a> package now +allows setting an optional server error logger +with <a href="/pkg/net/http/#Server"><code>Server.ErrorLog</code></a>. +The default is still that all errors go to stderr. +</li> + +<li> +The <a href="/pkg/net/http/"><code>net/http</code></a> package now +supports disabling HTTP keep-alive connections on the server +with <a href="/pkg/net/http/#Server.SetKeepAlivesEnabled"><code>Server.SetKeepAlivesEnabled</code></a>. +The default continues to be that the server does keep-alive (reuses +connections for multiple requests) by default. +Only resource-constrained servers or those in the process of graceful +shutdown will want to disable them. +</li> + +<li> +The <a href="/pkg/net/http/"><code>net/http</code></a> package adds an optional +<a href="/pkg/net/http/#Transport"><code>Transport.TLSHandshakeTimeout</code></a> +setting to cap the amount of time HTTP client requests will wait for +TLS handshakes to complete. +It's now also set by default +on <a href="/pkg/net/http#DefaultTransport"><code>DefaultTransport</code></a>. +</li> + +<li> +The <a href="/pkg/net/http/"><code>net/http</code></a> package's +<a href="/pkg/net/http/#DefaultTransport"><code>DefaultTransport</code></a>, +used by the HTTP client code, now +enables <a href="http://en.wikipedia.org/wiki/Keepalive#TCP_keepalive">TCP +keep-alives</a> by default. +Other <a href="/pkg/net/http/#Transport"><code>Transport</code></a> +values with a nil <code>Dial</code> field continue to function the same +as before: no TCP keep-alives are used. +</li> + +<li> +The <a href="/pkg/net/http/"><code>net/http</code></a> package +now enables <a href="http://en.wikipedia.org/wiki/Keepalive#TCP_keepalive">TCP +keep-alives</a> for incoming server requests when +<a href="/pkg/net/http/#ListenAndServe"><code>ListenAndServe</code></a> +or +<a href="/pkg/net/http/#ListenAndServeTLS"><code>ListenAndServeTLS</code></a> +are used. +When a server is started otherwise, TCP keep-alives are not enabled. +</li> + +<li> +The <a href="/pkg/net/http/"><code>net/http</code></a> package now +provides an +optional <a href="/pkg/net/http/#Server"><code>Server.ConnState</code></a> +callback to hook various phases of a server connection's lifecycle +(see <a href="/pkg/net/http/#ConnState"><code>ConnState</code></a>). +This can be used to implement rate limiting or graceful shutdown. +</li> + +<li> +The <a href="/pkg/net/http/"><code>net/http</code></a> package's HTTP +client now has an +optional <a href="/pkg/net/http/#Client"><code>Client.Timeout</code></a> +field to specify an end-to-end timeout on requests made using the +client. +</li> + +<li> In the <a href="/pkg/net/"><code>net</code></a> package, +the <a href="/pkg/net/#Dialer"><code>Dialer</code></a> struct now +has a <code>KeepAlive</code> option to specify a keep-alive period for the connection. +</li> + +<li> +The <a href="/pkg/net/http/"><code>net/http</code></a> package's +<a href="/pkg/net/http/#Transport"><code>Transport</code></a> +now closes <a href="/pkg/net/http/#Request"><code>Request.Body</code></a> +consistently, even on error. +</li> + +<li> +The <a href="/pkg/os/exec/"><code>os/exec</code></a> package now implements +what the documentation has always said with regard to relative paths for the binary. +In particular, it only calls <a href="/pkg/os/exec/#LookPath"><code>LookPath</code></a> +when the binary's file name contains no path separators. +</li> + +<li> +The <a href="/pkg/reflect/#Value.SetMapIndex"><code>SetMapIndex</code></a> +function in the <a href="/pkg/reflect/"><code>reflect</code></a> package +no longer panics when deleting from a <code>nil</code> map. +</li> + +<li> +If the main goroutine calls +<a href="/pkg/runtime/#Goexit"><code>runtime.Goexit</code></a> +and all other goroutines finish execution, the program now always crashes, +reporting a detected deadlock. +Earlier versions of Go handled this situation inconsistently: most instances +were reported as deadlocks, but some trivial cases exited cleanly instead. +</li> + +<li> +The runtime/debug package now has a new function +<a href="/pkg/runtime/debug/#WriteHeapDump"><code>debug.WriteHeapDump</code></a> +that writes out a description of the heap. +</li> + +<li> +The <a href="/pkg/strconv/#CanBackquote"><code>CanBackquote</code></a> +function in the <a href="/pkg/strconv/"><code>strconv</code></a> package +now considers the <code>DEL</code> character, <code>U+007F</code>, to be +non-printing. +</li> + +<li> +The <a href="/pkg/syscall/"><code>syscall</code></a> package now provides +<a href="/pkg/syscall/#SendmsgN"><code>SendmsgN</code></a> +as an alternate version of +<a href="/pkg/syscall/#Sendmsg"><code>Sendmsg</code></a> +that returns the number of bytes written. +</li> + +<li> +On Windows, the <a href="/pkg/syscall/"><code>syscall</code></a> package now +supports the cdecl calling convention through the addition of a new function +<a href="/pkg/syscall/#NewCallbackCDecl"><code>NewCallbackCDecl</code></a> +alongside the existing function +<a href="/pkg/syscall/#NewCallback"><code>NewCallback</code></a>. +</li> + +<li> +The <a href="/pkg/testing/"><code>testing</code></a> package now +diagnoses tests that call <code>panic(nil)</code>, which are almost always erroneous. +Also, tests now write profiles (if invoked with profiling flags) even on failure. +</li> + +<li> +The <a href="/pkg/unicode/"><code>unicode</code></a> package and associated +support throughout the system has been upgraded from +Unicode 6.2.0 to <a href="http://www.unicode.org/versions/Unicode6.3.0/">Unicode 6.3.0</a>. +</li> + +</ul> diff --git a/doc/go1.html b/doc/go1.html index 3bbe5d316..a664b6555 100644 --- a/doc/go1.html +++ b/doc/go1.html @@ -2035,4 +2035,4 @@ They are available for many combinations of architecture and operating system Installation details are described on the <a href="/doc/install">Getting Started</a> page, while the distributions themselves are listed on the -<a href="http://code.google.com/p/go/downloads/list">downloads page</a>. +<a href="/dl/">downloads page</a>. diff --git a/doc/go_faq.html b/doc/go_faq.html index f65dff796..b1945dda8 100644 --- a/doc/go_faq.html +++ b/doc/go_faq.html @@ -426,18 +426,20 @@ When a coroutine blocks, such as by calling a blocking system call, the run-time automatically moves other coroutines on the same operating system thread to a different, runnable thread so they won't be blocked. The programmer sees none of this, which is the point. -The result, which we call goroutines, can be very cheap: unless they spend a lot of time -in long-running system calls, they cost little more than the memory -for the stack, which is just a few kilobytes. +The result, which we call goroutines, can be very cheap: they have little +overhead beyond the memory for the stack, which is just a few kilobytes. </p> <p> -To make the stacks small, Go's run-time uses segmented stacks. A newly +To make the stacks small, Go's run-time uses resizable, bounded stacks. A newly minted goroutine is given a few kilobytes, which is almost always enough. -When it isn't, the run-time allocates (and frees) extension segments automatically. -The overhead averages about three cheap instructions per function call. +When it isn't, the run-time grows (and shrinks) the memory for storing +the stack automatically, allowing many goroutines to live in a modest +amount of memory. +The CPU overhead averages about three cheap instructions per function call. It is practical to create hundreds of thousands of goroutines in the same -address space. If goroutines were just threads, system resources would +address space. +If goroutines were just threads, system resources would run out at a much smaller number. </p> @@ -446,7 +448,7 @@ Why are map operations not defined to be atomic?</h3> <p> After long discussion it was decided that the typical use of maps did not require -safe access from multiple threads, and in those cases where it did, the map was +safe access from multiple goroutines, and in those cases where it did, the map was probably part of some larger data structure or computation that was already synchronized. Therefore requiring that all map operations grab a mutex would slow down most programs and add safety to few. This was not an easy decision, @@ -938,9 +940,9 @@ How are libraries documented?</h3> There is a program, <code>godoc</code>, written in Go, that extracts package documentation from the source code. It can be used on the command line or on the web. An instance is running at -<a href="http://golang.org/pkg/">http://golang.org/pkg/</a>. +<a href="/pkg/">http://golang.org/pkg/</a>. In fact, <code>godoc</code> implements the full site at -<a href="http://golang.org/">http://golang.org/</a>. +<a href="/">http://golang.org/</a>. </p> <h3 id="Is_there_a_Go_programming_style_guide"> @@ -957,6 +959,14 @@ compendium of do's and don'ts that allows interpretation. All the Go code in the repository has been run through <code>gofmt</code>. </p> +<p> +The document titled +<a href="http://golang.org/s/comments">Go Code Review Comments</a> +is a collection of very short essays about details of Go idiom that are often +missed by programmers. +It is a handy reference for people doing code reviews for Go projects. +</p> + <h3 id="How_do_I_submit_patches_to_the_Go_libraries"> How do I submit patches to the Go libraries?</h3> @@ -1427,7 +1437,7 @@ each closure shares that single variable. When the closure runs, it prints the value of <code>v</code> at the time <code>fmt.Println</code> is executed, but <code>v</code> may have been modified since the goroutine was launched. To help detect this and other problems before they happen, run -<a href="http://golang.org/cmd/go/#hdr-Run_go_tool_vet_on_packages"><code>go vet</code></a>. +<a href="/cmd/go/#hdr-Run_go_tool_vet_on_packages"><code>go vet</code></a>. </p> <p> @@ -1606,9 +1616,10 @@ it now. <code>Gccgo</code>'s run-time support uses <code>glibc</code>. <code>Gc</code> uses a custom library to keep the footprint under control; it is compiled with a version of the Plan 9 C compiler that supports -segmented stacks for goroutines. -The <code>gccgo</code> compiler implements segmented -stacks on Linux only, supported by recent modifications to the gold linker. +resizable stacks for goroutines. +The <code>gccgo</code> compiler implements these on Linux only, +using a technique called segmented stacks, +supported by recent modifications to the gold linker. </p> <h3 id="Why_is_my_trivial_program_such_a_large_binary"> diff --git a/doc/go_mem.html b/doc/go_mem.html index 3e769daec..2ea1ded7a 100644 --- a/doc/go_mem.html +++ b/doc/go_mem.html @@ -1,6 +1,6 @@ <!--{ "Title": "The Go Memory Model", - "Subtitle": "Version of March 6, 2012", + "Subtitle": "Version of May 31, 2014", "Path": "/ref/mem" }--> @@ -274,6 +274,41 @@ then the program would not be guaranteed to print crash, or do something else.) </p> +<p class="rule"> +The <i>k</i>th receive on a channel with capacity <i>C</i> happens before the <i>k</i>+<i>C</i>th send from that channel completes. +</p> + +<p> +This rule generalizes the previous rule to buffered channels. +It allows a counting semaphore to be modeled by a buffered channel: +the number of items in the channel corresponds to the number of active uses, +the capacity of the channel corresponds to the maximum number of simultaneous uses, +sending an item acquires the semaphore, and receiving an item releases +the semaphore. +This is a common idiom for limiting concurrency. +</p> + +<p> +This program starts a goroutine for every entry in the work list, but the +goroutines coordinate using the <code>limit</code> channel to ensure +that at most three are running work functions at a time. +</p> + +<pre> +var limit = make(chan int, 3) + +func main() { + for _, w := range work { + go func() { + limit <- 1 + w() + <-limit + }() + } + select{} +} +</pre> + <h3>Locks</h3> <p> diff --git a/doc/go_spec.html b/doc/go_spec.html index bc9ec682a..baa0ecf40 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1,6 +1,6 @@ <!--{ "Title": "The Go Programming Language Specification", - "Subtitle": "Version of Nov 13, 2013", + "Subtitle": "Version of May 28, 2014", "Path": "/ref/spec" }--> @@ -23,7 +23,7 @@ TODO <p> This is a reference manual for the Go programming language. For -more information and other documents, see <a href="http://golang.org/">http://golang.org</a>. +more information and other documents, see <a href="/">http://golang.org</a>. </p> <p> @@ -120,7 +120,7 @@ unicode_digit = /* a Unicode code point classified as "Decimal Digit" */ . </pre> <p> -In <a href="http://www.unicode.org/versions/Unicode6.2.0/">The Unicode Standard 6.2</a>, +In <a href="http://www.unicode.org/versions/Unicode6.3.0/">The Unicode Standard 6.3</a>, Section 4.5 "General Category" defines a set of character categories. Go treats those characters in category Lu, Ll, Lt, Lm, or Lo as Unicode letters, @@ -471,7 +471,7 @@ string composed of the uninterpreted (implicitly UTF-8-encoded) characters between the quotes; in particular, backslashes have no special meaning and the string may contain newlines. -Carriage returns inside raw string literals +Carriage return characters ('\r') inside raw string literals are discarded from the raw string value. </p> <p> @@ -674,7 +674,8 @@ types, the dynamic type is always the static type. <p> Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code> -is a predeclared type or a type literal, the corresponding underlying +is one of the predeclared boolean, numeric, or string types, or a type literal, +the corresponding underlying type is <code>T</code> itself. Otherwise, <code>T</code>'s underlying type is the underlying type of the type to which <code>T</code> refers in its <a href="#Type_declarations">type declaration</a>. @@ -695,19 +696,19 @@ and <code>T4</code> is <code>[]T1</code>. <h3 id="Method_sets">Method sets</h3> <p> -A type may have a <i>method set</i> associated with it -(§<a href="#Interface_types">Interface types</a>, §<a href="#Method_declarations">Method declarations</a>). +A type may have a <i>method set</i> associated with it. The method set of an <a href="#Interface_types">interface type</a> is its interface. -The method set of any other type <code>T</code> -consists of all methods with receiver type <code>T</code>. -The method set of the corresponding pointer type <code>*T</code> -is the set of all methods with receiver <code>*T</code> or <code>T</code> +The method set of any other type <code>T</code> consists of all +<a href="#Method_declarations">methods</a> declared with receiver type <code>T</code>. +The method set of the corresponding <a href="#Pointer_types">pointer type</a> <code>*T</code> +is the set of all methods declared with receiver <code>*T</code> or <code>T</code> (that is, it also contains the method set of <code>T</code>). Further rules apply to structs containing anonymous fields, as described in the section on <a href="#Struct_types">struct types</a>. Any other type has an empty method set. In a method set, each method must have a -<a href="#Uniqueness_of_identifiers">unique</a> <a href="#MethodName">method name</a>. +<a href="#Uniqueness_of_identifiers">unique</a> +non-<a href="#Blank_identifier">blank</a> <a href="#MethodName">method name</a>. </p> <p> @@ -817,8 +818,8 @@ ElementType = Type . </pre> <p> -The length is part of the array's type; it must evaluate to a non- -negative <a href="#Constants">constant</a> representable by a value +The length is part of the array's type; it must evaluate to a +non-negative <a href="#Constants">constant</a> representable by a value of type <code>int</code>. The length of array <code>a</code> can be discovered using the built-in function <a href="#Length_and_capacity"><code>len</code></a>. @@ -1009,7 +1010,7 @@ A field declaration may be followed by an optional string literal <i>tag</i>, which becomes an attribute for all the fields in the corresponding field declaration. The tags are made visible through a <a href="/pkg/reflect/#StructTag">reflection interface</a> -and take part in <a href="Type_identity">type identity</a> for structs +and take part in <a href="#Type_identity">type identity</a> for structs but are otherwise ignored. </p> @@ -1108,7 +1109,8 @@ InterfaceTypeName = TypeName . <p> As with all method sets, in an interface type, each method must have a -<a href="#Uniqueness_of_identifiers">unique</a> name. +<a href="#Uniqueness_of_identifiers">unique</a> +non-<a href="#Blank_identifier">blank</a> name. </p> <pre> @@ -1277,20 +1279,23 @@ may be added. <h3 id="Channel_types">Channel types</h3> <p> -A channel provides a mechanism for two concurrently executing functions -to synchronize execution and communicate by passing a value of a -specified element type. +A channel provides a mechanism for +<a href="#Go_statements">concurrently executing functions</a> +to communicate by +<a href="#Send_statements">sending</a> and +<a href="#Receive_operator">receiving</a> +values of a specified element type. The value of an uninitialized channel is <code>nil</code>. </p> <pre class="ebnf"> -ChannelType = ( "chan" [ "<-" ] | "<-" "chan" ) ElementType . +ChannelType = ( "chan" | "chan" "<-" | "<-" "chan" ) ElementType . </pre> <p> -The <code><-</code> operator specifies the channel <i>direction</i>, +The optional <code><-</code> operator specifies the channel <i>direction</i>, <i>send</i> or <i>receive</i>. If no direction is given, the channel is -<i>bi-directional</i>. +<i>bidirectional</i>. A channel may be constrained only to send or only to receive by <a href="#Conversions">conversion</a> or <a href="#Assignments">assignment</a>. </p> @@ -1317,7 +1322,7 @@ chan (<-chan int) A new, initialized channel value can be made using the built-in function <a href="#Making_slices_maps_and_channels"><code>make</code></a>, -which takes the channel type and an optional capacity as arguments: +which takes the channel type and an optional <i>capacity</i> as arguments: </p> <pre> @@ -1325,21 +1330,35 @@ make(chan int, 100) </pre> <p> -The capacity, in number of elements, sets the size of the buffer in the channel. If the -capacity is greater than zero, the channel is asynchronous: communication operations -succeed without blocking if the buffer is not full (sends) or not empty (receives), -and elements are received in the order they are sent. -If the capacity is zero or absent, the communication succeeds only when both a sender and -receiver are ready. +The capacity, in number of elements, sets the size of the buffer in the channel. +If the capacity is zero or absent, the channel is unbuffered and communication +succeeds only when both a sender and receiver are ready. Otherwise, the channel +is buffered and communication succeeds without blocking if the buffer +is not full (sends) or not empty (receives). A <code>nil</code> channel is never ready for communication. </p> <p> A channel may be closed with the built-in function -<a href="#Close"><code>close</code></a>; the -multi-valued assignment form of the +<a href="#Close"><code>close</code></a>. +The multi-valued assignment form of the <a href="#Receive_operator">receive operator</a> -tests whether a channel has been closed. +reports whether a received value was sent before +the channel was closed. +</p> + +<p> +A single channel may be used in +<a href="#Send_statements">send statements</a>, +<a href="#Receive_operator">receive operations</a>, +and calls to the built-in functions +<a href="#Length_and_capacity"><code>cap</code></a> and +<a href="#Length_and_capacity"><code>len</code></a> +by any number of goroutines without further synchronization. +Channels act as first-in-first-out queues. +For example, if one goroutine sends values on a channel +and a second goroutine receives them, the values are +received in the order sent. </p> <h2 id="Properties_of_types_and_values">Properties of types and values</h2> @@ -1515,6 +1534,9 @@ no identifier may be declared in both the file and package block. <p> The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier in a declaration, but it does not introduce a binding and thus is not declared. +In the package block, the identifier <code>init</code> may only be used for +<a href="#Package_initialization"><code>init</code> function</a> declarations, +and like the blank identifier it does not introduce a new binding. </p> <pre class="ebnf"> @@ -1770,9 +1792,9 @@ last non-empty expression list. <p> A type declaration binds an identifier, the <i>type name</i>, to a new type -that has the same <a href="#Types">underlying type</a> as -an existing type. The new type is <a href="#Type_identity">different</a> from -the existing type. +that has the same <a href="#Types">underlying type</a> as an existing type, +and operations defined for the existing type are also defined for the new type. +The new type is <a href="#Type_identity">different</a> from the existing type. </p> <pre class="ebnf"> @@ -2267,8 +2289,6 @@ Similarly, elements that are addresses of composite literals may elide the <code>&T</code> when the element type is <code>*T</code>. </p> - - <pre> [...]Point{{1.5, -3.5}, {0, 0}} // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}} [][]int{{1, 2, 3}, {4, 5}} // same as [][]int{[]int{1, 2, 3}, []int{4, 5}} @@ -2278,13 +2298,13 @@ the <code>&T</code> when the element type is <code>*T</code>. <p> A parsing ambiguity arises when a composite literal using the -TypeName form of the LiteralType appears between the -<a href="#Keywords">keyword</a> and the opening brace of the block of an -"if", "for", or "switch" statement, because the braces surrounding -the expressions in the literal are confused with those introducing -the block of statements. To resolve the ambiguity in this rare case, -the composite literal must appear within -parentheses. +TypeName form of the LiteralType appears as an operand between the +<a href="#Keywords">keyword</a> and the opening brace of the block +of an "if", "for", or "switch" statement, and the composite literal +is not enclosed in parentheses, square brackets, or curly braces. +In this rare case, the opening brace of the literal is erroneously parsed +as the one introducing the block of statements. To resolve the ambiguity, +the composite literal must appear within parentheses. </p> <pre> @@ -2692,7 +2712,7 @@ For arrays or strings, the indices are <i>in range</i> if otherwise they are <i>out of range</i>. For slices, the upper index bound is the slice capacity <code>cap(a)</code> rather than the length. A <a href="#Constants">constant</a> index must be non-negative and representable by a value of type -<code>int</code>. +<code>int</code>; for arrays or constant strings, constant indices must also be in range. If both indices are constant, they must satisfy <code>low <= high</code>. If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. </p> @@ -2752,7 +2772,7 @@ If the sliced operand is an array, it must be <a href="#Address_operators">addre The indices are <i>in range</i> if <code>0 <= low <= high <= max <= cap(a)</code>, otherwise they are <i>out of range</i>. A <a href="#Constants">constant</a> index must be non-negative and representable by a value of type -<code>int</code>. +<code>int</code>; for arrays, constant indices must also be in range. If multiple indices are constant, the constants that are present must be in range relative to each other. If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. @@ -2916,27 +2936,32 @@ There is no distinct method type and there are no method literals. <h3 id="Passing_arguments_to_..._parameters">Passing arguments to <code>...</code> parameters</h3> <p> -If <code>f</code> is variadic with final parameter type <code>...T</code>, -then within the function the argument is equivalent to a parameter of type -<code>[]T</code>. At each call of <code>f</code>, the argument -passed to the final parameter is -a new slice of type <code>[]T</code> whose successive elements are -the actual arguments, which all must be <a href="#Assignability">assignable</a> -to the type <code>T</code>. The length of the slice is therefore the number of -arguments bound to the final parameter and may differ for each call site. +If <code>f</code> is <a href="#Function_types">variadic</a> with a final +parameter <code>p</code> of type <code>...T</code>, then within <code>f</code> +the type of <code>p</code> is equivalent to type <code>[]T</code>. +If <code>f</code> is invoked with no actual arguments for <code>p</code>, +the value passed to <code>p</code> is <code>nil</code>. +Otherwise, the value passed is a new slice +of type <code>[]T</code> with a new underlying array whose successive elements +are the actual arguments, which all must be <a href="#Assignability">assignable</a> +to <code>T</code>. The length and capacity of the slice is therefore +the number of arguments bound to <code>p</code> and may differ for each +call site. </p> <p> -Given the function and call +Given the function and calls </p> <pre> func Greeting(prefix string, who ...string) +Greeting("nobody") Greeting("hello:", "Joe", "Anna", "Eileen") </pre> <p> within <code>Greeting</code>, <code>who</code> will have the value -<code>[]string{"Joe", "Anna", "Eileen"}</code> +<code>nil</code> in the first call, and +<code>[]string{"Joe", "Anna", "Eileen"}</code> in the second. </p> <p> @@ -3385,7 +3410,8 @@ and the type of the receive operation is the element type of the channel. The expression blocks until a value is available. Receiving from a <code>nil</code> channel blocks forever. A receive operation on a <a href="#Close">closed</a> channel can always proceed -immediately, yielding the element type's <a href="#The_zero_value">zero value</a>. +immediately, yielding the element type's <a href="#The_zero_value">zero value</a> +after any previously sent values have been received. </p> <pre> @@ -3929,7 +3955,7 @@ an untyped complex constant. <pre> const ic = complex(0, c) // ic == 3.75i (untyped complex constant) -const iΘ = complex(0, Θ) // iΘ == 1.5i (type complex128) +const iΘ = complex(0, Θ) // iΘ == 1i (type complex128) </pre> <p> @@ -3992,8 +4018,11 @@ precision. <h3 id="Order_of_evaluation">Order of evaluation</h3> <p> -When evaluating the <a href="#Operands">operands</a> of an expression, -<a href="#Assignments">assignment</a>, or +At package level, <a href="#Package_initialization">initialization dependencies</a> +determine the evaluation order of individual initialization expressions in +<a href="#Variable_declarations">variable declarations</a>. +Otherwise, when evaluating the <a href="#Operands">operands</a> of an +expression, assignment, or <a href="#Return_statements">return statement</a>, all function calls, method calls, and communication operations are evaluated in lexical left-to-right @@ -4001,7 +4030,7 @@ order. </p> <p> -For example, in the assignment +For example, in the (function-local) assignment </p> <pre> y[f()], ok = g(h(), i()+x[j()], <-c), k() @@ -4018,12 +4047,34 @@ of <code>y</code> is not specified. <pre> a := 1 f := func() int { a++; return a } -x := []int{a, f()} // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified -m := map[int]int{a: 1, a: 2} // m may be {2: 1} or {2: 2}: evaluation order between the two map assignments is not specified -m2 := map[int]int{a: f()} // m2 may be {2: 3} or {3: 3}: evaluation order between the key and the value is not specified +x := []int{a, f()} // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified +m := map[int]int{a: 1, a: 2} // m may be {2: 1} or {2: 2}: evaluation order between the two map assignments is not specified +n := map[int]int{a: f()} // n may be {2: 3} or {3: 3}: evaluation order between the key and the value is not specified </pre> <p> +At package level, initialization dependencies override the left-to-right rule +for individual initialization expressions, but not for operands within each +expression: +</p> + +<pre> +var a, b, c = f() + v(), g(), sqr(u()) + v() + +func f() int { return c } +func g() int { return a } +func sqr(x int) int { return x*x } + +// functions u and v are independent of all other variables and functions +</pre> + +<p> +The function calls happen in the order +<code>u()</code>, <code>sqr()</code>, <code>v()</code>, +<code>f()</code>, <code>v()</code>, and <code>g()</code>. +</p> + +<p> Floating-point operations within a single expression are evaluated according to the associativity of the operators. Explicit parentheses affect the evaluation by overriding the default associativity. @@ -4209,22 +4260,8 @@ A send on a closed channel proceeds by causing a <a href="#Run_time_panics">run- A send on a <code>nil</code> channel blocks forever. </p> -<p> -Channels act as first-in-first-out queues. -For example, if a single goroutine sends on a channel values -that are received by a single goroutine, the values are received in the order sent. -</p> - -<p> -A single channel may be used for send and receive -operations and calls to the built-in functions -<a href="#Length_and_capacity"><code>cap</code></a> and -<a href="#Length_and_capacity"><code>len</code></a> -by any number of goroutines without further synchronization. -</p> - <pre> -ch <- 3 +ch <- 3 // send value 3 to channel ch </pre> @@ -4459,8 +4496,8 @@ If no case matches and there is a "default" case, its statements are executed. There can be at most one default case and it may appear anywhere in the "switch" statement. -A missing switch expression is equivalent to -the expression <code>true</code>. +A missing switch expression is equivalent to the boolean value +<code>true</code>. </p> <pre class="ebnf"> @@ -4625,7 +4662,8 @@ Condition = Expression . In its simplest form, a "for" statement specifies the repeated execution of a block as long as a boolean condition evaluates to true. The condition is evaluated before each iteration. -If the condition is absent, it is equivalent to <code>true</code>. +If the condition is absent, it is equivalent to the boolean value +<code>true</code>. </p> <pre> @@ -4662,7 +4700,8 @@ only if the block was executed). Any element of the ForClause may be empty but the <a href="#Semicolons">semicolons</a> are required unless there is only a condition. -If the condition is absent, it is equivalent to <code>true</code>. +If the condition is absent, it is equivalent to the boolean value +<code>true</code>. </p> <pre> @@ -4844,8 +4883,12 @@ go func(ch chan<- bool) { for { sleep(10); ch <- true; }} (c) <h3 id="Select_statements">Select statements</h3> <p> -A "select" statement chooses which of a set of possible communications -will proceed. It looks similar to a "switch" statement but with the +A "select" statement chooses which of a set of possible +<a href="#Send_statements">send</a> or +<a href="#Receive_operator">receive</a> +operations will proceed. +It looks similar to a +<a href="#Switch_statements">"switch"</a> statement but with the cases all referring to communication operations. </p> @@ -4858,41 +4901,63 @@ RecvExpr = Expression . </pre> <p> -RecvExpr must be a <a href="#Receive_operator">receive operation</a>. -For all the cases in the "select" -statement, the channel expressions are evaluated in top-to-bottom order, along with -any expressions that appear on the right hand side of send statements. -A channel may be <code>nil</code>, -which is equivalent to that case not -being present in the select statement -except, if a send, its expression is still evaluated. -If any of the resulting operations can proceed, one of those is -chosen and the corresponding communication and statements are -evaluated. Otherwise, if there is a default case, that executes; -if there is no default case, the statement blocks until one of the communications can -complete. There can be at most one default case and it may appear anywhere in the -"select" statement. -If there are no cases with non-<code>nil</code> channels, -the statement blocks forever. -Even if the statement blocks, -the channel and send expressions are evaluated only once, -upon entering the select statement. +A case with a RecvStmt may assign the result of a RecvExpr to one or +two variables, which may be declared using a +<a href="#Short_variable_declarations">short variable declaration</a>. +The RecvExpr must be a (possibly parenthesized) receive operation. +There can be at most one default case and it may appear anywhere +in the list of cases. </p> + <p> -Since all the channels and send expressions are evaluated, any side -effects in that evaluation will occur for all the communications -in the "select" statement. +Execution of a "select" statement proceeds in several steps: </p> + +<ol> +<li> +For all the cases in the statement, the channel operands of receive operations +and the channel and right-hand-side expressions of send statements are +evaluated exactly once, in source order, upon entering the "select" statement. +The result is a set of channels to receive from or send to, +and the corresponding values to send. +Any side effects in that evaluation will occur irrespective of which (if any) +communication operation is selected to proceed. +Expressions on the left-hand side of a RecvStmt with a short variable declaration +or assignment are not yet evaluated. +</li> + +<li> +If one or more of the communications can proceed, +a single one that can proceed is chosen via a uniform pseudo-random selection. +Otherwise, if there is a default case, that case is chosen. +If there is no default case, the "select" statement blocks until +at least one of the communications can proceed. +</li> + +<li> +Unless the selected case is the default case, the respective communication +operation is executed. +</li> + +<li> +If the selected case is a RecvStmt with a short variable declaration or +an assignment, the left-hand side expressions are evaluated and the +received value (or values) are assigned. +</li> + +<li> +The statement list of the selected case is executed. +</li> +</ol> + <p> -If multiple cases can proceed, a uniform pseudo-random choice is made to decide -which single communication will execute. -<p> -The receive case may declare one or two new variables using a -<a href="#Short_variable_declarations">short variable declaration</a>. +Since communication on <code>nil</code> channels can never proceed, +a select with only <code>nil</code> channels and no default case blocks forever. </p> <pre> -var c, c1, c2, c3 chan int +var a []int +var c, c1, c2, c3, c4 chan int var i1, i2 int select { case i1 = <-c1: @@ -4905,6 +4970,10 @@ case i3, ok := (<-c3): // same as: i3, ok := <-c3 } else { print("c3 is closed\n") } +case a[f()] = <-c4: + // same as: + // case t := <-c4 + // a[f()] = t default: print("no communication\n") } @@ -5002,6 +5071,21 @@ function. A "return" statement that specifies results sets the result parameters any deferred functions are executed. </p> +<p> +Implementation restriction: A compiler may disallow an empty expression list +in a "return" statement if a different entity (constant, type, or variable) +with the same name as a result parameter is in +<a href="#Declarations_and_scope">scope</a> at the place of the return. +</p> + +<pre> +func f(n int) (res int, err error) { + if _, err := f(n-1); err != nil { + return // invalid return statement: err is shadowed + } + return +} +</pre> <h3 id="Break_statements">Break statements</h3> @@ -5009,7 +5093,8 @@ any deferred functions are executed. A "break" statement terminates execution of the innermost <a href="#For_statements">"for"</a>, <a href="#Switch_statements">"switch"</a>, or -<a href="#Select_statements">"select"</a> statement. +<a href="#Select_statements">"select"</a> statement +within the same function. </p> <pre class="ebnf"> @@ -5043,6 +5128,7 @@ OuterLoop: <p> A "continue" statement begins the next iteration of the innermost <a href="#For_statements">"for" loop</a> at its post statement. +The "for" loop must be within the same function. </p> <pre class="ebnf"> @@ -5070,7 +5156,8 @@ RowLoop: <h3 id="Goto_statements">Goto statements</h3> <p> -A "goto" statement transfers control to the statement with the corresponding label. +A "goto" statement transfers control to the statement with the corresponding label +within the same function. </p> <pre class="ebnf"> @@ -5263,7 +5350,7 @@ At any time the following relationship holds: <p> The length of a <code>nil</code> slice, map or channel is 0. -The capacity of a <code>nil</code> slice and channel is 0. +The capacity of a <code>nil</code> slice or channel is 0. </p> <p> @@ -5271,12 +5358,22 @@ The expression <code>len(s)</code> is <a href="#Constants">constant</a> if <code>s</code> is a string constant. The expressions <code>len(s)</code> and <code>cap(s)</code> are constants if the type of <code>s</code> is an array or pointer to an array and the expression <code>s</code> does not contain -<a href="#Receive_operator">channel receives</a> or +<a href="#Receive_operator">channel receives</a> or (non-constant) <a href="#Calls">function calls</a>; in this case <code>s</code> is not evaluated. Otherwise, invocations of <code>len</code> and <code>cap</code> are not constant and <code>s</code> is evaluated. </p> +<pre> +const ( + c1 = imag(2i) // imag(2i) = 2.0 is a constant + c2 = len([10]float64{2}) // [10]float64{2} contains no function calls + c3 = len([10]float64{c1}) // [10]float64{c1} contains no function calls + c4 = len([10]float64{imag(2i)}) // imag(2i) is a constant and no function call is issued + c5 = len([10]float64{imag(z)}) // invalid: imag(x) is a (non-constant) function call +) +var z complex128 +</pre> <h3 id="Allocation">Allocation</h3> @@ -5327,8 +5424,8 @@ make(T, n, m) slice slice of type T with length n and capacity m make(T) map map of type T make(T, n) map map of type T with initial space for n elements -make(T) channel synchronous channel of type T -make(T, n) channel asynchronous channel of type T, buffer size n +make(T) channel unbuffered channel of type T +make(T, n) channel buffered channel of type T, buffer size n </pre> @@ -5669,7 +5766,7 @@ If the PackageName is omitted, it defaults to the identifier specified in the If an explicit period (<code>.</code>) appears instead of a name, all the package's exported identifiers declared in that package's <a href="#Blocks">package block</a> will be declared in the importing source -file's file block and can be accessed without a qualifier. +file's file block and must be accessed without a qualifier. </p> <p> @@ -5681,7 +5778,7 @@ package and may be relative to a repository of installed packages. <p> Implementation restriction: A compiler may restrict ImportPaths to non-empty strings using only characters belonging to -<a href="http://www.unicode.org/versions/Unicode6.2.0/">Unicode's</a> +<a href="http://www.unicode.org/versions/Unicode6.3.0/">Unicode's</a> L, M, N, P, and S general categories (the Graphic characters without spaces) and may also exclude the characters <code>!"#$%&'()*,:;<=>?[\]^`{|}</code> @@ -5693,7 +5790,7 @@ Assume we have compiled a package containing the package clause <code>package math</code>, which exports function <code>Sin</code>, and installed the compiled package in the file identified by <code>"lib/math"</code>. -This table illustrates how <code>Sin</code> may be accessed in files +This table illustrates how <code>Sin</code> is accessed in files that import the package after the various types of import declaration. </p> @@ -5817,62 +5914,126 @@ The same would also be true after var t T </pre> -<h3 id="Program_execution">Program execution</h3> +<h3 id="Package_initialization">Package initialization</h3> <p> -A package with no imports is initialized by assigning initial values to -all its package-level variables -and then calling any -package-level function with the name and signature of -</p> -<pre> -func init() -</pre> -<p> -defined in its source. -A package-scope or file-scope identifier -with name <code>init</code> may only be -declared to be a function with this signature. -Multiple such functions may be defined, even -within a single source file; they execute -in unspecified order. -</p> -<p> -Within a package, package-level variables are initialized, -and constant values are determined, according to -order of reference: if the initializer of <code>A</code> -depends on <code>B</code>, <code>A</code> -will be set after <code>B</code>. -Dependency analysis does not depend on the actual values -of the items being initialized, only on their appearance -in the source. -<code>A</code> -depends on <code>B</code> if the value of <code>A</code> -contains a mention of <code>B</code>, contains a value -whose initializer -mentions <code>B</code>, or mentions a function that -mentions <code>B</code>, recursively. -It is an error if such dependencies form a cycle. -If two items are not interdependent, they will be initialized -in the order they appear in the source, possibly in multiple files, -as presented to the compiler. -Since the dependency analysis is done per package, it can produce -unspecified results if <code>A</code>'s initializer calls a function defined -in another package that refers to <code>B</code>. +Within a package, package-level variables are initialized according +to their <i>dependencies</i>: if a variable <code>x</code> depends on +a variable <code>y</code>, <code>x</code> will be initialized after +<code>y</code>. +</p> + +<p> +Dependency analysis does not rely on the actual values of the +variables, only on lexical <i>references</i> to them in the source, +analyzed transitively. For instance, a variable <code>x</code>'s +<a href="#Variable_declarations">initialization expression</a> +may refer to a function whose body refers to variable <code>y</code>; +if so, <code>x</code> depends on <code>y</code>. +Specifically: +</p> + +<ul> +<li> +A reference to a variable or function is an identifier denoting that +variable or function. +</li> + +<li> +A reference to a method <code>m</code> is a +<a href="#Method_values">method value</a> or +<a href="#Method_expressions">method expression</a> of the form +<code>t.m</code>, where the (static) type of <code>t</code> is +not an interface type, and the method <code>m</code> is in the +<a href="#Method_sets">method set</a> of <code>t</code>. +It is immaterial whether the resulting function value +<code>t.m</code> is invoked. +</li> + +<li> +A variable, function, or method <code>x</code> depends on a variable +<code>y</code> if <code>x</code>'s initialization expression or body +(for functions and methods) contains a reference to <code>y</code> +or to a function or method that depends on <code>y</code>. +</li> +</ul> + +<p> +Dependency analysis is performed per package; only references referring +to variables, functions, and methods declared in the current package +are considered. +It is an error if variable dependencies form a cycle +(but dependency cycles containing no variables are permitted). +If two variables are independent of each other, +they are initialized in the order they are declared +in the source, possibly in multiple files, as presented to the compiler. +</p> + +<p> +For example, given the declarations +</p> + +<pre> +var ( + a = c + b + b = f() + c = f() + d = 3 +) + +func f() int { + d++ + return d +} +</pre> + +<p> +the initialization order is <code>d</code>, <code>b</code>, <code>c</code>, <code>a</code>. +Since <code>b</code> and <code>c</code> are independent of each other, they are +initialized in declaration order (<code>b</code> before <code>c</code>). +</p> + +<p> +Variables may also be initialized using functions named <code>init</code> +declared in the package block, with no arguments and no result parameters. </p> + +<pre> +func init() { … } +</pre> + <p> -An <code>init</code> function cannot be referred to from anywhere -in a program. In particular, <code>init</code> cannot be called explicitly, -nor can a pointer to <code>init</code> be assigned to a function variable. +Multiple such functions may be defined, even within a single +source file. The <code>init</code> identifier is not +<a href="#Declarations_and_scope">declared</a> and thus +<code>init</code> functions cannot be referred to from anywhere +in a program. </p> + <p> +A package with no imports is initialized by assigning initial values +to all its package-level variables followed by calling all <code>init</code> +functions in the order they appear in the source, possibly in multiple files, +as presented to the compiler. If a package has imports, the imported packages are initialized before initializing the package itself. If multiple packages import -a package <code>P</code>, <code>P</code> will be initialized only once. +a package, the imported package will be initialized only once. +The importing of packages, by construction, guarantees that there +can be no cyclic initialization dependencies. </p> + <p> -The importing of packages, by construction, guarantees that there can -be no cyclic dependencies in initialization. +Package initialization—variable initialization and the invocation of +<code>init</code> functions—happens in a single goroutine, +sequentially, one package at a time. +An <code>init</code> function may launch other goroutines, which can run +concurrently with the initialization code. However, initialization +always sequences +the <code>init</code> functions: it will not invoke the next one +until the previous one has returned. </p> + + +<h3 id="Program_execution">Program execution</h3> <p> A complete program is created by linking a single, unimported package called the <i>main package</i> with all the packages it imports, transitively. @@ -5889,22 +6050,10 @@ func main() { … } <p> Program execution begins by initializing the main package and then invoking the function <code>main</code>. -When the function <code>main</code> returns, the program exits. +When that function invocation returns, the program exits. It does not wait for other (non-<code>main</code>) goroutines to complete. </p> -<p> -Package initialization—variable initialization and the invocation of -<code>init</code> functions—happens in a single goroutine, -sequentially, one package at a time. -An <code>init</code> function may launch other goroutines, which can run -concurrently with the initialization code. However, initialization -always sequences -the <code>init</code> functions: it will not start the next -<code>init</code> until -the previous one has returned. -</p> - <h2 id="Errors">Errors</h2> <p> diff --git a/doc/gopher/README b/doc/gopher/README new file mode 100644 index 000000000..936a24c66 --- /dev/null +++ b/doc/gopher/README @@ -0,0 +1,3 @@ +The Go gopher was designed by Renee French. (http://reneefrench.blogspot.com/) +The design is licensed under the Creative Commons 3.0 Attributions license. +Read this article for more details: http://blog.golang.org/gopher diff --git a/doc/help.html b/doc/help.html index 3de520640..ad92c5695 100644 --- a/doc/help.html +++ b/doc/help.html @@ -39,7 +39,7 @@ Go IRC channel.</p> <h3 id="twitter"><a href="http://twitter.com/golang">@golang at Twitter</a></h3> <p>The Go project's official Twitter account.</p> -<p>Tweeting your about problem with the <code>#golang</code> hashtag usually +<p>Tweeting about your problem with the <code>#golang</code> hashtag usually generates some helpful responses.</p> <h3 id="go_user_groups"><a href="/wiki/GoUserGroups">Go User Groups</a></h3> diff --git a/doc/install-source.html b/doc/install-source.html index b99360c71..6f6a15afd 100644 --- a/doc/install-source.html +++ b/doc/install-source.html @@ -69,8 +69,8 @@ goroutines, such as stacks that grow and shrink on demand. </p> <p> -The compilers can target the FreeBSD, Linux, NetBSD, OpenBSD, OS X (Darwin), Plan 9, -and Windows operating systems. +The compilers can target the DragonFly BSD, FreeBSD, Linux, NetBSD, OpenBSD, +OS X (Darwin), Plan 9, Solaris and Windows operating systems. The full set of supported combinations is listed in the discussion of <a href="#environment">environment variables</a> below. </p> @@ -95,7 +95,7 @@ have an <code>hg</code> command.) <p> If you do not have a working Mercurial installation, follow the instructions on the -<a href="http://mercurial.selenic.com/downloads/">Mercurial downloads</a> page. +<a href="http://mercurial.selenic.com/downloads">Mercurial downloads</a> page. </p> <p> @@ -176,6 +176,10 @@ architecture, and root directory used during the install. <p> For more information about ways to control the build, see the discussion of <a href="#environment">environment variables</a> below. +<code>all.bash</code> (or <code>all.bat</code>) runs important tests for Go, +which can take more time than simply building Go. If you do not want to run +the test suite use <code>make.bash</code> (or <code>make.bat</code>) +instead. </p> </div> @@ -354,9 +358,9 @@ These default to the values of <code>$GOHOSTOS</code> and <p> Choices for <code>$GOOS</code> are -<code>darwin</code> (Mac OS X 10.6 and above), <code>freebsd</code>, +<code>darwin</code> (Mac OS X 10.6 and above), <code>dragonfly</code>, <code>freebsd</code>, <code>linux</code>, <code>netbsd</code>, <code>openbsd</code>, -<code>plan9</code>, and <code>windows</code>. +<code>plan9</code>, <code>solaris</code> and <code>windows</code>. Choices for <code>$GOARCH</code> are <code>amd64</code> (64-bit x86, the most mature port), <code>386</code> (32-bit x86), and <code>arm</code> (32-bit ARM). @@ -372,6 +376,12 @@ The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> are: <td></td><td><code>darwin</code></td> <td><code>amd64</code></td> </tr> <tr> +<td></td><td><code>dragonfly</code></td> <td><code>386</code></td> +</tr> +<tr> +<td></td><td><code>dragonfly</code></td> <td><code>amd64</code></td> +</tr> +<tr> <td></td><td><code>freebsd</code></td> <td><code>386</code></td> </tr> <tr> @@ -411,6 +421,9 @@ The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> are: <td></td><td><code>plan9</code></td> <td><code>amd64</code></td> </tr> <tr> +<td></td><td><code>solaris</code></td> <td><code>amd64</code></td> +</tr> +<tr> <td></td><td><code>windows</code></td> <td><code>386</code></td> </tr> <tr> @@ -444,7 +457,7 @@ installs all commands there. </p> <li><code>$GO386</code> (for <code>386</code> only, default is auto-detected -if built natively, <code>387</code> if not) +if built on either <code>386</code> or <code>amd64</code>, <code>387</code> otherwise) <p> This controls the code generated by 8g to use either the 387 floating-point unit (set to <code>387</code>) or SSE2 instructions (set to <code>sse2</code>) for diff --git a/doc/install.html b/doc/install.html index af4c8f3d1..7282ae947 100644 --- a/doc/install.html +++ b/doc/install.html @@ -6,15 +6,15 @@ <h2 id="download">Download the Go distribution</h2> <p> -<a href="http://code.google.com/p/go/downloads" id="start" class="download" target="_blank"> +<a href="/dl/" id="start" class="download" target="_blank"> <span class="big">Download Go</span> <span class="desc">Click here to visit the downloads page</span> </a> </p> <p> -<a href="http://code.google.com/p/go/downloads" target="_blank">Official binary -distributions</a> are available for the FreeBSD, Linux, Mac OS X (Snow Leopard +<a href="https://code.google.com/p/go/wiki/Downloads?tm=2" target="_blank">Official binary +distributions</a> are available for the FreeBSD (release 8 and above), Linux, Mac OS X (Snow Leopard and above), and Windows operating systems and the 32-bit (<code>386</code>) and 64-bit (<code>amd64</code>) x86 processor architectures. </p> @@ -39,15 +39,15 @@ proceeding. If your OS or architecture is not on the list, it's possible that <table class="codetable" frame="border" summary="requirements"> <tr> -<th align="middle">Operating system</th> -<th align="middle">Architectures</th> -<th align="middle">Notes</th> +<th align="center">Operating system</th> +<th align="center">Architectures</th> +<th align="center">Notes</th> </tr> <tr><td colspan="3"><hr></td></tr> -<tr><td>FreeBSD 7 or later</td> <td>amd64, 386, arm</td> <td>Debian GNU/kFreeBSD not supported; FreeBSD/ARM needs FreeBSD 10 or later</td></tr> +<tr><td>FreeBSD 8 or later</td> <td>amd64, 386, arm</td> <td>Debian GNU/kFreeBSD not supported; FreeBSD/ARM needs FreeBSD 10 or later</td></tr> <tr><td>Linux 2.6.23 or later with glibc</td> <td>amd64, 386, arm</td> <td>CentOS/RHEL 5.x not supported; no binary distribution for ARM yet</td></tr> <tr><td>Mac OS X 10.6 or later</td> <td>amd64, 386</td> <td>use the gcc<sup>†</sup> that comes with Xcode<sup>‡</sup></td></tr> -<tr><td>Windows 2000 or later</td> <td>amd64, 386</td> <td>use mingw gcc<sup>†</sup>; cygwin or msys is not needed</td></tr> +<tr><td>Windows XP or later</td> <td>amd64, 386</td> <td>use MinGW gcc<sup>†</sup>. No need for cgywin or msys.</td></tr> </table> <p> @@ -70,18 +70,19 @@ first <a href="#uninstall">remove the existing version</a>. <h3 id="tarball">Linux, Mac OS X, and FreeBSD tarballs</h3> <p> -<a href="http://code.google.com/p/go/downloads/list?q=OpSys-FreeBSD+OR+OpSys-Linux+OR+OpSys-OSX+Type-Archive">Download the archive</a> +<a href="https://code.google.com/p/go/wiki/Downloads?tm=2">Download the archive</a> and extract it into <code>/usr/local</code>, creating a Go tree in <code>/usr/local/go</code>. For example: </p> <pre> -tar -C /usr/local -xzf go1.2.1.linux-amd64.tar.gz +tar -C /usr/local -xzf go$VERSION.$OS-$ARCH.tar.gz </pre> <p> -The name of the archive may differ, depending on the version of Go you are -installing and your system's operating system and processor architecture. +Choose the archive file appropriate for your installation. +For instance, if you are installing Go version 1.2.1 for 64-bit x86 on Linux, +the archive you want is called <code>go1.2.1.linux-amd64.tar.gz</code>. </p> <p> @@ -126,7 +127,7 @@ location. <h3 id="osx">Mac OS X package installer</h3> <p> -<a href="http://code.google.com/p/go/downloads/list?q=OpSys-OSX+Type-Installer">Download the package file</a>, +<a href="https://code.google.com/p/go/wiki/Downloads?tm=2">Download the package file</a>, open it, and follow the prompts to install the Go tools. The package installs the Go distribution to <code>/usr/local/go</code>. </p> @@ -149,7 +150,7 @@ MSI installer that configures your installation automatically. <h4 id="windows_msi">MSI installer</h4> <p> -Open the <a href="http://code.google.com/p/go/downloads/list?q=OpSys-Windows+Type%3DInstaller">MSI file</a> +Open the <a href="https://code.google.com/p/go/wiki/Downloads?tm=2">MSI file</a> and follow the prompts to install the Go tools. By default, the installer puts the Go distribution in <code>c:\Go</code>. </p> @@ -163,7 +164,7 @@ command prompts for the change to take effect. <h4 id="windows_zip">Zip archive</h4> <p> -<a href="http://code.google.com/p/go/downloads/list?q=OpSys-Windows+Type%3DArchive">Download the zip file</a> and extract it into the directory of your choice (we suggest <code>c:\Go</code>). +<a href="https://code.google.com/p/go/wiki/Downloads?tm=2">Download the zip file</a> and extract it into the directory of your choice (we suggest <code>c:\Go</code>). </p> <p> @@ -227,7 +228,7 @@ You just need to do a little more setup. </p> <p> -<a href="/doc/code.html" class="download" id="start"> +<a href="/doc/code.html" class="download" id="writing"> <span class="big">How to Write Go Code</span> <span class="desc">Learn how to set up and use the Go tools</span> </a> diff --git a/doc/root.html b/doc/root.html index 48280ac35..43637933a 100644 --- a/doc/root.html +++ b/doc/root.html @@ -140,7 +140,6 @@ window.initFuncs.push(function() { var videos = [ {h: 241, s: "//www.youtube.com/embed/ytEkHepK08c"}, // Tour of Go {h: 241, s: "//www.youtube.com/embed/f6kdp27TYZs"}, // Concurrency Patterns - {h: 233, s: "//player.vimeo.com/video/53221560"}, // Grows with grace {h: 233, s: "//player.vimeo.com/video/69237265"} // Simple environment ]; var v = videos[Math.floor(Math.random()*videos.length)]; |