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.
27 The latest Go release, version 1.21, arrives six months after <a href="/doc/go1.20">Go 1.20</a>.
28 Most of its changes are in the implementation of the toolchain, runtime, and libraries.
29 As always, the release maintains the Go 1 <a href="/doc/go1compat">promise of compatibility</a>;
30 in fact, Go 1.21 <a href="#godebug">improves upon that promise</a>.
31 We expect almost all Go programs to continue to compile and run as before.
35 Go 1.21 introduces a small change to the numbering of releases.
36 In the past, we used Go 1.<i>N</i> to refer to both the overall Go language version and release family
37 as well as the first release in that family.
38 Starting in Go 1.21, the first release is now Go 1.<i>N</i>.0.
39 Today we are releasing both the Go 1.21 language and its initial implementation, the Go 1.21.0 release.
40 These notes refer to “Go 1.21”; tools like <code>go</code> <code>version</code> will report “<code>go1.21.0</code>”
41 (until you upgrade to Go 1.21.1).
42 See “<a href="/doc/toolchain#versions">Go versions</a>” in the “Go Toolchains” documentation for details
43 about the new version numbering.
46 <h2 id="language">Changes to the language</h2>
49 Go 1.21 adds three new built-ins to the language.
52 <li><!-- https://go.dev/issue/59488 -->
53 The new functions <code>min</code> and <code>max</code> compute the
54 smallest (or largest, for <code>max</code>) value of a fixed number
56 See the language spec for
57 <a href="https://tip.golang.org/ref/spec#Min_and_max">details</a>.
59 <li><!-- https://go.dev/issue/56351 -->
60 The new function <code>clear</code> deletes all elements from a
61 map or zeroes all elements of a slice.
62 See the language spec for
63 <a href="https://tip.golang.org/ref/spec#Clear">details</a>.
68 <p><!-- https://go.dev/issue/57411 -->
69 Package initialization order is now specified more precisely. The
73 Sort all packages by import path.
75 <li>Repeat until the list of packages is empty:
78 Find the first package in the list for which all imports are
82 Initialize that package and remove it from the list.
87 This may change the behavior of some programs that rely on a
88 specific initialization ordering that was not expressed by explicit
89 imports. The behavior of such programs was not well defined by the
90 spec in past releases. The new rule provides an unambiguous definition.
94 Multiple improvements that increase the power and precision of type inference have been made.
97 <li><!-- https://go.dev/issue/59338 -->
98 A (possibly partially instantiated generic) function may now be called with arguments that are
99 themselves (possibly partially instantiated) generic functions.
100 The compiler will attempt to infer the missing type arguments of the callee (as before) and,
101 for each argument that is a generic function that is not fully instantiated,
102 its missing type arguments (new).
103 Typical use cases are calls to generic functions operating on containers
104 (such as <a href="/pkg/slices#IndexFunc">slices.IndexFunc</a>) where a function argument
105 may also be generic, and where the type argument of the called function and its arguments
106 are inferred from the container type.
107 More generally, a generic function may now be used without explicit instantiation when
108 it is assigned to a variable or returned as a result value if the type arguments can
109 be inferred from the assignment.
111 <li><!-- https://go.dev/issue/60353, https://go.dev/issue/57192, https://go.dev/issue/52397, https://go.dev/issue/41176 -->
112 Type inference now also considers methods when a value is assigned to an interface:
113 type arguments for type parameters used in method signatures may be inferred from
114 the corresponding parameter types of matching methods.
116 <li><!-- https://go.dev/issue/51593 https://go.dev/issue/39661 -->
117 Similarly, since a type argument must implement all the methods of its corresponding constraint,
118 the methods of the type argument and constraint are matched which may lead to the inference of
119 additional type arguments.
121 <li><!-- https://go.dev/issue/58671 -->
122 If multiple untyped constant arguments of different kinds (such as an untyped int and
123 an untyped floating-point constant) are passed to parameters with the same (not otherwise
124 specified) type parameter type, instead of an error, now type inference determines the
125 type using the same approach as an operator with untyped constant operands.
126 This change brings the types inferred from untyped constant arguments in line with the
127 types of constant expressions.
129 <li><!-- https://go.dev/issue/59750 -->
130 Type inference is now precise when matching corresponding types in assignments:
131 component types (such as the the elements of slices, or the parameter types in function signatures)
132 must be identical (given suitable type arguments) to match, otherwise inference fails.
133 This change produces more accurate error messages:
134 where in the past type inference may have succeeded incorrectly and lead to an invalid assignment,
135 the compiler now reports an inference error if two types can't possibly match.
139 <p><!-- https://go.dev/issue/58650 -->
140 More generally, the description of
141 <a href="https://tip.golang.org/ref/spec#Type_inference">type inference</a>
142 in the language spec has been clarified.
143 Together, all these changes make type inference more powerful and inference failures less surprising.
146 <!-- https://go.dev/issue/57969 -->
148 <!-- TODO(rsc): add GOEXPERIMENT=loopvar -->
153 TODO: complete this section
156 <h2 id="tools">Tools</h2>
158 Go 1.21 adds improved support for backwards compatibility and forwards compatibility
162 <p><!-- https://go.dev/issue/56986 -->
163 To improve backwards compatibility, Go 1.21 formalizes
164 Go's use of the GODEBUG environment variable to control
165 the default behavior for changes that are non-breaking according to the
166 <a href="/doc/go1compat">compatibility policy</a>
167 but nonetheless may cause existing programs to break.
168 (For example, programs that depend on buggy behavior may break
169 when a bug is fixed, but bug fixes are not considered breaking changes.)
170 When Go must make this kind of behavior change,
171 it now chooses between the old and new behavior based on the
172 <code>go</code> line in the workspace's <code>go.work</code> file
173 or else the main module's <code>go.mod</code> file.
174 Upgrading to a new Go toolchain but leaving the <code>go</code> line
175 set to its original (older) Go version preserves the behavior of the older
177 With this compatibility support, the latest Go toolchain should always
178 be the best, most secure, implementation of an older version of Go.
179 See “<a href="/doc/godebug">Go, Backwards Compatibility, and GODEBUG</a>” for details.
182 <p><!-- https://go.dev/issue/57001 -->
183 To improve forwards compatibility, Go 1.21 now reads the <code>go</code> line
184 in a <code>go.work</code> or <code>go.mod</code> file as a strict
185 minimum requirement: <code>go</code> <code>1.21.0</code> means
186 that the workspace or module cannot be used with Go 1.20 or with Go 1.21rc1.
187 This allows projects that depend on fixes made in later versions of Go
188 to ensure that they are not used with earlier versions.
189 It also gives better error reporting for projects that make use of new Go features:
190 when the problem is that a newer Go version is needed,
191 that problem is reported clearly, instead of attempting to build the code
192 and instead printing errors about unresolved imports or syntax errors.
196 To make these new stricter version requirements easier to manage,
197 the <code>go</code> command can now invoke not just the toolchain
198 bundled in its own release but also other Go toolchain versions found in the PATH
199 or downloaded on demand.
200 If a <code>go.mod</code> or <code>go.work</code> <code>go</code> line
201 declares a minimum requirement on a newer version of Go, the <code>go</code>
202 command will find and run that version automatically.
203 The new <code>toolchain</code> directive sets a suggested minimum toolchain to use,
204 which may be newer than the strict <code>go</code> minimum.
205 See “<a href="/doc/toolchain">Go Toolchains</a>” for details.
208 <h3 id="go-command">Go command</h3>
210 <p><!-- https://go.dev/issue/58099, CL 474236 -->
211 The <code>-pgo</code> build flag now defaults to <code>-pgo=auto</code>,
212 and the restriction of specifying a single main package on the command
213 line is now removed. If a file named <code>default.pgo</code> is present
214 in the main package's directory, the <code>go</code> command will use
215 it to enable profile-guided optimization for building the corresponding
220 The <code>-C</code> <code>dir</code> flag must now be the first
221 flag on the command-line when used.
224 <p><!-- https://go.dev/issue/37708, CL 463837 -->
225 The new <code>go</code> <code>test</code> option
226 <code>-fullpath</code> prints full path names in test log messages,
227 rather than just base names.
230 <p><!-- https://go.dev/issue/15513, CL 466397 -->
231 The <code>go</code> <code>test</code> <code>-c</code> flag now
232 supports writing test binaries for multiple packages, each to
233 <code>pkg.test</code> where <code>pkg</code> is the package name.
234 It is an error if more than one test package being compiled has a given package name.]
237 <p><!-- https://go.dev/issue/15513, CL 466397 -->
238 The <code>go</code> <code>test</code> <code>-o</code> flag now
239 accepts a directory argument, in which case test binaries are written to that
240 directory instead of the current directory.
243 <h3 id="cgo">Cgo</h3>
245 <p><!-- CL 490819 -->
246 In files that <code>import "C"</code>, the Go toolchain now
247 correctly reports errors for attempts to declare Go methods on C types.
250 <h2 id="runtime-changes">Runtime</h2>
253 TODO: complete this section, or delete if not needed
256 <p><!-- https://go.dev/issue/7181 -->
257 When printing very deep stacks, the runtime now prints the first 50
258 (innermost) frames followed by the bottom 50 (outermost) frames,
259 rather than just printing the first 100 frames. This makes it easier
260 to see how deeply recursive stacks started, and is especially
261 valuable for debugging stack overflows.
264 <p><!-- https://go.dev/issue/59960 -->
265 On Linux platforms that support transparent huge pages, the Go runtime
266 now manages which parts of the heap may be backed by huge pages more
267 explicitly. This leads to better utilization of memory: small heaps
268 should see less memory used (up to 50% in pathological cases) while
269 large heaps should see fewer broken huge pages for dense parts of the
270 heap, improving CPU usage and latency by up to 1%.
273 <p><!-- https://go.dev/issue/57069, https://go.dev/issue/56966 -->
274 As a result of runtime-internal garbage collection tuning,
275 applications may see up to a 40% reduction in application tail latency
276 and a small decrease in memory use. Some applications may also observe
277 a small loss in throughput.
279 The memory use decrease should be proportional to the loss in
280 throughput, such that the previous release's throughput/memory
281 tradeoff may be recovered (with little change to latency) by
282 increasing <code>GOGC</code> and/or <code>GOMEMLIMIT</code> slightly.
285 <p><!-- https://go.dev/issue/51676 -->
286 Calls from C to Go on threads created in C require some setup to prepare for
287 Go execution. On Unix platforms, this setup is now preserved across multiple
288 calls from the same thread. This significantly reduces the overhead of
289 subsequent C to Go calls from ~1-3 microseconds per call to ~100-200
290 nanoseconds per call.
293 <h2 id="compiler">Compiler</h2>
296 Profile-guide optimization (PGO), added as a preview in Go 1.20, is now ready
297 for general use. PGO enables additional optimizations on code identified as
298 hot by profiles of production workloads. As mentioned in the
299 <a href="#go-command">Go command section</a>, PGO is enabled by default for
300 binaries that contain a <code>default.pgo</code> profile in the main
301 package directory. Performance improvements vary depending on application
302 behavior, with most programs from a representative set of Go programs seeing
303 between 2 and 7% improvement from enabling PGO. See the
304 <a href="/doc/pgo">PGO user guide</a> for detailed documentation.
307 <!-- https://go.dev/issue/59959 -->
309 PGO builds can now devirtualize some interface method calls, adding a
310 concrete call to the most common callee. This enables further optimization,
311 such as inlining the callee.
315 TODO: complete this section, or delete if not needed
318 <h2 id="assembler">Assembler</h2>
322 The verifier that checks for incorrect uses of <code>R15</code> when dynamic linking on amd64 has been improved.
325 <h2 id="linker">Linker</h2>
327 <p><!-- https://go.dev/issue/57302, CL 461749 -->
328 On Windows AMD64, the linker (with help from the compiler) now emits
329 SEH unwinding data by default, which improves the integration
330 of Go applications with Windows debuggers and other tools.
335 <!-- cmd/link: generate .xdata PE section -->
337 <!-- CL 463395, CL 461315 -->
339 In Go 1.21 the linker (with help from the compiler) is now capable of
340 deleting dead (unreferenced) global map variables, if the number of
341 entries in the variable initializer is sufficiently large, and if the
342 initializer expressions are side-effect free.
345 TODO: complete this section, or delete if not needed
348 <h2 id="library">Core library</h2>
350 <h3 id="slog">New log/slog package</h3>
352 <p><!-- https://go.dev/issue/59060, https://go.dev/issue/59141, https://go.dev/issue/59204, https://go.dev/issue/59280,
353 https://go.dev/issue/59282, https://go.dev/issue/59339, https://go.dev/issue/59345,
354 CL 477295, CL 484096, CL 486376, CL 486415, CL 487855 -->
355 The new <a href="/pkg/log/slog">log/slog</a> package provides structured logging with levels.
356 Structured logging emits key-value pairs
357 to enable fast, accurate processing of large amounts of log data.
358 The package supports integration with popular log analysis tools and services.
361 <h3 id="slogtest">New testing/slogtest package</h3>
363 <p><!-- CL 487895 -->
364 The new <a href="/pkg/testing/slogtest">testing/slogtest</a> package can help
365 to validate <a href="/pkg/log/slog#Handler">slog.Handler</a> implementations.
368 <h3 id="slices">New slices package</h3>
370 <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 -->
371 The new <a href="/pkg/slices">slices</a> package provides many common
372 operations on slices, using generic functions that work with slices
376 <h3 id="maps">New maps package</h3>
378 <p><!-- https://go.dev/issue/57436, CL 464343 -->
379 The new <a href="/pkg/maps/">maps</a> package provides several
380 common operations on maps, using generic functions that work with
381 maps of any key or element type.
384 <h3 id="minor_library_changes">Minor changes to the library</h3>
387 As always, there are various minor changes and updates to the library,
388 made with the Go 1 <a href="/doc/go1compat">promise of compatibility</a>
390 There are also various performance improvements, not enumerated here.
394 TODO: complete this section
397 <dl id="archive/tar"><dt><a href="/pkg/archive/tar/">archive/tar</a></dt>
399 <p><!-- https://go.dev/issue/54451, CL 491175 -->
400 The implementation of the
401 <a href="/pkg/io/fs/#FileInfo"><code>io/fs.FileInfo</code></a>
402 interface returned by
403 <a href="/pkg/archive/tar/#Header.FileInfo"><code>Header.FileInfo</code></a>
404 now implements a <code>String</code> method that calls
405 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
408 </dl><!-- archive/tar -->
410 <dl id="archive/zip"><dt><a href="/pkg/archive/zip/">archive/zip</a></dt>
412 <p><!-- https://go.dev/issue/54451, CL 491175 -->
413 The implementation of the
414 <a href="/pkg/io/fs/#FileInfo"><code>io/fs.FileInfo</code></a>
415 interface returned by
416 <a href="/pkg/archive/zip/#FileHeader.FileInfo"><code>FileHeader.FileInfo</code></a>
417 now implements a <code>String</code> method that calls
418 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
421 <p><!-- https://go.dev/issue/54451, CL 491175 -->
422 The implementation of the
423 <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
424 interface returned by the
425 <a href="/pkg/io/fs/#ReadDirFile.ReadDir"><code>io/fs.ReadDirFile.ReadDir</code></a>
427 <a href="/pkg/io/fs/#File"><code>io/fs.File</code></a>
429 <a href="/pkg/archive/zip/#Reader.Open"><code>Reader.Open</code></a>
430 now implements a <code>String</code> method that calls
431 <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
434 </dl><!-- archive/zip -->
436 <dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt>
438 <p><!-- https://go.dev/issue/53685, CL 474635 -->
439 The <a href="/pkg/bytes/#Buffer"><code>Buffer</code></a> type
441 <a href="/pkg/bytes/#Buffer.Available"><code>Available</code></a>
442 and <a href="/pkg/bytes/#AvailableBuffer"><code>AvailableBuffer</code></a>.
443 These may be used along with the
444 <a href="/pkg/bytes/#Buffer.Write"><code>Write</code></a>
445 method to append directly to the <code>Buffer</code>.
450 <dl id="context"><dt><a href="/pkg/context/">context</a></dt>
452 <p><!-- https://go.dev/issue/40221, CL 479918 -->
453 The new <a href="/pkg/context/#WithoutCancel"><code>WithoutCancel</code></a>
454 function returns a copy of a context that is not canceled when the original
457 <p><!-- https://go.dev/issue/56661, CL 449318 -->
458 The new <a href="/pkg/context/#WithDeadlineCause"><code>WithDeadlineCause</code></a>
459 and <a href="/pkg/context/#WithTimeoutCause"><code>WithTimeoutCause</code></a>
460 functions provide a way to set a context cancellation cause when a deadline or
461 timer expires. The cause may be retrieved with the
462 <a href="/pkg/context/#Cause"><code>Cause</code></a> function.
464 <p><!-- https://go.dev/issue/57928, CL 482695 -->
465 The new <a href="/pkg/context/#AfterFunc"><code>AfterFunc</code></a>
466 function registers a function to run after a context has been cancelled.
471 <dl id="crypto/elliptic"><dt><a href="/pkg/crypto/elliptic/">crypto/elliptic</a></dt>
473 <p><!-- CL 459977 -->
474 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.
477 </dl><!-- crypto/elliptic -->
479 <dl id="crypto/rsa"><dt><a href="/pkg/crypto/rsa/">crypto/rsa</a></dt>
481 <p><!-- https://go.dev/issue/56921, CL 459976 -->
482 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.
485 </dl><!-- crypto/rsa -->
487 <dl id="crypto/sha256"><dt><a href="/pkg/crypto/sha256/">crypto/sha256</a></dt>
489 <p><!-- https://go.dev/issue/50543, CL 408795 -->
490 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.
493 </dl><!-- crypto/sha256 -->
495 <dl id="crypto/x509"><dt><a href="/pkg/crypto/x509/">crypto/x509</a></dt>
497 <p><!-- https://go.dev/issue/53573, CL 468875 -->
498 <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.
501 </dl><!-- crypto/x509 -->
503 <dl id="debug/elf"><dt><a href="/pkg/debug/elf/">debug/elf</a></dt>
505 <p><!-- https://go.dev/issue/56892, CL 452617 -->
507 <a href="/pkg/debug/elf/#File.DynValue"><code>File.DynValue</code></a>
508 method may be used to retrieve the numeric values listed with a
512 <p><!-- https://go.dev/issue/56887, CL 452496 -->
513 The constant flags permitted in a <code>DT_FLAGS_1</code>
514 dynamic tag are now defined with type
515 <a href="/pkg/debug/elf/#DynFlag1"><code>DynFlag1</code></a>. These
516 tags have names starting with <code>DF_1</code>.
519 <p><!-- CL 473256 -->
520 The package now defines the constant
521 <a href="/pkg/debug/elf/#COMPRESS_ZSTD"><code>COMPRESS_ZSTD</code></a>.
524 </dl><!-- debug/elf -->
526 <dl id="debug/pe"><dt><a href="/pkg/debug/pe/">debug/pe</a></dt>
528 <p><!-- CL 488475 -->
529 Attempts to read from a section containing uninitialized data
531 <a href="/pkg/debug/pe/#Section.Data"><code>Section.Data</code></a>
532 or the reader returned by <a href="/pkg/debug/pe/#Section.Open"><code>Section.Open</code></a>
536 </dl><!-- debug/pe -->
538 <dl id="embed"><dt><a href="/pkg/embed/">embed</a></dt>
540 <p><!-- https://go.dev/issue/57803, CL 483235 -->
541 The <a href="/pkg/io/fs/#File"><code>io/fs.File</code></a>
543 <a href="/pkg/embed/#FS.Open"><code>FS.Open</code></a> now
544 has a <code>ReadAt</code> method that
545 implements <a href="/pkg/io/#ReaderAt"><code>io.ReaderAt</code></a>.
548 <p><!-- https://go.dev/issue/54451, CL 491175 -->
549 Calling <code><a href="/pkg/embed/FS.Open">FS.Open</a>.<a href="/pkg/io/fs/#File.Stat">Stat</a></code>
550 will return a type that now implements a <code>String</code>
552 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
557 <dl id="errors"><dt><a href="/pkg/errors/">errors</a></dt>
559 <p><!-- https://go.dev/issue/41198, CL 473935 -->
561 <a href="/pkg/errors/#ErrUnsupported"><code>ErrUnsupported</code></a>
562 error provides a standardized way to indicate that a requested
563 operation may not be performed because it is unsupported.
564 For example, a call to
565 <a href="/pkg/os/#Link"><code>os.Link</code></a> when using a
566 file system that does not support hard links.
571 <dl id="flag"><dt><a href="/pkg/flag/">flag</a></dt>
573 <p><!-- https://go.dev/issue/53747, CL 476015 -->
574 The new <a href="/pkg/flag/#BoolFunc"><code>BoolFunc</code></a>
576 <a href="/pkg/flag/#FlagSet.BoolFunc"><code>FlagSet.BoolFunc</code></a>
577 method define a flag that does not require an argument and calls
578 a function when the flag is used. This is similar to
579 <a href="/pkg/flag/#Func"><code>Func</code></a> but for a
583 <p><!-- CL 480215 -->
585 (via <a href="/pkg/flag/#Bool"><code>Bool</code></a>,
586 <a href="/pkg/flag/#BoolVar"><code>BoolVar</code></a>,
587 <a href="/pkg/flag/#Int"><code>Int</code></a>,
588 <a href="/pkg/flag/#IntVar"><code>IntVar</code></a>, etc.)
589 will panic if <a href="/pkg/flag/#Set"><code>Set</code></a> has
590 already been called on a flag with the same name. This change is
591 intended to detect cases where <a href="#language">changes in
592 initialization order</a> cause flag operations to occur in a
593 different order than expected. In many cases the fix to this
594 problem is to introduce a explicit package dependence to
595 correctly order the definition before any
596 <a href="/pkg/flag/#Set"><code>Set</code></a> operations.
601 <dl id="go/ast"><dt><a href="/pkg/go/ast/">go/ast</a></dt>
603 <p><!-- https://go.dev/issue/28089, CL 487935 -->
604 The new <a href="/pkg/go/ast/#IsGenerated"><code>IsGenerated</code></a> predicate
605 reports whether a file syntax tree contains the
606 <a href="https://go.dev/s/generatedcode">special comment</a>
607 that conventionally indicates that the file was generated by a tool.
612 <p><!-- https://go.dev/issue/59033, CL 476276 -->
614 <a href="/pkg/go/ast/#File.GoVersion"><code>File.GoVersion</code></a>
615 field records the minimum Go version required by
616 any <code>//go:build</code> or <code>// +build</code>
622 <dl id="go/build"><dt><a href="/pkg/go/build/">go/build</a></dt>
624 <p><!-- https://go.dev/issue/56986, CL 453603 -->
625 The package now parses build directives (comments that start
626 with <code>//go:</code>) in file headers (before
627 the <code>package</code> declaration). These directives are
629 <a href="/pkg/go/build#Package"><code>Package</code></a> fields
630 <a href="/pkg/go/build#Package.Directives"><code>Directives</code></a>,
631 <a href="/pkg/go/build#Package.TestDirectives"><code>TestDirectives</code></a>,
633 <a href="/pkg/go/build#Package.XTestDirectives"><code>XTestDirectives</code></a>.
636 </dl><!-- go/build -->
638 <dl id="go/build/constraint"><dt><a href="/pkg/go/build/constraint/">go/build/constraint</a></dt>
640 <p><!-- https://go.dev/issue/59033, CL 476275 -->
642 <a href="/pkg/go/build/constraint/#GoVersion"><code>GoVersion</code></a>
643 function returns the minimum Go version implied by a build
647 </dl><!-- go/build/constraint -->
649 <dl id="go/token"><dt><a href="/pkg/go/token/">go/token</a></dt>
651 <p><!-- https://go.dev/issue/57708, CL 464515 -->
652 The new <a href="/pkg/go/token/#File.Lines"><code>File.Lines</code></a> method
653 returns the file's line-number table in the same form as accepted by
654 <code>File.SetLines</code>.
657 </dl><!-- go/token -->
659 <dl id="hash/maphash"><dt><a href="/pkg/hash/maphash/">hash/maphash</a></dt>
661 <p><!-- https://go.dev/issue/47342, CL 468795 -->
662 The <code>hash/maphash</code> package now has a pure Go implementation, selectable with the <code>purego</code> build tag.
665 </dl><!-- hash/maphash -->
667 <dl id="io/fs"><dt><a href="/pkg/io/fs/">io/fs</a></dt>
669 <p><!-- https://go.dev/issue/54451, CL 489555 -->
671 <a href="/pkg/io/fs/#FormatFileInfo"><code>FormatFileInfo</code></a>
672 function returns a formatted version of a
673 <a href="/pkg/io/fs/#FileInfo"><code>FileInfo</code></a>.
675 <a href="/pkg/io/fs/#FormatDirEntry"><code>FormatDirEntry</code></a>
676 function returns a formatted version of a
677 <a href="/pkg/io/fs/#FileInfo"><code>DirEntry</code></a>.
678 The implementation of
679 <a href="/pkg/io/fs/#DirEntry"><code>DirEntry</code></a>
681 <a href="/pkg/io/fs/#ReadDir"><code>ReadDir</code></a> now
682 implements a <code>String</code> method that calls
683 <a href="/pkg/io/fs/#FormatDirEntry"><code>FormatDirEntry</code></a>,
684 and the same is true for
685 the <a href="/pkg/io/fs/#DirEntry"><code>DirEntry</code></a>
687 <a href="/pkg/io/fs/#WalkDirFunc"><code>WalkDirFunc</code></a>.
692 <!-- https://go.dev/issue/56491 rolled back -->
693 <!-- CL 459435 reverted -->
694 <!-- CL 467515 reverted -->
696 <dl id="math/big"><dt><a href="/pkg/math/big/">math/big</a></dt>
698 <p><!-- https://go.dev/issue/56984, CL 453115 -->
699 The new <a href="/pkg/math/big/#Int.Float64"><code>Int.Float64</code></a>
700 method returns the nearest floating-point value to a
701 multi-precision integer, along with an indication of any
702 rounding that occurred.
705 </dl><!-- math/big -->
707 <dl id="net"><dt><a href="/pkg/net/">net</a></dt>
710 <!-- https://go.dev/issue/59166, https://go.dev/issue/56539 -->
711 <!-- CL 471136, CL 471137, CL 471140 -->
712 On Linux, the <a href="/pkg/net/">net</a> package can now use
713 Multipath TCP when the kernel supports it. It is not used by
714 default. To use Multipath TCP when available on a client, call
716 <a href="/pkg/net/#Dialer.SetMultipathTCP"><code>Dialer.SetMultipathTCP</code></a>
717 method before calling the
718 <a href="/pkg/net/#Dialer.Dial"><code>Dialer.Dial</code></a> or
719 <a href="/pkg/net/#Dialer.DialContext"><code>Dialer.DialContext</code></a>
720 methods. To use Multipath TCP when available on a server, call
722 <a href="/pkg/net/#ListenConfig.SetMultipathTCP"><code>ListenConfig.SetMultipathTCP</code></a>
723 method before calling the
724 <a href="/pkg/net/#ListenConfig.Listen"><code>ListenConfig.Listen</code></a>
725 method. Specify the network as <code>"tcp"</code> or
726 <code>"tcp4"</code> or <code>"tcp6"</code> as usual. If
727 Multipath TCP is not supported by the kernel or the remote host,
728 the connection will silently fall back to TCP. To test whether a
729 particular connection is using Multipath TCP, use the
730 <a href="/pkg/net/#TCPConn.MultipathTCP"><code>TCPConn.MultipathTCP</code></a>
734 In a future Go release we may enable Multipath TCP by default on
735 systems that support it.
740 <dl id="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt>
742 <p><!-- https://go.dev/issue/44855, CL 382117 -->
743 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.
746 <p><!-- CL 472636 -->
747 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
750 <p><!-- CL 494122 -->
751 The <a href="/pkg/net/http/">net/http</a> package now supports
752 <a href="/pkg/errors/#ErrUnsupported"><code>errors.ErrUnsupported</code></a>,
753 in that the expression
754 <code>errors.Is(http.ErrNotSupported, errors.ErrUnsupported)</code>
758 </dl><!-- net/http -->
760 <dl id="os"><dt><a href="/pkg/os/">os</a></dt>
762 <p><!-- https://go.dev/issue/32558, CL 219638 -->
763 Programs may now pass an empty <code>time.Time</code> value to
764 the <a href="/pkg/os/#Chtimes"><code>Chtimes</code></a> function
765 to leave either the access time or the modification time unchanged.
768 <p><!-- CL 480135 -->
770 <a href="/pkg/os#File.Chdir"><code>File.Chdir</code></a> method
771 now changes the current directory to the file, rather than
772 always returning an error.
775 <p><!-- CL 477215 -->
777 <a href="/pkg/os/#Truncate"><code>Truncate</code></a> on a
778 non-existent file used to create an empty file. It now returns
779 an error indicating that the file does not exist.
782 <p><!-- https://go.dev/issue/56899, CL 463219 -->
784 <a href="/pkg/os/#TempDir"><code>TempDir</code></a> now uses
785 GetTempPath2W when available, instead of GetTempPathW. The
786 new behavior is a security hardening measure that prevents
787 temporary files created by processes running as SYSTEM to
788 be accessed by non-SYSTEM processes.
791 <p><!-- CL 493036 -->
792 On Windows the os package now supports working with files whose
793 names, stored as UTF-16, can't be represented as valid UTF-8.
796 <p><!-- https://go.dev/issue/54451, CL 491175 -->
797 The implementation of the
798 <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
799 interface returned by the
800 <a href="/pkg/os/#ReadDir"><code>ReadDir</code></a> function and
801 the <a href="/pkg/os/#File.ReadDir"><code>File.ReadDir</code></a>
802 method now implements a <code>String</code> method that calls
803 <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
806 <p><!-- https://go.dev/issue/53761, CL 416775, CL 498015-->
807 The implementation of the
808 <a href="/pkg/io/fs/#FS"><code>io/fs.FS</code></a> interface returned by
809 the <a href="/pkg/os/#DirFS"><code>DirFS</code></a> function now implements
810 the <a href="/pkg/io/fs/#ReadFileFS"><code>io/fs.ReadFileFS</code></a> and
811 the <a href="/pkg/io/fs/#ReadDirFS"><code>io/fs.ReadDirFS</code></a>
817 <dl id="path/filepath"><dt><a href="/pkg/path/filepath/">path/filepath</a></dt>
820 The implementation of the
821 <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
822 interface passed to the function argument of
823 <a href="/pkg/path/filepath/#WalkDir"><code>WalkDir</code></a>
824 now implements a <code>String</code> method that calls
825 <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
828 </dl><!-- path/filepath -->
830 <!-- CL 459455 reverted -->
832 <dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
834 <p><!-- CL 408826, CL 413474 -->
835 In Go 1.21, <a href="/pkg/reflect/#ValueOf"><code>ValueOf</code></a>
836 no longer forces its argument to be allocated on the heap, allowing
837 a <code>Value</code>'s content to be allocated on the stack. Most
838 operations on a <code>Value</code> also allow the underlying value
839 to be stack allocated.
842 <p><!-- https://go.dev/issue/55002 -->
843 The new <a href="/pkg/reflect/#Value"><code>Value</code></a>
844 method <a href="/pkg/reflect/#Value.Clear"><code>Value.Clear</code></a>
845 clears the contents of a map or zeros the contents of a slice.
846 This corresponds to the new <code>clear</code> built-in
847 <a href="#language">added to the language</a>.
850 <p><!-- https://go.dev/issue/56906, CL 452762 -->
851 The <a href="/pkg/reflect/#SliceHeader"><code>SliceHeader</code></a>
852 and <a href="/pkg/reflect/#StringHeader"><code>StringHeader</code></a>
853 types are now deprecated. In new code
854 prefer <a href="/pkg/unsafe/#Slice"><code>unsafe.Slice</code></a>,
855 <a href="/pkg/unsafe/#SliceData"><code>unsafe.SliceData</code></a>,
856 <a href="/pkg/unsafe/#String"><code>unsafe.String</code></a>,
857 or <a href="/pkg/unsafe/#StringData"><code>unsafe.StringData</code></a>.
860 </dl><!-- reflect -->
862 <dl id="regexp"><dt><a href="/pkg/regexp/">regexp</a></dt>
864 <p><!-- https://go.dev/issue/46159, CL 479401 -->
865 <a href="/pkg/regexp#Regexp"><code>Regexp</code></a> now defines
866 <a href="/pkg/regexp#Regexp.MarshalText"><code>MarshalText</code></a>
867 and <a href="/pkg/regexp#Regexp.UnmarshalText"><code>UnmarshalText</code></a>
868 methods. These implement
869 <a href="/pkg/encoding#TextMarshaler"><code>encoding.TextMarshaler</code></a>
871 <a href="/pkg/encoding#TextUnmarshaler"><code>encoding.TextUnmarshaler</code></a>
872 and will be used by packages such as
873 <a href="/pkg/encoding/json">encoding/json</a>.
878 <dl id="runtime"><dt><a href="/pkg/runtime/">runtime</a></dt>
880 <p><!-- https://go.dev/issue/38651 -->
881 TODO: <a href="https://go.dev/issue/38651">https://go.dev/issue/38651</a>: add 'created by goroutine number' to stack traces
884 <p><!-- https://go.dev/issue/57441, CL 474915 -->
885 Crashing Go applications can now opt-in to Windows Error Reporting (WER) by setting the environment variable
886 <code>GOTRACEBACK=wer</code> or calling <a href="/pkg/runtime/debug/#SetTraceback"><code>debug.SetTraceback("wer")</code></a>
887 before the crash. Other than enabling WER, the runtime will behave as with <code>GOTRACEBACK=crash</code>.
888 On non-Windows systems, <code>GOTRACEBACK=wer</code> is ignored.
891 <p><!-- CL 447778 -->
892 <code>GODEBUG=cgocheck=2</code>, a thorough checker of cgo pointer passing rules,
893 is no longer available as a <a href="/pkg/runtime#hdr-Environment_Variables">debug option</a>.
894 Instead, it is available as an experiment using <code>GOEXPERIMENT=cgocheck2</code>.
895 In particular this means that this mode has to be selected at build time instead of startup time.
897 <code>GODEBUG=cgocheck=1</code> is still available (and is still the default).
900 <p><!-- https://go.dev/issue/46787 -->
901 A new type <code>Pinner</code> has been added to the runtime
902 package. <code>Pinner</code>s may be used to "pin" Go memory
903 such that it may be used more freely by non-Go code. For instance,
904 passing Go values that reference pinned Go memory to C code is
905 now allowed. Previously, passing any such nested reference was
907 <a href="https://pkg.go.dev/cmd/cgo#hdr-Passing_pointers">cgo pointer passing rules.</a>
909 See <a href="/pkg/runtime#Pinner">the docs</a> for more details.
912 </dl><!-- runtime -->
914 <dl id="runtime/trace"><dt><a href="/pkg/runtime/trace/">runtime/trace</a></dt>
916 <p><!-- https://go.dev/issue/16638 -->
917 Collecting traces on amd64 and arm64 now incurs a substantially
918 smaller CPU cost: up to a 10x improvement over the previous release.
921 <p><!-- CL 494495 -->
922 Traces now contain explicit stop-the-world events for every reason
923 the Go runtime might stop-the-world, not just garbage collection.
926 </dl><!-- runtime/trace -->
928 <dl id="runtime/metrics"><dt><a href="/pkg/runtime/metrics/">runtime/metrics</a></dt>
930 <p><!-- https://go.dev/issue/56857 -->
931 A few previously-internal GC metrics, such as live heap size, are
934 <code>GOGC</code> and <code>GOMEMLIMIT</code> are also now
935 available as metrics.
938 </dl><!-- runtime/metrics -->
940 <dl id="sync"><dt><a href="/pkg/sync/">sync</a></dt>
942 <p><!-- https://go.dev/issue/56102, CL 451356 -->
943 The new <a href="/pkg/sync/#OnceFunc"><code>OnceFunc</code></a>,
944 <a href="/pkg/sync/#OnceValue"><code>OnceValue</code></a>, and
945 <a href="/pkg/sync/#OnceValues"><code>OnceValues</code></a>
946 functions capture a common use of <a href="/pkg/sync/#Once">Once</a> to
947 lazily initialize a value on first use.
952 <dl id="syscall"><dt><a href="/pkg/syscall/">syscall</a></dt>
954 <p><!-- CL 480135 -->
956 <a href="/pkg/syscall#Fchdir"><code>Fchdir</code></a> function
957 now changes the current directory to its argument, rather than
958 always returning an error.
961 <p><!-- https://go.dev/issue/46259, CL 458335 -->
963 <a href="/pkg/syscall#SysProcAttr"><code>SysProcAttr</code></a>
964 has a new field <code>Jail</code> that may be used to put the
965 newly created process in a jailed environment.
968 <p><!-- CL 493036 -->
969 On Windows the syscall package now supports working with files whose
970 names, stored as UTF-16, can't be represented as valid UTF-8.
971 The <a href="/pkg/syscall#UTF16ToString"><code>UTF16ToString</code></a>
972 and <a href="/pkg/syscall#UTF16FromString"><code>UTF16FromString</code></a>
973 functions now convert between UTF-16 data and
974 <a href="https://simonsapin.github.io/wtf-8/">WTF-8</a> strings.
975 This is backward compatible as WTF-8 is a superset of the UTF-8
976 format that was used in earlier releases.
979 <p><!-- CL 476578, CL 476875, CL 476916 -->
980 Several error values match the new
981 <a href="/pkg/errors/#ErrUnsupported"><code>errors.ErrUnsupported</code></a>,
982 such that <code>errors.Is(err, errors.ErrUnsupported)</code>
985 <li><code>ENOSYS</code></li>
986 <li><code>ENOTSUP</code></li>
987 <li><code>EOPNOTSUPP</code></li>
988 <li><code>EPLAN9</code> (Plan 9 only)</li>
989 <li><code>ERROR_CALL_NOT_IMPLEMENTED</code> (Windows only)</li>
990 <li><code>ERROR_NOT_SUPPORTED</code> (Windows only)</li>
991 <li><code>EWINDOWS</code> (Windows only)</li>
995 </dl><!-- syscall -->
997 <dl id="testing"><dt><a href="/pkg/testing/">testing</a></dt>
999 <p><!-- https://go.dev/issue/37708, CL 463837 -->
1000 The new <code>-test.fullpath</code> option will print full path
1001 names in test log messages, rather than just base names.
1004 <p><!-- https://go.dev/issue/52600, CL 475496 -->
1005 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>.
1008 </dl><!-- testing -->
1010 <dl id="testing/fstest"><dt><a href="/pkg/testing/fstest/">testing/fstest</a></dt>
1012 <p><!-- https://go.dev/issue/54451, CL 491175 -->
1013 Calling <code><a href="/pkg/testing/fstest/MapFS.Open">Open</a>.<a href="/pkg/io/fs/#File.Stat">Stat</a></code>
1014 will return a type that now implements a <code>String</code>
1016 <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
1019 </dl><!-- testing/fstest -->
1021 <dl id="unicode"><dt><a href="/pkg/unicode/">unicode</a></dt>
1023 <p><!-- CL 456837 -->
1024 The <a href="/pkg/unicode/"><code>unicode</code></a> package and
1025 associated support throughout the system has been upgraded to
1026 <a href="https://www.unicode.org/versions/Unicode15.0.0/">Unicode 15.0.0</a>.
1028 </dl><!-- unicode -->
1030 <h2 id="ports">Ports</h2>
1032 <h3 id="darwin">Darwin</h3>
1034 <p><!-- go.dev/issue/57125 -->
1035 As <a href="go1.20#darwin">announced</a> in the Go 1.20 release notes,
1036 Go 1.21 requires macOS 10.15 Catalina or later;
1037 support for previous versions has been discontinued.
1040 <h3 id="windows">Windows</h3>
1042 <p><!-- go.dev/issue/57003, go.dev/issue/57004 -->
1043 As <a href="go1.20#windows">announced</a> in the Go 1.20 release notes,
1044 Go 1.21 requires at least Windows 10 or Windows Server 2016;
1045 support for previous versions has been discontinued.
1050 <!-- cmd/dist: default to GOARM=7 on all non-arm systems -->
1053 <h3 id="wasm">WebAssembly</h3>
1055 <p><!-- https://go.dev/issue/38248, https://go.dev/issue/59149, CL 489255 -->
1056 The new <code>go:wasmimport</code> directive can now be used in Go programs
1057 to import functions from the WebAssembly host.
1060 <!-- https://go.dev/issue/56100 -->
1062 The Go scheduler now interacts much more efficiently with the
1063 JavaScript event loop, especially in applications that block
1064 frequently on asynchronous events.
1068 <h3 id="wasip1">WebAssembly System Interface</h3>
1070 <p><!-- https://go.dev/issue/58141 -->
1071 Go 1.21 adds an experimental port to the <a href="https://wasi.dev/">
1072 WebAssembly System Interface (WASI)</a>, Preview 1
1073 (<code>GOOS=wasip1</code>, <code>GOARCH=wasm</code>).
1077 As a result of the addition of the new <code>GOOS</code> value
1078 "<code>wasip1</code>", Go files named <code>*_wasip1.go</code>
1079 will now be <a href="/pkg/go/build/#hdr-Build_Constraints">ignored
1080 by Go tools</a> except when that <code>GOOS</code> value is being
1082 If you have existing filenames matching that pattern, you will
1083 need to rename them.
1087 <!-- proposals for x repos that don't need to be mentioned here but
1088 are picked up by the relnote tool. -->
1089 <!-- https://go.dev/issue/54232 -->
1090 <!-- https://go.dev/issue/57906 -->
1091 <!-- https://go.dev/issue/58668 -->