diff options
Diffstat (limited to 'doc/go1.3.html')
| -rw-r--r-- | doc/go1.3.html | 599 |
1 files changed, 599 insertions, 0 deletions
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> |