[gostls13.git] / doc / go1.21.html

<!--{
        "Title": "Go 1.21 Release Notes",
        "Path":  "/doc/go1.21"
}-->

<!--
NOTE: In this document and others in this directory, the convention is to
set fixed-width phrases with non-fixed-width spaces, as in
<code>hello</code> <code>world</code>.
Do not send CLs removing the interior tags from such phrases.
-->

<style>
  main ul li { margin: 0.5em 0; }
</style>

<h2 id="introduction">DRAFT RELEASE NOTES — Introduction to Go 1.21</h2>

<p>
  <strong>
    Go 1.21 is not yet released. These are work-in-progress
    release notes. Go 1.21 is expected to be released in August 2023.
  </strong>
</p>

<h2 id="language">Changes to the language</h2>

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

  <ul>
    <li><!-- https://go.dev/issue/59488 -->
      The new functions <code>min</code> and <code>max</code> compute the
      smallest (or largest, for <code>max</code>) value of a fixed number
      of given arguments.
      See the language spec for
      <a href="https://tip.golang.org/ref/spec#Min_and_max">details</a>.
    </li>
    <li><!-- https://go.dev/issue/56351 -->
      The new function <code>clear</code> deletes all elements from a
      map or zeroes all elements of a slice.
      See the language spec for
      <a href="https://tip.golang.org/ref/spec#Clear">details</a>.
    </li>
  </ul>
</p>

<p><!-- https://go.dev/issue/57411 -->
  Package initialization order is now specified more precisely. The
  new algorithm is:
  <ul>
    <li>
      Sort all packages by import path.
    </li>
    <li>Repeat until the list of packages is empty:
      <ul>
        <li>
          Find the first package in the list for which all imports are
          already initialized.
        </li>
        <li>
          Initialize that package and remove it from the list.
        </li>
      </ul>
    </li>
  </ul>
  This may change the behavior of some programs that rely on a
  specific initialization ordering that was not expressed by explicit
  imports. The behavior of such programs was not well defined by the
  spec in past releases. The new rule provides an unambiguous definition.
</p>

<p><!-- https://go.dev/issue/59338 -->
  TODO: <a href="https://go.dev/issue/59338">https://go.dev/issue/59338</a>: infer type arguments from assignments of generic functions (reverse type inference)
</p>

<p><!-- https://go.dev/issue/56986 -->
  TODO: <a href="https://go.dev/issue/56986">https://go.dev/issue/56986</a>: extended backwards compatibility for Go
</p>

<!-- https://go.dev/issue/57969 -->
<p>
  <!-- add GOEXPERIMENT=loopvar -->
</p>


<p>
  TODO: complete this section
</p>

<h2 id="ports">Ports</h2>

<!-- CL 470695 -->
<p>
  <!-- cmd/dist: default to GOARM=7 on all non-arm systems -->
</p>

<!-- https://go.dev/issue/38248 -->
<p>
  <!-- replace CallImport with go:wasmimport directive -->
</p>

<h3 id="wasm">WebAssembly</h3>

<!-- https://go.dev/issue/59149 -->
<p>
  <!-- allow the use of go:wasmimport globally -->
</p>

<!-- CL 489255 -->
<p>
  <!-- cmd/compile: remove go:wasmimport restriction -->
</p>

<!-- https://go.dev/issue/56100 -->
<p>
  The Go scheduler now interacts much more efficiently with the
  JavaScript event loop, especially in applications that block
  frequently on asynchronous events.
</p>


<h3 id="wasip1">WebAssembly System Interface</h3>

<p><!-- https://go.dev/issue/58141 -->
  Go 1.21 adds an experimental port to the <a href="https://wasi.dev/">
  WebAssembly System Interface (WASI)</a>, Preview 1
  (<code>GOOS=wasip1</code>, <code>GOARCH=wasm</code>).
</p>

<p>
  As a result of the addition of the new <code>GOOS</code> value
  "<code>wasip1</code>", Go files named <code>*_wasip1.go</code>
  will now be <a href="/pkg/go/build/#hdr-Build_Constraints">ignored
  by Go tools</a> except when that <code>GOOS</code> value is being
  used.
  If you have existing filenames matching that pattern, you will
  need to rename them.
</p>

