runtime: documentation update for Pinner

[pjebs]

After reading https://pkg.go.dev/runtime#Pinner, I am unsure (given the risks involved) if I am permitted to reuse a Pinner after calling unpin.

The docs do not elucidate.

[gabyhelp]

Related Issues

• [release-branch.go1.21] runtime: fix Pinner.Pin documentation #64920 (closed)
• doc/go1.23: document runtime.Pinner.Pin change #65326
• runtime: documentation on runtime.Pinner and cgo slightly conflicting or confusing #62380
• runtime: pinner.Pin doesn't panic when it says it will [1.21 backport] #63768 (closed)

Related Code Changes

• runtime: reword the documentation for Pinner

Related Discussions

• Question about runtime.Pinner

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[cherrymui]

cc @golang/runtime

[mknyszek]

Yes, you can definitely reuse a Pinner (the implementation explicitly supports and encourages it).

Sure, we can add a sentence making this clearer.

[CAFxX]

Also would be nice to clarify what happens if a Pinner becomes unreachable before Unpin is called. From the current wording it may sound like all pinned objects leak:

Pin pins a Go object, preventing it from being moved or freed by the garbage collector until the Pinner.Unpin method has been called.

[pjebs]

And it would be nice if documentation explained if it keeps garbage collector at bay in this hypothetical situation (in case garbage collector changes in future versions of Go): https://www.reddit.com/r/golang/comments/1oykk5l/comment/nqg64x0/

[mknyszek]

And it would be nice if documentation explained if it keeps garbage collector at bay in this hypothetical situation (in case garbage collector changes in future versions of Go): https://www.reddit.com/r/golang/comments/1oykk5l/comment/nqg64x0/

I'm really not sure that specific scenario needs to be described so explicitly.

IMO, the answer to that question is already evident from the existing documentation: "Pin pins a Go object, preventing it from being moved or freed by the garbage collector until the Pinner.Unpin method has been called."

"Moved" is the key word here.

[mknyszek]

Also would be nice to clarify what happens if a Pinner becomes unreachable before Unpin is called. From the current wording it may sound like all pinned objects leak:

Good point, the fact that it has a finalizer on it should be documented.

[gopherbot]

Change https://go.dev/cl/726641 mentions this issue: runtime: expand Pinner documentation