From 268bc396c1ce5b7495c5818a286ef92763c1ba7e Mon Sep 17 00:00:00 2001 From: Brad Fitzpatrick Date: Tue, 29 Nov 2016 19:36:44 +0000 Subject: [PATCH] doc: more go1.8.html tweaks and new context additions section TBR=See https://golang.org/cl/33244 Updates #17929 Change-Id: Id5d5472cf1e41472d8d0f82ee133c7387257ba2b Reviewed-on: https://go-review.googlesource.com/33664 Reviewed-by: Brad Fitzpatrick --- doc/go1.8.html | 140 +++++++++++++++++++++++++++++++------------------ 1 file changed, 89 insertions(+), 51 deletions(-) diff --git a/doc/go1.8.html b/doc/go1.8.html index 6f828b13d3..a70cc44284 100644 --- a/doc/go1.8.html +++ b/doc/go1.8.html @@ -35,7 +35,8 @@ The release adds support for 32-bit MIPS, updates the compiler back end to generate more efficient code, reduces GC pauses by eliminating stop-the-world stack rescanning, adds HTTP/2 Push support, -adds HTTP graceful shutdown, +adds HTTP graceful shutdown, +more context support, and simplifies sorting slices.

@@ -43,7 +44,7 @@ and simplifies sorting slices.

When explicitly converting structs, tags are now ignored for structural type identity. - See language specification for details. + See the language specification for details.

@@ -74,7 +75,7 @@ and cancelation.

Go 1.8 now only supports OS X 10.8 or later. This is likely the last - Go release to continue supporting 10.8. Compiling Go or running + Go release to support 10.8. Compiling Go or running binaries on older OS X versions is untested.

@@ -229,7 +230,7 @@ see improvements closer to the 32-bit ARM numbers.

In addition to enabling the new compiler back end for all systems, Go 1.8 also introduces a new compiler front end. The new compiler - front end should not be noticeable to users is the foundation for + front end should not be noticeable to users but is the foundation for future performance work.

@@ -252,14 +253,15 @@ see improvements closer to the 32-bit ARM numbers.

Go command

-The go command's basic operation -is unchanged, but there are a number of changes worth noting. +The go command's basic operation +is unchanged, but there is one addition worth noting.

- A new + The new “go - bug” command helps users file bug reports. + bug” starts a bug report on GitHub, prefilled + with information about the current system.

Go doc

@@ -274,14 +276,15 @@ is unchanged, but there are a number of changes worth noting.

- In order to improve the readability of the doc's + In order to improve the readability of doc's output, each summary of the first-level items is guaranteed to occupy a single line.

- Documentation for interface methods is now only shown when requested - explicitly. + Documentation for a specific method in an interface definition can + now be requested, as in + “go doc net.Conn.SetDeadline”.

Plugins

@@ -307,10 +310,14 @@ is unchanged, but there are a number of changes worth noting.

- Updating: Users of finalizers should see the example - in the KeepAlive documentation - to see where a call to KeepAlive might be needed. -

+ Updating: + Code that sets a finalizer on an allocated object may need to add + calls to runtime.KeepAlive in functions or methods + using that object. + Read the + KeepAlive + documentation and its example for more details. +

MemStats Documentation

@@ -344,8 +351,8 @@ packages.

Garbage collection pauses should be significantly shorter than they - were in Go 1.7, often as low as 10 microseconds and usually under 100 - microseconds. + were in Go 1.7, usually under 100 microseconds and often as low as + 10 microseconds. See the document on eliminating stop-the-world stack re-scanning @@ -357,7 +364,7 @@ packages.

The overhead of deferred - function calls has been reduced by half. + function calls has been reduced by about half.

Cgo

@@ -409,11 +416,33 @@ now implements the new

The HTTP Server now has support for graceful shutdown using the new Server.Shutdown - method. The related and more abrupt + method and abrupt shutdown using the new Server.Close - is also new. + method. +

+ +

More Context Support