<h2 id="tools">Tools</h2>

<!-- https://go.dev/issue/15513 -->
<p>
  <!-- support compiling all tests without running -->
</p>

<h3 id="go-command">Go command</h3>

<p><!-- https://go.dev/issue/58099, CL 474236 -->
  The <code>-pgo</code> build flag now defaults to <code>-pgo=auto</code>,
  and the restriction of specifying a single main package on the command
  line is now removed. If a file named <code>default.pgo</code> is present
  in the main package's directory, the <code>go</code> command will use
  it to enable profile-guided optimization for building the corresponding
  program.
</p>

<p><!-- https://go.dev/issue/37708, CL 463837 -->
  The new <code>go</code> <code>test</code> option
  <code>-fullpath</code> prints full path names in test log messages,
  rather than just base names.
</p>

<p><!-- CL 453603 -->
  TODO: <a href="https://go.dev/cl/453603">https://go.dev/cl/453603</a>: cmd/go, go/build: parse directives in file headers; modified api/next/56986.txt
</p>

<!-- CL 466397 -->
<p>
  <!-- cmd/go: make go test build multiple executables; The go test command now supports using the -c flag with multiple packages. -->
</p>

<h2 id="runtime-changes">Runtime</h2>

<p>
  TODO: complete this section, or delete if not needed
</p>

<p><!-- https://go.dev/issue/7181 -->
  When printing very deep stacks, the runtime now prints the first 50
  (innermost) frames followed by the bottom 50 (outermost) frames,
  rather than just printing the first 100 frames. This makes it easier
  to see how deeply recursive stacks started, and is especially
  valuable for debugging stack overflows.
</p>

<p><!-- https://go.dev/issue/59960 -->
  On Linux platforms that support transparent huge pages, the Go runtime
  now manages which parts of the heap may be backed by huge pages more
  explicitly. This leads to better utilization of memory: small heaps
  should see less memory used (up to 50% in pathological cases) while
  large heaps should see fewer broken huge pages for dense parts of the
  heap, improving CPU usage and latency by up to 1%.
</p>

<p><!-- https://go.dev/issue/57069, https://go.dev/issue/56966 -->
  As a result of runtime-internal garbage collection tuning,
  applications may see up to a 40% reduction in application tail latency
  and a small decrease in memory use. Some applications may also observe
  a small loss in throughput.

  The memory use decrease should be proportional to the loss in
  throughput, such that the previous release's throughput/memory
  tradeoff may be recovered (with little change to latency) by
  increasing <code>GOGC</code> and/or <code>GOMEMLIMIT</code> slightly.
</p>

<h2 id="compiler">Compiler</h2>

<!-- CL 490819 -->
<p>
  <!-- cmd/cgo: reject attempts to declare methods on C types -->
</p>

<!-- CL 461315 -->
<p>
  <!-- cmd/compile: enable deadcode of unreferenced large global maps -->
</p>

<p>
  TODO: complete this section, or delete if not needed
</p>

<h2 id="linker">Linker</h2>

<!-- CL 457455 -->
<p>
  <!-- cmd/link: generate .xdata PE section -->
</p>
<!-- CL 463395 -->
<p>
  In Go 1.21 the linker (with help from the compiler) is now capable of
  deleting dead (unreferenced) global map variables, if the number of
  entries in the variable initializer is sufficiently large, and if the
  initializer expressions are side-effect free.
</p>
<p>
  TODO: complete this section, or delete if not needed
</p>

<h2 id="library">Core library</h2>

<h3 id="slog">New log/slog package</h3>

<p>
  The new <a href="/pkg/log/slog">log/slog</a> package provides structured logging with levels.
  Structured logging emits key-value pairs
  to enable fast, accurate processing of large amounts of log data.
  The package supports integration with popular log analysis tools and services.
</p>

<h3 id="slices">New slices package</h3>

<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 -->
  The new <a href="/pkg/slices">slices</a> package provides many common
  operations on slices, using generic functions that work with slices
  of any element type.
</p>

<h3 id="maps">New maps package</h3>

<p><!-- https://go.dev/issue/57436, CL 464343 -->
  The new <a href="/pkg/maps/">maps</a> package provides several
  common operations on maps, using generic functions that work with
  maps of any key or element type.
