runtime: warn that KeepAlive is not an unsafe.Pointer workaround

Even experienced users occasionally mistake that runtime.KeepAlive can
be used as a workaround for following the unsafe.Pointer safety rules,
but it cannot. Add an explicit warning to this effect to dissuade
users from trying to use it as such.

Fixes #47562.

Change-Id: I842e33a3e1c080933c6b1bd1b6318448adbf495c
Reviewed-on: https://go-review.googlesource.com/c/go/+/340269
Trust: Matthew Dempsky <mdempsky@google.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/runtime/mfinal.go b/src/runtime/mfinal.go
index fd318d49a8d20475713b0b0482fb811a79b2fea3..c134a0f22d8e6f49d3b102218b4c92a0d6412437 100644 (file)
--- a/src/runtime/mfinal.go
+++ b/src/runtime/mfinal.go
@@ -466,6 +466,10 @@ okarg:
 // Without the KeepAlive call, the finalizer could run at the start of
 // syscall.Read, closing the file descriptor before syscall.Read makes
 // the actual system call.
+//
+// Note: KeepAlive should only be used to prevent finalizers from
+// running prematurely. In particular, when used with unsafe.Pointer,
+// the rules for valid uses of unsafe.Pointer still apply.
 func KeepAlive(x interface{}) {
        // Introduce a use of x that the compiler can't eliminate.
        // This makes sure x is alive on entry. We need x to be alive