DRAFT RELEASE NOTES — Introduction to Go 1.21

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.

Changes to the language

Go 1.21 adds three new built-ins to the language.

The new functions min and max compute the smallest (or largest, for max) value of a fixed number of given arguments. See the language spec for details.
The new function 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:

Sort all packages by import path.
Repeat until the list of packages is empty:
- Find the first package in the list for which all imports are already initialized.
- Initialize that package and remove it from the list.

This may change the behavior of some programs that rely on a specific initialization ordering that was not expressed by explicit imports. The behavior of such programs was not well defined by the spec in past releases. The new rule provides an unambiguous definition.

TODO: https://go.dev/issue/59338: infer type arguments from assignments of generic functions (reverse type inference)

TODO: https://go.dev/issue/56986: extended backwards compatibility for Go

TODO: complete this section

Ports

WebAssembly

The Go scheduler now interacts much more efficiently with the JavaScript event loop, especially in applications that block frequently on asynchronous events.

WebAssembly System Interface

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.

Tools

Go command

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 new go test option -fullpath prints full path names in test log messages, rather than just base names.

TODO: https://go.dev/cl/453603: cmd/go, go/build: parse directives in file headers; modified api/next/56986.txt

Runtime

TODO: complete this section, or delete if not needed

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.

Compiler

TODO: complete this section, or delete if not needed

Linker

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.

TODO: complete this section, or delete if not needed

Core library

New log/slog package

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.

New slices package

The new slices package provides many common operations on slices, using generic functions that work with slices of any element type.

New maps package

The new maps package provides several common operations on maps, using generic functions that work with maps of any key or element type.

Minor changes to the library

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.

TODO: https://go.dev/cl/456837: all: upgrade Unicode from 13.0.0 to 15.0.0; modified api/except.txt, api/next/55079.txt

TODO: complete this section

bytes

TODO: https://go.dev/issue/53685: add Buffer.Available and Buffer.AvailableBuffer

TODO: https://go.dev/cl/474635: bytes: add Buffer.Available and Buffer.AvailableBuffer; modified api/next/53685.txt

context

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.

crypto/elliptic: TODO: https://go.dev/cl/459977: crypto/elliptic: deprecate unsafe APIs; modified api/next/34648.txt, api/next/52221.txt

crypto/rsa

TODO: https://go.dev/issue/56921: deprecate GenerateMultiPrimeKey and PrecomputedValues.CRTValues

TODO: https://go.dev/cl/459976: crypto/rsa: deprecate multiprime RSA support; modified api/next/56921.txt

crypto/sha1: TODO: https://go.dev/cl/483815: crypto/sha1: add WriteString and WriteByte method

crypto/sha256

TODO: https://go.dev/issue/50543: add native SHA256 instruction implementation for AMD64

TODO: https://go.dev/cl/408795: crypto/sha256: add sha-ni implementation; crypto/sha256 uses Intel SHA extensions on new enough x86 processors, making it 3-4X faster.

TODO: https://go.dev/cl/481478: crypto/sha256: add WriteString and WriteByte method

crypto/sha512: TODO: https://go.dev/cl/483816: crypto/sha512: add WriteString and WriteByte method

crypto/x509

TODO: https://go.dev/issue/53573: surface ReasonCode inside x509.RevocationList entries

TODO: https://go.dev/cl/468875: crypto/x509: surface ReasonCode in RevocationList API; modified api/next/53573.txt

debug/elf

TODO: https://go.dev/issue/56887: add DT_FLAGS_1 (dynamic flags) constants

TODO: https://go.dev/issue/56892: add (*File).DynValue

TODO: https://go.dev/cl/452496: debug/elf: add DT_FLAGS_1 constants; modified api/next/56887.txt

TODO: https://go.dev/cl/452617: debug/elf: retrieve values for dynamic section tags; modified api/next/56892.txt

TODO: https://go.dev/cl/473256: debug/elf: support zstd compression; modified api/next/55107.txt

debug/pe: TODO: https://go.dev/cl/488475: debug/pe: return error on reading from section with uninitialized data

embed

TODO: https://go.dev/issue/57803: openFile should implement ReaderAt

TODO: https://go.dev/cl/483235: embed: implement openFile.ReadAt

errors: 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.

flag

TODO: https://go.dev/issue/53747: add BoolFunc(name, usage string, fn func(string)error)

TODO: https://go.dev/cl/476015: flag: add BoolFunc; FlagSet.BoolFunc; modified api/next/53747.txt

TODO: https://go.dev/cl/480215: flag: panic if a flag is defined after being set

fs: TODO: https://go.dev/issue/54451: standard implementations of FileInfo and DirEntry should implement fmt.Stringer

