go/doc/go1.4.html

<!--{
	"Title": "Go 1.4 Release Notes",
	"Path":  "/doc/go1.4",
	"Template": true
}-->

<h2 id="introduction">Introduction to Go 1.4</h2>

<p>
The latest Go release, version 1.4, arrives as scheduled six months after 1.3
and contains only one tiny language change,
a backwards-compatible simple form of <code>for</code>-<code>range</code> loop.
The release focuses primarily on implementation work, improving the garbage collector
and preparing the ground for a fully concurrent collector to be rolled out in the
next few releases.
Stacks are now contiguous, reallocated when necessary rather than linking on new
"segments";
this release therefore eliminates the notorious "hot stack split" problem.
There are some new tools available including support in the <code>go</code> command
for build-time source code generation
and TODO.
The release also adds support for TODO architecture and TODO operating systems.
As always, Go 1.4 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.4.
</p>

<h2 id="language">Changes to the language</h2>

<h3 id="forrange">For-range loops</h3>
<p>
Up until Go 1.3, <code>for</code>-<code>range</code> loop had two forms
</p>

<pre>
for k, v := range x {
	...
}
</pre>

<p>
and
</p>

<pre>
for k := range x {
	...
}
</pre>

<p>
If one was not interested in the loop values, only the iteration itself, it was still
necessary to mention a variable (probably the <a href="/ref/spec#Blank_identifier">blank identifier</a>, as in
<code>for</code> <code>_</code> <code>=</code> <code>range</code> <code>x</code>), because
the form
</p>

<pre>
for range x {
	...
}
</pre>

<p>
was not syntactically permitted.
</p>

<p>
This situation seemed awkward, so as of Go 1.4 the variable-free form is now legal.
The situation arises only rarely but the code can be cleaner when it does.
</p>

<p>
<em>Updating</em>: The change is strictly backwards compatible to existing Go
programs, but tools that analyze Go parse trees may need to be modified to accept
this new form as the
<code>Key</code> field of <a href="/pkg/go/ast/#RangeStmt"><code>RangeStmt</code></a>
may now be <code>nil</code>.
</p>

<h2 id="os">Changes to the supported operating systems and architectures</h2>

<h3 id="foobarblatz">FooBarBlatz</h3>

<p>
TODO news about foobarblatz
</p>

<h2 id="compatibility">Changes to the compatibility guidelines</h2>

<p>
The <a href="/pkg/unsafe/"><code>unsafe</code></a> package allows one
to defeat Go's type system by exploiting internal details of the implementation
or machine representation of data.
It was never explicitly specified what use of <code>unsafe</code> meant
with respect to compatibility as specified in the
<a href="go1compat.html">Go compatibilty guidelines</a>.
The answer, of course, is that we can make no promise of compatibility
for code that does unsafe things.
</p>

<p>
We have clarified this situation in the documentation included in the release.
The <a href="go1compat.html">Go compatibilty guidelines</a> and the
docs for the <a href="/pkg/unsafe/"><code>unsafe</code></a> package
are now explicit that unsafe code is not guaranteed to remain compatible.
</p>
  
<p>
<em>Updating</em>: Nothing technical has changed; this is just a clarification
of the documentation.
</p>


<h2 id="impl">Changes to the implementations and tools</h2>

<h3 id="runtime">Changes to the runtime</h3>

<p>
Up to Go 1.4, the runtime (garbage collector, concurrency support, interface management,
maps, slices, strings, ...) was mostly written in C, with some assembler support.
In 1.4, much of the code has been translated to Go so that the garbage collector can scan
the stacks of programs in the runtime and get accurate information about what variables
are active.
This change was large but should have no semantic effect on programs.
</p>

<p>
This rewrite allows the garbage collector in 1.4 to be fully precise,
meaning that it is aware of the location of all active pointers in the program.
This means the heap will be smaller as there will be no false positives keeping non-pointers alive.
Other related changes also reduce the heap size, which is smaller by 10%-30% overall
relative to the previous release.
</p>

<p>
A consequence is that stacks are no longer segmented, eliminating the "hot split" problem.
When a stack limit is reached, a new, larger stack is allocated, all active frames for
the goroutine are copied there, and any pointers into the stack are updated.
Performance can be noticeably better in some cases and is always more predictable.
Details are available in <a href="/s/contigstacks">the design document</a>.
</p>

<p>
The use of contiguous stacks means that stacks can start smaller without triggering performance issues,
so the default starting size for a goroutine's stack in 1.4 has been reduced to 2048 bytes from 8192 bytes.
TODO: It may be bumped to 4096 for the release.
</p>