</p>

<h3 id="minor_library_changes">Minor changes to the library</h3>

<p>
  As always, there are various minor changes and updates to the library,
  made with the Go 1 <a href="/doc/go1compat">promise of compatibility</a>
  in mind.
  There are also various performance improvements, not enumerated here.
</p>

<p><!-- CL 456837 -->
  TODO: <a href="https://go.dev/cl/456837">https://go.dev/cl/456837</a>: all: upgrade Unicode from 13.0.0 to 15.0.0; modified api/except.txt, api/next/55079.txt
</p>

<p>
  TODO: complete this section
</p>

<dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/53685 -->
      TODO: <a href="https://go.dev/issue/53685">https://go.dev/issue/53685</a>: add Buffer.Available and Buffer.AvailableBuffer
    </p>

    <p><!-- CL 474635 -->
      TODO: <a href="https://go.dev/cl/474635">https://go.dev/cl/474635</a>: bytes: add Buffer.Available and Buffer.AvailableBuffer; modified api/next/53685.txt
    </p>
  </dd>
</dl><!-- bytes -->

<dl id="context"><dt><a href="/pkg/context/">context</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/40221, CL 479918 -->
      The new <a href="/pkg/context/#WithoutCancel"><code>WithoutCancel</code></a>
      function returns a copy of a context that is not canceled when the original
      context is canceled.
    </p>
    <p><!-- https://go.dev/issue/56661, CL 449318 -->
      The new <a href="/pkg/context/#WithDeadlineCause"><code>WithDeadlineCause</code></a>
      and <a href="/pkg/context/#WithTimeoutCause"><code>WithTimeoutCause</code></a>
      functions provide a way to set a context cancellation cause when a deadline or
      timer expires. The cause may be retrieved with the
      <a href="/pkg/context/#Cause"><code>Cause</code></a> function.
    </p>
    <p><!-- https://go.dev/issue/57928, CL 482695 -->
      The new <a href="/pkg/context/#AfterFunc"><code>AfterFunc</code></a>
      function registers a function to run after a context has been cancelled.
    </p>
  </dd>
</dl>

<dl id="crypto/elliptic"><dt><a href="/pkg/crypto/elliptic/">crypto/elliptic</a></dt>
  <dd>
    <p><!-- CL 459977 -->
      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
    </p>
  </dd>
</dl><!-- crypto/elliptic -->

<dl id="crypto/rsa"><dt><a href="/pkg/crypto/rsa/">crypto/rsa</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56921 -->
      TODO: <a href="https://go.dev/issue/56921">https://go.dev/issue/56921</a>: deprecate GenerateMultiPrimeKey and PrecomputedValues.CRTValues
    </p>

    <p><!-- CL 459976 -->
      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
    </p>
  </dd>
</dl><!-- crypto/rsa -->

<dl id="crypto/sha1"><dt><a href="/pkg/crypto/sha1/">crypto/sha1</a></dt>
  <dd>
    <p><!-- CL 483815 -->
      TODO: <a href="https://go.dev/cl/483815">https://go.dev/cl/483815</a>: crypto/sha1: add WriteString and WriteByte method
    </p>
  </dd>
</dl><!-- crypto/sha1 -->

<dl id="crypto/sha256"><dt><a href="/pkg/crypto/sha256/">crypto/sha256</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/50543 -->
      TODO: <a href="https://go.dev/issue/50543">https://go.dev/issue/50543</a>: add native SHA256 instruction implementation for AMD64
    </p>

    <p><!-- CL 408795 -->
      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.
    </p>

    <p><!-- CL 481478 -->
      TODO: <a href="https://go.dev/cl/481478">https://go.dev/cl/481478</a>: crypto/sha256: add WriteString and WriteByte method
    </p>
  </dd>
</dl><!-- crypto/sha256 -->

<dl id="crypto/sha512"><dt><a href="/pkg/crypto/sha512/">crypto/sha512</a></dt>
  <dd>
    <p><!-- CL 483816 -->
      TODO: <a href="https://go.dev/cl/483816">https://go.dev/cl/483816</a>: crypto/sha512: add WriteString and WriteByte method
    </p>
  </dd>
</dl><!-- crypto/sha512 -->