go/ast: 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.; TODO: https://go.dev/cl/476276: go/ast: add File.GoVersion; modified api/next/59033.txt

go/build: TODO: https://go.dev/cl/453603: cmd/go, go/build: parse directives in file headers; modified api/next/56986.txt

go/build/constraint: TODO: https://go.dev/cl/476275: go/build/constraint: add GoVersion; modified api/next/59033.txt

go/token: The new File.Lines method returns the file's line-number table in the same form as accepted by File.SetLines.

hash/maphash

TODO: https://go.dev/issue/47342: Provide a `purego` implementation

TODO: https://go.dev/cl/468795: hash/maphash: add purego implementation

io/fs: TODO: https://go.dev/cl/489555: io/fs: add FormatFileInfo and FormatDirEntry functions; modified api/next/54451.txt

log/slog

TODO: https://go.dev/issue/59060: arg to Record.Attrs should return bool

TODO: https://go.dev/issue/59141: handle panics in LogValuer.LogValue

TODO: https://go.dev/issue/59204: change slog.Group signature to ...any

TODO: https://go.dev/issue/59280: ReplaceAttr gets Source struct instead of file:line

TODO: https://go.dev/issue/59282: drop only completely empty Attrs

TODO: https://go.dev/issue/59339: change constructors to NewXXXHandler(io.Writer, *HandlerOptions)

TODO: https://go.dev/issue/59345: JSONHandler should format everything like json.Marshal

TODO: https://go.dev/cl/477295: log/slog: initial commit; modified api/next/56345.txt

TODO: https://go.dev/cl/484096: log/slog: function argument to Record.Attrs returns bool; modified api/next/59060.txt

TODO: https://go.dev/cl/486376: log/slog: add Source type for source location; modified api/next/59280.txt

TODO: https://go.dev/cl/486415: log/slog: built-in handler constructors take options as a second arg; modified api/next/56345.txt, api/next/59339.txt

TODO: https://go.dev/cl/487855: log/slog: Group takes ...any; modified api/next/56345.txt, api/next/59204.txt

math

TODO: https://go.dev/issue/56491: add Compare and Compare32

TODO: https://go.dev/cl/459435: math: add Compare and Compare32; modified api/next/56491.txt

TODO: https://go.dev/cl/467515: math: add Compare and Compare32; modified api/next/56491.txt

math/big: The new Int.ToFloat64 method returns the nearest floating-point value to a multi-precision integer, along with an indication of any rounding that occurred.

net

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.

net/http

The new ErrSchemeMismatch error is returned by Client and Transport when the server responds to an HTTPS request with an HTTP response.

TODO: https://go.dev/cl/472636: net/http: support full-duplex HTTP/1 responses; modified api/next/57786.txt

The net/http package now supports errors.ErrUnsupported, in that the expression errors.Is(http.ErrNotSupported, errors.ErrUnsupported) will return true.

os

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 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 the os package now supports working with files whose
      names, stored as UTF-16, can't be represented as valid UTF-8.





reflect
  
    
      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
  
    
      Regexp now defines
      MarshalText
      and UnmarshalText
      methods. These implement
      encoding.TextMarshaler
      and
      encoding.TextUnmarshaler
      and will be used by packages such as
      encoding/json.
    
  


runtime
  
    
      TODO: https://go.dev/issue/38651: add 'created by goroutine number' to stack traces
    

    
      TODO: https://go.dev/issue/57441: use WER for GOTRACEBACK=wer on Windows
    

    
      TODO: https://go.dev/cl/447778: runtime: reimplement GODEBUG=cgocheck=2 as a GOEXPERIMENT
    

    
      TODO: https://go.dev/cl/472195: runtime: remove NOFRAME from asmcgocall, systemstack and mcall
    

    
      TODO: https://go.dev/cl/474915: runtime: support GOTRACEBACK=wer on Windows
    

    
      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.
    
  


runtime/trace
  
    
      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.
    
  


runtime/metrics
  
    
      A few previously-internal GC metrics, such as live heap size, are
      now available.

      GOGC and GOMEMLIMIT are also now
      available as metrics.
    
  


sync
  
    
      The new OnceFunc,
      OnceValue, and
      OnceValues
      functions capture a common use of Once to
      lazily initialize a value on first use.
    
  


syscall
  
    
      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.
      

	ENOSYS
	ENOTSUP
	EOPNOTSUPP
	EPLAN9 (Plan 9 only)
	ERROR_CALL_NOT_IMPLEMENTED (Windows only)
	ERROR_NOT_SUPPORTED (Windows only)
	EWINDOWS (Windows only)
      
    
  


testing
  
    
      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.
    
  


testing/slogtest
  
    
      TODO: https://go.dev/cl/487895: testing/slogtest: tests for slog handlers; modified api/next/56345.txt