mirror
/
go
mirror of https://github.com/golang/go.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

runtime: clarify Pinner doc 

Rewrite in idiomatic form, fix a typo, break into paragraph, rephrase
slightly.

Change-Id: If146db86aa84214e61128a3bc3e9905396d44710
Reviewed-on: https://go-review.googlesource.com/c/go/+/498716
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Ansiwen <ansiwen@gmail.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: Michael Knyszek <mknyszek@google.com>
This commit is contained in:
Jonathan Amsterdam 2023-05-27 08:48:31 -04:00
parent 5ad676a7ce
commit c7b2f6494c
1 changed files with 12 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
src/runtime/pinner.go
View File

@ -9,21 +9,25 @@ import (
"unsafe"
)
// Pinner represents a set of pinned Go objects. An object can be pinned with
// A Pinner is a set of pinned Go objects. An object can be pinned with
// the Pin method and all pinned objects of a Pinner can be unpinned with the
// Unpin method.
type Pinner struct {
*pinner
}
// Pin a Go object. The object will not be moved or freed by the garbage
// collector until the Unpin method has been called. The pointer to a pinned
// Pin pins a Go object, preventing it from being moved or freed by the garbage
// collector until the Unpin method has been called.
//
// A pointer to a pinned
// object can be directly stored in C memory or can be contained in Go memory
// passed to C functions. If the pinned object iftself contains pointers to Go
// passed to C functions. If the pinned object itself contains pointers to Go
// objects, these objects must be pinned separately if they are going to be
// accessed from C code. The argument must be a pointer of any type or an
// unsafe.Pointer. It must be a pointer to an object allocated by calling new,
// by taking the address of a composite literal, or by taking the address of a
// accessed from C code.
//
// The argument must be a pointer of any type or an
// unsafe.Pointer. It must be the result of calling new,
// taking the address of a composite literal, or taking the address of a
// local variable. If one of these conditions is not met, Pin will panic.
func (p *Pinner) Pin(pointer any) {
if p.pinner == nil {
@ -59,7 +63,7 @@ func (p *Pinner) Pin(pointer any) {
p.refs = append(p.refs, ptr)
}
// Unpin all pinned objects of the Pinner.
// Unpin unpins all pinned objects of the Pinner.
func (p *Pinner) Unpin() {
p.pinner.unpin()