<dl id="crypto/x509"><dt><a href="/pkg/crypto/x509/">crypto/x509</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/53573 -->
      TODO: <a href="https://go.dev/issue/53573">https://go.dev/issue/53573</a>: surface ReasonCode inside x509.RevocationList entries
    </p>

    <p><!-- CL 468875 -->
      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
    </p>
  </dd>
</dl><!-- crypto/x509 -->

<dl id="debug/elf"><dt><a href="/pkg/debug/elf/">debug/elf</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56887 -->
      TODO: <a href="https://go.dev/issue/56887">https://go.dev/issue/56887</a>: add DT_FLAGS_1 (dynamic flags) constants
    </p>

    <p><!-- https://go.dev/issue/56892 -->
      TODO: <a href="https://go.dev/issue/56892">https://go.dev/issue/56892</a>: add (*File).DynValue
    </p>

    <p><!-- CL 452496 -->
      TODO: <a href="https://go.dev/cl/452496">https://go.dev/cl/452496</a>: debug/elf: add DT_FLAGS_1 constants; modified api/next/56887.txt
    </p>

    <p><!-- CL 452617 -->
      TODO: <a href="https://go.dev/cl/452617">https://go.dev/cl/452617</a>: debug/elf: retrieve values for dynamic section tags; modified api/next/56892.txt
    </p>

    <p><!-- CL 473256 -->
      TODO: <a href="https://go.dev/cl/473256">https://go.dev/cl/473256</a>: debug/elf: support zstd compression; modified api/next/55107.txt
    </p>
  </dd>
</dl><!-- debug/elf -->

<dl id="debug/pe"><dt><a href="/pkg/debug/pe/">debug/pe</a></dt>
  <dd>
    <p><!-- CL 488475 -->
      TODO: <a href="https://go.dev/cl/488475">https://go.dev/cl/488475</a>: debug/pe: return error on reading from section with uninitialized data
    </p>
  </dd>
</dl><!-- debug/pe -->

<dl id="embed"><dt><a href="/pkg/embed/">embed</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/57803 -->
      TODO: <a href="https://go.dev/issue/57803">https://go.dev/issue/57803</a>: openFile should implement ReaderAt
    </p>

    <p><!-- CL 483235 -->
      TODO: <a href="https://go.dev/cl/483235">https://go.dev/cl/483235</a>: embed: implement openFile.ReadAt
    </p>
  </dd>
</dl><!-- embed -->

<dl id="errors"><dt><a href="/pkg/errors/">errors</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/41198 -->
      TODO: <a href="https://go.dev/issue/41198">https://go.dev/issue/41198</a>: add ErrUnsupported
    </p>

    <p><!-- CL 473935 -->
      TODO: <a href="https://go.dev/cl/473935">https://go.dev/cl/473935</a>: errors: add ErrUnsupported; modified api/next/41198.txt
    </p>
  </dd>
</dl><!-- errors -->

<dl id="flag"><dt><a href="/pkg/flag/">flag</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/53747 -->
      TODO: <a href="https://go.dev/issue/53747">https://go.dev/issue/53747</a>: add BoolFunc(name, usage string, fn func(string)error)
    </p>

    <p><!-- CL 476015 -->
      TODO: <a href="https://go.dev/cl/476015">https://go.dev/cl/476015</a>: flag: add BoolFunc; FlagSet.BoolFunc; modified api/next/53747.txt
    </p>

    <p><!-- CL 480215 -->
      TODO: <a href="https://go.dev/cl/480215">https://go.dev/cl/480215</a>: flag: panic if a flag is defined after being set
    </p>
  </dd>
</dl><!-- flag -->

<dl id="fs"><dt><a href="/pkg/fs/">fs</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/54451 -->
      TODO: <a href="https://go.dev/issue/54451">https://go.dev/issue/54451</a>: standard implementations of FileInfo and DirEntry should implement fmt.Stringer
    </p>
  </dd>
</dl><!-- fs -->

<dl id="go/ast"><dt><a href="/pkg/go/ast/">go/ast</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/28089, CL 487935 -->
      The new <a href="/pkg/go/ast/#IsGenerated"><code>IsGenerated</code></a> predicate
      reports whether a file syntax tree contains the
      <a href="https://go.dev/s/generatedcode">special comment</a>
      that conventionally indicates that the file was generated by a tool.
    </p>
  </dd>

  <dd>
    <p><!-- CL 476276 -->
      TODO: <a href="https://go.dev/cl/476276">https://go.dev/cl/476276</a>: go/ast: add File.GoVersion; modified api/next/59033.txt
    </p>
  </dd>
