]> Cypherpunks repositories - gostls13.git/commitdiff
runtime: add package doc for checkfinalizer mode
authorMichael Anthony Knyszek <mknyszek@google.com>
Wed, 2 Apr 2025 01:46:45 +0000 (01:46 +0000)
committerGopher Robot <gobot@golang.org>
Tue, 20 May 2025 19:05:59 +0000 (12:05 -0700)
Fixes #72949.

Change-Id: I114eda73c57bc7d596eb1656e738b80c1cbe5254
Reviewed-on: https://go-review.googlesource.com/c/go/+/662039
Reviewed-by: Carlos Amedee <carlos@golang.org>
Reviewed-by: Michael Pratt <mpratt@google.com>
Auto-Submit: Michael Knyszek <mknyszek@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

src/runtime/extern.go

index eb30b0566ecb3661e8f7e5d1237f9dfd467182e0..62dab74bc0ccc3f167fe7e9958df2998ac4a2f89 100644 (file)
@@ -52,6 +52,21 @@ It is a comma-separated list of name=val pairs setting these named variables:
        cgocheck mode can be enabled using GOEXPERIMENT (which
        requires a rebuild), see https://pkg.go.dev/internal/goexperiment for details.
 
+       checkfinalizers: setting checkfinalizers=1 causes the garbage collector to run
+       multiple partial non-parallel stop-the-world collections to identify common issues with
+       finalizers and cleanups, like those listed at
+       https://go.dev/doc/gc-guide#Finalizers_cleanups_and_weak_pointers. If a potential issue
+       is found, the program will terminate with a description of all potential issues, the
+       associated values, and a list of those values' finalizers and cleanups, including where
+       they were created. It also adds tracking for tiny blocks to help diagnose issues with
+       those as well. The analysis performed during the partial collection is conservative.
+       Notably, it flags any path back to the original object from the cleanup function,
+       cleanup arguments, or finalizer function as a potential issue, even if that path might
+       be severed sometime later during execution (though this is not a recommended pattern).
+       This mode also produces one line of output to stderr every GC cycle with information
+       about the finalizer and cleanup queue lengths. Lines produced by this mode start with
+       "checkfinalizers:".
+
        decoratemappings: controls whether the Go runtime annotates OS
        anonymous memory mappings with context about their purpose. These
        annotations appear in /proc/self/maps and /proc/self/smaps as