<p>
As preparation for the concurrent garbage collector scheduled for the 1.5 release,
writes to pointer values in the heap are now done by a function call,
called a write barrier, rather than directly from the function updating the value.
In this next release, this will permit the garbage collector to mediate writes to the heap while it is running.
This change has no semantic effect on programs in 1.4, but was
included in the release to test the compiler and the resulting performance.
</p>

<p>
The implementation of interface values has been modified.
In earlier releases, the interface contained a word that was either a pointer or a one-word
scalar value, depending on the type of the concrete object stored.
This implementation was problematical for the garbage collector,
so as of 1.4 interface values always hold a pointer.
In running programs, most interface values were pointers anyway,
so the effect is minimal, but programs that store integers (for example) in
interfaces will see more allocations.
</p>

<h3 id="gccgo">Status of gccgo</h3>

<p>
TODO gccgo news
</p>

<h3 id="internalpackages">Internal packages</h3>
<pre>
TODO prose for these
cmd/go: implement "internal" (CL 120600043)
</pre>

<h3 id="importcomments">Import comments</h3>

<pre>
TODO prose for these
cmd/go: import comments (CL 124940043)
</pre>

<h3 id="gogenerate">The go generate subcommand</h3>

<p>
The <a href="/cmd/go/"><code>go</code></a> command has a new subcommand,
<a href="/cmd/go/#hdr-Generate_Go_files_by_processing_source"><code>go generate</code></a>,
to automate the running of tools to generate source code before compilation.
For example, it can be used to run the <a href="http://en.wikipedia.org/wiki/Yacc"><code>yacc</code></a>
compiler-compiler on a <code>.y</code> file to produce the Go source file implementing the grammar,
or to automate the generation of <code>String</code> methods for typed constants using the new
<a href="http://godoc.org/code.google.com/p/go.tools/cmd/stringer">stringer</a>
tool in the <code>go.tools</code> repository.
</p>

<p>
For more information, see the 
<a href="http://golang.org/s/go1.4-generate">design document</a>.
</p>

<h3 id="filenames">Change to file name handling</h3>

<p>
Build constraints, also known as build tags, control compilation by including or excluding files
(see the documentation <a href="/pkg/go/build/"><code>/go/build</code></a>).
Compilation can also be controlled by the name of the file itself by "tagging" the file with
a suffix (before the <code>.go</code> or <code>.s</code> extension) with an underscore
and the name of the architecture or operating system.
For instance, the file <code>gopher_arm.go</code> will only be compiled if the target
processor is an ARM.
</p>

<p>
Before Go 1.4, a file called just <code>arm.go</code> was similarly tagged, but this behavior
can break sources when new architectures are added, causing files to suddenly become tagged.
In 1.4, therefore, a file will be tagged in this manner only if the tag (architecture or operating
system name) is preceded by an underscore.
</p>

<p>
<em>Updating</em>: Packages that depend on the old behavior will no longer compile correctly.
Files with names like <code>windows.go</code> or <code>arm64.go</code> should either
have explicit build tags added to the source or be renamed to something like
<code>os_windows.go</code> or <code>support_arm64.go</code>.
</p>

<h3 id="gocmd">Other changes to the go command</h3>

<p>
There were a number of minor changes to the
<a href="/cmd/go/"><code>cmd/go</code></a>
command worth noting.
</p>

<ul>

<li>
Unless <a href="/cmd/cgo/"><code>cgo</code></a> is being used to build the package,
the <code>go</code> command now refuses to compile C source files,
since the relevant C compilers
(<a href="/cmd/6c/"><code>6c</code></a> etc.)
are intended to be removed from the installation in some future release.
(They are used today only to build part of the runtime.)
It is difficult to use them correctly in any case, so any extant uses are likely incorrect,
so we have disabled them.
</li>

<li>
The <a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>test</code></a>
subcommand has a new flag, <code>-o</code>, to set the name of the resulting binary,
corresponding to the same flag in other subcommands.
The non-functional <code>-file</code> flag has been removed.
</li>

<li>
The <a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>test</code></a>
will compile and link all <code>*_test.go</code> files in the package,
even when there are no <code>Test</code> functions in them. 
It previously ignored such files.
</li>

<li>
The behavior of the
<a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>build</code></a>'s
<code>-a</code> flag has been changed for non-development installations.
For installations running a released distribution, the <code>-a</code> flag will no longer
rebuild the standard library and commands, to avoid overwriting the installation's files.
</li>

</ul>

<h3 id="cgo">Changes to cgo</h3>

<p>
TODO cgo news
</p>


<h3 id="godoc">Changes to godoc</h3>
<p>
TODO godoc news
</p>