</dl><!-- go/ast -->

<dl id="go/build"><dt><a href="/pkg/go/build/">go/build</a></dt>
  <dd>
    <p><!-- CL 453603 -->
      TODO: <a href="https://go.dev/cl/453603">https://go.dev/cl/453603</a>: cmd/go, go/build: parse directives in file headers; modified api/next/56986.txt
    </p>
  </dd>
</dl><!-- go/build -->

<dl id="go/build/constraint"><dt><a href="/pkg/go/build/constraint/">go/build/constraint</a></dt>
  <dd>
    <p><!-- CL 476275 -->
      TODO: <a href="https://go.dev/cl/476275">https://go.dev/cl/476275</a>: go/build/constraint: add GoVersion; modified api/next/59033.txt
    </p>
  </dd>
</dl><!-- go/build/constraint -->

<dl id="go/token"><dt><a href="/pkg/go/token/">go/token</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/57708, CL 464515 -->
      The new <a href="/pkg/go/token/#File.Lines"><code>File.Lines</code></a> method
      returns the file's line-number table in the same form as accepted by
      <code>File.SetLines</code>.
    </p>
  </dd>
</dl><!-- go/token -->

<dl id="hash/maphash"><dt><a href="/pkg/hash/maphash/">hash/maphash</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/47342 -->
      TODO: <a href="https://go.dev/issue/47342">https://go.dev/issue/47342</a>: Provide a `purego` implementation
    </p>

    <p><!-- CL 468795 -->
      TODO: <a href="https://go.dev/cl/468795">https://go.dev/cl/468795</a>: hash/maphash: add purego implementation
    </p>
  </dd>
</dl><!-- hash/maphash -->

<dl id="io/fs"><dt><a href="/pkg/io/fs/">io/fs</a></dt>
  <dd>
    <p><!-- CL 489555 -->
      TODO: <a href="https://go.dev/cl/489555">https://go.dev/cl/489555</a>: io/fs: add FormatFileInfo and FormatDirEntry functions; modified api/next/54451.txt
    </p>
  </dd>
</dl><!-- io/fs -->

<dl id="log/slog"><dt><a href="/pkg/log/slog/">log/slog</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/59060 -->
      TODO: <a href="https://go.dev/issue/59060">https://go.dev/issue/59060</a>: arg to Record.Attrs should return bool
    </p>

    <p><!-- https://go.dev/issue/59141 -->
      TODO: <a href="https://go.dev/issue/59141">https://go.dev/issue/59141</a>: handle panics in LogValuer.LogValue
    </p>

    <p><!-- https://go.dev/issue/59204 -->
      TODO: <a href="https://go.dev/issue/59204">https://go.dev/issue/59204</a>: change slog.Group signature to ...any
    </p>

    <p><!-- https://go.dev/issue/59280 -->
      TODO: <a href="https://go.dev/issue/59280">https://go.dev/issue/59280</a>: ReplaceAttr gets Source struct instead of file:line
    </p>

    <p><!-- https://go.dev/issue/59282 -->
      TODO: <a href="https://go.dev/issue/59282">https://go.dev/issue/59282</a>: drop only completely empty Attrs
    </p>

    <p><!-- https://go.dev/issue/59339 -->
      TODO: <a href="https://go.dev/issue/59339">https://go.dev/issue/59339</a>: change constructors to NewXXXHandler(io.Writer, *HandlerOptions)
    </p>

    <p><!-- https://go.dev/issue/59345 -->
      TODO: <a href="https://go.dev/issue/59345">https://go.dev/issue/59345</a>: JSONHandler should format everything like json.Marshal
    </p>

    <p><!-- CL 477295 -->
      TODO: <a href="https://go.dev/cl/477295">https://go.dev/cl/477295</a>: log/slog: initial commit; modified api/next/56345.txt
    </p>

    <p><!-- CL 484096 -->
      TODO: <a href="https://go.dev/cl/484096">https://go.dev/cl/484096</a>: log/slog: function argument to Record.Attrs returns bool; modified api/next/59060.txt
    </p>

    <p><!-- CL 486376 -->
      TODO: <a href="https://go.dev/cl/486376">https://go.dev/cl/486376</a>: log/slog: add Source type for source location; modified api/next/59280.txt
    </p>

    <p><!-- CL 486415 -->
      TODO: <a href="https://go.dev/cl/486415">https://go.dev/cl/486415</a>: log/slog: built-in handler constructors take options as a second arg; modified api/next/56345.txt, api/next/59339.txt
    </p>

    <p><!-- CL 487855 -->
      TODO: <a href="https://go.dev/cl/487855">https://go.dev/cl/487855</a>: log/slog: Group takes ...any; modified api/next/56345.txt, api/next/59204.txt
    </p>
  </dd>
