- - Go 1.21 is not yet released. These are work-in-progress - release notes. Go 1.21 is expected to be released in August 2023. - -
- -- The latest Go release, version 1.21, arrives six months after Go 1.20. - Most of its changes are in the implementation of the toolchain, runtime, and libraries. - As always, the release maintains the Go 1 promise of compatibility; - in fact, Go 1.21 improves upon that promise. - We expect almost all Go programs to continue to compile and run as before. -
- -
- Go 1.21 introduces a small change to the numbering of releases.
- In the past, we used Go 1.N to refer to both the overall Go language version and release family
- as well as the first release in that family.
- Starting in Go 1.21, the first release is now Go 1.N.0.
- Today we are releasing both the Go 1.21 language and its initial implementation, the Go 1.21.0 release.
- These notes refer to “Go 1.21”; tools like go version will report “go1.21.0”
- (until you upgrade to Go 1.21.1).
- See “Go versions” in the “Go Toolchains” documentation for details
- about the new version numbering.
-
- Go 1.21 adds three new built-ins to the language. - -
min and max compute the
- smallest (or largest, for max) value of a fixed number
- of given arguments.
- See the language spec for
- details.
- clear deletes all elements from a
- map or zeroes all elements of a slice.
- See the language spec for
- details.
- - Package initialization order is now specified more precisely. The - new algorithm is: -
- Multiple improvements that increase the power and precision of type inference have been made. -
-- More generally, the description of - type inference - in the language spec has been clarified. - Together, all these changes make type inference more powerful and inference failures less surprising. -
- - -- Go 1.21 includes a preview of a language change we are considering for a future version of Go: - making for loop variables per-iteration instead of per-loop, to avoid accidental sharing bugs. - For details about how to try that language change, see the LoopvarExperiment wiki page. -
- -- Go 1.21 adds improved support for backwards compatibility and forwards compatibility - in the Go toolchain. -
- -
- To improve backwards compatibility, Go 1.21 formalizes
- Go's use of the GODEBUG environment variable to control
- the default behavior for changes that are non-breaking according to the
- compatibility policy
- but nonetheless may cause existing programs to break.
- (For example, programs that depend on buggy behavior may break
- when a bug is fixed, but bug fixes are not considered breaking changes.)
- When Go must make this kind of behavior change,
- it now chooses between the old and new behavior based on the
- go line in the workspace's go.work file
- or else the main module's go.mod file.
- Upgrading to a new Go toolchain but leaving the go line
- set to its original (older) Go version preserves the behavior of the older
- toolchain.
- With this compatibility support, the latest Go toolchain should always
- be the best, most secure, implementation of an older version of Go.
- See “Go, Backwards Compatibility, and GODEBUG” for details.
-
- To improve forwards compatibility, Go 1.21 now reads the go line
- in a go.work or go.mod file as a strict
- minimum requirement: go 1.21.0 means
- that the workspace or module cannot be used with Go 1.20 or with Go 1.21rc1.
- This allows projects that depend on fixes made in later versions of Go
- to ensure that they are not used with earlier versions.
- It also gives better error reporting for projects that make use of new Go features:
- when the problem is that a newer Go version is needed,
- that problem is reported clearly, instead of attempting to build the code
- and instead printing errors about unresolved imports or syntax errors.
-
- To make these new stricter version requirements easier to manage,
- the go command can now invoke not just the toolchain
- bundled in its own release but also other Go toolchain versions found in the PATH
- or downloaded on demand.
- If a go.mod or go.work go line
- declares a minimum requirement on a newer version of Go, the go
- command will find and run that version automatically.
- The new toolchain directive sets a suggested minimum toolchain to use,
- which may be newer than the strict go minimum.
- See “Go Toolchains” for details.
-
- The -pgo build flag now defaults to -pgo=auto,
- and the restriction of specifying a single main package on the command
- line is now removed. If a file named default.pgo is present
- in the main package's directory, the go command will use
- it to enable profile-guided optimization for building the corresponding
- program.
-
- The -C dir flag must now be the first
- flag on the command-line when used.
-
- The new go test option
- -fullpath prints full path names in test log messages,
- rather than just base names.
-
- The go test -c flag now
- supports writing test binaries for multiple packages, each to
- pkg.test where pkg is the package name.
- It is an error if more than one test package being compiled has a given package name.]
-
- The go test -o flag now
- accepts a directory argument, in which case test binaries are written to that
- directory instead of the current directory.
-
- In files that import "C", the Go toolchain now
- correctly reports errors for attempts to declare Go methods on C types.
-
- When printing very deep stacks, the runtime now prints the first 50 - (innermost) frames followed by the bottom 50 (outermost) frames, - rather than just printing the first 100 frames. This makes it easier - to see how deeply recursive stacks started, and is especially - valuable for debugging stack overflows. -
- -- On Linux platforms that support transparent huge pages, the Go runtime - now manages which parts of the heap may be backed by huge pages more - explicitly. This leads to better utilization of memory: small heaps - should see less memory used (up to 50% in pathological cases) while - large heaps should see fewer broken huge pages for dense parts of the - heap, improving CPU usage and latency by up to 1%. -
- -
- As a result of runtime-internal garbage collection tuning,
- applications may see up to a 40% reduction in application tail latency
- and a small decrease in memory use. Some applications may also observe
- a small loss in throughput.
-
- The memory use decrease should be proportional to the loss in
- throughput, such that the previous release's throughput/memory
- tradeoff may be recovered (with little change to latency) by
- increasing GOGC and/or GOMEMLIMIT slightly.
-
- Calls from C to Go on threads created in C require some setup to prepare for - Go execution. On Unix platforms, this setup is now preserved across multiple - calls from the same thread. This significantly reduces the overhead of - subsequent C to Go calls from ~1-3 microseconds per call to ~100-200 - nanoseconds per call. -
- -
- Profile-guide optimization (PGO), added as a preview in Go 1.20, is now ready
- for general use. PGO enables additional optimizations on code identified as
- hot by profiles of production workloads. As mentioned in the
- Go command section, PGO is enabled by default for
- binaries that contain a default.pgo profile in the main
- package directory. Performance improvements vary depending on application
- behavior, with most programs from a representative set of Go programs seeing
- between 2 and 7% improvement from enabling PGO. See the
- PGO user guide for detailed documentation.
-
- PGO builds can now devirtualize some interface method calls, adding a - concrete call to the most common callee. This enables further optimization, - such as inlining the callee. -
- - -- Go 1.21 improves build speed by up to 6%, largely thanks to building the - compiler itself with PGO. -
- -
- On amd64, frameless nosplit assembly functions are no longer automatically marked as NOFRAME.
- Instead, the NOFRAME attribute must be explicitly specified if desired,
- which is already the behavior on other architectures supporting frame pointers.
- With this, the runtime now maintains the frame pointers for stack transitions.
-
- The verifier that checks for incorrect uses of R15 when dynamic linking on amd64 has been improved.
-
- On windows/amd64, the linker (with help from the compiler) now emits - SEH unwinding data by default, which improves the integration - of Go applications with Windows debuggers and other tools. -
- - -- In Go 1.21 the linker (with help from the compiler) is now capable of - deleting dead (unreferenced) global map variables, if the number of - entries in the variable initializer is sufficiently large, and if the - initializer expressions are side-effect free. -
- -- The new log/slog package provides structured logging with levels. - Structured logging emits key-value pairs - to enable fast, accurate processing of large amounts of log data. - The package supports integration with popular log analysis tools and services. -
- -- The new testing/slogtest package can help - to validate slog.Handler implementations. -
- -- - - - - - The new slices package provides many common - operations on slices, using generic functions that work with slices - of any element type. -
- -- The new maps package provides several - common operations on maps, using generic functions that work with - maps of any key or element type. -
- -
- The new cmp package defines the type
- constraint Ordered and
- two new generic functions
- Less
- and Compare that are
- useful with ordered
- types.
-
- As always, there are various minor changes and updates to the library, - made with the Go 1 promise of compatibility - in mind. - There are also various performance improvements, not enumerated here. -
- -
- The implementation of the
- io/fs.FileInfo
- interface returned by
- Header.FileInfo
- now implements a String method that calls
- io/fs.FormatFileInfo.
-
- The implementation of the
- io/fs.FileInfo
- interface returned by
- FileHeader.FileInfo
- now implements a String method that calls
- io/fs.FormatFileInfo.
-
- The implementation of the
- io/fs.DirEntry
- interface returned by the
- io/fs.ReadDirFile.ReadDir
- method of the
- io/fs.File
- returned by
- Reader.Open
- now implements a String method that calls
- io/fs.FormatDirEntry.
-
- The Buffer type
- has two new methods:
- Available
- and AvailableBuffer.
- These may be used along with the
- Write
- method to append directly to the Buffer.
-
- The new WithoutCancel
- function returns a copy of a context that is not canceled when the original
- context is canceled.
-
- The new WithDeadlineCause
- and WithTimeoutCause
- functions provide a way to set a context cancellation cause when a deadline or
- timer expires. The cause may be retrieved with the
- Cause function.
-
- The new AfterFunc
- function registers a function to run after a context has been cancelled.
-
- An optimization means that the results of calling
- Background
- and TODO and
- converting them to a shared type can be considered equal.
- In previous releases they were always different. Comparing
- Context values
- for equality has never been well-defined, so this is not
- considered to be an incompatible change.
-
- All of the Curve methods have been deprecated, along with GenerateKey, Marshal, and Unmarshal. For ECDH operations, the new crypto/ecdh package should be used instead. For lower-level operations, use third-party modules such as filippo.io/nistec.
-
- The crypto/rand package now uses the getrandom system call on NetBSD 10.0 and later.
-
- The performance of private RSA operations (decryption and signing) is now better than Go 1.19 for GOARCH=amd64 and GOARCH=arm64. It had regressed in Go 1.20.
-
- Due to the addition of private fields to PrecomputedValues, PrivateKey.Precompute must be called for optimal performance even if deserializing (for example from JSON) a previously-precomputed private key.
-
- The GenerateMultiPrimeKey function and the PrecomputedValues.CRTValues field have been deprecated. PrecomputedValues.CRTValues will still be populated when PrivateKey.Precompute is called, but the values will not be used during decryption operations.
-
- SHA-224 and SHA-256 operations now use native instructions when available when GOARCH=amd64, providing a performance improvement on the order of 3-4x.
-
- Applications can now control the content of session tickets. -
SessionState type
- describes a resumable session.
- SessionState.Bytes
- method and ParseSessionState
- function serialize and deserialize a SessionState.
- Config.WrapSession and
- Config.UnwrapSession
- hooks convert a SessionState to and from a ticket.
- Config.EncryptTicket
- and Config.DecryptTicket
- methods provide a default implementation of WrapSession and
- UnwrapSession.
- ClientSessionState.ResumptionState method and
- NewResumptionState function
- may be used by a ClientSessionCache implementation to store and
- resume sessions.
-
- The package now supports the extended master secret extension (RFC 7627),
- and enables it by default. Additionally, the deprecation of
- ConnectionState.TLSUnique
- has been reverted, and it is populated when a connection which uses
- extended master secret is resumed. Session tickets produced by
- Go pre-1.21 are not interoperable with Go 1.21, meaning connections
- resumed across versions will fall back to full handshakes.
-
- The new QUICConn type
- provides support for QUIC implementations. Note that this is not itself
- a QUIC implementation.
-
- The new VersionName function - returns the name for a TLS version number. -
-
- RevocationList.RevokedCertificates has been deprecated and replaced with the new RevokedCertificateEntries field, which is a slice of RevocationListEntry. RevocationListEntry contains all of the fields in pkix.RevokedCertificate, as well as the revocation reason code.
-
- The new
- File.DynValue
- method may be used to retrieve the numeric values listed with a
- given dynamic tag.
-
- The constant flags permitted in a DT_FLAGS_1
- dynamic tag are now defined with type
- DynFlag1. These
- tags have names starting with DF_1.
-
- The package now defines the constant
- COMPRESS_ZSTD.
-
- The package now defines the constant
- R_PPC64_REL24_P9NOTOC.
-
- Attempts to read from a section containing uninitialized data
- using
- Section.Data
- or the reader returned by Section.Open
- now return an error.
-
- The io/fs.File
- returned by
- FS.Open now
- has a ReadAt method that
- implements io.ReaderAt.
-
- Calling FS.Open.Stat
- will return a type that now implements a String
- method that calls
- io/fs.FormatFileInfo.
-
- The new
- ErrUnsupported
- error provides a standardized way to indicate that a requested
- operation may not be performed because it is unsupported.
- For example, a call to
- os.Link when using a
- file system that does not support hard links.
-
- The new BoolFunc
- function and
- FlagSet.BoolFunc
- method define a flag that does not require an argument and calls
- a function when the flag is used. This is similar to
- Func but for a
- boolean flag.
-
- A flag definition
- (via Bool,
- BoolVar,
- Int,
- IntVar, etc.)
- will panic if Set has
- already been called on a flag with the same name. This change is
- intended to detect cases where changes in
- initialization order cause flag operations to occur in a
- different order than expected. In many cases the fix to this
- problem is to introduce a explicit package dependence to
- correctly order the definition before any
- Set operations.
-
- The new IsGenerated predicate
- reports whether a file syntax tree contains the
- special comment
- that conventionally indicates that the file was generated by a tool.
-
- The new
- File.GoVersion
- field records the minimum Go version required by
- any //go:build or // +build
- directives.
-
- The package now parses build directives (comments that start
- with //go:) in file headers (before
- the package declaration). These directives are
- available in the new
- Package fields
- Directives,
- TestDirectives,
- and
- XTestDirectives.
-
- The new
- GoVersion
- function returns the minimum Go version implied by a build
- expression.
-
- The new File.Lines method
- returns the file's line-number table in the same form as accepted by
- File.SetLines.
-
- TODO: https://go.dev/cl/507975: go/types: record Config.GoVersion for reporting in Package.GoVersion method; modified api/go1.21.txt -
-
- The hash/maphash package now has a pure Go implementation, selectable with the purego build tag.
-
- The new error
- ErrJSTemplate
- is returned when an action appears in a JavaScript template
- literal. Previously an unexported error was returned.
-
- The new
- FormatFileInfo
- function returns a formatted version of a
- FileInfo.
- The new
- FormatDirEntry
- function returns a formatted version of a
- DirEntry.
- The implementation of
- DirEntry
- returned by
- ReadDir now
- implements a String method that calls
- FormatDirEntry,
- and the same is true for
- the DirEntry
- value passed to
- WalkDirFunc.
-
- The new Int.Float64
- method returns the nearest floating-point value to a
- multi-precision integer, along with an indication of any
- rounding that occurred.
-
-
-
- On Linux, the net package can now use
- Multipath TCP when the kernel supports it. It is not used by
- default. To use Multipath TCP when available on a client, call
- the
- Dialer.SetMultipathTCP
- method before calling the
- Dialer.Dial or
- Dialer.DialContext
- methods. To use Multipath TCP when available on a server, call
- the
- ListenConfig.SetMultipathTCP
- method before calling the
- ListenConfig.Listen
- method. Specify the network as "tcp" or
- "tcp4" or "tcp6" as usual. If
- Multipath TCP is not supported by the kernel or the remote host,
- the connection will silently fall back to TCP. To test whether a
- particular connection is using Multipath TCP, use the
- TCPConn.MultipathTCP
- method.
-
- In a future Go release we may enable Multipath TCP by default on - systems that support it. -
-
- The new ResponseController.EnableFullDuplex
- method allows server handlers to concurrently read from an HTTP/1
- request body while writing the response. Normally, the HTTP/1 server
- automatically consumes any remaining request body before starting to
- write the response, to avoid deadlocking clients which attempt to
- write a complete request before reading the response. The
- EnableFullDuplex method disables this behavior.
-
- The new ErrSchemeMismatch error is returned by Client and Transport when the server responds to an HTTPS request with an HTTP response.
-
- The net/http package now supports
- errors.ErrUnsupported,
- in that the expression
- errors.Is(http.ErrNotSupported, errors.ErrUnsupported)
- will return true.
-
- Programs may now pass an empty time.Time value to
- the Chtimes function
- to leave either the access time or the modification time unchanged.
-
- On Windows the
- File.Chdir method
- now changes the current directory to the file, rather than
- always returning an error.
-
- On Unix systems, if a non-blocking descriptor is passed
- to NewFile, calling
- the File.Fd method
- will now return a non-blocking descriptor. Previously the
- descriptor was converted to blocking mode.
-
- On Windows calling
- Truncate on a
- non-existent file used to create an empty file. It now returns
- an error indicating that the file does not exist.
-
- On Windows calling
- TempDir now uses
- GetTempPath2W when available, instead of GetTempPathW. The
- new behavior is a security hardening measure that prevents
- temporary files created by processes running as SYSTEM to
- be accessed by non-SYSTEM processes.
-
- On Windows the os package now supports working with files whose - names, stored as UTF-16, can't be represented as valid UTF-8. -
- -
- On Windows Lstat now resolves
- symbolic links for paths ending with a path separator, consistent with its
- behavior on POSIX platforms.
-
- The implementation of the
- io/fs.DirEntry
- interface returned by the
- ReadDir function and
- the File.ReadDir
- method now implements a String method that calls
- io/fs.FormatDirEntry.
-
- The implementation of the
- io/fs.FS interface returned by
- the DirFS function now implements
- the io/fs.ReadFileFS and
- the io/fs.ReadDirFS
- interfaces.
-
- The implementation of the
- io/fs.DirEntry
- interface passed to the function argument of
- WalkDir
- now implements a String method that calls
- io/fs.FormatDirEntry.
-
- In Go 1.21, ValueOf
- no longer forces its argument to be allocated on the heap, allowing
- a Value's content to be allocated on the stack. Most
- operations on a Value also allow the underlying value
- to be stack allocated.
-
- The new Value
- method Value.Clear
- clears the contents of a map or zeros the contents of a slice.
- This corresponds to the new clear built-in
- added to the language.
-
- The SliceHeader
- and StringHeader
- types are now deprecated. In new code
- prefer unsafe.Slice,
- unsafe.SliceData,
- unsafe.String,
- or unsafe.StringData.
-
- Regexp now defines
- MarshalText
- and UnmarshalText
- methods. These implement
- encoding.TextMarshaler
- and
- encoding.TextUnmarshaler
- and will be used by packages such as
- encoding/json.
-
- Textual stack traces produced by Go programs, such as those
- produced when crashing, calling runtime.Stack, or
- collecting a goroutine profile with debug=2, now
- include the IDs of the goroutines that created each goroutine in
- the stack trace.
-
- Crashing Go applications can now opt-in to Windows Error Reporting (WER) by setting the environment variable
- GOTRACEBACK=wer or calling debug.SetTraceback("wer")
- before the crash. Other than enabling WER, the runtime will behave as with GOTRACEBACK=crash.
- On non-Windows systems, GOTRACEBACK=wer is ignored.
-
- GODEBUG=cgocheck=2, a thorough checker of cgo pointer passing rules,
- is no longer available as a debug option.
- Instead, it is available as an experiment using GOEXPERIMENT=cgocheck2.
- In particular this means that this mode has to be selected at build time instead of startup time.
-
- GODEBUG=cgocheck=1 is still available (and is still the default).
-
- A new type Pinner has been added to the runtime
- package. Pinners may be used to "pin" Go memory
- such that it may be used more freely by non-Go code. For instance,
- passing Go values that reference pinned Go memory to C code is
- now allowed. Previously, passing any such nested reference was
- disallowed by the
- cgo pointer passing rules.
-
- See the docs for more details.
-
- A few previously-internal GC metrics, such as live heap size, are
- now available.
-
- GOGC and GOMEMLIMIT are also now
- available as metrics.
-
- Collecting traces on amd64 and arm64 now incurs a substantially - smaller CPU cost: up to a 10x improvement over the previous release. -
- -- Traces now contain explicit stop-the-world events for every reason - the Go runtime might stop-the-world, not just garbage collection. -
-
- The new OnceFunc,
- OnceValue, and
- OnceValues
- functions capture a common use of Once to
- lazily initialize a value on first use.
-
- On Windows the
- Fchdir function
- now changes the current directory to its argument, rather than
- always returning an error.
-
- On FreeBSD
- SysProcAttr
- has a new field Jail that may be used to put the
- newly created process in a jailed environment.
-
- On Windows the syscall package now supports working with files whose
- names, stored as UTF-16, can't be represented as valid UTF-8.
- The UTF16ToString
- and UTF16FromString
- functions now convert between UTF-16 data and
- WTF-8 strings.
- This is backward compatible as WTF-8 is a superset of the UTF-8
- format that was used in earlier releases.
-
- Several error values match the new
- errors.ErrUnsupported,
- such that errors.Is(err, errors.ErrUnsupported)
- returns true.
-
ENOSYSENOTSUPEOPNOTSUPPEPLAN9 (Plan 9 only)ERROR_CALL_NOT_IMPLEMENTED (Windows only)ERROR_NOT_SUPPORTED (Windows only)EWINDOWS (Windows only)
- The new -test.fullpath option will print full path
- names in test log messages, rather than just base names.
-
- The new Testing function reports whether the program is a test created by go test.
-
- Calling Open.Stat
- will return a type that now implements a String
- method that calls
- io/fs.FormatFileInfo.
-
- The unicode package and
- associated support throughout the system has been upgraded to
- Unicode 15.0.0.
-
- As announced in the Go 1.20 release notes, - Go 1.21 requires macOS 10.15 Catalina or later; - support for previous versions has been discontinued. -
- -- As announced in the Go 1.20 release notes, - Go 1.21 requires at least Windows 10 or Windows Server 2016; - support for previous versions has been discontinued. -
- - -- -
- -
- The new go:wasmimport directive can now be used in Go programs
- to import functions from the WebAssembly host.
-
- The Go scheduler now interacts much more efficiently with the - JavaScript event loop, especially in applications that block - frequently on asynchronous events. -
- - -
- Go 1.21 adds an experimental port to the
- WebAssembly System Interface (WASI), Preview 1
- (GOOS=wasip1, GOARCH=wasm).
-
- As a result of the addition of the new GOOS value
- "wasip1", Go files named *_wasip1.go
- will now be ignored
- by Go tools except when that GOOS value is being
- used.
- If you have existing filenames matching that pattern, you will
- need to rename them.
-
- On Linux, GOPPC64=power10 now generates PC-relative instructions, prefixed
- instructions, and other new Power10 instructions. On AIX, GOPPC64=power10
- generates Power10 instructions, but does not generate PC-relative instructions.
-
- When building position-independent binaries for GOPPC64=power10
- GOOS=linux GOARCH=ppc64le, users can expect reduced binary
- sizes in most cases, in some cases 3.5%. Position-independent binaries are built for
- ppc64le with the following -buildmode values:
- c-archive, c-shared, shared, pie, plugin.
-
- The linux/loong64 port now supports -buildmode=c-archive,
- -buildmode=c-shared and -buildmode=pie.
-