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>
142 <h3 id="darwin">Darwin</h3>
144 <p><!-- go.dev/issue/57125 -->
145 As <a href="go1.20#darwin">announced</a> in the Go 1.20 release notes,
146 Go 1.21 requires macOS 10.15 Catalina or later;
147 support for previous versions has been discontinued.
150 <h3 id="windows">Windows</h3>
152 <p><!-- go.dev/issue/57003, go.dev/issue/57004 -->
153 As <a href="go1.20#windows">announced</a> in the Go 1.20 release notes,
154 Go 1.21 requires at least Windows 10 or Windows Server 2016;
155 support for previous versions has been discontinued.
160 <!-- cmd/dist: default to GOARM=7 on all non-arm systems -->
163 <h3 id="wasm">WebAssembly</h3>
165 <p><!-- https://go.dev/issue/38248, https://go.dev/issue/59149, CL 489255 -->
166 The new <code>go:wasmimport</code> directive can now be used in Go programs
167 to import functions from the WebAssembly host.
170 <!-- https://go.dev/issue/56100 -->
172 The Go scheduler now interacts much more efficiently with the
173 JavaScript event loop, especially in applications that block
174 frequently on asynchronous events.
178 <h3 id="wasip1">WebAssembly System Interface</h3>
180 <p><!-- https://go.dev/issue/58141 -->
181 Go 1.21 adds an experimental port to the <a href="https://wasi.dev/">
182 WebAssembly System Interface (WASI)</a>, Preview 1
183 (<code>GOOS=wasip1</code>, <code>GOARCH=wasm</code>).
187 As a result of the addition of the new <code>GOOS</code> value
188 "<code>wasip1</code>", Go files named <code>*_wasip1.go</code>
189 will now be <a href="/pkg/go/build/#hdr-Build_Constraints">ignored
190 by Go tools</a> except when that <code>GOOS</code> value is being
192 If you have existing filenames matching that pattern, you will
196 <h2 id="tools">Tools</h2>
198 <!-- https://go.dev/issue/15513 -->
200 <!-- support compiling all tests without running -->
203 <h3 id="go-command">Go command</h3>
205 <p><!-- https://go.dev/issue/58099, CL 474236 -->
206 The <code>-pgo</code> build flag now defaults to <code>-pgo=auto</code>,
207 and the restriction of specifying a single main package on the command
208 line is now removed. If a file named <code>default.pgo</code> is present
209 in the main package's directory, the <code>go</code> command will use
210 it to enable profile-guided optimization for building the corresponding
214 <p><!-- https://go.dev/issue/37708, CL 463837 -->
215 The new <code>go</code> <code>test</code> option
216 <code>-fullpath</code> prints full path names in test log messages,
217 rather than just base names.
222 <!-- cmd/go: make go test build multiple executables; The go test command now supports using the -c flag with multiple packages. -->
225 <h3 id="cgo">Cgo</h3>
227 <p><!-- CL 490819 -->
228 In files that <code>import "C"</code>, the Go toolchain now
229 correctly reports errors for attempts to declare Go methods on C types.
232 <h2 id="runtime-changes">Runtime</h2>
235 TODO: complete this section, or delete if not needed
238 <p><!-- https://go.dev/issue/7181 -->
239 When printing very deep stacks, the runtime now prints the first 50
240 (innermost) frames followed by the bottom 50 (outermost) frames,
241 rather than just printing the first 100 frames. This makes it easier
242 to see how deeply recursive stacks started, and is especially
243 valuable for debugging stack overflows.
246 <p><!-- https://go.dev/issue/59960 -->
247 On Linux platforms that support transparent huge pages, the Go runtime
248 now manages which parts of the heap may be backed by huge pages more
249 explicitly. This leads to better utilization of memory: small heaps
250 should see less memory used (up to 50% in pathological cases) while
251 large heaps should see fewer broken huge pages for dense parts of the
252 heap, improving CPU usage and latency by up to 1%.
255 <p><!-- https://go.dev/issue/57069, https://go.dev/issue/56966 -->
256 As a result of runtime-internal garbage collection tuning,
257 applications may see up to a 40% reduction in application tail latency
258 and a small decrease in memory use. Some applications may also observe
259 a small loss in throughput.
261 The memory use decrease should be proportional to the loss in
262 throughput, such that the previous release's throughput/memory
263 tradeoff may be recovered (with little change to latency) by
264 increasing <code>GOGC</code> and/or <code>GOMEMLIMIT</code> slightly.
267 <p><!-- https://go.dev/issue/51676 -->
268 Calls from C to Go on threads created in C require some setup to prepare for
269 Go execution. On Unix platforms, this setup is now preserved across multiple
270 calls from the same thread. This significantly reduces the overhead of
271 subsequent C to Go calls from ~1-3 microseconds per call to ~100-200
272 nanoseconds per call.
275 <h2 id="compiler">Compiler</h2>
278 Profile-guide optimization (PGO), added as a preview in Go 1.20, is now ready
279 for general use. PGO enables additional optimizations on code identified as
280 hot by profiles of production workloads. As mentioned in the
281 <a href="#go-command">Go command section</a>, PGO is enabled by default for
282 binaries that contain a <code>default.pgo</code> profile in the main
283 package directory. Performance improvements vary depending on application
284 behavior, with most programs from a representative set of Go programs seeing
285 between 2 and 7% improvement from enabling PGO. See the
286 <a href="/doc/pgo">PGO user guide</a> for detailed documentation.
289 <!-- https://go.dev/issue/59959 -->
291 PGO builds can now devirtualize some interface method calls, adding a
292 concrete call to the most common callee. This enables further optimization,
293 such as inlining the callee.
297 TODO: complete this section, or delete if not needed
300 <h2 id="assembler">Assembler</h2>
304 The verifier that checks for incorrect uses of <code>R15</code> when dynamic linking on amd64 has been improved.
307 <h2 id="linker">Linker</h2>
309 <p><!-- https://go.dev/issue/57302, CL 461749 -->
310 On Windows AMD64, the linker (with help from the compiler) now emits
311 SEH unwinding data by default, which improves the integration
312 of Go applications with Windows debuggers and other tools.
317 <!-- cmd/link: generate .xdata PE section -->
319 <!-- CL 463395, CL 461315 -->
321 In Go 1.21 the linker (with help from the compiler) is now capable of
322 deleting dead (unreferenced) global map variables, if the number of
323 entries in the variable initializer is sufficiently large, and if the
324 initializer expressions are side-effect free.
327 TODO: complete this section, or delete if not needed
330 <h2 id="library">Core library</h2>
332 <h3 id="slog">New log/slog package</h3>
334 <p><!-- https://go.dev/issue/59060, https://go.dev/issue/59141, https://go.dev/issue/59204, https://go.dev/issue/59280,
335 https://go.dev/issue/59282, https://go.dev/issue/59339, https://go.dev/issue/59345,
336 CL 477295, CL 484096, CL 486376, CL 486415, CL 487855 -->
337 The new <a href="/pkg/log/slog">log/slog</a> package provides structured logging with levels.
338 Structured logging emits key-value pairs
339 to enable fast, accurate processing of large amounts of log data.
340 The package supports integration with popular log analysis tools and services.
343 <h3 id="slogtest">New testing/slogtest package</h3>
345 <p><!-- CL 487895 -->
346 The new <a href="/pkg/testing/slogtest">testing/slogtest</a> package can help
347 to validate <a href="/pkg/log/slog#Handler">slog.Handler</a> implementations.
350 <h3 id="slices">New slices package</h3>
352 <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 -->
353 The new <a href="/pkg/slices">slices</a> package provides many common
354 operations on slices, using generic functions that work with slices
358 <h3 id="maps">New maps package</h3>
360 <p><!-- https://go.dev/issue/57436, CL 464343 -->
361 The new <a href="/pkg/maps/">maps</a> package provides several
362 common operations on maps, using generic functions that work with
363 maps of any key or element type.
366 <h3 id="minor_library_changes">Minor changes to the library</h3>
369 As always, there are various minor changes and updates to the library,
370 made with the Go 1 <a href="/doc/go1compat">promise of compatibility</a>
372 There are also various performance improvements, not enumerated here.
376 TODO: complete this section
379 <dl id="archive/tar"><dt><a href="/pkg/archive/tar/">archive/tar</a></dt>
381 <p><!-- https://go.dev/issue/54451, CL 491175 -->
382 The implementation of the
383 <a href="/pkg/io/fs/#FileInfo"><code>io/fs.FileInfo</code></a>
384 interface returned by
385 <a href="/pkg/archive/tar/#Header.FileInfo"><code>Header.FileInfo</code></a>
386 now implements a <code>String</code> method that calls
387 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
390 </dl><!-- archive/tar -->
392 <dl id="archive/zip"><dt><a href="/pkg/archive/zip/">archive/zip</a></dt>
394 <p><!-- https://go.dev/issue/54451, CL 491175 -->
395 The implementation of the
396 <a href="/pkg/io/fs/#FileInfo"><code>io/fs.FileInfo</code></a>
397 interface returned by
398 <a href="/pkg/archive/zip/#FileHeader.FileInfo"><code>FileHeader.FileInfo</code></a>
399 now implements a <code>String</code> method that calls
400 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
403 <p><!-- https://go.dev/issue/54451, CL 491175 -->
404 The implementation of the
405 <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
406 interface returned by the
407 <a href="/pkg/io/fs/#ReadDirFile.ReadDir"><code>io/fs.ReadDirFile.ReadDir</code></a>
409 <a href="/pkg/io/fs/#File"><code>io/fs.File</code></a>
411 <a href="/pkg/archive/zip/#Reader.Open"><code>Reader.Open</code></a>
412 now implements a <code>String</code> method that calls
413 <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
416 </dl><!-- archive/zip -->
418 <dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt>
420 <p><!-- https://go.dev/issue/53685, CL 474635 -->
421 The <a href="/pkg/bytes/#Buffer"><code>Buffer</code></a> type
423 <a href="/pkg/bytes/#Buffer.Available"><code>Available</code></a>
424 and <a href="/pkg/bytes/#AvailableBuffer"><code>AvailableBuffer</code></a>.
425 These may be used along with the
426 <a href="/pkg/bytes/#Buffer.Write"><code>Write</code></a>
427 method to append directly to the <code>Buffer</code>.
432 <dl id="context"><dt><a href="/pkg/context/">context</a></dt>
434 <p><!-- https://go.dev/issue/40221, CL 479918 -->
435 The new <a href="/pkg/context/#WithoutCancel"><code>WithoutCancel</code></a>
436 function returns a copy of a context that is not canceled when the original
439 <p><!-- https://go.dev/issue/56661, CL 449318 -->
440 The new <a href="/pkg/context/#WithDeadlineCause"><code>WithDeadlineCause</code></a>
441 and <a href="/pkg/context/#WithTimeoutCause"><code>WithTimeoutCause</code></a>
442 functions provide a way to set a context cancellation cause when a deadline or
443 timer expires. The cause may be retrieved with the
444 <a href="/pkg/context/#Cause"><code>Cause</code></a> function.
446 <p><!-- https://go.dev/issue/57928, CL 482695 -->
447 The new <a href="/pkg/context/#AfterFunc"><code>AfterFunc</code></a>
448 function registers a function to run after a context has been cancelled.
453 <dl id="crypto/elliptic"><dt><a href="/pkg/crypto/elliptic/">crypto/elliptic</a></dt>
455 <p><!-- CL 459977 -->
456 All of the <a href="/pkg/crypto/elliptic/#Curve"><code>Curve</code></a> methods have been deprecated, along with <a href="/pkg/crypto/elliptic/#GenerateKey"><code>GenerateKey</code></a>, <a href="/pkg/crypto/elliptic/#Marshal"><code>Marshal</code></a>, and <a href="/pkg/crypto/elliptic/#Unmarshal"><code>Unmarshal</code></a>. For ECDH operations, the new <a href="/pkg/crypto/ecdh/"><code>crypto/ecdh</code></a> package should be used instead.
459 </dl><!-- crypto/elliptic -->
461 <dl id="crypto/rsa"><dt><a href="/pkg/crypto/rsa/">crypto/rsa</a></dt>
463 <p><!-- https://go.dev/issue/56921, CL 459976 -->
464 The <a href="/pkg/crypto/rsa/#GenerateMultiPrimeKey"><code>GenerateMultiPrimeKey</code></a> function and the <a href="/pkg/crypto/rsa/#PrecomputedValues.CRTValues"><code>PrecomputedValues.CRTValues</code></a> field have been deprecated. <a href="/pkg/crypto/rsa/#PrecomputedValues.CRTValues"><code>PrecomputedValues.CRTValues</code></a> will still be populated when <a href="/pkg/crypto/rsa/#PrivateKey.Precompute"><code>PrivateKey.Precompute</code></a> is called, but the values will not be used during decryption operations.
467 </dl><!-- crypto/rsa -->
469 <dl id="crypto/sha256"><dt><a href="/pkg/crypto/sha256/">crypto/sha256</a></dt>
471 <p><!-- https://go.dev/issue/50543, CL 408795 -->
472 SHA-224 and SHA-256 operations now use native instructions when available when <code>GOOS=amd64</code>, providing a performance improvement on the order of 3-4x.
475 </dl><!-- crypto/sha256 -->
477 <dl id="crypto/x509"><dt><a href="/pkg/crypto/x509/">crypto/x509</a></dt>
479 <p><!-- https://go.dev/issue/53573, CL 468875 -->
480 <a href="/pkg/crypto/x509/#RevocationList.RevokedCertificates"><code>RevocationList.RevokedCertificates</code></a> has been deprecated and replaced with the new <a href="/pkg/crypto/x509/#RevocationList.Entries"><code>RevocationList.Entries</code></a> field, which is a slice of <a href="/pkg/crypto/x509/#RevocationListEntry"><code>RevocationListEntry</code></a>. <a href="/pkg/crypto/x509/#RevocationListEntry"><code>RevocationListEntry</code></a> contains all of the fields in <a href="/pkg/crypto/x509/#pkix.RevokedCertificate"><code>pkix.RevokedCertificate</code></a>, as well as the revocation reason code.
483 </dl><!-- crypto/x509 -->
485 <dl id="debug/elf"><dt><a href="/pkg/debug/elf/">debug/elf</a></dt>
487 <p><!-- https://go.dev/issue/56892, CL 452617 -->
489 <a href="/pkg/debug/elf/#File.DynValue"><code>File.DynValue</code></a>
490 method may be used to retrieve the numeric values listed with a
494 <p><!-- https://go.dev/issue/56887, CL 452496 -->
495 The constant flags permitted in a <code>DT_FLAGS_1</code>
496 dynamic tag are now defined with type
497 <a href="/pkg/debug/elf/#DynFlag1"><code>DynFlag1</code></a>. These
498 tags have names starting with <code>DF_1</code>.
501 <p><!-- CL 473256 -->
502 The package now defines the constant
503 <a href="/pkg/debug/elf/#COMPRESS_ZSTD"><code>COMPRESS_ZSTD</code></a>.
506 </dl><!-- debug/elf -->
508 <dl id="debug/pe"><dt><a href="/pkg/debug/pe/">debug/pe</a></dt>
510 <p><!-- CL 488475 -->
511 Attempts to read from a section containing uninitialized data
513 <a href="/pkg/debug/pe/#Section.Data"><code>Section.Data</code></a>
514 or the reader returned by <a href="/pkg/debug/pe/#Section.Open"><code>Section.Open</code></a>
518 </dl><!-- debug/pe -->
520 <dl id="embed"><dt><a href="/pkg/embed/">embed</a></dt>
522 <p><!-- https://go.dev/issue/57803, CL 483235 -->
523 The <a href="/pkg/io/fs/#File"><code>io/fs.File</code></a>
525 <a href="/pkg/embed/#FS.Open"><code>FS.Open</code></a> now
526 has a <code>ReadAt</code> method that
527 implements <a href="/pkg/io/#ReaderAt"><code>io.ReaderAt</code></a>.
530 <p><!-- https://go.dev/issue/54451, CL 491175 -->
531 Calling <code><a href="/pkg/embed/FS.Open">FS.Open</a>.<a href="/pkg/io/fs/#File.Stat">Stat</a></code>
532 will return a type that now implements a <code>String</code>
534 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
539 <dl id="errors"><dt><a href="/pkg/errors/">errors</a></dt>
541 <p><!-- https://go.dev/issue/41198, CL 473935 -->
543 <a href="/pkg/errors/#ErrUnsupported"><code>ErrUnsupported</code></a>
544 error provides a standardized way to indicate that a requested
545 operation may not be performed because it is unsupported.
546 For example, a call to
547 <a href="/pkg/os/#Link"><code>os.Link</code></a> when using a
548 file system that does not support hard links.
553 <dl id="flag"><dt><a href="/pkg/flag/">flag</a></dt>
555 <p><!-- https://go.dev/issue/53747, CL 476015 -->
556 The new <a href="/pkg/flag/#BoolFunc"><code>BoolFunc</code></a>
558 <a href="/pkg/flag/#FlagSet.BoolFunc"><code>FlagSet.BoolFunc</code></a>
559 method define a flag that does not require an argument and calls
560 a function when the flag is used. This is similar to
561 <a href="/pkg/flag/#Func"><code>Func</code></a> but for a
565 <p><!-- CL 480215 -->
567 (via <a href="/pkg/flag/#Bool"><code>Bool</code></a>,
568 <a href="/pkg/flag/#BoolVar"><code>BoolVar</code></a>,
569 <a href="/pkg/flag/#Int"><code>Int</code></a>,
570 <a href="/pkg/flag/#IntVar"><code>IntVar</code></a>, etc.)
571 will panic if <a href="/pkg/flag/#Set"><code>Set</code></a> has
572 already been called on a flag with the same name. This change is
573 intended to detect cases where <a href="#language">changes in
574 initialization order</a> cause flag operations to occur in a
575 different order than expected. In many cases the fix to this
576 problem is to introduce a explicit package dependence to
577 correctly order the definition before any
578 <a href="/pkg/flag/#Set"><code>Set</code></a> operations.
583 <dl id="go/ast"><dt><a href="/pkg/go/ast/">go/ast</a></dt>
585 <p><!-- https://go.dev/issue/28089, CL 487935 -->
586 The new <a href="/pkg/go/ast/#IsGenerated"><code>IsGenerated</code></a> predicate
587 reports whether a file syntax tree contains the
588 <a href="https://go.dev/s/generatedcode">special comment</a>
589 that conventionally indicates that the file was generated by a tool.
594 <p><!-- https://go.dev/issue/59033, CL 476276 -->
596 <a href="/pkg/go/ast/#File.GoVersion"><code>File.GoVersion</code></a>
597 field records the minimum Go version required by
598 any <code>//go:build</code> or <code>// +build</code>
604 <dl id="go/build"><dt><a href="/pkg/go/build/">go/build</a></dt>
606 <p><!-- https://go.dev/issue/56986, CL 453603 -->
607 The package now parses build directives (comments that start
608 with <code>//go:</code>) in file headers (before
609 the <code>package</code> declaration). These directives are
611 <a href="/pkg/go/build#Package"><code>Package</code></a> fields
612 <a href="/pkg/go/build#Package.Directives"><code>Directives</code></a>,
613 <a href="/pkg/go/build#Package.TestDirectives"><code>TestDirectives</code></a>,
615 <a href="/pkg/go/build#Package.XTestDirectives"><code>XTestDirectives</code></a>.
618 </dl><!-- go/build -->
620 <dl id="go/build/constraint"><dt><a href="/pkg/go/build/constraint/">go/build/constraint</a></dt>
622 <p><!-- https://go.dev/issue/59033, CL 476275 -->
624 <a href="/pkg/go/build/constraint/#GoVersion"><code>GoVersion</code></a>
625 function returns the minimum Go version implied by a build
629 </dl><!-- go/build/constraint -->
631 <dl id="go/token"><dt><a href="/pkg/go/token/">go/token</a></dt>
633 <p><!-- https://go.dev/issue/57708, CL 464515 -->
634 The new <a href="/pkg/go/token/#File.Lines"><code>File.Lines</code></a> method
635 returns the file's line-number table in the same form as accepted by
636 <code>File.SetLines</code>.
639 </dl><!-- go/token -->
641 <dl id="hash/maphash"><dt><a href="/pkg/hash/maphash/">hash/maphash</a></dt>
643 <p><!-- https://go.dev/issue/47342, CL 468795 -->
644 The <code>hash/maphash</code> package now has a pure Go implementation, selectable with the <code>purego</code> build tag.
647 </dl><!-- hash/maphash -->
649 <dl id="io/fs"><dt><a href="/pkg/io/fs/">io/fs</a></dt>
651 <p><!-- https://go.dev/issue/54451, CL 489555 -->
653 <a href="/pkg/io/fs/#FormatFileInfo"><code>FormatFileInfo</code></a>
654 function returns a formatted version of a
655 <a href="/pkg/io/fs/#FileInfo"><code>FileInfo</code></a>.
657 <a href="/pkg/io/fs/#FormatDirEntry"><code>FormatDirEntry</code></a>
658 function returns a formatted version of a
659 <a href="/pkg/io/fs/#FileInfo"><code>DirEntry</code></a>.
660 The implementation of
661 <a href="/pkg/io/fs/#DirEntry"><code>DirEntry</code></a>
663 <a href="/pkg/io/fs/#ReadDir"><code>ReadDir</code></a> now
664 implements a <code>String</code> method that calls
665 <a href="/pkg/io/fs/#FormatDirEntry"><code>FormatDirEntry</code></a>,
666 and the same is true for
667 the <a href="/pkg/io/fs/#DirEntry"><code>DirEntry</code></a>
669 <a href="/pkg/io/fs/#WalkDirFunc"><code>WalkDirFunc</code></a>.
674 <!-- https://go.dev/issue/56491 rolled back -->
675 <!-- CL 459435 reverted -->
676 <!-- CL 467515 reverted -->
678 <dl id="math/big"><dt><a href="/pkg/math/big/">math/big</a></dt>
680 <p><!-- https://go.dev/issue/56984, CL 453115 -->
681 The new <a href="/pkg/math/big/#Int.Float64"><code>Int.Float64</code></a>
682 method returns the nearest floating-point value to a
683 multi-precision integer, along with an indication of any
684 rounding that occurred.
687 </dl><!-- math/big -->
689 <dl id="net"><dt><a href="/pkg/net/">net</a></dt>
692 <!-- https://go.dev/issue/59166, https://go.dev/issue/56539 -->
693 <!-- CL 471136, CL 471137, CL 471140 -->
694 On Linux, the <a href="/pkg/net/">net</a> package can now use
695 Multipath TCP when the kernel supports it. It is not used by
696 default. To use Multipath TCP when available on a client, call
698 <a href="/pkg/net/#Dialer.SetMultipathTCP"><code>Dialer.SetMultipathTCP</code></a>
699 method before calling the
700 <a href="/pkg/net/#Dialer.Dial"><code>Dialer.Dial</code></a> or
701 <a href="/pkg/net/#Dialer.DialContext"><code>Dialer.DialContext</code></a>
702 methods. To use Multipath TCP when available on a server, call
704 <a href="/pkg/net/#ListenConfig.SetMultipathTCP"><code>ListenConfig.SetMultipathTCP</code></a>
705 method before calling the
706 <a href="/pkg/net/#ListenConfig.Listen"><code>ListenConfig.Listen</code></a>
707 method. Specify the network as <code>"tcp"</code> or
708 <code>"tcp4"</code> or <code>"tcp6"</code> as usual. If
709 Multipath TCP is not supported by the kernel or the remote host,
710 the connection will silently fall back to TCP. To test whether a
711 particular connection is using Multipath TCP, use the
712 <a href="/pkg/net/#TCPConn.MultipathTCP"><code>TCPConn.MultipathTCP</code></a>
716 In a future Go release we may enable Multipath TCP by default on
717 systems that support it.
722 <dl id="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt>
724 <p><!-- https://go.dev/issue/44855, CL 382117 -->
725 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.
728 <p><!-- CL 472636 -->
729 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
732 <p><!-- CL 494122 -->
733 The <a href="/pkg/net/http/">net/http</a> package now supports
734 <a href="/pkg/errors/#ErrUnsupported"><code>errors.ErrUnsupported</code></a>,
735 in that the expression
736 <code>errors.Is(http.ErrNotSupported, errors.ErrUnsupported)</code>
740 </dl><!-- net/http -->
742 <dl id="os"><dt><a href="/pkg/os/">os</a></dt>
744 <p><!-- https://go.dev/issue/32558, CL 219638 -->
745 Programs may now pass an empty <code>time.Time</code> value to
746 the <a href="/pkg/os/#Chtimes"><code>Chtimes</code></a> function
747 to leave either the access time or the modification time unchanged.
750 <p><!-- CL 480135 -->
752 <a href="/pkg/os#File.Chdir"><code>File.Chdir</code></a> method
753 now changes the current directory to the file, rather than
754 always returning an error.
757 <p><!-- CL 477215 -->
759 <a href="/pkg/os/#Truncate"><code>Truncate</code></a> on a
760 non-existent file used to create an empty file. It now returns
761 an error indicating that the file does not exist.
764 <p><!-- https://go.dev/issue/56899, CL 463219 -->
766 <a href="/pkg/os/#TempDir"><code>TempDir</code></a> now uses
767 GetTempPath2W when available, instead of GetTempPathW. The
768 new behavior is a security hardening measure that prevents
769 temporary files created by processes running as SYSTEM to
770 be accessed by non-SYSTEM processes.
773 <p><!-- CL 493036 -->
774 On Windows the os package now supports working with files whose
775 names, stored as UTF-16, can't be represented as valid UTF-8.
778 <p><!-- https://go.dev/issue/54451, CL 491175 -->
779 The implementation of the
780 <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
781 interface returned by the
782 <a href="/pkg/os/#ReadDir"><code>ReadDir</code></a> function and
783 the <a href="/pkg/os/#File.ReadDir"><code>File.ReadDir</code></a>
784 method now implements a <code>String</code> method that calls
785 <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
788 <p><!-- https://go.dev/issue/53761, CL 416775, CL 498015-->
789 The implementation of the
790 <a href="/pkg/io/fs/#FS"><code>io/fs.FS</code></a> interface returned by
791 the <a href="/pkg/os/#DirFS"><code>DirFS</code></a> function now implements
792 the <a href="/pkg/io/fs/#ReadFileFS"><code>io/fs.ReadFileFS</code></a> and
793 the <a href="/pkg/io/fs/#ReadDirFS"><code>io/fs.ReadDirFS</code></a>
799 <dl id="path/filepath"><dt><a href="/pkg/path/filepath/">path/filepath</a></dt>
802 The implementation of the
803 <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
804 interface passed to the function argument of
805 <a href="/pkg/path/filepath/#WalkDir"><code>WalkDir</code></a>
806 now implements a <code>String</code> method that calls
807 <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
810 </dl><!-- path/filepath -->
812 <!-- CL 459455 reverted -->
814 <dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
816 <p><!-- CL 408826, CL 413474 -->
817 In Go 1.21, <a href="/pkg/reflect/#ValueOf"><code>ValueOf</code></a>
818 no longer forces its argument to be allocated on the heap, allowing
819 a <code>Value</code>'s content to be allocated on the stack. Most
820 operations on a <code>Value</code> also allow the underlying value
821 to be stack allocated.
824 <p><!-- https://go.dev/issue/55002 -->
825 The new <a href="/pkg/reflect/#Value"><code>Value</code></a>
826 method <a href="/pkg/reflect/#Value.Clear"><code>Value.Clear</code></a>
827 clears the contents of a map or zeros the contents of a slice.
828 This corresponds to the new <code>clear</code> built-in
829 <a href="#language">added to the language</a>.
832 <p><!-- https://go.dev/issue/56906, CL 452762 -->
833 The <a href="/pkg/reflect/#SliceHeader"><code>SliceHeader</code></a>
834 and <a href="/pkg/reflect/#StringHeader"><code>StringHeader</code></a>
835 types are now deprecated. In new code
836 prefer <a href="/pkg/unsafe/#Slice"><code>unsafe.Slice</code></a>,
837 <a href="/pkg/unsafe/#SliceData"><code>unsafe.SliceData</code></a>,
838 <a href="/pkg/unsafe/#String"><code>unsafe.String</code></a>,
839 or <a href="/pkg/unsafe/#StringData"><code>unsafe.StringData</code></a>.
842 </dl><!-- reflect -->
844 <dl id="regexp"><dt><a href="/pkg/regexp/">regexp</a></dt>
846 <p><!-- https://go.dev/issue/46159, CL 479401 -->
847 <a href="/pkg/regexp#Regexp"><code>Regexp</code></a> now defines
848 <a href="/pkg/regexp#Regexp.MarshalText"><code>MarshalText</code></a>
849 and <a href="/pkg/regexp#Regexp.UnmarshalText"><code>UnmarshalText</code></a>
850 methods. These implement
851 <a href="/pkg/encoding#TextMarshaler"><code>encoding.TextMarshaler</code></a>
853 <a href="/pkg/encoding#TextUnmarshaler"><code>encoding.TextUnmarshaler</code></a>
854 and will be used by packages such as
855 <a href="/pkg/encoding/json">encoding/json</a>.
860 <dl id="runtime"><dt><a href="/pkg/runtime/">runtime</a></dt>
862 <p><!-- https://go.dev/issue/38651 -->
863 TODO: <a href="https://go.dev/issue/38651">https://go.dev/issue/38651</a>: add 'created by goroutine number' to stack traces
866 <p><!-- https://go.dev/issue/57441, CL 474915 -->
867 Crashing Go applications can now opt-in to Windows Error Reporting (WER) by setting the environment variable
868 <code>GOTRACEBACK=wer</code> or calling <a href="/pkg/runtime/debug/#SetTraceback"><code>debug.SetTraceback("wer")</code></a>
869 before the crash. Other than enabling WER, the runtime will behave as with <code>GOTRACEBACK=crash</code>.
870 On non-Windows systems, <code>GOTRACEBACK=wer</code> is ignored.
873 <p><!-- CL 447778 -->
874 <code>GODEBUG=cgocheck=2</code>, a thorough checker of cgo pointer passing rules,
875 is no longer available as a <a href="/pkg/runtime#hdr-Environment_Variables">debug option</a>.
876 Instead, it is available as an experiment using <code>GOEXPERIMENT=cgocheck2</code>.
877 In particular this means that this mode has to be selected at build time instead of startup time.
879 <code>GODEBUG=cgocheck=1</code> is still available (and is still the default).
882 <p><!-- https://go.dev/issue/46787 -->
883 A new type <code>Pinner</code> has been added to the runtime
884 package. <code>Pinner</code>s may be used to "pin" Go memory
885 such that it may be used more freely by non-Go code. For instance,
886 passing Go values that reference pinned Go memory to C code is
887 now allowed. Previously, passing any such nested reference was
889 <a href="https://pkg.go.dev/cmd/cgo#hdr-Passing_pointers">cgo pointer passing rules.</a>
891 See <a href="/pkg/runtime#Pinner">the docs</a> for more details.
894 </dl><!-- runtime -->
896 <dl id="runtime/trace"><dt><a href="/pkg/runtime/trace/">runtime/trace</a></dt>
898 <p><!-- https://go.dev/issue/16638 -->
899 Collecting traces on amd64 and arm64 now incurs a substantially
900 smaller CPU cost: up to a 10x improvement over the previous release.
903 <p><!-- CL 494495 -->
904 Traces now contain explicit stop-the-world events for every reason
905 the Go runtime might stop-the-world, not just garbage collection.
908 </dl><!-- runtime/trace -->
910 <dl id="runtime/metrics"><dt><a href="/pkg/runtime/metrics/">runtime/metrics</a></dt>
912 <p><!-- https://go.dev/issue/56857 -->
913 A few previously-internal GC metrics, such as live heap size, are
916 <code>GOGC</code> and <code>GOMEMLIMIT</code> are also now
917 available as metrics.
920 </dl><!-- runtime/metrics -->
922 <dl id="sync"><dt><a href="/pkg/sync/">sync</a></dt>
924 <p><!-- https://go.dev/issue/56102, CL 451356 -->
925 The new <a href="/pkg/sync/#OnceFunc"><code>OnceFunc</code></a>,
926 <a href="/pkg/sync/#OnceValue"><code>OnceValue</code></a>, and
927 <a href="/pkg/sync/#OnceValues"><code>OnceValues</code></a>
928 functions capture a common use of <a href="/pkg/sync/#Once">Once</a> to
929 lazily initialize a value on first use.
934 <dl id="syscall"><dt><a href="/pkg/syscall/">syscall</a></dt>
936 <p><!-- CL 480135 -->
938 <a href="/pkg/syscall#Fchdir"><code>Fchdir</code></a> function
939 now changes the current directory to its argument, rather than
940 always returning an error.
943 <p><!-- https://go.dev/issue/46259, CL 458335 -->
945 <a href="/pkg/syscall#SysProcAttr"><code>SysProcAttr</code></a>
946 has a new field <code>Jail</code> that may be used to put the
947 newly created process in a jailed environment.
950 <p><!-- CL 493036 -->
951 On Windows the syscall package now supports working with files whose
952 names, stored as UTF-16, can't be represented as valid UTF-8.
953 The <a href="/pkg/syscall#UTF16ToString"><code>UTF16ToString</code></a>
954 and <a href="/pkg/syscall#UTF16FromString"><code>UTF16FromString</code></a>
955 functions now convert between UTF-16 data and
956 <a href="https://simonsapin.github.io/wtf-8/">WTF-8</a> strings.
957 This is backward compatible as WTF-8 is a superset of the UTF-8
958 format that was used in earlier releases.
961 <p><!-- CL 476578, CL 476875, CL 476916 -->
962 Several error values match the new
963 <a href="/pkg/errors/#ErrUnsupported"><code>errors.ErrUnsupported</code></a>,
964 such that <code>errors.Is(err, errors.ErrUnsupported)</code>
967 <li><code>ENOSYS</code></li>
968 <li><code>ENOTSUP</code></li>
969 <li><code>EOPNOTSUPP</code></li>
970 <li><code>EPLAN9</code> (Plan 9 only)</li>
971 <li><code>ERROR_CALL_NOT_IMPLEMENTED</code> (Windows only)</li>
972 <li><code>ERROR_NOT_SUPPORTED</code> (Windows only)</li>
973 <li><code>EWINDOWS</code> (Windows only)</li>
977 </dl><!-- syscall -->
979 <dl id="testing"><dt><a href="/pkg/testing/">testing</a></dt>
981 <p><!-- https://go.dev/issue/37708, CL 463837 -->
982 The new <code>-test.fullpath</code> option will print full path
983 names in test log messages, rather than just base names.
986 <p><!-- https://go.dev/issue/52600, CL 475496 -->
987 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>.
990 </dl><!-- testing -->
992 <dl id="testing/fstest"><dt><a href="/pkg/testing/fstest/">testing/fstest</a></dt>
994 <p><!-- https://go.dev/issue/54451, CL 491175 -->
995 Calling <code><a href="/pkg/testing/fstest/MapFS.Open">Open</a>.<a href="/pkg/io/fs/#File.Stat">Stat</a></code>
996 will return a type that now implements a <code>String</code>
998 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
1001 </dl><!-- testing/fstest -->
1003 <dl id="unicode"><dt><a href="/pkg/unicode/">unicode</a></dt>
1005 <p><!-- CL 456837 -->
1006 The <a href="/pkg/unicode/"><code>unicode</code></a> package and
1007 associated support throughout the system has been upgraded to
1008 <a href="https://www.unicode.org/versions/Unicode15.0.0/">Unicode 15.0.0</a>.
1010 </dl><!-- unicode -->
1012 <!-- proposals for x repos that don't need to be mentioned here but
1013 are picked up by the relnote tool. -->
1014 <!-- https://go.dev/issue/54232 -->
1015 <!-- https://go.dev/issue/57906 -->
1016 <!-- https://go.dev/issue/58668 -->