</dl><!-- log/slog -->

<dl id="math"><dt><a href="/pkg/math/">math</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56491 -->
      TODO: <a href="https://go.dev/issue/56491">https://go.dev/issue/56491</a>: add Compare and Compare32
    </p>

    <p><!-- CL 459435 -->
      TODO: <a href="https://go.dev/cl/459435">https://go.dev/cl/459435</a>: math: add Compare and Compare32; modified api/next/56491.txt
    </p>

    <p><!-- CL 467515 -->
      TODO: <a href="https://go.dev/cl/467515">https://go.dev/cl/467515</a>: math: add Compare and Compare32; modified api/next/56491.txt
    </p>
  </dd>
</dl><!-- math -->

<dl id="math/big"><dt><a href="/pkg/math/big/">math/big</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56984, CL 453115 -->
      The new <a href="/pkg/math/big/#Int.ToFloat64"><code>Int.ToFloat64</code></a>
      method returns the nearest floating-point value to a
      multi-precision integer, along with an indication of any
      rounding that occurred.
    </p>
  </dd>
</dl><!-- math/big -->

<dl id="net"><dt><a href="/pkg/net/">net</a></dt>
  <dd>
    <p>
      <!-- https://go.dev/issue/59166, https://go.dev/issue/56539 -->
      <!-- CL 471136, CL 471137, CL 471140 -->
      On Linux, the <a href="/pkg/net/">net</a> package can now use
      Multipath TCP when the kernel supports it. It is not used by
      default. To use Multipath TCP when available on a client, call
      the
      <a href="/pkg/net/#Dialer.SetMultipathTCP"><code>Dialer.SetMultipathTCP</code></a>
      method before calling the
      <a href="/pkg/net/#Dialer.Dial"><code>Dialer.Dial</code></a> or
      <a href="/pkg/net/#Dialer.DialContext"><code>Dialer.DialContext</code></a>
      methods. To use Multipath TCP when available on a server, call
      the
      <a href="/pkg/net/#ListenConfig.SetMultipathTCP"><code>ListenConfig.SetMultipathTCP</code></a>
      method before calling the
      <a href="/pkg/net/#ListenConfig.Listen"><code>ListenConfig.Listen</code></a>
      method. Specify the network as <code>"tcp"</code> or
      <code>"tcp4"</code> or <code>"tcp6"</code> as usual. If
      Multipath TCP is not supported by the kernel or the remote host,
      the connection will silently fall back to TCP. To test whether a
      particular connection is using Multipath TCP, use the
      <a href="/pkg/net/#TCPConn.MultipathTCP"><code>TCPConn.MultipathTCP</code></a>
      method.
    </p>
    <p>
      In a future Go release we may enable Multipath TCP by default on
      systems that support it.
    </p>
  </dd>
</dl><!-- net -->

<dl id="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/44855, CL 382117 -->
      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.
    </p>

    <p><!-- CL 472636 -->
      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
    </p>

    <p><!-- CL 494122 -->
      TODO: <a href="https://go.dev/cl/494122">https://go.dev/cl/494122</a>: net/http: let ErrNotSupported match errors.ErrUnsupported; modified api/next/41198.txt
    </p>
  </dd>
</dl><!-- net/http -->

