From acfff428029130654d44b56e80a5e9c7e825e951 Mon Sep 17 00:00:00 2001
From: Michael Anthony Knyszek <mknyszek@google.com>
Date: Sat, 4 Jun 2022 05:42:30 +0000
Subject: [PATCH] doc/go1.19: add release notes for the soft memory limit and
 idle GC

This change resolves some TODOs in the release notes, and while we're
here, also clarifies how CPU profile samples are represented in runtime
traces.

Change-Id: Idaa36ccf65b03fd5463b2d5da682d3fa578d2f46
Reviewed-on: https://go-review.googlesource.com/c/go/+/410356
Reviewed-by: Michael Pratt <mpratt@google.com>
Reviewed-by: Austin Clements <austin@google.com>
---
 doc/go1.19.html | 33 +++++++++++++++++++++++++++++----
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/doc/go1.19.html b/doc/go1.19.html
index 9a689d1980e10..a932a717ba308 100644
--- a/doc/go1.19.html
+++ b/doc/go1.19.html
@@ -82,12 +82,37 @@ <h4 id="go-unix">New <code>unix</code> build constraint</h4>
 
 <h2 id="runtime">Runtime</h2>
 
-<p><!-- https://go.dev/issue/48409 -->
-  TODO: soft memory limit
+<p><!-- https://go.dev/issue/48409 --><!-- CL 397018 -->
+  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 <code>GOMEMLIMIT</code> environment variable or the
+  <code>SetMemoryLimit</code> function in the runtime/debug package. The limit
+  works in conjunction with <code>GOGC</code> and <code>SetGCPercent</code>,
+  and will be respected even if <code>GOGC=off</code>, 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.
+</p>
+
+<p><!-- CL 353989 -->
+  In order to limit the effects of GC thrashing when the program's live heap
+  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
+  <code>/gc/limiter/last-enabled:gc-cycle</code> reports when this last
+  occurred.
 </p>
 
 <p><!-- https://go.dev/issue/44163 -->
-  TODO: idle mark workers
+  The runtime now schedules many fewer GC worker goroutines on idle operating
+  system threads when the application is idle enough to force a periodic GC
+  cycle.
 </p>
 
 <p><!-- https://go.dev/issue/18138 --><!-- CL 345889 -->
@@ -494,7 +519,7 @@ <h3 id="minor_library_changes">Minor changes to the library</h3>
     <p><!-- CL 400795 -->
       When used together with the
       <a href="/pkg/runtime/pprof#StartCPUProfile">CPU profiler</a>, the
-      execution trace includes CPU profile samples.
+      execution trace includes CPU profile samples as instantaneous events.
     </p>
   </dd>
 </dl><!-- runtime/trace -->