<h3 id="pkg">Changes to package source layout</h3>

<p>
In the main Go source repository, the source code for the packages was kept in
the directory <code>src/pkg</code>, which made sense but differed from
other repositories, including the Go sub-repositories such as <code>go.tools</code>.
In Go 1.4, the<code> pkg</code> level of the source tree is now gone, so for example
the <a href="/pkg/fmt/"><code>fmt</code></a> package's source, once kept in
directory <code>src/pkg/fmt</code>, now lives one level higher in <code>src/fmt</code>.
</p>

<p>
<em>Updating</em>: Tools like <code>godoc</code> that discover source code
need to know about the new location. All tools and services maintained by the Go team
have been updated.
</p>

<h3 id="misc">Miscellany</h3>

<p>
TODO misc news
</p>

<h2 id="performance">Performance</h2>

<p>
Most programs will run about the same speed or slightly faster in 1.4 than in 1.3;
some will be slightly slower.
There are many changes, making it hard to be precise about what to expect.
</p>

<p>
As mentioned above, much of the runtime was translated to Go from C,
which led to some reduction in heap sizes.
It also improved performance slightly because the Go compiler is better
at optimization, due to things like inlining, than the C compiler used to build
the runtime.
</p>

<p>
The garbage collector was sped up, leading to measurable improvements for
garbage-heavy programs.
On the other hand, the new write barriers slow things down again, typically
by about the same amount but, depending on their behavior, some programs
may be somewhat slower or faster.
</p>

<p>
Library changes that affect performance are documented below.
</p>

<h2 id="library">Changes to the standard library</h2>

<h3 id="new_packages">New packages</h3>

<p>
TODO new packages
</p>

<h3 id="major_library_changes">Major changes to the library</h3>

<p>
TODO major changes
</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> TODO changes
</li>
</ul>

<pre>

cmd/6l, liblink: use pc-relative addressing for all memory references, so that linking Go binaries at high addresses works (CL 125140043). This cuts the maximum size of a Go binary's text+data+bss from 4GB to 2GB.

asm: make textflag.h available outside of cmd/ld (CL 128050043)
bufio: handling of empty tokens at EOF changed, may require scanner change (CL 145390043)
compress/flate, compress/gzip, compress/zlib: Reset support (https://codereview.appspot.com/97140043)
crypto/tls: add support for ALPN (RFC 7301) (CL 108710046)
crypto/tls: support programmatic selection of server certificates (CL 107400043)
encoding/asn1: optional elements with a default value will now only be omitted if they have that value (CL 86960045)
flag: it is now an error to set a flag multiple times (CL 156390043)
fmt: print type *map[T]T as &amp;map[k:v] (CL 154870043)
encoding/csv: do not quote empty strings, quote \. (CL 164760043)
encoding/gob: remove unsafe (CL 102680045)
misc: deleted editor support; refer to https://code.google.com/p/go-wiki/wiki/IDEsAndTextEditorPlugins instead (CL 105470043)
net/http: add Request.BasicAuth method (CL 76540043)
net/http: add Transport.DialTLS hook (CL 137940043)
net/http/httputil: add ReverseProxy.ErrorLog (CL 132750043)
os: implement symlink support for windows (CL 86160044)
reflect: add type.Comparable (CL 144020043)
reflect: Value is one word smaller
runtime: implement monotonic clocks on windows (CL 108700045)
runtime: MemStats.Mallocs now counts very small allocations missed in Go 1.3. This may break tests using runtime.ReadMemStats or testing.AllocsPerRun by giving a more accurate answer than Go 1.3 did (CL 143150043).
runtime/race: freebsd is supported (CL 107270043)
swig: Due to runtime changes Go 1.4 will require SWIG 3.0.3 (not yet released)
sync/atomic: add Value (CL 136710045)
syscall: Setuid, Setgid are disabled on linux platforms. On linux those syscalls operate on the calling thread, not the whole process. This does not match the semantics of other platforms, nor the expectations of the caller, so the operations have been disabled until issue 1435 is resolved (CL 106170043)
syscall: now frozen (CL 129820043)
testing: add Coverage (CL 98150043)
testing: add TestMain support (CL 148770043)
text/scanner: add IsIdentRune field of Scanner. (CL 108030044)
text/template: allow comparison of signed and unsigned integers (CL 149780043)
time: use the micro symbol (µ (U+00B5)) to print microsecond duration (CL 105030046)
unsafe: document the existing situation that unsafe programs are not go1-guaranteed (CL 162060043)

go.sys subrepo created: http://golang.org/s/go1.4-syscall
</pre>