<dl id="os"><dt><a href="/pkg/os/">os</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/32558, CL 219638 -->
      Programs may now pass an empty <code>time.Time</code> value to
      the <a href="/pkg/os/#Chtimes"><code>Chtimes</code></a> function
      to leave either the access time or the modification time unchanged.
    </p>

    <p><!-- CL 480135 -->
      On Windows the
      <a href="/pkg/os#File.Chdir"><code>File.Chdir></a> method
      now changes the current directory to the file, rather than
      always returning an error.
    </p>

    <p><!-- CL 477215 -->
      On Windows calling
      <a href="/pkg/os/#Truncate"><code>Truncate</code></a> on a
      non-existent file used to create an empty file. It now returns
      an error indicating that the file does not exist.
    </p>

    <p><!-- CL 493036 -->
      On Windows the os package now supports working with files whose
      names, stored as UTF-16, can't be represented as valid UTF-8.
    </p>
  </dd>
</dl><!-- os -->

<!-- CL 459455 reverted -->

<dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
  <dd>
    <p><!-- CL 408826, CL 413474 -->
      In Go 1.21, <a href="/pkg/reflect/#ValueOf"><code>ValueOf</code></a>
      no longer forces its argument to be allocated on the heap, allowing
      a <code>Value</code>'s content to be allocated on the stack. Most
      operations on a <code>Value</code> also allow the underlying value
      to be stack allocated.
    </p>

    <p><!-- https://go.dev/issue/55002 -->
      The new <a href="/pkg/reflect/#Value"><code>Value</code></a>
      method <a href="/pkg/reflect/#Value.Clear"><code>Value.Clear</code></a>
      clears the contents of a map or zeros the contents of a slice.
      This corresponds to the new <code>clear</code> built-in
      <a href="#language">added to the language</a>.
    </p>

    <p><!-- https://go.dev/issue/56906, CL 452762 -->
      The <a href="/pkg/reflect/#SliceHeader"><code>SliceHeader</code></a>
      and <a href="/pkg/reflect/#StringHeader"><code>StringHeader</code></a>
      types are now deprecated. In new code
      prefer <a href="/pkg/unsafe/#Slice"><code>unsafe.Slice</code></a>,
      <a href="/pkg/unsafe/#SliceData"><code>unsafe.SliceData</code></a>,
      <a href="/pkg/unsafe/#String"><code>unsafe.String</code></a>,
      or <a href="/pkg/unsafe/#StringData"><code>unsafe.StringData</code></a>.
    </p>
  </dd>
</dl><!-- reflect -->

<dl id="regexp"><dt><a href="/pkg/regexp/">regexp</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/46159, CL 479401 -->
      <a href="/pkg/regexp#Regexp"><code>Regexp</code></a> now defines
      <a href="/pkg/regexp#Regexp.MarshalText"><code>MarshalText</code></a>
      and <a href="/pkg/regexp#Regexp.UnmarshalText"><code>UnmarshalText</code></a>
      methods. These implement
      <a href="/pkg/encoding#TextMarshaler"><code>encoding.TextMarshaler</code></a>
      and
      <a href="/pkg/encoding#TextUnmarshaler"><code>encoding.TextUnmarshaler</code></a>
      and will be used by packages such as
      <a href="/pkg/encoding/json">encoding/json</a>.
    </p>
  </dd>
</dl><!-- regexp -->

<dl id="runtime"><dt><a href="/pkg/runtime/">runtime</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/38651 -->
      TODO: <a href="https://go.dev/issue/38651">https://go.dev/issue/38651</a>: add &#39;created by goroutine number&#39; to stack traces
    </p>

    <p><!-- https://go.dev/issue/57441 -->
      TODO: <a href="https://go.dev/issue/57441">https://go.dev/issue/57441</a>: use WER for GOTRACEBACK=wer on Windows
    </p>

    <p><!-- CL 447778 -->
      TODO: <a href="https://go.dev/cl/447778">https://go.dev/cl/447778</a>: runtime: reimplement GODEBUG=cgocheck=2 as a GOEXPERIMENT
    </p>

    <p><!-- CL 472195 -->
      TODO: <a href="https://go.dev/cl/472195">https://go.dev/cl/472195</a>: runtime: remove NOFRAME from asmcgocall, systemstack and mcall
    </p>

    <p><!-- CL 474915 -->
      TODO: <a href="https://go.dev/cl/474915">https://go.dev/cl/474915</a>: runtime: support GOTRACEBACK=wer on Windows
    </p>

    <p><!-- https://go.dev/issue/46787 -->
      A new type <code>Pinner</code> has been added to the runtime
      package. <code>Pinner</code>s may be used to "pin" Go memory
      such that it may be used more freely by non-Go code. For instance,
      passing Go values that reference pinned Go memory to C code is
      now allowed. Previously, passing any such nested reference was
      disallowed by the
      <a href="https://pkg.go.dev/cmd/cgo#hdr-Passing_pointers">cgo pointer passing rules.</a>

      See <a href="/pkg/runtime#Pinner">the docs</a> for more details.
    </p>
  </dd>
