From ac1dbe6392f2d392f9554127f96597a9aaa721fd Mon Sep 17 00:00:00 2001 From: Brad Fitzpatrick Date: Tue, 22 Nov 2016 08:24:13 -0700 Subject: [PATCH] doc: more go1.8.html content TBR=See https://golang.org/cl/33244 and review there. Updates #17929 Change-Id: I37b49318a9203b16c0c788926039288b99a36ce5 Reviewed-on: https://go-review.googlesource.com/33450 Reviewed-by: Brad Fitzpatrick --- doc/go1.8.html | 353 +++++++++++++++++++++++++++++++++++++++++++++---- doc/go1.8.txt | 218 +++++++++++++++++------------- 2 files changed, 453 insertions(+), 118 deletions(-) diff --git a/doc/go1.8.html b/doc/go1.8.html index 79f2605209..a88af0c077 100644 --- a/doc/go1.8.html +++ b/doc/go1.8.html @@ -43,8 +43,15 @@ and simplifies sorting slices.

Changes to the language

-When explicitly converting structs, tags are now ignored for structural type identity. -See change 24190 for details. + When explicitly converting structs, tags are now ignored for structural type identity. + See change 24190 for details. +

+ +

+ The language specification now only requires that implementations + support up to 16-bit exponents in constants. This does not affect + either the gc or gccgo compilers, both of + which still support 32-bit exponents.

Ports

@@ -56,7 +63,7 @@ Go now supports 32-bit MIPS on Linux for both big-endian

-Go now requires DragonFly BSD 4.4.4 or later. +Go now requires DragonFly BSD 4.4.4 or later.

@@ -65,16 +72,23 @@ and matches the behavior of Unix and Windows with respect to deadlines 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 + binaries on older OS X versions is untested. +

+

Known Issues

-There are some instabilities on FreeBSD that are known but not understood. +There are some instabilities on FreeBSD and NetBSD that are known but not understood. These can lead to program crashes in rare cases. See -issue 15658 -and issue 16396. -Any help in solving these FreeBSD-specific issues would be appreciated. +issue 15658, +issue 16396, and +issue 16511. +Any help in solving these issues would be appreciated.

Tools

@@ -99,7 +113,7 @@ added. See change 30510.

Yacc

-

+

The yacc (previously available via “go tool yacc”) has been removed. As of Go 1.7 it was no longer used by the Go compiler. @@ -132,15 +146,22 @@ the new backend has been removed in Go 1.8.

-The compiler and linker have been optimized and run faster in this -release than in Go 1.7, although they are still slower than we would -like and will continue to be optimized in future releases. + 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 + future performance work. +

+ +

+ The compiler and linker have been optimized and run faster in this + release than in Go 1.7, although they are still slower than we would + like and will continue to be optimized in future releases.

-Due to changes across the compiler toolchain and standard library, -binaries built with this release should typically be smaller than binaries -built with Go 1.7, sometimes by as much as TODO numbers. + Due to changes across the compiler toolchain and standard library, + binaries built with this release should typically be smaller than + binaries built with Go 1.7, sometimes by as much as TODO numbers.

@@ -165,19 +186,53 @@ A new “go bug” command helps users file bug report

Go doc

-

+

The “go doc” command now groups constants and variables with their type, following the behavior of godoc.

-

+

In order to improve the readability of the 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. +

+ +

Plug-ins

+ +

+ Go now supports a “plugin” build mode for generating + plug-ins written in Go, and a + new plugin package for + loading such plug-ins at run time. Plug-ins support is only currently + available on Linux and Darwin. +

+ +

Runtime

+ +

Argument Liveness

+ +

+ The garbage collector no longer considers + arguments live throughout the entirety of a function. For more + information, and for how to force a variable to remain live, see + the runtime.KeepAlive + function added in Go 1.7. +

+ +

MemStats Documentation

+ +

+ The runtime's MemStats + type has been more throroughly documented. +

+

Performance

@@ -185,7 +240,7 @@ As always, the changes are so general and varied that precise statements about performance are difficult to make. Most programs should run a bit faster, due to speedups in the garbage collector and -optimizations in the core library. +optimizations in the standard library.

@@ -219,20 +274,20 @@ More work remains for Go 1.9.

Calls from Go into C are now TODO% faster.

-

Core library

+

Standard library

Examples

-Many examples have been added to the documentation across many packages. +Examples have been added to the documentation across many packages.

-

Sort

+

Sort

The sort package now includes a convenience function -sort.Slice to sort a +Slice to sort a slice given a less function. In many cases this means that writing a new sorter type is not @@ -241,8 +296,8 @@ necessary.

Also new are -sort.SliceStable and -sort.SliceIsSorted. +SliceStable and +SliceIsSorted.

