// AddCleanup attaches a cleanup function to ptr. Some time after ptr is no longer
// reachable, the runtime will call cleanup(arg) in a separate goroutine.
//
-// If ptr is reachable from cleanup or arg, ptr will never be collected
-// and the cleanup will never run. AddCleanup panics if arg is equal to ptr.
+// A typical use is that ptr is an object wrapping an underlying resource (e.g.,
+// a File object wrapping an OS file descriptor), arg is the underlying resource
+// (e.g., the OS file descriptor), and the cleanup function releases the underlying
+// resource (e.g., by calling the close system call).
//
-// The cleanup(arg) call is not always guaranteed to run; in particular it is not
-// guaranteed to run before program exit.
+// There are few constraints on ptr. In particular, multiple cleanups may be
+// attached to the same pointer, or to different pointers within the same
+// allocation.
//
-// Cleanups are not guaranteed to run if the size of T is zero bytes, because
-// it may share same address with other zero-size objects in memory. See
-// https://go.dev/ref/spec#Size_and_alignment_guarantees.
+// If ptr is reachable from cleanup or arg, ptr will never be collected
+// and the cleanup will never run. As a protection against simple cases of this,
+// AddCleanup panics if arg is equal to ptr.
//
// There is no specified order in which cleanups will run.
+// In particular, if several objects point to each other and all become
+// unreachable at the same time, their cleanups all become eligible to run
+// and can run in any order. This is true even if the objects form a cycle.
//
// A single goroutine runs all cleanup calls for a program, sequentially. If a
// cleanup function must run for a long time, it should create a new goroutine.
// If ptr has both a cleanup and a finalizer, the cleanup will only run once
// it has been finalized and becomes unreachable without an associated finalizer.
//
+// The cleanup(arg) call is not always guaranteed to run; in particular it is not
+// guaranteed to run before program exit.
+//
+// Cleanups are not guaranteed to run if the size of T is zero bytes, because
+// it may share same address with other zero-size objects in memory. See
+// https://go.dev/ref/spec#Size_and_alignment_guarantees.
+//
// It is not guaranteed that a cleanup will run for objects allocated
// in initializers for package-level variables. Such objects may be
// linker-allocated, not heap-allocated.
// allocation may never run if it always exists in the same batch as a
// referenced object. Typically, this batching only happens for tiny
// (on the order of 16 bytes or less) and pointer-free objects.
+//
+// A cleanup may run as soon as an object becomes unreachable.
+// In order to use cleanups correctly, the program must ensure that
+// the object is reachable until it is safe to run its cleanup.
+// Objects stored in global variables, or that can be found by tracing
+// pointers from a global variable, are reachable. A function argument or
+// receiver may become unreachable at the last point where the function
+// mentions it. To ensure a cleanup does not get called prematurely,
+// pass the object to the [KeepAlive] function after the last point
+// where the object must remain reachable.
func AddCleanup[T, S any](ptr *T, cleanup func(S), arg S) Cleanup {
// Explicitly force ptr to escape to the heap.
ptr = abi.Escape(ptr)