doc/go1.10: process comments from CL 78131 PS 5
Change-Id: Ie246756452cd872961aeb659b35297c229504a3c
Reviewed-on: https://go-review.googlesource.com/81936
Reviewed-by: Russ Cox <rsc@golang.org>
diff --git a/doc/go1.10.html b/doc/go1.10.html
index a42c719..dcf45cd 100644
--- a/doc/go1.10.html
+++ b/doc/go1.10.html
@@ -22,6 +22,16 @@
release notes. Go 1.10 is expected to be released in February 2018.
</strong></p>
+<!-- TODO: not sure about these relnotes
+
+cmd/compile
+ https://golang.org/cl/60410: cmd/compile: fix and improve struct field reflect information
+encoding/json
+ https://golang.org/cl/76851: encoding/json: always ignore embedded pointers to unexported struct types
+runtime
+ https://golang.org/cl/59970: runtime: separate soft and hard heap limits
+-->
+
<p>
The latest Go release, version 1.10, arrives six months after <a href="go1.9">go1.9</a>.
Most of its changes are in the implementation of the toolchain, runtime, and libraries.
@@ -141,8 +151,8 @@
dependencies had been installed.
To force the installation of dependencies, use the new
<code>go</code> <code>install</code> <code>-i</code> flag.
-Installing dependencies should not be necessary in general,
-and the very concept or installed packages may disappear in a future release.
+Installing dependency packages should not be necessary in general,
+and the very concept of installed packages may disappear in a future release.
</p>
<p>
@@ -208,7 +218,7 @@
<p>
The <code>go</code> <code>test</code> <code>-v</code> output
now includes <code>PAUSE</code> and <code>CONT</code> status update
-lines to make clearer when <a href="/pkg/testing/#T.Parallel">parallel tests</a> pause and continue.
+lines to mark when <a href="/pkg/testing/#T.Parallel">parallel tests</a> pause and continue.
</p>
<p>
@@ -320,13 +330,14 @@
<p>
The <a href="/cmd/pprof/"><code>go</code> <code>tool</code> <code>pprof</code></a> profile visualizer has been updated to
-the latest version from <a href="https://github.com/google/pprof">github.com/google/pprof</a>.
+the latest version from <a href="https://github.com/google/pprof">github.com/google/pprof</a>,
+which includes an updated web interface.
</p>
<h3 id="vet">Vet</h3>
<p>
-The <a href="/cmd/pprof/"><code>go</code> <code>vet</code></a> command now always has access to
+The <a href="/cmd/vet/"><code>go</code> <code>vet</code></a> command now always has access to
complete, up-to-date type information when checking packages, even for packages using cgo or vendored imports.
The reports should be more accurate as a result.
Note that only <code>go</code> <code>vet</code> has access to this information;
@@ -386,9 +397,10 @@
</p>
<p>
-TODO: What to say about DWARF work, if anything?
-Global constants (CL 61019), variable decomposition (CL 50878), variable liveness and location lists (CL 41770), more?
-What is enabled by default?
+The DWARF debug information recorded in binaries has been improved in a few ways:
+constant values are now recorded;
+line number information is more accurate, making source-level stepping through a program work better;
+and each package is now presented as its own DWARF compilation unit.
</p>
<p>
@@ -493,8 +505,8 @@
</p>
<p>
-For the X86 64-bit port, the assembler now supports 359 new instructions
-and is believed to be complete up to and including the Intel AVX-256 extensions.
+For the X86 64-bit port, the assembler now supports 359 new instructions,
+including the full AVX, AVX2, BMI, BMI2, F16C, FMA3, SSE2, SSE3, SSSE3, SSE4.1, and SSE4.2 extension sets.
The assembler also no longer implements <code><small>MOVL</small></code> <code><small>$0,</small></code> <code><small>AX</small></code>
as an <code><small>XORL</small></code> instruction,
to avoid clearing the condition flags unexpectedly.
@@ -509,12 +521,35 @@
<h2 id="runtime">Runtime</h2>
<p>
-TODO: Don't start new threads from locked threads or threads that Go did not create. LockOSThread/UnlockOSThread now nest. LockOSThread + return kills the thread
+The behavior of nested calls to
+<a href="/pkg/runtime/#LockOSThread"><code>LockOSThread</code></a> and
+<a href="/pkg/runtime/#UnlockOSThread"><code>UnlockOSThread</code></a>
+has changed.
+These functions control whether a goroutine is locked to a specific operating system thread,
+so that the goroutine only runs on that thread, and the thread only runs that goroutine.
+Previously, calling <code>LockOSThread</code> more than once in a row
+was equivalent to calling it once, and a single <code>UnlockOSThread</code>
+always unlocked the thread.
+Now, the calls nest: if <code>LockOSThread</code> is called multiple times,
+<code>UnlockOSThread</code> must be called the same number of times
+in order to unlock the thread.
+Existing code that was careful not to nest these calls will remain correct.
+Existing code that incorrectly assumed the calls nested will become correct.
+Most uses of these functions in public Go source falls into the second category.
+</p>
+
+<p>
+Because one common use of <code>LockOSThread</code> and <code>UnlockOSThread</code>
+is to allow Go code to reliably modify thread-local state (for example, Linux or Plan 9 name spaces),
+the runtime now treats locked threads as unsuitable for reuse or for creating new threads.
</p>
<p>
Stack traces no longer include implicit wrapper functions (previously marked <code><autogenerated></code>),
unless a fault or panic happens in the wrapper itself.
+As a result, skip counts passed to functions like <a href="/pkg/runtime/#Caller"><code>Caller</code></a>
+should now always match the structure of the code as written, rather than depending on
+optimization decisions and implementation details.
</p>
<p>
@@ -534,7 +569,7 @@
<h2 id="gc">Garbage Collector</h2>
<p>
-TODO: Anything?
+Many applications should experience significantly lower allocation latency and overall performance overhead when the garbage collector is active.
</p>
<h2 id="library">Core library</h2>
@@ -571,12 +606,13 @@
of type <a href="/pkg/archive/tar/#Format"><code>Format</code></a>
controls which tar header format the <a href="/pkg/archive/tar/#Writer"><code>Writer</code></a> uses.
The default, as before, is to select the most widely-supported header type
-that can encoding the fields needed by the header (USTAR if possible, or else PAX if possible, or else GNU).
+that can encode the fields needed by the header (USTAR if possible, or else PAX if possible, or else GNU).
The <a href="/pkg/archive/tar/#Reader"><code>Reader</code></a> sets <code>Header.Format</code> for each header it reads.
</p>
<p>
-<code>Reader</code> and the <code>Writer</code> now support PAX records,
-using the new <a href="/pkg/archive/tar/#Header"><code>Header.PAXRecords</code></a> field.
+<code>Reader</code> and the <code>Writer</code> now support arbitrary PAX records,
+using the new <a href="/pkg/archive/tar/#Header"><code>Header.PAXRecords</code></a> field,
+a generalization of the existing <code>Xattrs</code> field.
</p>
<p>
The <code>Reader</code> no longer insists that the file name or link name in GNU headers
@@ -587,10 +623,6 @@
the <code>Header.AccessTime</code> and <code>Header.ChangeTime</code> fields (if set).
When writing PAX-format headers, the times include sub-second precision.
</p>
-<p>
-The <a href="/pkg/archive/tar/#Writer.Flush"><code>Writer.Flush</code></a> method,
-which has had no real effect since Go 1.1, is now marked deprecated.
-</p>
</dl>
<dl id="archive/zip"><dt><a href="/pkg/archive/zip/">archive/zip</a></dt>
@@ -607,8 +639,9 @@
The <a href="/pkg/archive/zip/#FileHeader"><code>FileHeader</code></a>'s new <code>Modified</code> field of type <a href="/pkg/time/#Time"><code>time.Time</code></a>
obsoletes the <code>ModifiedTime</code> and <code>ModifiedDate</code> fields, which continue to hold the MS-DOS encoding.
The <code>Reader</code> and <code>Writer</code> now adopt the common
-convention that ZIP archive storing the Unix time encoding store the local time
-in the MS-DOS field, so that the time zone offset can be inferred.
+convention that a ZIP archive storing a time zone-independent Unix time
+also stores the local time in the MS-DOS field,
+so that the time zone offset can be inferred.
For compatibility, the <a href="/pkg/archive/zip/#FileHeader.ModTime"><code>ModTime</code></a> and
<a href="/pkg/archive/zip/#FileHeader.SetModTime"><code>SetModTime</code></a> methods
behave the same as in earlier releases; new code should use <code>Modified</code> directly.
@@ -770,7 +803,7 @@
<p>
Go 1.10 adds support for reading relocations from Mach-O sections,
using the <a href="/pkg/debug/macho#Section"><code>Section</code></a> struct's new <code>Relocs</code> field
-and the new<a href="/pkg/debug/macho/#Reloc"><code>Reloc</code></a>,
+and the new <a href="/pkg/debug/macho/#Reloc"><code>Reloc</code></a>,
<a href="/pkg/debug/macho/#RelocTypeARM"><code>RelocTypeARM</code></a>,
<a href="/pkg/debug/macho/#RelocTypeARM64"><code>RelocTypeARM64</code></a>,
<a href="/pkg/debug/macho/#RelocTypeGeneric"><code>RelocTypeGeneric</code></a>,
@@ -846,7 +879,7 @@
and
<a href="/pkg/encoding/hex/#DecodeString"><code>DecodeString</code></a>
encounter malformed input,
-they each now return the number of bytes already converted
+they now return the number of bytes already converted
along with the error.
Previously they always returned a count of 0 with any error.
</p>
@@ -857,7 +890,7 @@
<p>
The <a href="/pkg/encoding/json/#Decoder"><code>Decoder</code></a>
adds a new method
-<a href="/pkg/encoding/json/#DisallowUnknownFields"><code>DisallowUnknownFields</code></a>
+<a href="/pkg/encoding/json/#Decoder.DisallowUnknownFields"><code>DisallowUnknownFields</code></a>
that causes it to report inputs with unknown JSON fields as a decoding error.
(The default behavior has always been to discard unknown fields.)
</p>
@@ -872,6 +905,10 @@
no longer generate partial output when presented with a
block that is impossible to encode as PEM data.
</p>
+
+<p>
+TODO: Reflect fallout.
+</p>
</dl>
<dl id="encoding/xml"><dt><a href="/pkg/encoding/xml/">encoding/xml</a></dt>
@@ -1005,7 +1042,7 @@
<dl id="math/rand"><dt><a href="/pkg/math/rand/">math/rand</a></dt>
<dd>
<p>
-The new <a href="/pkg/math/rand/#Shuffle"> function and corresponding
+The new <a href="/pkg/math/rand/#Shuffle"><code>Shuffle</code></a> function and corresponding
<a href="/pkg/math/rand/#Rand.Shuffle"><code>Rand.Shuffle</code></a> method
shuffle an input sequence.
</p>
@@ -1018,9 +1055,9 @@
<a href="/pkg/math/#Round"><code>Round</code></a>
and
<a href="/pkg/math/#RoundToEven"><code>RoundToEven</code></a>
-round their arguments to the nearest integer;
+round their arguments to the nearest floating-point integer;
<code>Round</code> rounds a half-integer to its larger integer neighbor (away from zero)
-while <code>RoundToEven</code> rounds a half-integer its even integer neighbor.
+while <code>RoundToEven</code> rounds a half-integer to its even integer neighbor.
</p>
<p>
@@ -1112,21 +1149,7 @@
<dl id="net/http/httputil"><dt><a href="/pkg/net/http/httputil/">net/http/httputil</a></dt>
<dd>
<p>
-The <a href="/pkg/net/http/httputil/#ReverseProxy">ReverseProxy</a> now invokes
-the <code>
-On the client side, an HTTP proxy (most commonly configured by
-<a href="/pkg/net/http/#ProxyFromEnvironment"><code>ProxyFromEnvironment</code></a>)
-can now be specified as an <code>https://</code> URL,
-meaning that the client connects to the proxy over HTTPS before issuing a standard, proxied HTTP request.
-(Previously, HTTP proxy URLs were required to begin with <code>http://</code> or <code>socks5://</code>.)
-</p>
-<p>
-On the server side, <a href="/pkg/net/http/#FileServer"><code>FileServer</code></a> and its single-file equivalent <a href="/pkg/net/http/#ServeFile"><code>ServeFile</code></a>
-now apply <code>If-Range</code> checks to <code>HEAD</code> requests.
-<code>FileServer</code> also now reports directory read failures to the <a href="/pkg/net/http/#Server"><code>Server</code></a>'s <code>ErrorLog</code>.
-</p>
-<p>
-<a href="/pkg/net/http/#Redirect"><code>Redirect</code></a> now sets the <code>Content-Type</code> header before writing its HTTP response.
+TODO: ReverseProxy and back end errors and ModifyResponse.
</p>
</dl>
@@ -1134,7 +1157,7 @@
<dd>
<p>
<a href="/pkg/net/mail/#ParseAddress"><code>ParseAddress</code></a> and
-<a href="/pkg/net/mail/#ParseAddressList"><code>ParseAddressList</code></a> and
+<a href="/pkg/net/mail/#ParseAddressList"><code>ParseAddressList</code></a>
now support a variety of obsolete address formats.
</p>
</dl>
@@ -1243,6 +1266,10 @@
from a string into a byte array or byte slice, to match the
<a href="/pkg/builtin/#copy">built-in copy function</a>.
</p>
+
+<p>
+TODO: New reflect CanSet change for pointers to unexported fields.
+</p>
</dl>
<dl id="runtime/pprof"><dt><a href="/pkg/runtime/pprof/">runtime/pprof</a></dt>