HTTP/2 Push

@@ -327,4 +382,256 @@ in mind. +
archive/tar
+
+

+ The DeadlineExceeded error now implements + net.Error + and reports true for both the Timeout and + Temporary methods. +

+
+
+ +
encoding/binary
+
+

+ The package now supports boolean values. + TODO: add docs in encoding/binary package, then link to package docs + here. +

+
+
+ +
expvar
+
+

+ The new methods + Int.Value, + String.Value, + Float.Value, and + Func.Value + report the current value of an exported variable. +

+ +

+ The new + function Handler + returns the package's HTTP handler, to enable installing it in + non-standard locations. +

+
+
+ +
image/png
+
+

+ The PNG decoder now supports truecolor and grayscale transparency. +

+

+ The PNG encoder is now faster and creates smaller output + when encoding paletted images. +

+
+
+ +
math/rand
+
+ +

+ There is a new + method Rand.Uint64 + to return uint64 values. +

+ +
+
+ +
mime/quotedprintable
+
+ +

+ The package'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. + + 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. +

+ +
+
+ + +
net/http
+
+ +

+ TODO +

+ +
+
+ +
net/mail
+
+ +

+ Empty quoted strings are now allowed in the name part of an + address. That is, this is now a legal address: + "" <gopher@example.com> +

+ +

+ The ParseDate + function has been exported. +

+ +
+
+ +
net/smtp
+
+ +

+ If implementations of the Auth + interface return an empty toServer value, the package + no longer sends trailing whitespace after the SMTP AUTH + command, which some servers rejected. +

+ +
+
+ +
net/url
+
+ +

The new functions + PathEscape + and + PathUnescape + deal with path escaping.

+ +

The new methods + 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. +

+ +

The existing method + URL.ResolveReference + now properly handles paths with escaped bytes without losing + the escaping. +

+ +

+ The URL type now implements + encoding.BinaryMarshaler and + encoding.BinaryUnmarshaler. +

+ +

+ Parse now rejects relative URLs containing a ":" in + the first path segment. Such paths should be prefixed with "./". + The URL.String method now prepends "./" to such paths. +

+ +
+
+ +
reflect
+
+

+ The new function + Swapper was + added to support + the new sort.Slice + support. +

+
+
+ + +
strconv
+
+

+ The Unquote + function now strips carriage returns (\r) in + backquoted raw strings. +

+
+
+ +
time
+
+ +

The new function + Until complements + the analogous Since function. +

+ +

ParseDuration now accepts long fractional parts.

+ +

+ Parse now validates days that are too small, in + addition to days that are too large. +

+ +

+

+
+ +
testing
+
+

+ The new method + T.Name + (and B.Name) returns the name of the current + test or benchmark. +

+ +

+ The new method + T.Context + (and B.Context) returns + a Context for + the current running test or benchmark. +

+

+ The new function + CoverMode + reports what the test coverage mode is set to. +

+ +

+ Tests and benchmarks are now marked as failed if the race + detector is enabled and a data race occurs during execution. +

+ +
+
+ +
unicode
+
+

+ SimpleFold now returns its argument unchanged + if the provided input was an invalid rune. +

+
+
+ + + + +
foo
+
+

+ +

