From 7a82c6859f14d97b741073083849bace7693f7e2 Mon Sep 17 00:00:00 2001 From: Michael Pratt Date: Mon, 6 Jun 2022 17:32:03 -0400 Subject: [PATCH] doc/go1.19: adjust runtime release notes This addresses comments from CL 410356. For #48409. For #51400. Change-Id: I03560e820a06c0745700ac997b02d13bc03adfc6 Reviewed-on: https://go-review.googlesource.com/c/go/+/410735 Run-TryBot: Michael Pratt TryBot-Result: Gopher Robot Reviewed-by: Chris Hines Reviewed-by: Russ Cox --- doc/go1.19.html | 53 +++++++++++++++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 19 deletions(-) diff --git a/doc/go1.19.html b/doc/go1.19.html index 037ea4fec6..2674ad6972 100644 --- a/doc/go1.19.html +++ b/doc/go1.19.html @@ -103,19 +103,26 @@ Do not send CLs removing the interior tags from such phrases.

The runtime now includes support for a soft memory limit. This memory limit - includes all memory mapped and managed by the runtime, and excludes external - memory sources such as binary size, memory managed in other languages, and - memory held by the operating system on behalf of the Go program. This limit - may be managed via the GOMEMLIMIT environment variable or the - SetMemoryLimit function in the runtime/debug package. The limit - works in conjunction with GOGC and SetGCPercent, + includes the Go heap and all other memory managed by the runtime, and + excludes external memory sources such as mappings of the binary itself, + memory managed in other languages, and memory held by the operating system on + behalf of the Go program. This limit may be managed via + runtime/debug.SetMemoryLimit + or the equivalent + GOMEMLIMIT + environment variable. The limit works in conjunction with + runtime/debug.SetGCPercent + / GOGC, and will be respected even if GOGC=off, allowing Go programs to always make maximal use of their memory limit, improving resource efficiency - in some cases. Please note that small memory limits, on the order of tens of - megabytes or less, are less likely to be adhered to due to external latency - factors, such as OS scheduling. See https://go.dev/issue/52433 for more - details. Larger memory limits, on the order of hundreds of megabytes or more, - are stable and production-ready. + in some cases. See the GC guide for + a detailed guide explaining the soft memory limit in more detail, as well as + a variety of common use-cases and scenarios. Please note that small memory + limits, on the order of tens of megabytes or less, are less likely to be + respected due to external latency factors, such as OS scheduling. See + issue 52433 for more details. Larger + memory limits, on the order of hundreds of megabytes or more, are stable and + production-ready.

@@ -123,7 +130,8 @@ Do not send CLs removing the interior tags from such phrases. size approaches the soft memory limit, the Go runtime also attempts to limit total GC CPU utilization to 50%, excluding idle time, choosing to use more memory over preventing application progress. In practice, we expect this limit - to only play a role in exceptional cases, and the new runtime/metrics metric + to only play a role in exceptional cases, and the new + runtime metric /gc/limiter/last-enabled:gc-cycle reports when this last occurred.

@@ -667,20 +675,27 @@ Do not send CLs removing the interior tags from such phrases.
runtime/metrics

- The new /sched/gomaxprocs:threads metric reports the current - runtime.GOMAXPROCS value. + The new /sched/gomaxprocs:threads + metric reports + the current + runtime.GOMAXPROCS + value.

- The new /cgo/go-to-c-calls:calls metric reports the total - number of calls made from Go to C. This metric is identical to the runtime.NumCgoCall + The new /cgo/go-to-c-calls:calls + metric + reports the total number of calls made from Go to C. This metric is + identical to the + runtime.NumCgoCall function.

- The new /gc/limiter/last-enabled:gc-cycle metric reports the - last GC cycle when the GC CPU limiter was enabled. + The new /gc/limiter/last-enabled:gc-cycle + metric + reports the last GC cycle when the GC CPU limiter was enabled. See the + runtime notes for details about the GC CPU limiter.