+ +

+ Continuing Go 1.7's adoption + of context.Context + into the standard library, Go 1.8 adds more context support + to existing packages:

+ +

Minor changes to the library

@@ -493,8 +522,8 @@ in mind. Similarly, the Reader - now updates the Header.ModTime field only if the - encoded MTIME field is non-zero. + now reports a zero encoded MTIME field as a zero + Header.ModTime.

@@ -519,12 +548,11 @@ in mind. ending in Context such as DB.QueryContext and DB.PrepareContext - that support Context. By using the new Context methods it ensures + that take context arguments. Using the new Context methods ensures that connections are closed and returned to the connection pool when the - request is done. It also enables canceling in-progress queries - should the driver support it. Finally, using the Context - methods allows the database pool to cancel waiting for the next - available connection. + request is done; enables canceling in-progress queries + should the driver support that; and allows the database + pool to cancel waiting for the next available connection.

The IsolationLevel @@ -541,8 +569,9 @@ in mind. which can include SQL type information, column type lengths, and the Go type.

- Multiple result sets are now supported on Rows. After - Rows.Next returns false + A Rows + can now represent multiple result sets. After + Rows.Next returns false, Rows.NextResultSet may be called to advance to the next result set. The existing Rows should be continued to be used after it advances to the next result set. @@ -553,11 +582,14 @@ in mind. helps create a NamedParam more succinctly.

- Drivers that support the new Pinger - interface can now check if the server is still alive when the the + If a driver supports the new + Pinger + interface, the DB's DB.Ping - or DB.PingContext - is called. + and + DB.PingContext + methods will use that interface to check whether a + database connection is still valid.

The new Context query methods work for all drivers, but @@ -619,8 +651,8 @@ pkg debug/pe, type StringTable []uint8

- A nil Marshaler - now marshals as a JSON "null" value. + A nil Marshaler + now marshals as a JSON null value.

@@ -629,17 +661,20 @@ pkg debug/pe, type StringTable []uint8

- Marshal encodes floating-point numbers using the same format as in ES6, + Marshal + encodes floating-point numbers using the same format as in ES6, preferring decimal (not exponential) notation for a wider range of values. In particular, all floating-point integers up to 264 format the same as the equivalent int64 representation.

- Implementations + + In previous versions of Go, unmarshaling a JSON null into an of Unmarshaler - are now called with the literal "null" and can - decide how to handle it. + was considered a no-op; now the Unmarshaler's + UnmarshalJSON method is called with the JSON literal + null and can define the semantics of that case.

@@ -695,12 +730,13 @@ pkg debug/pe, type StringTable []uint8

The new Rand.Uint64 - method returns uint64 values. The - new Rand.Source64 + method returns uint64 values. The + new Source64 interface describes sources capable of generating such values directly; otherwise the Rand.Uint64 method constructs a uint64 from two calls - to Rand.Source's Int63 method. + to Source's + Int63 method.

@@ -713,13 +749,15 @@ pkg debug/pe, type StringTable []uint8 The Reader's parsing has been relaxed in two ways to accept - more input seen in the wild. First, it now accepts - a = sign even if it's not followed by two hex - digits. + more input seen in the wild. + + + First, it accepts an equals sign (=) not followed + by two hex digits as a literal equal sign. - Second, it accepts a trailing soft line-break at the end of a - message. That is, the final byte of the - message may be a = sign and it will now be ignored. + + Second, it silently ignores a trailing equals sign at the end of + an encoded input.

@@ -926,8 +964,8 @@ pkg debug/pe, type StringTable []uint8 URL.Hostname and URL.Port - are accessors to the hostname and port fields of a URL - and deal with the case where the port may or may not be present. + return the hostname and port fields of a URL, + correctly handling the case where the port may not be present.

The existing method @@ -961,7 +999,7 @@ pkg debug/pe, type StringTable []uint8

The new function Executable returns - the running executable path name. + the path name of the running executable.

-- 2.52.0