+
+
diff --git a/doc/go1.8.txt b/doc/go1.8.txt index 95a1db7eaf..65fe180d27 100644 --- a/doc/go1.8.txt +++ b/doc/go1.8.txt @@ -1,47 +1,34 @@ -Overall: +Note: once things are added to go1.8.html or deemed too minor they're +moved from the sections at top down to the "HTMLified" or "Probably +omit" sections below. -plugin build mode & package (many CLs) -Many ppc64, s390x, arm, arm64 optimizations -New frontend -Improvements to binary size, runtime speed, compile speed. -Hybrid barrier. <100us GC pauses. -cmd/compile: args no longer live until end of function - use runtime.KeepAlive instead (CL 28310) - -Language: - -When explicitly converting structs, tags are ignored for structural type identity (CL 24190). +These top sections remain to be HTMLified or deemed too boring: Tools: -compile: SSA for 386, nacl, arm, arm64, ppc64, ppc64le, s390x ... (many CLs) -yacc: "go tool yacc" is removed. now at golang.org/x/tools/cmd/goyacc (CL 27324, CL 27325) go: -buildmode=c-archive now builds PIC on ELF (CL 24180) go: mobile pkg dir change, recommend using go list in scripts (CL 24930, CL 27929) go, dist: can set default pkg-config tool using PKG_CONFIG env var (CL 29991) go: can set secure/insecure GIT schemes using GIT_ALLOW_PROTOCOL env var (CL 30135) -Ports: - -dragonfly: go1.8 requires DragonFly BSD 4.4.4 or above (CL 29491) -plan9: various fixes (Close unblocks Read, I/O deadline maybe?) -mips, mipsle - API additions and behavior changes: -all: freeze net/rpc and reword the 'frozen' message in other frozen packages (CL 32112) archive/tar: fix and cleanup readOldGNUSparseMap (CL 28471) archive/tar: fix parsePAX to be POSIX.1-2001 compliant (CL 31440) archive/tar: fix parsePAXTime (CL 31441) archive/tar: make Reader handle GNU format properly (CL 31444) archive/tar: reapply Header.Size to regFileReader after merging (CL 28418) archive/tar: validate sparse headers in parsePAX (CL 31439) + archive/zip: handle mtime in NTFS/UNIX/ExtendedTS extra fields (CL 18274) archive/zip: only use Extended Timestamp on non-zero MS-DOS timestamps (CL 30811) + cmd/cgo: add #line directives to avoid printing bogus references to Go source files (CL 32613) cmd/cgo: add -srcdir option (CL 32354) cmd/cgo: don't ignore qualifiers, don't cast to void* (CL 33097) cmd/cgo: fix line info in _cgo_gotypes.go (CL 29713) cmd/cgo: throw if C.malloc returns nil (CL 31768) + cmd/compile, runtime, etc: get rid of constant FP registers (CL 28095) cmd/compile, runtime: add go:yeswritebarrierrec pragma (CL 30938) cmd/compile/internal/gc: add runtime/trace support (CL 25354) @@ -54,22 +41,20 @@ cmd/compile: add inline explainer (CL 22782) cmd/compile: do more type conversion inline (CL 32313) cmd/compile: enable flag-specified dump of specific phase+function (CL 23044) cmd/compile: fail gracefully on export format skew (CL 27814) -cmd/compile: import/export of alias declarations (CL 32090) cmd/compile: inline convI2E (CL 31260) -cmd/compile: make ssa compilation unconditional (CL 29155) cmd/compile: remove -A flag (CL 31497) -cmd/compile: remove old lexer and parser (CL 32020) cmd/compile: remove support for textual export format (CL 27171) + cmd/cover: Fix compiler directives handling (CL 30161) cmd/cover: change covered block for switch/select case to exclude expression (CL 32612) cmd/cover: handle gotos (CL 30977) + cmd/dist, go/build: make CGO_ENABLED during make.bash sticky (CL 31141) cmd/dist: enable plugin test on darwin/amd64 (CL 29396) cmd/dist: test PIE internal linking on linux/amd64 (CL 28545) -cmd/doc: ensure summaries truly are only one line (CL 25420) -cmd/doc: perform type grouping for constants and variables (CL 25419) -cmd/doc: show documentation for interface methods when requested explicitly (CL 31852) + cmd/fix: add golang.org/x/net/context fix (CL 28872) + cmd/go, testing: indicate when no tests are run (CL 22341) cmd/go: add bug command (CL 28485) cmd/go: add distribution-specific info for Linux to bug command (CL 28581) @@ -82,7 +67,7 @@ cmd/go: make go test -i -o x.test actually write x.test (CL 31352) cmd/go: print more env variables in "go env" (CL 31330) cmd/go: referee another vendor vs symlink fight (CL 31665) cmd/go: use cgo -srcdir when using SWIG (CL 32485) -cmd/gofmt: don't eat source if -w fails (CL 33018) + cmd/internal/obj, cmd/link: darwin dynlink support (CL 29393) cmd/internal/objfile: add ppc64/ppc64le disassembler support (CL 9682) cmd/link, cmd/go: delay linking of mingwex and mingw32 until very end (CL 26670) @@ -100,12 +85,15 @@ cmd/link: remove the -shared flag (CL 28852) cmd/link: split large elf text sections on ppc64x (CL 27790) cmd/link: trampoline support for external linking on ARM (CL 31143) cmd/objdump: implement objdump of .o files (CL 24818) + cmd/pprof: add options to skip tls verification (CL 33157) cmd/pprof: don't print binary outputs in interactive mode (CL 31123) cmd/pprof: instruction-level granularity in callgrind output (CL 23781) + cmd/trace: add option to output pprof files (CL 23324) cmd/trace: fix a runnable goroutine count bug (CL 25552) cmd/trace: move process-wide GC events to their own row (CL 30017) + cmd/vet: accept space-separated tag lists for compatibility with cmd/go (CL 32030) cmd/vet: allow ^& uintptr arithmetic (CL 27156) cmd/vet: allow any printf verb with any interface (CL 27127) @@ -116,17 +104,18 @@ cmd/vet: diagnose non-space-separated struct tag like `json:"x",xml:"y"` (CL 320 cmd/vet: improve asmdecl parameter handling (CL 27150) cmd/vet: properly handle indexed arguments in printf (CL 24391) cmd/vet: skip printf check for non-constant format string during failed import (CL 29014) + compress/flate: always return uncompressed data in the event of error (CL 28216) compress/flate: level 1 (best speed) match across blocks (CL 31640) compress/flate: make compression level 0 consistent (CL 31174) compress/flate: tighten the BestSpeed max match offset bound. (CL 32149) compress/gzip, compress/zlib: add HuffmanOnly as compression levels. (CL 31186) compress/gzip: only encode MTIME if it is valid (CL 32325) -context: make DeadlineExceeded implement net.Error (CL 30370) + crypto/cipher: enforce message size limits for GCM (CL 28410) crypto/rsa: ensure that generating toy RSA keys doesn't loop (CL 28969) -crypto/tls: add CloseWrite method to Conn (CL 25159) -crypto/tls: add CloseWrite method to Conn (CL 31318) + +crypto/tls: add CloseWrite method to Conn (CL 25159, 31318) crypto/tls: add Config.Clone (CL 28075) crypto/tls: add Config.GetConfigForClient (CL 30790) crypto/tls: add GetClientCertificate callback (CL 32115) @@ -143,6 +132,7 @@ crypto/tls: set Conn.ConnectionState.ServerName unconditionally (CL 22862) crypto/tls: support AES-128-CBC cipher suites with SHA-256 (CL 27315) crypto/tls: support ChaCha20-Poly1305. (CL 30957) crypto/tls: support X25519 (CL 30824, CL 30825) + crypto/x509: Fix bug in UnknownAuthorityError.Error (CL 27992) crypto/x509: allow a leaf certificate to be specified directly as root (CL 27393) crypto/x509: check that the issuer name matches the issuer's subject name (CL 23571) @@ -157,7 +147,9 @@ crypto/x509: require a NULL parameters for RSA public keys (CL 27312) crypto/x509: return error for missing SerialNumber (CL 27238) crypto/x509: support PSS signatures (CL 24743) crypto/x509: support RHEL 7 cert bundle (CL 30375) + crypto/{cipher,tls,internal/cryptohw}: prioritise AES-GCM when hardware support is present. (CL 32871) + database/sql: accept nil pointers to Valuers implemented on value receivers (CL 31259) database/sql: add Pinger interface to driver Conn (CL 32136) database/sql: add context helper methods and transaction types (CL 31258) @@ -166,25 +158,27 @@ database/sql: add option to use named parameter in query arguments (CL 30166) database/sql: add support for multiple result sets (CL 30592) database/sql: don't hang if the driver Exec method panics (CL 23576) database/sql: support returning query database types (CL 29961) + debug/elf: add sparc64 relocations (CL 30870) debug/pe: revert CL 22720 (CL 27212) -doc: document minimum OS X version as 10.8 (CL 28870) encoding/asn1: return error for unexported fields in Marshal, Unmarshal (CL 31540) + encoding/base64: add Encoding.Strict (CL 24964) -encoding/binary: add bool support (CL 28514) + encoding/json: add struct and field name to UnmarshalTypeError message (CL 18692) encoding/json: encode nil Marshaler as "null" (CL 31932) encoding/json: fix decoding of null into Unmarshaler, TextUnmarshaler (CL 30944) encoding/json: marshal the RawMessage value type the same as its pointer type (CL 21811) encoding/json: use standard ES6 formatting for numbers during marshal (CL 30371) + encoding/pem: be stricter about the ending line (CL 27391) + encoding/xml: add wildcard support for collecting all attributes (CL 30946) encoding/xml: prevent omitempty from omitting non-nil pointers to empty values (CL 15684) -expvar: add Value methods (CL 30917) -expvar: export http.Handler (CL 24722) + flag: arrange for FlagSet.Usage to be non-nil by default (CL 31576) fmt: document and adjust Scanf space handling to eliminate a few paradoxes (CL 30611) -go/ast, go/parser: parse alias declarations (CL 30211) + go/build: allow % in ${SRCDIR} expansion for Jenkins (CL 31611) go/build: do not record go:binary-only-package if build tags not satisfied (CL 31577) go/build: implement default GOPATH (CL 32019) @@ -194,29 +188,21 @@ go/internal/gcimporter: fail gracefully on export format skew (CL 27816) go/printer: don't drop required semi/linebreak after /*-comment (CL 33016) go/token: fix race in FileSet.PositionFor. (CL 25345) go/types: expose Default function, which converts untyped T to T (CL 30715) -go/types: handle imported aliases (CL 32534) go/types: match cmd/compile's alignment for complex64 (CL 31939) -go/types: minimal support for alias declarations: don't crash (CL 30213) + html/template: check "type" attribute in