2 "Title": "Go 1.21 Release Notes",
7 NOTE: In this document and others in this directory, the convention is to
8 set fixed-width phrases with non-fixed-width spaces, as in
9 <code>hello</code> <code>world</code>.
10 Do not send CLs removing the interior tags from such phrases.
14 main ul li { margin: 0.5em 0; }
17 <h2 id="introduction">DRAFT RELEASE NOTES — Introduction to Go 1.21</h2>
21 Go 1.21 is not yet released. These are work-in-progress
22 release notes. Go 1.21 is expected to be released in August 2023.
26 <h2 id="language">Changes to the language</h2>
29 Go 1.21 adds three new built-ins to the language.
32 <li><!-- https://go.dev/issue/59488 -->
33 The new functions <code>min</code> and <code>max</code> compute the
34 smallest (or largest, for <code>max</code>) value of a fixed number
36 See the language spec for
37 <a href="https://tip.golang.org/ref/spec#Min_and_max">details</a>.
39 <li><!-- https://go.dev/issue/56351 -->
40 The new function <code>clear</code> deletes all elements from a
41 map or zeroes all elements of a slice.
42 See the language spec for
43 <a href="https://tip.golang.org/ref/spec#Clear">details</a>.
48 <p><!-- https://go.dev/issue/57411 -->
49 Package initialization order is now specified more precisely. The
53 Sort all packages by import path.
55 <li>Repeat until the list of packages is empty:
58 Find the first package in the list for which all imports are
62 Initialize that package and remove it from the list.
67 This may change the behavior of some programs that rely on a
68 specific initialization ordering that was not expressed by explicit
69 imports. The behavior of such programs was not well defined by the
70 spec in past releases. The new rule provides an unambiguous definition.
74 Multiple improvements that increase the power and precision of type inference have been made.
77 <li><!-- https://go.dev/issue/59338 -->
78 A (possibly partially instantiated generic) function may now be called with arguments that are
79 themselves (possibly partially instantiated) generic functions.
80 The compiler will attempt to infer the missing type arguments of the callee (as before) and,
81 for each argument that is a generic function that is not fully instantiated,
82 its missing type arguments (new).
83 Typical use cases are calls to generic functions operating on containers
84 (such as <a href="/pkg/slices#IndexFunc">slices.IndexFunc</a>) where a function argument
85 may also be generic, and where the type argument of the called function and its arguments
86 are inferred from the container type.
87 More generally, a generic function may now be used without explicit instantiation when
88 it is assigned to a variable or returned as a result value if the type arguments can
89 be inferred from the assignment.
91 <li><!-- https://go.dev/issue/60353, https://go.dev/issue/57192, https://go.dev/issue/52397, https://go.dev/issue/41176 -->
92 Type inference now also considers methods when a value is assigned to an interface:
93 type arguments for type parameters used in method signatures may be inferred from
94 the corresponding parameter types of matching methods.
96 <li><!-- https://go.dev/issue/51593 https://go.dev/issue/39661 -->
97 Similarly, since a type argument must implement all the methods of its corresponding constraint,
98 the methods of the type argument and constraint are matched which may lead to the inference of
99 additional type arguments.
101 <li><!-- https://go.dev/issue/58671 -->
102 If multiple untyped constant arguments of different kinds (such as an untyped int and
103 an untyped floating-point constant) are passed to parameters with the same (not otherwise
104 specified) type parameter type, instead of an error, now type inference determines the
105 type using the same approach as an operator with untyped constant operands.
106 This change brings the types inferred from untyped constant arguments in line with the
107 types of constant expressions.
109 <li><!-- https://go.dev/issue/59750 -->
110 Type inference is now precise when matching corresponding types in assignments:
111 component types (such as the the elements of slices, or the parameter types in function signatures)
112 must be identical (given suitable type arguments) to match, otherwise inference fails.
113 This change produces more accurate error messages:
114 where in the past type inference may have succeeded incorrectly and lead to an invalid assignment,
115 the compiler now reports an inference error if two types can't possibly match.
119 <p><!-- https://go.dev/issue/58650 -->
120 More generally, the description of
121 <a href="https://tip.golang.org/ref/spec#Type_inference">type inference</a>
122 in the language spec has been clarified.
123 Together, all these changes make type inference more powerful and inference failures less surprising.
126 <p><!-- https://go.dev/issue/56986 -->
127 TODO: <a href="https://go.dev/issue/56986">https://go.dev/issue/56986</a>: extended backwards compatibility for Go
130 <!-- https://go.dev/issue/57969 -->
132 <!-- add GOEXPERIMENT=loopvar -->
137 TODO: complete this section
140 <h2 id="ports">Ports</h2>
144 <!-- cmd/dist: default to GOARM=7 on all non-arm systems -->
147 <h3 id="wasm">WebAssembly</h3>
149 <p><!-- https://go.dev/issue/38248, https://go.dev/issue/59149, CL 489255 -->
150 The new <code>go:wasmimport</code> directive can now be used in Go programs
151 to import functions from the WebAssembly host.
154 <!-- https://go.dev/issue/56100 -->
156 The Go scheduler now interacts much more efficiently with the
157 JavaScript event loop, especially in applications that block
158 frequently on asynchronous events.
162 <h3 id="wasip1">WebAssembly System Interface</h3>
164 <p><!-- https://go.dev/issue/58141 -->
165 Go 1.21 adds an experimental port to the <a href="https://wasi.dev/">
166 WebAssembly System Interface (WASI)</a>, Preview 1
167 (<code>GOOS=wasip1</code>, <code>GOARCH=wasm</code>).
171 As a result of the addition of the new <code>GOOS</code> value
172 "<code>wasip1</code>", Go files named <code>*_wasip1.go</code>
173 will now be <a href="/pkg/go/build/#hdr-Build_Constraints">ignored
174 by Go tools</a> except when that <code>GOOS</code> value is being
176 If you have existing filenames matching that pattern, you will
180 <h2 id="tools">Tools</h2>
182 <!-- https://go.dev/issue/15513 -->
184 <!-- support compiling all tests without running -->
187 <h3 id="go-command">Go command</h3>
189 <p><!-- https://go.dev/issue/58099, CL 474236 -->
190 The <code>-pgo</code> build flag now defaults to <code>-pgo=auto</code>,
191 and the restriction of specifying a single main package on the command
192 line is now removed. If a file named <code>default.pgo</code> is present
193 in the main package's directory, the <code>go</code> command will use
194 it to enable profile-guided optimization for building the corresponding
198 <p><!-- https://go.dev/issue/37708, CL 463837 -->
199 The new <code>go</code> <code>test</code> option
200 <code>-fullpath</code> prints full path names in test log messages,
201 rather than just base names.
206 <!-- cmd/go: make go test build multiple executables; The go test command now supports using the -c flag with multiple packages. -->
209 <h3 id="cgo">Cgo</h3>
211 <p><!-- CL 490819 -->
212 In files that <code>import "C"</code>, the Go toolchain now
213 correctly reports errors for attempts to declare Go methods on C types.
216 <h2 id="runtime-changes">Runtime</h2>
219 TODO: complete this section, or delete if not needed
222 <p><!-- https://go.dev/issue/7181 -->
223 When printing very deep stacks, the runtime now prints the first 50
224 (innermost) frames followed by the bottom 50 (outermost) frames,
225 rather than just printing the first 100 frames. This makes it easier
226 to see how deeply recursive stacks started, and is especially
227 valuable for debugging stack overflows.
230 <p><!-- https://go.dev/issue/59960 -->
231 On Linux platforms that support transparent huge pages, the Go runtime
232 now manages which parts of the heap may be backed by huge pages more
233 explicitly. This leads to better utilization of memory: small heaps
234 should see less memory used (up to 50% in pathological cases) while
235 large heaps should see fewer broken huge pages for dense parts of the
236 heap, improving CPU usage and latency by up to 1%.
239 <p><!-- https://go.dev/issue/57069, https://go.dev/issue/56966 -->
240 As a result of runtime-internal garbage collection tuning,
241 applications may see up to a 40% reduction in application tail latency
242 and a small decrease in memory use. Some applications may also observe
243 a small loss in throughput.
245 The memory use decrease should be proportional to the loss in
246 throughput, such that the previous release's throughput/memory
247 tradeoff may be recovered (with little change to latency) by
248 increasing <code>GOGC</code> and/or <code>GOMEMLIMIT</code> slightly.
251 <p><!-- https://go.dev/issue/51676 -->
252 Calls from C to Go on threads created in C require some setup to prepare for
253 Go execution. On Unix platforms, this setup is now preserved across multiple
254 calls from the same thread. This significantly reduces the overhead of
255 subsequent C to Go calls from ~1-3 microseconds per call to ~100-200
256 nanoseconds per call.
259 <h2 id="compiler">Compiler</h2>
262 Profile-guide optimization (PGO), added as a preview in Go 1.20, is now ready
263 for general use. PGO enables additional optimizations on code identified as
264 hot by profiles of production workloads. As mentioned in the
265 <a href="#go-command">Go command section</a>, PGO is enabled by default for
266 binaries that contain a <code>default.pgo</code> profile in the main
267 package directory. Performance improvements vary depending on application
268 behavior, with most programs from a representative set of Go programs seeing
269 between 2 and 7% improvement from enabling PGO. See the
270 <a href="/doc/pgo">PGO user guide</a> for detailed documentation.
273 <!-- https://go.dev/issue/59959 -->
275 PGO builds can now devirtualize some interface method calls, adding a
276 concrete call to the most common callee. This enables further optimization,
277 such as inlining the callee.
282 <!-- cmd/compile: enable deadcode of unreferenced large global maps -->
286 TODO: complete this section, or delete if not needed
289 <h2 id="assembler">Assembler</h2>
293 The verifier that checks for incorrect uses of <code>R15</code> when dynamic linking on amd64 has been improved.
296 <h2 id="linker">Linker</h2>
298 <p><!-- https://go.dev/issue/57302, CL 461749 -->
299 On Windows AMD64, the linker (with help from the compiler) now emits
300 SEH unwinding data by default, which improves the integration
301 of Go applications with Windows debuggers and other tools.
306 <!-- cmd/link: generate .xdata PE section -->
310 In Go 1.21 the linker (with help from the compiler) is now capable of
311 deleting dead (unreferenced) global map variables, if the number of
312 entries in the variable initializer is sufficiently large, and if the
313 initializer expressions are side-effect free.
316 TODO: complete this section, or delete if not needed
319 <h2 id="library">Core library</h2>
321 <h3 id="slog">New log/slog package</h3>
323 <p><!-- https://go.dev/issue/59060, https://go.dev/issue/59141, https://go.dev/issue/59204, https://go.dev/issue/59280,
324 https://go.dev/issue/59282, https://go.dev/issue/59339, https://go.dev/issue/59345,
325 CL 477295, CL 484096, CL 486376, CL 486415, CL 487855 -->
326 The new <a href="/pkg/log/slog">log/slog</a> package provides structured logging with levels.
327 Structured logging emits key-value pairs
328 to enable fast, accurate processing of large amounts of log data.
329 The package supports integration with popular log analysis tools and services.
332 <h3 id="slogtest">New testing/slogtest package</h3>
334 <p><!-- CL 487895 -->
335 The new <a href="/pkg/testing/slogtest">testing/slogtest</a> package can help
336 to validate <a href="/pkg/log/slog#Handler">slog.Handler<a/> implementations.
339 <h3 id="slices">New slices package</h3>
341 <p><!-- https://go.dev/issue/45955, https://go.dev/issue/54768, https://go.dev/issue/57348, https://go.dev/issue/57433, CL 467417, CL 483175 -->
342 The new <a href="/pkg/slices">slices</a> package provides many common
343 operations on slices, using generic functions that work with slices
347 <h3 id="maps">New maps package</h3>
349 <p><!-- https://go.dev/issue/57436, CL 464343 -->
350 The new <a href="/pkg/maps/">maps</a> package provides several
351 common operations on maps, using generic functions that work with
352 maps of any key or element type.
355 <h3 id="minor_library_changes">Minor changes to the library</h3>
358 As always, there are various minor changes and updates to the library,
359 made with the Go 1 <a href="/doc/go1compat">promise of compatibility</a>
361 There are also various performance improvements, not enumerated here.
365 TODO: complete this section
368 <dl id="archive/tar"><dt><a href="/pkg/archive/tar/">archive/tar</a></dt>
370 <p><!-- https://go.dev/issue/54451, CL 491175 -->
371 The implementation of the
372 <a href="/pkg/io/fs/#FileInfo"><code>io/fs.FileInfo</code></a>
373 interface returned by
374 <a href="/pkg/archive/tar/#Header.FileInfo"><code>Header.FileInfo</code></a>
375 now implements a <code>String</code> method that calls
376 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
379 </dl><!-- archive/tar -->
381 <dl id="archive/zip"><dt><a href="/pkg/archive/zip/">archive/zip</a></dt>
383 <p><!-- https://go.dev/issue/54451, CL 491175 -->
384 The implementation of the
385 <a href="/pkg/io/fs/#FileInfo"><code>io/fs.FileInfo</code></a>
386 interface returned by
387 <a href="/pkg/archive/zip/#FileHeader.FileInfo"><code>FileHeader.FileInfo</code></a>
388 now implements a <code>String</code> method that calls
389 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
392 <p><!-- https://go.dev/issue/54451, CL 491175 -->
393 The implementation of the
394 <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
395 interface returned by the
396 <a href="/pkg/io/fs/#ReadDirFile.ReadDir"><code>io/fs.ReadDirFile.ReadDir</code></a>
398 <a href="/pkg/io/fs/#File"><code>io/fs.File</code></a>
400 <a href="/pkg/archive/zip/#Reader.Open"><code>Reader.Open</code></a>
401 now implements a <code>String</code> method that calls
402 <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
405 </dl><!-- archive/zip -->
407 <dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt>
409 <p><!-- https://go.dev/issue/53685, CL 474635 -->
410 The <a href="/pkg/bytes/#Buffer"><code>Buffer</code></a> type
412 <a href="/pkg/bytes/#Buffer.Available"><code>Available</code></a>
413 and <a href="/pkg/bytes/#AvailableBuffer"><code>AvailableBuffer</code></a>.
414 These may be used along with the
415 <a href="/pkg/bytes/#Buffer.Write"><code>Write</code></a>
416 method to append directly to the <code>Buffer</code>.
421 <dl id="context"><dt><a href="/pkg/context/">context</a></dt>
423 <p><!-- https://go.dev/issue/40221, CL 479918 -->
424 The new <a href="/pkg/context/#WithoutCancel"><code>WithoutCancel</code></a>
425 function returns a copy of a context that is not canceled when the original
428 <p><!-- https://go.dev/issue/56661, CL 449318 -->
429 The new <a href="/pkg/context/#WithDeadlineCause"><code>WithDeadlineCause</code></a>
430 and <a href="/pkg/context/#WithTimeoutCause"><code>WithTimeoutCause</code></a>
431 functions provide a way to set a context cancellation cause when a deadline or
432 timer expires. The cause may be retrieved with the
433 <a href="/pkg/context/#Cause"><code>Cause</code></a> function.
435 <p><!-- https://go.dev/issue/57928, CL 482695 -->
436 The new <a href="/pkg/context/#AfterFunc"><code>AfterFunc</code></a>
437 function registers a function to run after a context has been cancelled.
442 <dl id="crypto/elliptic"><dt><a href="/pkg/crypto/elliptic/">crypto/elliptic</a></dt>
444 <p><!-- CL 459977 -->
445 TODO: <a href="https://go.dev/cl/459977">https://go.dev/cl/459977</a>: crypto/elliptic: deprecate unsafe APIs; modified api/next/34648.txt, api/next/52221.txt
448 </dl><!-- crypto/elliptic -->
450 <dl id="crypto/rsa"><dt><a href="/pkg/crypto/rsa/">crypto/rsa</a></dt>
452 <p><!-- https://go.dev/issue/56921 -->
453 TODO: <a href="https://go.dev/issue/56921">https://go.dev/issue/56921</a>: deprecate GenerateMultiPrimeKey and PrecomputedValues.CRTValues
456 <p><!-- CL 459976 -->
457 TODO: <a href="https://go.dev/cl/459976">https://go.dev/cl/459976</a>: crypto/rsa: deprecate multiprime RSA support; modified api/next/56921.txt
460 </dl><!-- crypto/rsa -->
462 <dl id="crypto/sha1"><dt><a href="/pkg/crypto/sha1/">crypto/sha1</a></dt>
464 <p><!-- CL 483815 -->
465 TODO: <a href="https://go.dev/cl/483815">https://go.dev/cl/483815</a>: crypto/sha1: add WriteString and WriteByte method
468 </dl><!-- crypto/sha1 -->
470 <dl id="crypto/sha256"><dt><a href="/pkg/crypto/sha256/">crypto/sha256</a></dt>
472 <p><!-- https://go.dev/issue/50543 -->
473 TODO: <a href="https://go.dev/issue/50543">https://go.dev/issue/50543</a>: add native SHA256 instruction implementation for AMD64
476 <p><!-- CL 408795 -->
477 TODO: <a href="https://go.dev/cl/408795">https://go.dev/cl/408795</a>: crypto/sha256: add sha-ni implementation; crypto/sha256 uses Intel SHA extensions on new enough x86 processors, making it 3-4X faster.
480 <p><!-- CL 481478 -->
481 TODO: <a href="https://go.dev/cl/481478">https://go.dev/cl/481478</a>: crypto/sha256: add WriteString and WriteByte method
484 </dl><!-- crypto/sha256 -->
486 <dl id="crypto/sha512"><dt><a href="/pkg/crypto/sha512/">crypto/sha512</a></dt>
488 <p><!-- CL 483816 -->
489 TODO: <a href="https://go.dev/cl/483816">https://go.dev/cl/483816</a>: crypto/sha512: add WriteString and WriteByte method
492 </dl><!-- crypto/sha512 -->
494 <dl id="crypto/x509"><dt><a href="/pkg/crypto/x509/">crypto/x509</a></dt>
496 <p><!-- https://go.dev/issue/53573 -->
497 TODO: <a href="https://go.dev/issue/53573">https://go.dev/issue/53573</a>: surface ReasonCode inside x509.RevocationList entries
500 <p><!-- CL 468875 -->
501 TODO: <a href="https://go.dev/cl/468875">https://go.dev/cl/468875</a>: crypto/x509: surface ReasonCode in RevocationList API; modified api/next/53573.txt
504 </dl><!-- crypto/x509 -->
506 <dl id="debug/elf"><dt><a href="/pkg/debug/elf/">debug/elf</a></dt>
508 <p><!-- https://go.dev/issue/56892, CL 452617 -->
510 <a href="https:/pkg/debug/elf/#File.DynValue"><code>File.DynValue</code></a>
511 method may be used to retrieve the numeric values listed with a
515 <p><!-- https://go.dev/issue/56887, CL 452496 -->
516 The constant flags permitted in a <code>DT_FLAGS_1</code>
517 dynamic tag are now defined with type
518 <a href="/pkg/debug/elf/#DynFlag1"><code>DynFlag1</code></a>. These
519 tags have names starting with <code>DF_1</code>.
522 <p><!-- CL 473256 -->
523 The package now defines the constant
524 <a href="/pkg/debug/elf/#COMPRESS_ZSTD"><code>COMPRESS_ZSTD</code></a>.
527 </dl><!-- debug/elf -->
529 <dl id="debug/pe"><dt><a href="/pkg/debug/pe/">debug/pe</a></dt>
531 <p><!-- CL 488475 -->
532 Attempts to read from a section containing uninitialized data
534 <a href="/pkg/debug/pe/#Section.Data"><code>Section.Data</code></a>
535 or the reader returned by <a href="/pkg/debug/pe/#Section.Open"><code>Section.Open</code></a>
539 </dl><!-- debug/pe -->
541 <dl id="embed"><dt><a href="/pkg/embed/">embed</a></dt>
543 <p><!-- https://go.dev/issue/57803, CL 483235 -->
544 The <a href="/pkg/io/fs/#File"><code>io/fs.File</code></a>
546 <a href="/pkg/embed/#FS.Open"><code>FS.Open</code></a> now
547 has a <code>ReadAt</code> method that
548 implements <a href="/pkg/io/#ReaderAt"><code>io.ReaderAt</code></a>.
551 <p><!-- https://go.dev/issue/54451, CL 491175 -->
552 Calling <code><a href="/pkg/embed/FS.Open">FS.Open</a>.<a href="/pkg/io/fs/#File.Stat">Stat</a></code>
553 will return a type that now implements a <code>String</code>
555 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
560 <dl id="errors"><dt><a href="/pkg/errors/">errors</a></dt>
562 <p><!-- https://go.dev/issue/41198, CL 473935 -->
564 <a href="/pkg/errors/#ErrUnsupported"><code>ErrUnsupported</code></a>
565 error provides a standardized way to indicate that a requested
566 operation may not be performed because it is unsupported.
567 For example, a call to
568 <a href="/pkg/os/#Link"><code>os.Link</code></a> when using a
569 file system that does not support hard links.
574 <dl id="flag"><dt><a href="/pkg/flag/">flag</a></dt>
576 <p><!-- https://go.dev/issue/53747, CL 476015 -->
577 The new <a href="/pkg/flag/#BoolFunc"><code>BoolFunc</code></a>
579 <a href="/pkg/flag/#FlagSet.BoolFunc"><code>FlagSet.BoolFunc</code></a>
580 method define a flag that does not require an argument and calls
581 a function when the flag is used. This is similar to
582 <a href="/pkg/flag/#Func"><code>Func</code></a> but for a
586 <p><!-- CL 480215 -->
587 A flag definition (via <code>Bool</code>, <code>BoolVar</code>, <code>Int</code>, <code>IntVar</code>, etc.) will panic if <code>Set</code> has already been called on a flag with the same name.
589 This change is intended to detect cases where <a href="#language">changes in initialization order</a> 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 <code>Set</code> operations.
594 <dl id="go/ast"><dt><a href="/pkg/go/ast/">go/ast</a></dt>
596 <p><!-- https://go.dev/issue/28089, CL 487935 -->
597 The new <a href="/pkg/go/ast/#IsGenerated"><code>IsGenerated</code></a> predicate
598 reports whether a file syntax tree contains the
599 <a href="https://go.dev/s/generatedcode">special comment</a>
600 that conventionally indicates that the file was generated by a tool.
605 <p><!-- https://go.dev/issue/59033, CL 476276 -->
607 <a href="/pkg/go/ast/#File.GoVersion"><code>File.GoVersion</code></a>
608 field records the minimum Go version required by
609 any <code>//go:build</code> or <code>// +build</code>
615 <dl id="go/build"><dt><a href="/pkg/go/build/">go/build</a></dt>
617 <p><!-- https://go.dev/issue/56986, CL 453603 -->
618 The package now parses build directives (comments that start
619 with <code>//go:</code>) in file headers (before
620 the <code>package</code> declaration). These directives are
622 <a href="/pkg/go/build/Package"><code>Package</code></a> fields
623 <a href="/pkg/go/build/Package.Directives"><code>Directives</code></a>,
624 <a href="/pkg/go/build/Package.TestDirectives"><code>TestDirectives</code></a>,
626 <a href="/pkg/go/build/Package.XTestDirectives"><code>XTestDirectives</code></a>.
629 </dl><!-- go/build -->
631 <dl id="go/build/constraint"><dt><a href="/pkg/go/build/constraint/">go/build/constraint</a></dt>
633 <p><!-- https://go.dev/issue/59033, CL 476275 -->
635 <a href="/pkg/go/build/constraint/#GoVersion"><code>GoVersion</code></a>
636 function returns the minimum Go version implied by a build
640 </dl><!-- go/build/constraint -->
642 <dl id="go/token"><dt><a href="/pkg/go/token/">go/token</a></dt>
644 <p><!-- https://go.dev/issue/57708, CL 464515 -->
645 The new <a href="/pkg/go/token/#File.Lines"><code>File.Lines</code></a> method
646 returns the file's line-number table in the same form as accepted by
647 <code>File.SetLines</code>.
650 </dl><!-- go/token -->
652 <dl id="hash/maphash"><dt><a href="/pkg/hash/maphash/">hash/maphash</a></dt>
654 <p><!-- https://go.dev/issue/47342, CL 468795 -->
655 The <code>hash/maphash</code> package now has a pure Go implementation, selectable with the <code>purego</code> build tag.
658 </dl><!-- hash/maphash -->
660 <dl id="io/fs"><dt><a href="/pkg/io/fs/">io/fs</a></dt>
662 <p><!-- https://go.dev/issue/54451, CL 489555 -->
664 <a href="/pkg/io/fs/#FormatFileInfo"><code>FormatFileInfo</code></a>
665 function returns a formatted version of a
666 <a href="/pkg/io/fs/#FileInfo"><code>FileInfo</code></a>.
668 <a href="/pkg/io/fs/#FormatDirEntry"><code>FormatDirEntry</code></a>
669 function returns a formatted version of a
670 <a href="/pkg/io/fs/#FileInfo"><code>DirEntry</code></a>.
671 The implementation of
672 <a href="/pkg/io/fs/#DirEntry"><code>DirEntry</code></a>
674 <a href="/pkg/io/fs/#ReadDir"><code>ReadDir</code></a> now
675 implements a <code>String</code> method that calls
676 <a href="/pkg/io/fs/#FormatDirEntry"><code>FormatDirEntry</code></a>,
677 and the same is true for
678 the <a href="/pkg/io/fs/#DirEntry"><code>DirEntry</code></a>
680 <a href="/pkg/io/fs/#WalkDirFunc"><code>WalkDirFunc</code></a>.
685 <!-- https://go.dev/issue/56491 rolled back -->
686 <!-- CL 459435 reverted -->
687 <!-- CL 467515 reverted -->
689 <dl id="math/big"><dt><a href="/pkg/math/big/">math/big</a></dt>
691 <p><!-- https://go.dev/issue/56984, CL 453115 -->
692 The new <a href="/pkg/math/big/#Int.ToFloat64"><code>Int.ToFloat64</code></a>
693 method returns the nearest floating-point value to a
694 multi-precision integer, along with an indication of any
695 rounding that occurred.
698 </dl><!-- math/big -->
700 <dl id="net"><dt><a href="/pkg/net/">net</a></dt>
703 <!-- https://go.dev/issue/59166, https://go.dev/issue/56539 -->
704 <!-- CL 471136, CL 471137, CL 471140 -->
705 On Linux, the <a href="/pkg/net/">net</a> package can now use
706 Multipath TCP when the kernel supports it. It is not used by
707 default. To use Multipath TCP when available on a client, call
709 <a href="/pkg/net/#Dialer.SetMultipathTCP"><code>Dialer.SetMultipathTCP</code></a>
710 method before calling the
711 <a href="/pkg/net/#Dialer.Dial"><code>Dialer.Dial</code></a> or
712 <a href="/pkg/net/#Dialer.DialContext"><code>Dialer.DialContext</code></a>
713 methods. To use Multipath TCP when available on a server, call
715 <a href="/pkg/net/#ListenConfig.SetMultipathTCP"><code>ListenConfig.SetMultipathTCP</code></a>
716 method before calling the
717 <a href="/pkg/net/#ListenConfig.Listen"><code>ListenConfig.Listen</code></a>
718 method. Specify the network as <code>"tcp"</code> or
719 <code>"tcp4"</code> or <code>"tcp6"</code> as usual. If
720 Multipath TCP is not supported by the kernel or the remote host,
721 the connection will silently fall back to TCP. To test whether a
722 particular connection is using Multipath TCP, use the
723 <a href="/pkg/net/#TCPConn.MultipathTCP"><code>TCPConn.MultipathTCP</code></a>
727 In a future Go release we may enable Multipath TCP by default on
728 systems that support it.
733 <dl id="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt>
735 <p><!-- https://go.dev/issue/44855, CL 382117 -->
736 The new <a href="/pkg/net/http/#ErrSchemeMismatch"><code>ErrSchemeMismatch</code></a> error is returned by <a href="/pkg/net/http/#Client"><code>Client</code></a> and <a href="/pkg/net/http/#Transport"><code>Transport</code></a> when the server responds to an HTTPS request with an HTTP response.
739 <p><!-- CL 472636 -->
740 TODO: <a href="https://go.dev/cl/472636">https://go.dev/cl/472636</a>: net/http: support full-duplex HTTP/1 responses; modified api/next/57786.txt
743 <p><!-- CL 494122 -->
744 The <a href="/pkg/net/http/">net/http</a> package now supports
745 <a href="/pkg/errors/#ErrUnsupported"><code>errors.ErrUnsupported</code></a>,
746 in that the expression
747 <code>errors.Is(http.ErrNotSupported, errors.ErrUnsupported)</code>
751 </dl><!-- net/http -->
753 <dl id="os"><dt><a href="/pkg/os/">os</a></dt>
755 <p><!-- https://go.dev/issue/32558, CL 219638 -->
756 Programs may now pass an empty <code>time.Time</code> value to
757 the <a href="/pkg/os/#Chtimes"><code>Chtimes</code></a> function
758 to leave either the access time or the modification time unchanged.
761 <p><!-- CL 480135 -->
763 <a href="/pkg/os#File.Chdir"><code>File.Chdir</code></a> method
764 now changes the current directory to the file, rather than
765 always returning an error.
768 <p><!-- CL 477215 -->
770 <a href="/pkg/os/#Truncate"><code>Truncate</code></a> on a
771 non-existent file used to create an empty file. It now returns
772 an error indicating that the file does not exist.
775 <p><!-- CL 493036 -->
776 On Windows the os package now supports working with files whose
777 names, stored as UTF-16, can't be represented as valid UTF-8.
780 <p><!-- https://go.dev/issue/54451, CL 491175 -->
781 The implementation of the
782 <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
783 interface returned by the
784 <a href="/pkg/os/#ReadDir"><code>ReadDir</code></a> function and
785 the <a href="/pkg/os/#File.ReadDir"><code>File.ReadDir</code></a>
786 method now implements a <code>String</code> method that calls
787 <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
790 <p><!-- https://go.dev/issue/53761, CL 416775, CL 498015-->
791 The implementation of the
792 <a href="/pkg/io/fs/#FS"><code>io/fs.FS</code></a> interface returned by
793 the <a href="/pkg/os/#DirFS"><code>DirFS</code></a> function now implements
794 the <a href="/pkg/io/fs/#ReadFileFS"><code>io/fs.ReadFileFS</code></a> and
795 the <a href="/pkg/io/fs/#ReadDirFS"><code></code>ios/fs.ReadDirFS</a>
801 <dl id="path/filepath"><dt><a href="/pkg/path/filepath/">path/filepath</a></dt>
804 The implementation of the
805 <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
806 interface passed to the function argument of
807 <a href="/pkg/path/filepath/#WalkDir"><code>WalkDir</code></a>
808 now implements a <code>String</code> method that calls
809 <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
812 </dl><!-- path/filepath -->
814 <!-- CL 459455 reverted -->
816 <dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
818 <p><!-- CL 408826, CL 413474 -->
819 In Go 1.21, <a href="/pkg/reflect/#ValueOf"><code>ValueOf</code></a>
820 no longer forces its argument to be allocated on the heap, allowing
821 a <code>Value</code>'s content to be allocated on the stack. Most
822 operations on a <code>Value</code> also allow the underlying value
823 to be stack allocated.
826 <p><!-- https://go.dev/issue/55002 -->
827 The new <a href="/pkg/reflect/#Value"><code>Value</code></a>
828 method <a href="/pkg/reflect/#Value.Clear"><code>Value.Clear</code></a>
829 clears the contents of a map or zeros the contents of a slice.
830 This corresponds to the new <code>clear</code> built-in
831 <a href="#language">added to the language</a>.
834 <p><!-- https://go.dev/issue/56906, CL 452762 -->
835 The <a href="/pkg/reflect/#SliceHeader"><code>SliceHeader</code></a>
836 and <a href="/pkg/reflect/#StringHeader"><code>StringHeader</code></a>
837 types are now deprecated. In new code
838 prefer <a href="/pkg/unsafe/#Slice"><code>unsafe.Slice</code></a>,
839 <a href="/pkg/unsafe/#SliceData"><code>unsafe.SliceData</code></a>,
840 <a href="/pkg/unsafe/#String"><code>unsafe.String</code></a>,
841 or <a href="/pkg/unsafe/#StringData"><code>unsafe.StringData</code></a>.
844 </dl><!-- reflect -->
846 <dl id="regexp"><dt><a href="/pkg/regexp/">regexp</a></dt>
848 <p><!-- https://go.dev/issue/46159, CL 479401 -->
849 <a href="/pkg/regexp#Regexp"><code>Regexp</code></a> now defines
850 <a href="/pkg/regexp#Regexp.MarshalText"><code>MarshalText</code></a>
851 and <a href="/pkg/regexp#Regexp.UnmarshalText"><code>UnmarshalText</code></a>
852 methods. These implement
853 <a href="/pkg/encoding#TextMarshaler"><code>encoding.TextMarshaler</code></a>
855 <a href="/pkg/encoding#TextUnmarshaler"><code>encoding.TextUnmarshaler</code></a>
856 and will be used by packages such as
857 <a href="/pkg/encoding/json">encoding/json</a>.
862 <dl id="runtime"><dt><a href="/pkg/runtime/">runtime</a></dt>
864 <p><!-- https://go.dev/issue/38651 -->
865 TODO: <a href="https://go.dev/issue/38651">https://go.dev/issue/38651</a>: add 'created by goroutine number' to stack traces
868 <p><!-- https://go.dev/issue/57441, CL 474915 -->
869 Crashing Go applications can now opt-in to Windows Error Reporting (WER) by setting the environment variable
870 <code>GOTRACEBACK=wer</code> or calling <a href="/pkg/runtime/debug/#SetTraceback"><code>debug.SetTraceback("wer")</code></a>
871 before the crash. Other than enabling WER, the runtime will behave as with <code>GOTRACEBACK=crash</code>.
872 On non-Windows systems, <code>GOTRACEBACK=wer</code> is ignored.
875 <p><!-- CL 447778 -->
876 <code>GODEBUG=cgocheck=2</code>, a thorough checker of cgo pointer passing rules,
877 is no longer available as a <a href="/pkg/runtime#hdr-Environment_Variables">debug option</a>.
878 Instead, it is available as an experiment using <code>GOEXPERIMENT=cgocheck2</code>.
879 In particular this means that this mode has to be selected at build time instead of startup time.
881 <code>GODEBUG=cgocheck=1</code> is still available (and is still the default).
884 <p><!-- https://go.dev/issue/46787 -->
885 A new type <code>Pinner</code> has been added to the runtime
886 package. <code>Pinner</code>s may be used to "pin" Go memory
887 such that it may be used more freely by non-Go code. For instance,
888 passing Go values that reference pinned Go memory to C code is
889 now allowed. Previously, passing any such nested reference was
891 <a href="https://pkg.go.dev/cmd/cgo#hdr-Passing_pointers">cgo pointer passing rules.</a>
893 See <a href="/pkg/runtime#Pinner">the docs</a> for more details.
896 </dl><!-- runtime -->
898 <dl id="runtime/trace"><dt><a href="/pkg/runtime/trace/">runtime/trace</a></dt>
900 <p><!-- https://go.dev/issue/16638 -->
901 Collecting traces on amd64 and arm64 now incurs a substantially
902 smaller CPU cost: up to a 10x improvement over the previous release.
905 <p><!-- CL 494495 -->
906 Traces now contain explicit stop-the-world events for every reason
907 the Go runtime might stop-the-world, not just garbage collection.
910 </dl><!-- runtime/trace -->
912 <dl id="runtime/metrics"><dt><a href="/pkg/runtime/metrics/">runtime/metrics</a></dt>
914 <p><!-- https://go.dev/issue/56857 -->
915 A few previously-internal GC metrics, such as live heap size, are
918 <code>GOGC</code> and <code>GOMEMLIMIT</code> are also now
919 available as metrics.
922 </dl><!-- runtime/metrics -->
924 <dl id="sync"><dt><a href="/pkg/sync/">sync</a></dt>
926 <p><!-- https://go.dev/issue/56102, CL 451356 -->
927 The new <a href="/pkg/sync/#OnceFunc"><code>OnceFunc</code></a>,
928 <a href="/pkg/sync/#OnceValue"><code>OnceValue</code></a>, and
929 <a href="/pkg/sync/#OnceValues"><code>OnceValues</code></a>
930 functions capture a common use of <a href="/pkg/sync/#Once">Once</a> to
931 lazily initialize a value on first use.
936 <dl id="syscall"><dt><a href="/pkg/syscall/">syscall</a></dt>
938 <p><!-- CL 480135 -->
940 <a href="/pkg/syscall#Fchdir"><code>Fchdir</code></a> function
941 now changes the current directory to its argument, rather than
942 always returning an error.
945 <p><!-- https://go.dev/issue/46259, CL 458335 -->
947 <a href="/pkg/syscall#SysProcAttr"><code>SysProcAttr</code></a>
948 has a new field <code>Jail</code> that may be used to put the
949 newly created process in a jailed environment.
952 <p><!-- CL 493036 -->
953 On Windows the syscall package now supports working with files whose
954 names, stored as UTF-16, can't be represented as valid UTF-8.
955 The <a href="/pkg/syscall#UTF16ToString"><code>UTF16ToString</code></a>
956 and <a href="/pkg/syscall#UTF16FromString"><code>UTF16FromString</code></a>
957 functions now convert between UTF-16 data and
958 <a href="https://simonsapin.github.io/wtf-8/">WTF-8</a> strings.
959 This is backward compatible as WTF-8 is a superset of the UTF-8
960 format that was used in earlier releases.
963 <p><!-- CL 476578, CL 476875, CL 476916 -->
964 Several error values match the new
965 <a href="/pkg/errors/#ErrUnsupported"><code>errors.ErrUnsupported</code></a>,
966 such that <code>errors.Is(err, errors.ErrUnsupported)</code>
969 <li><code>ENOSYS</code></li>
970 <li><code>ENOTSUP</code></li>
971 <li><code>EOPNOTSUPP</code></li>
972 <li><code>EPLAN9</code> (Plan 9 only)</li>
973 <li><code>ERROR_CALL_NOT_IMPLEMENTED</code> (Windows only)</li>
974 <li><code>ERROR_NOT_SUPPORTED</code> (Windows only)</li>
975 <li><code>EWINDOWS</code> (Windows only)</li>
979 </dl><!-- syscall -->
981 <dl id="testing"><dt><a href="/pkg/testing/">testing</a></dt>
983 <p><!-- https://go.dev/issue/37708, CL 463837 -->
984 The new <code>-test.fullpath</code> option will print full path
985 names in test log messages, rather than just base names.
988 <p><!-- https://go.dev/issue/52600, CL 475496 -->
989 The new <a href="/pkg/testing/#Testing"><code>Testing</code></a> function reports whether the program is a test created by <code>go</code> <code>test</code>.
992 </dl><!-- testing -->
994 <dl id="testing/fstest"><dt><a href="/pkg/testing/fstest/">testing/fstest</a></dt>
996 <p><!-- https://go.dev/issue/54451, CL 491175 -->
997 Calling <code><a href="/pkg/testing/fstest/MapFS.Open">Open</a>.<a href="/pkg/io/fs/#File.Stat">Stat</a></code>
998 will return a type that now implements a <code>String</code>
1000 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
1003 </dl><!-- testing/fstest -->
1005 <dl id="unicode"><dt><a href="/pkg/unicode/">unicode</a></dt>
1007 <p><!-- CL 456837 -->
1008 The <a href="/pkg/unicode/"><code>unicode</code></a> package and
1009 associated support throughout the system has been upgraded to
1010 <a href="https://www.unicode.org/versions/Unicode15.0.0/">Unicode 15.0.0</a>.
1012 </dl><!-- unicode -->
1014 <!-- proposals for x repos that don't need to be mentioned here but
1015 are picked up by the relnote tool. -->
1016 <!-- https://go.dev/issue/54232 -->
1017 <!-- https://go.dev/issue/57906 -->
1018 <!-- https://go.dev/issue/58668 -->