</dl><!-- runtime -->

<dl id="runtime/trace"><dt><a href="/pkg/runtime/trace/">runtime/trace</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/16638 -->
      Collecting traces on amd64 and arm64 now incurs a substantially
      smaller CPU cost: up to a 10x improvement over the previous release.
    </p>

    <p><!-- CL 494495 -->
      Traces now contain explicit stop-the-world events for every reason
      the Go runtime might stop-the-world, not just garbage collection.
    </p>
  </dd>
</dl><!-- runtime/trace -->

<dl id="runtime/metrics"><dt><a href="/pkg/runtime/metrics/">runtime/metrics</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56857 -->
      A few previously-internal GC metrics, such as live heap size, are
      now available.

      <code>GOGC</code> and <code>GOMEMLIMIT</code> are also now
      available as metrics.
    </p>
  </dd>
</dl><!-- runtime/metrics -->

<dl id="sync"><dt><a href="/pkg/sync/">sync</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56102, CL 451356 -->
      The new <a href="/pkg/sync/#OnceFunc"><code>OnceFunc</code></a>,
      <a href="/pkg/sync/#OnceValue"><code>OnceValue</code></a>, and
      <a href="/pkg/sync/#OnceValues"><code>OnceValues</code></a>
      functions capture a common use of <a href="/pkg/sync/#Once">Once</a> to
      lazily initialize a value on first use.
    </p>
  </dd>
</dl>

<dl id="syscall"><dt><a href="/pkg/syscall/">syscall</a></dt>
  <dd>
    <p><!-- CL 480135 -->
      On Windows the
      <a href="/pkg/syscall#Fchdir"><code>Fchdir</code></a> function
      now changes the current directory to its argument, rather than
      always returning an error.
    </p>

    <p><!-- https://go.dev/issue/46259, CL 458335 -->
      On FreeBSD
      <a href="/pkg/syscall#SysProcAttr"><code>SysProcAttr</code></a>
      has a new field <code>Jail</code> that may be used to put the
      newly created process in a jailed environment.
    </p>

    <p><!-- CL 493036 -->
      On Windows the syscall package now supports working with files whose
      names, stored as UTF-16, can't be represented as valid UTF-8.
      The <a href="/pkg/syscall#UTF16ToString"><code>UTF16ToString</code></a>
      and <a href="/pkg/syscall#UTF16FromString"><code>UTF16FromString</code></a>
      functions now convert between UTF-16 data and
      <a href=http://simonsapin.github.io/wtf-8/"">WTF-8</a> strings.
      This is backward compatible as WTF-8 is a superset of the UTF-8
      format that was used in earlier releases.
    </p>
  </dd>
</dl><!-- syscall -->

<dl id="testing"><dt><a href="/pkg/testing/">testing</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/37708, CL 463837 -->
      The new <code>-test.fullpath</code> option will print full path
      names in test log messages, rather than just base names.
    </p>

    <p><!-- https://go.dev/issue/52600, CL 475496 -->
      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>.
    </p>
  </dd>
</dl><!-- testing -->

<dl id="testing/slogtest"><dt><a href="/pkg/testing/slogtest/">testing/slogtest</a></dt>
  <dd>
    <p><!-- CL 487895 -->
      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
    </p>
  </dd>
</dl><!-- testing/slogtest -->

<!-- proposals for x repos that don't need to be mentioned here but
     are picked up by the relnote tool. -->
<!-- https://go.dev/issue/54232 -->
<!-- https://go.dev/issue/57906 -->
<!-- https://go.dev/issue/58668 -->