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 <!-- https://go.dev/issue/38248 -->
149 <!-- replace CallImport with go:wasmimport directive -->
152 <h3 id="wasm">WebAssembly</h3>
154 <!-- https://go.dev/issue/59149 -->
156 <!-- allow the use of go:wasmimport globally -->
161 <!-- cmd/compile: remove go:wasmimport restriction -->
164 <!-- https://go.dev/issue/56100 -->
166 The Go scheduler now interacts much more efficiently with the
167 JavaScript event loop, especially in applications that block
168 frequently on asynchronous events.
172 <h3 id="wasip1">WebAssembly System Interface</h3>
174 <p><!-- https://go.dev/issue/58141 -->
175 Go 1.21 adds an experimental port to the <a href="https://wasi.dev/">
176 WebAssembly System Interface (WASI)</a>, Preview 1
177 (<code>GOOS=wasip1</code>, <code>GOARCH=wasm</code>).
181 As a result of the addition of the new <code>GOOS</code> value
182 "<code>wasip1</code>", Go files named <code>*_wasip1.go</code>
183 will now be <a href="/pkg/go/build/#hdr-Build_Constraints">ignored
184 by Go tools</a> except when that <code>GOOS</code> value is being
186 If you have existing filenames matching that pattern, you will
190 <h2 id="tools">Tools</h2>
192 <!-- https://go.dev/issue/15513 -->
194 <!-- support compiling all tests without running -->
197 <h3 id="go-command">Go command</h3>
199 <p><!-- https://go.dev/issue/58099, CL 474236 -->
200 The <code>-pgo</code> build flag now defaults to <code>-pgo=auto</code>,
201 and the restriction of specifying a single main package on the command
202 line is now removed. If a file named <code>default.pgo</code> is present
203 in the main package's directory, the <code>go</code> command will use
204 it to enable profile-guided optimization for building the corresponding
208 <p><!-- https://go.dev/issue/37708, CL 463837 -->
209 The new <code>go</code> <code>test</code> option
210 <code>-fullpath</code> prints full path names in test log messages,
211 rather than just base names.
216 <!-- cmd/go: make go test build multiple executables; The go test command now supports using the -c flag with multiple packages. -->
219 <h2 id="runtime-changes">Runtime</h2>
222 TODO: complete this section, or delete if not needed
225 <p><!-- https://go.dev/issue/7181 -->
226 When printing very deep stacks, the runtime now prints the first 50
227 (innermost) frames followed by the bottom 50 (outermost) frames,
228 rather than just printing the first 100 frames. This makes it easier
229 to see how deeply recursive stacks started, and is especially
230 valuable for debugging stack overflows.
233 <p><!-- https://go.dev/issue/59960 -->
234 On Linux platforms that support transparent huge pages, the Go runtime
235 now manages which parts of the heap may be backed by huge pages more
236 explicitly. This leads to better utilization of memory: small heaps
237 should see less memory used (up to 50% in pathological cases) while
238 large heaps should see fewer broken huge pages for dense parts of the
239 heap, improving CPU usage and latency by up to 1%.
242 <p><!-- https://go.dev/issue/57069, https://go.dev/issue/56966 -->
243 As a result of runtime-internal garbage collection tuning,
244 applications may see up to a 40% reduction in application tail latency
245 and a small decrease in memory use. Some applications may also observe
246 a small loss in throughput.
248 The memory use decrease should be proportional to the loss in
249 throughput, such that the previous release's throughput/memory
250 tradeoff may be recovered (with little change to latency) by
251 increasing <code>GOGC</code> and/or <code>GOMEMLIMIT</code> slightly.
254 <p><!-- https://go.dev/issue/51676 -->
255 Calls from C to Go on threads created in C require some setup to prepare for
256 Go execution. On Unix platforms, this setup is now preserved across multiple
257 calls from the same thread. This significantly reduces the overhead of
258 subsequent C to Go calls from ~1-3 microseconds per call to ~100-200
259 nanoseconds per call.
262 <h2 id="compiler">Compiler</h2>
266 <!-- cmd/cgo: reject attempts to declare methods on C types -->
271 <!-- cmd/compile: enable deadcode of unreferenced large global maps -->
275 TODO: complete this section, or delete if not needed
278 <h2 id="assembler">Assembler</h2>
282 The verifier that checks for incorrect uses of <code>R15</code> when dynamic linking on amd64 has been improved.
285 <h2 id="linker">Linker</h2>
287 <p><!-- https://go.dev/issue/57302, CL 461749 -->
288 On Windows AMD64, the linker (with help from the compiler) now emits
289 SEH unwinding data by default, which improves the integration
290 of Go applications with Windows debuggers and other tools.
295 <!-- cmd/link: generate .xdata PE section -->
299 In Go 1.21 the linker (with help from the compiler) is now capable of
300 deleting dead (unreferenced) global map variables, if the number of
301 entries in the variable initializer is sufficiently large, and if the
302 initializer expressions are side-effect free.
305 TODO: complete this section, or delete if not needed
308 <h2 id="library">Core library</h2>
310 <h3 id="slog">New log/slog package</h3>
312 <p><!-- https://go.dev/issue/59060, https://go.dev/issue/59141, https://go.dev/issue/59204, https://go.dev/issue/59280,
313 https://go.dev/issue/59282, https://go.dev/issue/59339, https://go.dev/issue/59345,
314 CL 477295, CL 484096, CL 486376, CL 486415, CL 487855 -->
315 The new <a href="/pkg/log/slog">log/slog</a> package provides structured logging with levels.
316 Structured logging emits key-value pairs
317 to enable fast, accurate processing of large amounts of log data.
318 The package supports integration with popular log analysis tools and services.
321 <h3 id="slices">New slices package</h3>
323 <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 -->
324 The new <a href="/pkg/slices">slices</a> package provides many common
325 operations on slices, using generic functions that work with slices
329 <h3 id="maps">New maps package</h3>
331 <p><!-- https://go.dev/issue/57436, CL 464343 -->
332 The new <a href="/pkg/maps/">maps</a> package provides several
333 common operations on maps, using generic functions that work with
334 maps of any key or element type.
337 <h3 id="minor_library_changes">Minor changes to the library</h3>
340 As always, there are various minor changes and updates to the library,
341 made with the Go 1 <a href="/doc/go1compat">promise of compatibility</a>
343 There are also various performance improvements, not enumerated here.
347 TODO: complete this section
350 <dl id="archive/tar"><dt><a href="/pkg/archive/tar/">archive/tar</a></dt>
352 <p><!-- https://go.dev/issue/54451, CL 491175 -->
353 The implementation of the
354 <a href="/pkg/io/fs/#FileInfo"><code>io/fs.FileInfo</code></a>
355 interface returned by
356 <a href="/pkg/archive/tar/#Header.FileInfo"><code>Header.FileInfo</code></a>
357 now implements a <code>String</code> method that calls
358 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
361 </dl><!-- archive/tar -->
363 <dl id="archive/zip"><dt><a href="/pkg/archive/zip/">archive/zip</a></dt>
365 <p><!-- https://go.dev/issue/54451, CL 491175 -->
366 The implementation of the
367 <a href="/pkg/io/fs/#FileInfo"><code>io/fs.FileInfo</code></a>
368 interface returned by
369 <a href="/pkg/archive/zip/#FileHeader.FileInfo"><code>FileHeader.FileInfo</code></a>
370 now implements a <code>String</code> method that calls
371 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
374 <p><!-- https://go.dev/issue/54451, CL 491175 -->
375 The implementation of the
376 <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
377 interface returned by the
378 <a href="/pkg/io/fs/#ReadDirFile.ReadDir"><code>io/fs.ReadDirFile.ReadDir</code></a>
380 <a href="/pkg/io/fs/#File"><code>io/fs.File</code></a>
382 <a href="/pkg/archive/zip/#Reader.Open"><code>Reader.Open</code></a>
383 now implements a <code>String</code> method that calls
384 <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
387 </dl><!-- archive/zip -->
389 <dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt>
391 <p><!-- https://go.dev/issue/53685, CL 474635 -->
392 The <a href="/pkg/bytes/#Buffer"><code>Buffer</code></a> type
394 <a href="/pkg/bytes/#Buffer.Available"><code>Available</code></a>
395 and <a href="/pkg/bytes/#AvailableBuffer"><code>AvailableBuffer</code></a>.
396 These may be used along with the
397 <a href="/pkg/bytes/#Buffer.Write"><code>Write</code></a>
398 method to append directly to the <code>Buffer</code>.
403 <dl id="context"><dt><a href="/pkg/context/">context</a></dt>
405 <p><!-- https://go.dev/issue/40221, CL 479918 -->
406 The new <a href="/pkg/context/#WithoutCancel"><code>WithoutCancel</code></a>
407 function returns a copy of a context that is not canceled when the original
410 <p><!-- https://go.dev/issue/56661, CL 449318 -->
411 The new <a href="/pkg/context/#WithDeadlineCause"><code>WithDeadlineCause</code></a>
412 and <a href="/pkg/context/#WithTimeoutCause"><code>WithTimeoutCause</code></a>
413 functions provide a way to set a context cancellation cause when a deadline or
414 timer expires. The cause may be retrieved with the
415 <a href="/pkg/context/#Cause"><code>Cause</code></a> function.
417 <p><!-- https://go.dev/issue/57928, CL 482695 -->
418 The new <a href="/pkg/context/#AfterFunc"><code>AfterFunc</code></a>
419 function registers a function to run after a context has been cancelled.
424 <dl id="crypto/elliptic"><dt><a href="/pkg/crypto/elliptic/">crypto/elliptic</a></dt>
426 <p><!-- CL 459977 -->
427 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
430 </dl><!-- crypto/elliptic -->
432 <dl id="crypto/rsa"><dt><a href="/pkg/crypto/rsa/">crypto/rsa</a></dt>
434 <p><!-- https://go.dev/issue/56921 -->
435 TODO: <a href="https://go.dev/issue/56921">https://go.dev/issue/56921</a>: deprecate GenerateMultiPrimeKey and PrecomputedValues.CRTValues
438 <p><!-- CL 459976 -->
439 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
442 </dl><!-- crypto/rsa -->
444 <dl id="crypto/sha1"><dt><a href="/pkg/crypto/sha1/">crypto/sha1</a></dt>
446 <p><!-- CL 483815 -->
447 TODO: <a href="https://go.dev/cl/483815">https://go.dev/cl/483815</a>: crypto/sha1: add WriteString and WriteByte method
450 </dl><!-- crypto/sha1 -->
452 <dl id="crypto/sha256"><dt><a href="/pkg/crypto/sha256/">crypto/sha256</a></dt>
454 <p><!-- https://go.dev/issue/50543 -->
455 TODO: <a href="https://go.dev/issue/50543">https://go.dev/issue/50543</a>: add native SHA256 instruction implementation for AMD64
458 <p><!-- CL 408795 -->
459 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.
462 <p><!-- CL 481478 -->
463 TODO: <a href="https://go.dev/cl/481478">https://go.dev/cl/481478</a>: crypto/sha256: add WriteString and WriteByte method
466 </dl><!-- crypto/sha256 -->
468 <dl id="crypto/sha512"><dt><a href="/pkg/crypto/sha512/">crypto/sha512</a></dt>
470 <p><!-- CL 483816 -->
471 TODO: <a href="https://go.dev/cl/483816">https://go.dev/cl/483816</a>: crypto/sha512: add WriteString and WriteByte method
474 </dl><!-- crypto/sha512 -->
476 <dl id="crypto/x509"><dt><a href="/pkg/crypto/x509/">crypto/x509</a></dt>
478 <p><!-- https://go.dev/issue/53573 -->
479 TODO: <a href="https://go.dev/issue/53573">https://go.dev/issue/53573</a>: surface ReasonCode inside x509.RevocationList entries
482 <p><!-- CL 468875 -->
483 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
486 </dl><!-- crypto/x509 -->
488 <dl id="debug/elf"><dt><a href="/pkg/debug/elf/">debug/elf</a></dt>
490 <p><!-- https://go.dev/issue/56892, CL 452617 -->
492 <a href="https:/pkg/debug/elf/#File.DynValue"><code>File.DynValue</code></a>
493 method may be used to retrieve the numeric values listed with a
497 <p><!-- https://go.dev/issue/56887, CL 452496 -->
498 The constant flags permitted in a <code>DT_FLAGS_1</code>
499 dynamic tag are now defined with type
500 <a href="/pkg/debug/elf/#DynFlag1"><code>DynFlag1</code></a>. These
501 tags have names starting with <code>DF_1</code>.
504 <p><!-- CL 473256 -->
505 The package now defines the constant
506 <a href="/pkg/debug/elf/#COMPRESS_ZSTD"><code>COMPRESS_ZSTD</code></a>.
509 </dl><!-- debug/elf -->
511 <dl id="debug/pe"><dt><a href="/pkg/debug/pe/">debug/pe</a></dt>
513 <p><!-- CL 488475 -->
514 Attempts to read from a section containing uninitialized data
516 <a href="/pkg/debug/pe/#Section.Data"><code>Section.Data</code></a>
517 or the reader returned by <a href="/pkg/debug/pe/#Section.Open"><code>Section.Open</code></a>
521 </dl><!-- debug/pe -->
523 <dl id="embed"><dt><a href="/pkg/embed/">embed</a></dt>
525 <p><!-- https://go.dev/issue/57803, CL 483235 -->
526 The <a href="/pkg/io/fs/#File"><code>io/fs.File</code></a>
528 <a href="/pkg/embed/#FS.Open"><code>FS.Open</code></a> now
529 has a <code>ReadAt</code> method that
530 implements <a href="/pkg/io/#ReaderAt"><code>io.ReaderAt</code></a>.
533 <p><!-- https://go.dev/issue/54451, CL 491175 -->
534 Calling <code><a href="/pkg/embed/FS.Open">FS.Open</a>.<a href="/pkg/io/fs/#File.Stat">Stat</a></code>
535 will return a type that now implements a <code>String</code>
537 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
542 <dl id="errors"><dt><a href="/pkg/errors/">errors</a></dt>
544 <p><!-- https://go.dev/issue/41198, CL 473935 -->
546 <a href="/pkg/errors/#ErrUnsupported"><code>ErrUnsupported</code></a>
547 error provides a standardized way to indicate that a requested
548 operation may not be performed because it is unsupported.
549 For example, a call to
550 <a href="/pkg/os/#Link"><code>os.Link</code></a> when using a
551 file system that does not support hard links.
556 <dl id="flag"><dt><a href="/pkg/flag/">flag</a></dt>
558 <p><!-- https://go.dev/issue/53747, CL 476015 -->
559 The new <a href="/pkg/flag/#BoolFunc"><code>BoolFunc</code></a>
561 <a href="/pkg/flag/#FlagSet.BoolFunc"><code>FlagSet.BoolFunc</code></a>
562 method define a flag that does not require an argument and calls
563 a function when the flag is used. This is similar to
564 <a href="/pkg/flag/#Func"><code>Func</code></a> but for a
568 <p><!-- CL 480215 -->
569 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.
571 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.
576 <dl id="go/ast"><dt><a href="/pkg/go/ast/">go/ast</a></dt>
578 <p><!-- https://go.dev/issue/28089, CL 487935 -->
579 The new <a href="/pkg/go/ast/#IsGenerated"><code>IsGenerated</code></a> predicate
580 reports whether a file syntax tree contains the
581 <a href="https://go.dev/s/generatedcode">special comment</a>
582 that conventionally indicates that the file was generated by a tool.
587 <p><!-- https://go.dev/issue/59033, CL 476276 -->
589 <a href="/pkg/go/ast/#File.GoVersion"><code>File.GoVersion</code></a>
590 field records the minimum Go version required by
591 any <code>//go:build</code> or <code>// +build</code>
597 <dl id="go/build"><dt><a href="/pkg/go/build/">go/build</a></dt>
599 <p><!-- https://go.dev/issue/56986, CL 453603 -->
600 The package now parses build directives (comments that start
601 with <code>//go:</code>) in file headers (before
602 the <code>package</code> declaration). These directives are
604 <a href="/pkg/go/build/Package"><code>Package</code></a> fields
605 <a href="/pkg/go/build/Package.Directives"><code>Directives</code></a>,
606 <a href="/pkg/go/build/Package.TestDirectives"><code>TestDirectives</code></a>,
608 <a href="/pkg/go/build/Package.XTestDirectives"><code>XTestDirectives</code></a>.
611 </dl><!-- go/build -->
613 <dl id="go/build/constraint"><dt><a href="/pkg/go/build/constraint/">go/build/constraint</a></dt>
615 <p><!-- https://go.dev/issue/59033, CL 476275 -->
617 <a href="/pkg/go/build/constraint/#GoVersion"><code>GoVersion</code></a>
618 function returns the minimum Go version implied by a build
622 </dl><!-- go/build/constraint -->
624 <dl id="go/token"><dt><a href="/pkg/go/token/">go/token</a></dt>
626 <p><!-- https://go.dev/issue/57708, CL 464515 -->
627 The new <a href="/pkg/go/token/#File.Lines"><code>File.Lines</code></a> method
628 returns the file's line-number table in the same form as accepted by
629 <code>File.SetLines</code>.
632 </dl><!-- go/token -->
634 <dl id="hash/maphash"><dt><a href="/pkg/hash/maphash/">hash/maphash</a></dt>
636 <p><!-- https://go.dev/issue/47342, CL 468795 -->
637 The <code>hash/maphash</code> package now has a pure Go implementation, selectable with the <code>purego</code> build tag.
640 </dl><!-- hash/maphash -->
642 <dl id="io/fs"><dt><a href="/pkg/io/fs/">io/fs</a></dt>
644 <p><!-- https://go.dev/issue/54451, CL 489555 -->
646 <a href="/pkg/io/fs/#FormatFileInfo"><code>FormatFileInfo</code></a>
647 function returns a formatted version of a
648 <a href="/pkg/io/fs/#FileInfo"><code>FileInfo</code></a>.
650 <a href="/pkg/io/fs/#FormatDirEntry"><code>FormatDirEntry</code></a>
651 function returns a formatted version of a
652 <a href="/pkg/io/fs/#FileInfo"><code>DirEntry</code></a>.
653 The implementation of
654 <a href="/pkg/io/fs/#DirEntry"><code>DirEntry</code></a>
656 <a href="/pkg/io/fs/#ReadDir"><code>ReadDir</code></a> now
657 implements a <code>String</code> method that calls
658 <a href="/pkg/io/fs/#FormatDirEntry"><code>FormatDirEntry</code></a>,
659 and the same is true for
660 the <a href="/pkg/io/fs/#DirEntry"><code>DirEntry</code></a>
662 <a href="/pkg/io/fs/#WalkDirFunc"><code>WalkDirFunc</code></a>.
667 <dl id="math"><dt><a href="/pkg/math/">math</a></dt>
669 <p><!-- https://go.dev/issue/56491 -->
670 TODO: <a href="https://go.dev/issue/56491">https://go.dev/issue/56491</a>: add Compare and Compare32
673 <p><!-- CL 459435 -->
674 TODO: <a href="https://go.dev/cl/459435">https://go.dev/cl/459435</a>: math: add Compare and Compare32; modified api/next/56491.txt
677 <p><!-- CL 467515 -->
678 TODO: <a href="https://go.dev/cl/467515">https://go.dev/cl/467515</a>: math: add Compare and Compare32; modified api/next/56491.txt
683 <dl id="math/big"><dt><a href="/pkg/math/big/">math/big</a></dt>
685 <p><!-- https://go.dev/issue/56984, CL 453115 -->
686 The new <a href="/pkg/math/big/#Int.ToFloat64"><code>Int.ToFloat64</code></a>
687 method returns the nearest floating-point value to a
688 multi-precision integer, along with an indication of any
689 rounding that occurred.
692 </dl><!-- math/big -->
694 <dl id="net"><dt><a href="/pkg/net/">net</a></dt>
697 <!-- https://go.dev/issue/59166, https://go.dev/issue/56539 -->
698 <!-- CL 471136, CL 471137, CL 471140 -->
699 On Linux, the <a href="/pkg/net/">net</a> package can now use
700 Multipath TCP when the kernel supports it. It is not used by
701 default. To use Multipath TCP when available on a client, call
703 <a href="/pkg/net/#Dialer.SetMultipathTCP"><code>Dialer.SetMultipathTCP</code></a>
704 method before calling the
705 <a href="/pkg/net/#Dialer.Dial"><code>Dialer.Dial</code></a> or
706 <a href="/pkg/net/#Dialer.DialContext"><code>Dialer.DialContext</code></a>
707 methods. To use Multipath TCP when available on a server, call
709 <a href="/pkg/net/#ListenConfig.SetMultipathTCP"><code>ListenConfig.SetMultipathTCP</code></a>
710 method before calling the
711 <a href="/pkg/net/#ListenConfig.Listen"><code>ListenConfig.Listen</code></a>
712 method. Specify the network as <code>"tcp"</code> or
713 <code>"tcp4"</code> or <code>"tcp6"</code> as usual. If
714 Multipath TCP is not supported by the kernel or the remote host,
715 the connection will silently fall back to TCP. To test whether a
716 particular connection is using Multipath TCP, use the
717 <a href="/pkg/net/#TCPConn.MultipathTCP"><code>TCPConn.MultipathTCP</code></a>
721 In a future Go release we may enable Multipath TCP by default on
722 systems that support it.
727 <dl id="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt>
729 <p><!-- https://go.dev/issue/44855, CL 382117 -->
730 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.
733 <p><!-- CL 472636 -->
734 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
737 <p><!-- CL 494122 -->
738 The <a href="/pkg/net/http/">net/http</a> package now supports
739 <a href="/pkg/errors/#ErrUnsupported"><code>errors.ErrUnsupported</code></a>,
740 in that the expression
741 <code>errors.Is(http.ErrNotSupported, errors.ErrUnsupported)</code>
745 </dl><!-- net/http -->
747 <dl id="os"><dt><a href="/pkg/os/">os</a></dt>
749 <p><!-- https://go.dev/issue/32558, CL 219638 -->
750 Programs may now pass an empty <code>time.Time</code> value to
751 the <a href="/pkg/os/#Chtimes"><code>Chtimes</code></a> function
752 to leave either the access time or the modification time unchanged.
755 <p><!-- CL 480135 -->
757 <a href="/pkg/os#File.Chdir"><code>File.Chdir</code></a> method
758 now changes the current directory to the file, rather than
759 always returning an error.
762 <p><!-- CL 477215 -->
764 <a href="/pkg/os/#Truncate"><code>Truncate</code></a> on a
765 non-existent file used to create an empty file. It now returns
766 an error indicating that the file does not exist.
769 <p><!-- CL 493036 -->
770 On Windows the os package now supports working with files whose
771 names, stored as UTF-16, can't be represented as valid UTF-8.
774 <p><!-- https://go.dev/issue/54451, CL 491175 -->
775 The implementation of the
776 <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
777 interface returned by the
778 <a href="/pkg/os/#ReadDir"><code>ReadDir</code></a> function and
779 the <a href="/pkg/os/#File.ReadDir"><code>File.ReadDir</code>
780 method now implements a <code>String</code> method that calls
781 <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
786 <dl id="path/filepath"><dt><a href="/pkg/path/filepath/">path/filepath</a></dt>
789 The implementation of the
790 <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
791 interface passed to the function argument of
792 <a href="/pkg/path/filepath/#WalkDir"><code>WalkDir</code></a>
793 now implements a <code>String</code> method that calls
794 <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
797 </dl><!-- path/filepath -->
799 <!-- CL 459455 reverted -->
801 <dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
803 <p><!-- CL 408826, CL 413474 -->
804 In Go 1.21, <a href="/pkg/reflect/#ValueOf"><code>ValueOf</code></a>
805 no longer forces its argument to be allocated on the heap, allowing
806 a <code>Value</code>'s content to be allocated on the stack. Most
807 operations on a <code>Value</code> also allow the underlying value
808 to be stack allocated.
811 <p><!-- https://go.dev/issue/55002 -->
812 The new <a href="/pkg/reflect/#Value"><code>Value</code></a>
813 method <a href="/pkg/reflect/#Value.Clear"><code>Value.Clear</code></a>
814 clears the contents of a map or zeros the contents of a slice.
815 This corresponds to the new <code>clear</code> built-in
816 <a href="#language">added to the language</a>.
819 <p><!-- https://go.dev/issue/56906, CL 452762 -->
820 The <a href="/pkg/reflect/#SliceHeader"><code>SliceHeader</code></a>
821 and <a href="/pkg/reflect/#StringHeader"><code>StringHeader</code></a>
822 types are now deprecated. In new code
823 prefer <a href="/pkg/unsafe/#Slice"><code>unsafe.Slice</code></a>,
824 <a href="/pkg/unsafe/#SliceData"><code>unsafe.SliceData</code></a>,
825 <a href="/pkg/unsafe/#String"><code>unsafe.String</code></a>,
826 or <a href="/pkg/unsafe/#StringData"><code>unsafe.StringData</code></a>.
829 </dl><!-- reflect -->
831 <dl id="regexp"><dt><a href="/pkg/regexp/">regexp</a></dt>
833 <p><!-- https://go.dev/issue/46159, CL 479401 -->
834 <a href="/pkg/regexp#Regexp"><code>Regexp</code></a> now defines
835 <a href="/pkg/regexp#Regexp.MarshalText"><code>MarshalText</code></a>
836 and <a href="/pkg/regexp#Regexp.UnmarshalText"><code>UnmarshalText</code></a>
837 methods. These implement
838 <a href="/pkg/encoding#TextMarshaler"><code>encoding.TextMarshaler</code></a>
840 <a href="/pkg/encoding#TextUnmarshaler"><code>encoding.TextUnmarshaler</code></a>
841 and will be used by packages such as
842 <a href="/pkg/encoding/json">encoding/json</a>.
847 <dl id="runtime"><dt><a href="/pkg/runtime/">runtime</a></dt>
849 <p><!-- https://go.dev/issue/38651 -->
850 TODO: <a href="https://go.dev/issue/38651">https://go.dev/issue/38651</a>: add 'created by goroutine number' to stack traces
853 <p><!-- https://go.dev/issue/57441, CL 474915 -->
854 Crashing Go applications can now opt-in to Windows Error Reporting (WER) by setting the environment variable
855 <code>GOTRACEBACK=wer</code> or calling <a href="/pkg/runtime/debug/#SetTraceback"><code>debug.SetTraceback("wer")</code></a>
856 before the crash. Other than enabling WER, the runtime will behave as with <code>GOTRACEBACK=crash</code>.
857 On non-Windows systems, <code>GOTRACEBACK=wer</code> is ignored.
860 <p><!-- CL 447778 -->
861 <code>GODEBUG=cgocheck=2</code>, a thorough checker of cgo pointer passing rules,
862 is no longer available as a <a href="/pkg/runtime#hdr-Environment_Variables">debug option</a>.
863 Instead, it is available as an experiment using <code>GOEXPERIMENT=cgocheck2</code>.
864 In particular this means that this mode has to be selected at build time instead of startup time.
866 <code>GODEBUG=cgocheck=1</code> is still available (and is still the default).
869 <p><!-- https://go.dev/issue/46787 -->
870 A new type <code>Pinner</code> has been added to the runtime
871 package. <code>Pinner</code>s may be used to "pin" Go memory
872 such that it may be used more freely by non-Go code. For instance,
873 passing Go values that reference pinned Go memory to C code is
874 now allowed. Previously, passing any such nested reference was
876 <a href="https://pkg.go.dev/cmd/cgo#hdr-Passing_pointers">cgo pointer passing rules.</a>
878 See <a href="/pkg/runtime#Pinner">the docs</a> for more details.
881 </dl><!-- runtime -->
883 <dl id="runtime/trace"><dt><a href="/pkg/runtime/trace/">runtime/trace</a></dt>
885 <p><!-- https://go.dev/issue/16638 -->
886 Collecting traces on amd64 and arm64 now incurs a substantially
887 smaller CPU cost: up to a 10x improvement over the previous release.
890 <p><!-- CL 494495 -->
891 Traces now contain explicit stop-the-world events for every reason
892 the Go runtime might stop-the-world, not just garbage collection.
895 </dl><!-- runtime/trace -->
897 <dl id="runtime/metrics"><dt><a href="/pkg/runtime/metrics/">runtime/metrics</a></dt>
899 <p><!-- https://go.dev/issue/56857 -->
900 A few previously-internal GC metrics, such as live heap size, are
903 <code>GOGC</code> and <code>GOMEMLIMIT</code> are also now
904 available as metrics.
907 </dl><!-- runtime/metrics -->
909 <dl id="sync"><dt><a href="/pkg/sync/">sync</a></dt>
911 <p><!-- https://go.dev/issue/56102, CL 451356 -->
912 The new <a href="/pkg/sync/#OnceFunc"><code>OnceFunc</code></a>,
913 <a href="/pkg/sync/#OnceValue"><code>OnceValue</code></a>, and
914 <a href="/pkg/sync/#OnceValues"><code>OnceValues</code></a>
915 functions capture a common use of <a href="/pkg/sync/#Once">Once</a> to
916 lazily initialize a value on first use.
921 <dl id="syscall"><dt><a href="/pkg/syscall/">syscall</a></dt>
923 <p><!-- CL 480135 -->
925 <a href="/pkg/syscall#Fchdir"><code>Fchdir</code></a> function
926 now changes the current directory to its argument, rather than
927 always returning an error.
930 <p><!-- https://go.dev/issue/46259, CL 458335 -->
932 <a href="/pkg/syscall#SysProcAttr"><code>SysProcAttr</code></a>
933 has a new field <code>Jail</code> that may be used to put the
934 newly created process in a jailed environment.
937 <p><!-- CL 493036 -->
938 On Windows the syscall package now supports working with files whose
939 names, stored as UTF-16, can't be represented as valid UTF-8.
940 The <a href="/pkg/syscall#UTF16ToString"><code>UTF16ToString</code></a>
941 and <a href="/pkg/syscall#UTF16FromString"><code>UTF16FromString</code></a>
942 functions now convert between UTF-16 data and
943 <a href="https://simonsapin.github.io/wtf-8/">WTF-8</a> strings.
944 This is backward compatible as WTF-8 is a superset of the UTF-8
945 format that was used in earlier releases.
948 <p><!-- CL 476578, CL 476875, CL 476916 -->
949 Several error values match the new
950 <a href="/pkg/errors/#ErrUnsupported"><code>errors.ErrUnsupported</code></a>,
951 such that <code>errors.Is(err, errors.ErrUnsupported)</code>
954 <li><code>ENOSYS</code></li>
955 <li><code>ENOTSUP</code></li>
956 <li><code>EOPNOTSUPP</code></li>
957 <li><code>EPLAN9</code> (Plan 9 only)</li>
958 <li><code>ERROR_CALL_NOT_IMPLEMENTED</code> (Windows only)</li>
959 <li><code>ERROR_NOT_SUPPORTED</code> (Windows only)</li>
960 <li><code>EWINDOWS</code> (Windows only)</li>
964 </dl><!-- syscall -->
966 <dl id="testing"><dt><a href="/pkg/testing/">testing</a></dt>
968 <p><!-- https://go.dev/issue/37708, CL 463837 -->
969 The new <code>-test.fullpath</code> option will print full path
970 names in test log messages, rather than just base names.
973 <p><!-- https://go.dev/issue/52600, CL 475496 -->
974 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>.
977 </dl><!-- testing -->
979 <dl id="testing/fstest"><dt><a href="/pkg/testing/fstest/">testing/fstest</a></dt>
981 <p><!-- https://go.dev/issue/54451, CL 491175 -->
982 Calling <code><a href="/pkg/testing/fstest/MapFS.Open">Open</a>.<a href="/pkg/io/fs/#File.Stat">Stat</a></code>
983 will return a type that now implements a <code>String</code>
985 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
988 </dl><!-- testing/fstest -->
990 <dl id="testing/slogtest"><dt><a href="/pkg/testing/slogtest/">testing/slogtest</a></dt>
992 <p><!-- CL 487895 -->
993 TODO: <a href="https://go.dev/cl/487895">https://go.dev/cl/487895</a>: testing/slogtest: tests for slog handlers; modified api/next/56345.txt
996 </dl><!-- testing/slogtest -->
998 <dl id="unicode"><dt><a href="/pkg/unicode/">unicode</a></dt>
1000 <p><!-- CL 456837 -->
1001 The <a href="/pkg/unicode/"><code>unicode</code></a> package and
1002 associated support throughout the system has been upgraded to
1003 <a href="https://www.unicode.org/versions/Unicode15.0.0/">Unicode 15.0.0</a>.
1005 </dl><!-- unicode -->
1007 <!-- proposals for x repos that don't need to be mentioned here but
1008 are picked up by the relnote tool. -->
1009 <!-- https://go.dev/issue/54232 -->
1010 <!-- https://go.dev/issue/57906 -->
1011 <!-- https://go.dev/issue/58668 -->