proposal: runtime: provide Pinner API for object pinning

[ansiwen]

Update, 2021-10-20: the latest proposal is the API in #46787 (comment).

---

Problem Statement

The pointer passing rules state:

Go code may pass a Go pointer to C provided the Go memory to which it points does not contain any Go pointers.

and

Go code may not store a Go pointer in C memory.

There are C APIs, most notably the iovec based ones for vectored I/O which expect an array of structs that describe buffers to read to or write from. The naive approach would be to allocate both the array and the buffers with C.malloc() and then either work on the C buffers directly or copy the content to Go buffers. In the case of Go bindings for a C API, which is assumably the most common use case for Cgo, the users of the bindings shouldn't have to deal with C types, which means that all data has to be copied into Go allocated buffers. This of course impairs the performance, especially for larger buffers. Therefore it would be desirable to have a safe possibility to let the C API write directly into the Go buffers. This, however, is not possible because

• either the buffer array is allocated in C memory, but then the pointers of the Go buffers can't be stored in it. (Storing Go pointers in C memory is forbidden.)
• or the buffer array is allocated in Go memory and the Go buffer pointers are stored in it. But then the pointer to that buffer array can't be passed to a C function. (Passing a Go pointer that points to memory containing other Go pointers to a C function is forbidden.)

Obviously, what is missing is a safe way to pin an arbitrary number of Go pointers in order to store them in C memory or in passed-to-C Go memory for the duration of a C call.

Workarounds

Break the rules and store the Go pointer in C memory

(click)

with something like

IovecCPtr.iov_base = unsafe.Pointer(myGoPtr)

but GODEBUG=cgocheck=2 would catch that.

However, you can circumvent cgocheck=2 with this casting trick:

*(*uintptr)(unsafe.Pointer(&IovecCPtr.iov_base)) = uintptr(myGoPtr)

This might work, as long as the GC is not moving the pointers, which might be a fact as of now, but is not guaranteed.

Break the rules and hide the Go pointer in Go memory

(click)

with something like

type iovecT struct {
  iov_base uintptr
  iov_len  C.size_t
}
iovec := make([]iovecT, numberOfBuffers)
for i := range iovec {
  bufferPtr := unsafe.Pointer(&bufferArray[i][0])
  iovec[i].iov_base = uintptr(bufferPtr)
  iovec[i].iov_len = C.size_t(len(bufferArray[i]))
}
n := C.my_iovec_read((*C.struct_iovec)(unsafe.Pointer(&iovec[0])), C.int(numberOfBuffers))

Again: This might work, as long as the GC is not moving the pointers. GODEBUG=cgocheck=2 wouldn't complain about this.

Break the rules and temporarily disable cgocheck

(click)

If hiding the Go pointer as a uintptr like in the last workaround is not possible, passing Go memory that contains Go pointers usually bails out because of the default cgocheck=1 setting. It is possible to disable temporarily cgocheck during a C call, which can especially useful, when the pointer have been "pinned" with one of the later workarounds. For example the _cgoCheckPtr() function, that is used in the generated Cgo code, can be shadowed in the local scope, which disables the check for the following C calls in the scope:

func ... {
  _cgoCheckPointer := func(interface{}, interface{}) {}
  C.my_c_function(x, y)
}

Maybe slightly more robust, is to export the runtime.dbgvars list:

type dbgVar struct {
	name  string
	value *int32
}

//go:linkname dbgvars runtime.dbgvars
var dbgvars []dbgVar

var cgocheck = func() *int32 {
	for i := range dbgvars {
		if dbgvars[i].name == "cgocheck" {
			return dbgvars[i].value
		}
	}
	panic("Couln't find cgocheck debug variable")
}()

func ... {
	before := *cgocheck
	*cgocheck = 0
	C.my_c_function(x, y)
	*cgocheck = before
}

Use a C function to store the Go pointer in C memory

(click)

The rules allow that a C function stores a Go pointer in C memory for the duration of the call. So, for each Go pointer a C function can be called in a Go routine, that stores the Go pointer in C memory and then calls a Go function callback that waits for a release signal. After the release signal is received, the Go callback returns to the C function, the C function clears the C memory from the Go pointer, and returns as well, finishing the Go routine.

This approach fully complies with the rules, but is quite expensive, because each Go routine that calls a C function creates a new thread, that means one thread per stored Go pointer.

Use the //go:uintptrescapes compiler directive

(click)

//go:uintptrescapes is a compiler directive that

specifies that the function's uintptr arguments may be pointer values that have been converted to uintptr and must be treated as such by the garbage collector.

So, similar to the workaround before, a Go function with this directive can be called in a Go routine, which simply waits for a release signal. When the signal is received, the function returns and sets the pointer free.

This seems already almost like a proper solution, so that I implemented a package with this approach, that allows to Pin() a Go pointer and Poke() it into C memory: PtrGuard

But there are still caveats. The compiler and the runtime (cgocheck=2) don't seem to know about which pointers are protected by the directive, because they still don't allow to pass Go memory containing these Go pointers to a C function, or to store the pointers in C memory. Therefore the two first workarounds are additionally necessary. Also there is the small overhead for the Go routine and the release signalling.

Proposal

It would make Cgo a lot more usable for C APIs with more complex pointer handling like iovec, if there would be a programmatic way to provide what //go:uintptrescapes provides already through the backdoor. There should be a possibility to pin an arbitrary amount of Go pointers in the current scope, so that they are allowed to be stored in C memory or be contained in Go memory that is passed to a C function within this scope, for example with a runtime.PtrEscapes() function. It's cumbersome, that it's required to abuse Go routines, channels and casting tricks in order provide bindings to such C APIs. As long as the Go GC is not moving pointers, it could be a trivial implementation, but it would encapsulate this knowledge and would give users a guarantee.

I know from the other issues and discussions around this topic that it's seen as dangerous if it is possible to pin an arbitrary amount of pointers. But

1. it is possible to call an arbitrary amount of C or //go:uintptrescapes functions, therefore it is also possible to pin arbitrary amount of Go pointers already.
2. it is necessary for some C APIs

Related issues: #32115, #40431

/cc @ianlancetaylor @rsc @seebs

edit: the first workaround had an incorrect statement.
edit 2: add workarounds for disabling cgocheck

[DeedleFake]

From what I can tell from the documentation for the new cgo.Handle, it's intended only for a situation where a pointer needs to be passed from Go to C and then back to Go without the C code doing anything with what it points to. As it passes a handle ID, not a real pointer, the C code can't actually get access to the actual data. Maybe a function could be provided on the C side that takes a handle ID and returns the original pointer, thus allowing the C code to access the data? Would that solve this issue?

Edit: Wait, that doesn't make sense. Could you just use Handle to make sure that it's held onto? Could the definition of Handle be extended to mean that the pointer itself is valid for the duration of the Handle's existence? In other words, this would be defined to be valid:

// void doSomethingWithAPointer(int *a);
import "C"

func main() {
  v := C.int(3)
  h := cgo.NewHandle(&v)
  doSomethingWithAPointer(&v) // Safe because the handle exists for that pointer.
  h.Delete()
}

Alternatively, if that's not feasible, what about a method on Handle that returns a valid pointer for the given value?

// Pointer returns a C pointer that points to the underlying value of the handle
// and is valid for the life of the handle.
func (h Handle) Pointer() C.uintptr_t

Disclaimer: I'm not familiar enough with the internals of either the Go garbage collector or Cgo to know if either of these even make sense.

[ansiwen]

@DeedleFake As you pointed out yourself, the cgo.Handle has a very different purpose. It's just a registry for a map from a C compatible arbitrary ID (uintptr) to an arbitrary Go value. It's purpose is to refer to a Go value in the C world, not to access it from there. It doesn't affect the behavior of the garbage collector, which could still freely move around the values in the Handle map, and would never delete them, since they are referenced by the map.

[ianlancetaylor]

An big advantage of the current cgo mechanisms, including go:uintptrescapes, is that the pointers are automatically unpinned when the cgo function returns. As far as I can see you didn't propose any particular mechanism for pinning pointers, but it would be very desirable to somehow ensure that the pointers are unpinned. Otherwise code could easily get into scenarios in which pointers remain pinned forever, which if Go ever implements a full moving garbage collector will cause the garbage collector to silently behave quite poorly. In other words, some APIs that could solve this problem will be be footguns: code that can easily cause a program to silently behave badly in ways that will be very hard to detect.

It's hard to say more without a specific API to discuss. If you suggested one, my apologies for missing it.

[ansiwen]

@ianlancetaylor thanks for taking the time to answer.

An big advantage of the current cgo mechanisms, including go:uintptrescapes, is that the pointers are automatically unpinned when the cgo function returns.

I agree, that is an advantage. However, with go routines it's trivial to fire-and-forget thousands of such function calls, that never return.

As far as I can see you didn't propose any particular mechanism for pinning pointers, but it would be very desirable to somehow ensure that the pointers are unpinned. Otherwise code could easily get into scenarios in which pointers remain pinned forever, which if Go ever implements a full moving garbage collector will cause the garbage collector to silently behave quite poorly. In other words, some APIs that could solve this problem will be be footguns: code that can easily cause a program to silently behave badly in ways that will be very hard to detect.

I didn't describe a specific API, that's true. I hoped that this could be developed here together once we agreed on the requirements. One of the requirements that I mentioned was, that the pinning happens only for the current scope. That implies automatic unpinning when the scope is left. Sorry that I didn't make that clear enough. So, to rephrase more compactly, the requirements would be:

• possibility to pin pointers in the current scope (exactly as if they would be the argument of a C function call)
• automatic unpinning when the current scope is left (the current function returns)
• cgocheck knows about the pinning and does not complain

It's hard to say more without a specific API to discuss. If you suggested one, my apologies for missing it.

As stated above, I didn't want to suggest a specific API, but characteristics of it. In the end it could be a function like runtime.PtrEscapes(unsafe.Pointer). The usage could look like this:

func ReadFileIntoBufferArray(f *os.File, bufferArray [][]byte) int {
  numberOfBuffers := len(bufferArray)

  iovec := make([]C.struct_iovec, numberOfBuffers)

  for i := range iovec {
    bufferPtr := unsafe.Pointer(&bufferArray[i][0])
    runtime.PtrEscapes(bufferPtr) // <- pins the pointer and makes it known to escape to C
    iovec[i].iov_base = bufferPtr
    iovec[i].iov_len = C.size_t(len(bufferArray[i]))
  }

  n := C.readv(C.int(f.Fd()), &iovec[0], C.int(numberOfBuffers))
  // ^^^ cgocheck doesn't complain, because Go pointers in iovec are pinned
  return int(n) // <- all pinned pointers in iovec are unpinned
}

As long as the GC is not moving, runtime.PtrEscapes() is almost a no-op, it would basically only tell cgocheck not to bail out for these pointers. But users would have a guarantee, that if the GC becomes moving later, this function will take care of it.

Regarding footguns I'm pretty sure, that the workarounds, that have to be used at the moment to solve these problems, will cause more "programs to silently behave badly" than the potential abuse of a proper pinning method.

[bcmills]

it would be very desirable to somehow ensure that the pointers are unpinned

Drawing from runtime.KeepAlive, one possibility might be something like:

package runtime

// Pin prevents the object to which p points from being relocated until
// the returned PointerPin either is unpinned or becomes unreachable.
func Pin[T any](p *T) PointerPin

type PointerPin struct {…}
func (p PointerPin) Unpin() {}

Then the example might look like:

func ReadFileIntoBufferArray(f *os.File, bufferArray [][]byte) int {
	numberOfBuffers := len(bufferArray)

	iovec := make([]C.struct_iovec, numberOfBuffers)

	for i := range iovec {
		bufferPtr := unsafe.Pointer(&bufferArray[i][0])
		defer runtime.Pin(bufferPtr).Unpin()
		iovec[i].iov_base = bufferPtr
		iovec[i].iov_len = C.size_t(len(bufferArray[i]))
	}

	n := C.readv(C.int(f.Fd()), &iovec[0], C.int(numberOfBuffers))
	return int(n)
}

A vet warning could verify that the result of runtime.Pin is used, to ensure that it is not accidentally released too early (see also #20803).

[phlogistonjohn]

@ansiwen when you write "automatic unpinning when the current scope is left (the current function returns)" the current scope you refer to is the scope of the Go function correct? In your example that would be ReadFileIntoBufferArray.
I'm trying to double check what the behavior would be regarding if we needed to make multiple calls into C using the same pointer.

@bcmills version also looks very natural flowing to me, and in that version it's clear that the pointer would be pinned until the defer at the end of ReadFileIntoBufferArray.

[ansiwen]

@ansiwen when you write "automatic unpinning when the current scope is left (the current function returns)" the current scope you refer to is the scope of the Go function correct? In your example that would be ReadFileIntoBufferArray.

@phlogistonjohn Yes, exactly.

@bcmills version also looks very natural flowing to me, and in that version it's clear that the pointer would be pinned until the defer at the end of ReadFileIntoBufferArray.

Yes, I also would prefer @bcmills version from a user's perspective, because it's more explicit and it's basically the same API that we use with PtrGuard.

I just don't know enough about the implications on the implementation side and effects on the Go internals, so I don't know what API would be more feasible. My proposal is about providing an official way to solve the described problem. I really don't care so much about the "form", that is how exactly the API looks like. Whatever works best with the current Go and Cgo implementation. 😊

[ansiwen]

@bcmills I guess, an argument @ianlancetaylor might bring up against your API proposal is, that it would allow to store the PointerPin value in a variable and keep them pinned for an unlimited time, so it would not "ensure that the pointers are unpinned". If the unpinning is implicit, it is more comparable to //go:uintptrescapes.

[ansiwen]

@ianlancetaylor

it would be very desirable to somehow ensure that the pointers are unpinned.

So, if you want to enforce the unpinning, the only strict RAII pattern in Go that I could come up with is using a scoped constructor like this API:

package runtime

// Pinner is the context for pinning pointers with Pin()
// can't be copied or constructed outside a Pinner scope
type Pinner struct {…}

// Pin prevents the object to which p points from being relocated until
// Pinner becomes invalid.
func (Pinner) Pin(p unsafe.Pointer) {...}

func WithPinner(func(Pinner)) {...}

which would be used like this:

func ReadFileIntoBufferArray(f *os.File, bufferArray [][]byte) int {
    numberOfBuffers := len(bufferArray)
    
    iovec := make([]C.struct_iovec, numberOfBuffers)

    var n C.ssize_t
    runtime.WithPinner(func (pinner runtime.Pinner) {
        for i := range iovec {
            bufferPtr := unsafe.Pointer(&bufferArray[i][0])
            pinner.Pin(bufferPtr)
            iovec[i].iov_base = bufferPtr
            iovec[i].iov_len = C.size_t(len(bufferArray[i]))
        }
        
        n = C.readv(C.int(f.Fd()), &iovec[0], C.int(numberOfBuffers))
    }) // <- All pinned pointers are released here and pinner is invalidated (in case it's copied out of scope).
    return int(n)
}

I personally would prefer a thinner API, where either it must be explicitly unpinned, like in the proposal of @bcmills, or - even better - the pinning implicitly creates a defer for the scope in which the pinning function has been called from. Given, that this will be implemented in the runtime package, I guess there are tricks and magic that can be used there.

[Merovius]

@ansiwen Even with the func API you suggest, a user might store the argument in a closed-over variable, to have it survive the function. In general, as long as the pin is represented by some value, we can't prevent that value from being kept around. So I don't think your version has significant safety-benefits as to compared to @bcmills, while being less wieldy and also potentially heavier in runtime cost (the closure might make it easier for things to escape).

Personally, as long as the PointerPin has to be intentionally kept around, I think that's fine. I think the suggestion to unpin when the PointerPin becomes unreachable already makes it sufficiently hard to shoot yourself in the foot to tolerate the risk. And we might be able to use go vet for additional safety (like warning if the result of Pin is assigned to a global var or something).

[ansiwen]

@Merovius

@ansiwen Even with the func API you suggest, a user might store the argument in a closed-over variable, to have it survive the function. In general, as long as the pin is represented by some value, we can't prevent that value from being kept around. So I don't think your version has significant safety-benefits as to compared to @bcmills, while being less wieldy and also potentially heavier in runtime cost (the closure might make it easier for things to escape).

The "keeping-around" can easily be prevented by one pointer indirection that get's invalidated when the scope is left. You can have a look at my implementation of PtrGuard that even has test case for exactly the case of a scope escaping variable.

Personally, as long as the PointerPin has to be intentionally kept around, I think that's fine. I think the suggestion to unpin when the PointerPin becomes unreachable already makes it sufficiently hard to shoot yourself in the foot to tolerate the risk. And we might be able to use go vet for additional safety (like warning if the result of Pin is assigned to a global var or something).

Yeah, I agree, as I wrote before, I'm totally fine with both. It's just something I came up with to address @ianlancetaylor's concerns. I also think that the risks are "manageable", there are all kinds of other risks when dealing with runtime and/or unsafe packages after all.

[beoran]

I think that the API proposed by @bcmills is the most useful one. Although there is a risk of forgetting to unpin a pointer, once Go gets a moving garby collector, for certain low level uses, certain blocks of memory will have to stay pinned for the duration of the program. Certainly for system calls in Linux, such as for the frame buffers. In other words, Pin and Unpin are also useful without cgo.

[hnes]

Hi @rsc, any updates on this issue recently? I noticed it has been several days after the 2021-08-04's review meeting minutes.

[rsc]

The compiler/runtime team has been talking a bit about this but don't have any clear suggestions yet.

The big problem with pinning is that if we ever want a moving garbage collector in the future, pins will make it much more complex. That's why we've avoided it so far.

/cc @aclements

[ansiwen]

The big problem with pinning is that if we ever want a moving garbage collector in the future, pins will make it much more complex. That's why we've avoided it so far.

@rsc But my point in the description was, that we have pinning already when C functions are called with Go pointers or when the //go:uintptrescapes directive is used. So the situation is complex already, isn't it?

[beoran]

@rsc I would say the converse is also true. If you are going to implement a moving garbage collector without support for pinning, that will make it much more complex to use Go for certain direct operating calls without cgo, e.g. on Linux.
In other words, as @ansiwen says, there's really no way to avoid that complexity. And therefore I think it would be better if Go supported it explicitly than through workarounds.

[ianlancetaylor]

Unbounded pinning has the potential to be significantly worse than bounded pinning. If people accidentally or intentionally leave many pointers pinned, that can fragment the spaces that the GC uses, and make it very hard for a moving GC to make any progress at all. This can in principle happen with cgo today, but it is unlikely that many programs pass a bunch of pointers to a cgo function that never returns. When programmers control the pinning themselves, bugs are more likely. If the bug is in some imported third party library, the effect will be strange garbage collection behavior for the overall program. This will be hard to understand and hard to diagnose, and it will be hard to find the root cause. (One likely effect will be a set of tools similar to the memory profiler that track pinned pointers.)

It's also worth noting that we don't have a moving garbage collector today, so any problems that pinned pointers may introduce for a moving garbage collector will not be seen today. So if we ever do introduce a moving garbage collector, we will have a flag day of hard-to-diagnose garbage collection problems. This will make it that much harder to ever change the garbage collector in practice.

So I do not think the current situation is nearly as complex as the situation would be if we add unbounded pinning. This doesn't mean that we shouldn't add unbounded pinning. But I think that it does mean that the argument for it has to be something other than "we can already pin pointers today."

[beoran]

@ianlancetaylor That is fair enough. But then it seems to me the best way ahead is to put this issue on hold until we can implement a prototype moving garbage collector.

There is always a workaround if there is no pinning available and that is to manually allocate memory directly from the OS so the GC doesn't know about it. It is not ideal but it can work.

[egonelbre]

Yeah, one workaround that is missing from the discussion is hiding the C api allocation concerns, e.g. iovec could be implemented like:

package iovec

type Buffers struct {
	Data [][]byte

	data *C.uint8_t
	list *C.iovecT
}

func NewBuffers(sizes []int) *Buffers {
	...
	// C.malloc everything
	// cast from *C.uint8_t to []byte
}

func (buffers *Buffers) ReadFrom(f *os.File) error { ...

Or in other words, from the problem statement, it's unclear why it's required to use bufferArray [][]byte as the argument.

[ansiwen]

@ianlancetaylor

So I do not think the current situation is nearly as complex as the situation would be if we add unbounded pinning. This doesn't mean that we shouldn't add unbounded pinning. But I think that it does mean that the argument for it has to be something other than "we can already pin pointers today."

Let's separate the two questions "pinning yes/no" and "pinning bounded/unbounded".

pinning yes/no

I also proposed

1. an API that allows bounded pinning (runtime.WithPinner()).
2. the potential possibility of a runtime.Pin() with no return value and an implicit defer that automatically gets unpinned when the current function returns.

Both provide a similar behaviour as the //go:uintptrescapes directive, if that is what you mean with "bounded". What do you think of these options?

pinning bounded/unbounded

1. when we will have a moving GC, there will always be also a possibility to pin pointer or pause the moving, so this needs to be implemented in any case. Is this correct?
2. when people leave pointers pinned, the GC will behave like a non-moving GC, so there is no regression beyond our current status-quo, right? So, what exactly do you mean with "hard-to-diagnose garbage collection problems"?
3. would the risk of many unpinned pointers not be similar to that of memory leaks, like with global dynamic data structures, that are possible now? I know, memory fragmentation is potentially worse than just allocating memory, but the effect would be similar: OOM errors.

For me personally the first question is more important. Bounded or unbounded, I think the existing and required ways of pinning should be made less hacky in their usage.

@egonelbre

Or in other words, from the problem statement, it's unclear why it's required to use bufferArray [][]byte as the argument.

The bufferArray [][]byte is just a placeholder for an arbitrary "native Go data structure". As the problem statement mentions, the goal is to avoid copying of the data. Especially vectored I/O is used for big amounts of data, so depending on the use case, you can't choose the target data structure by yourself, but it is provided by another library that you intend to use (let's say video processing for example). That would mean, that in all these cases you have to copy the data from your own C allocated data structure to the Go-allocated target data structure of your library, for no good reason.

[ianlancetaylor]

when we will have a moving GC, there will always be also a possibility to pin pointer or pause the moving, so this needs to be implemented in any case. Is this correct?

In some manner, yes.

when people leave pointers pinned, the GC will behave like a non-moving GC, so there is no regression beyond our current status-quo, right? So, what exactly do you mean with "hard-to-diagnose garbage collection problems"?

A GC that is based on moving pointers is not the same as a GC that does not move pointers. A GC based on moving pointers may be completely blocked by a pinned pointer, whereas for a non-moving GC a pinned pointer is just the same as a live pointer.

would the risk of many unpinned pointers not be similar to that of memory leaks, like with global dynamic data structures, that are possible now? I know, memory fragmentation is potentially worse than just allocating memory, but the effect would be similar: OOM errors.

Same answer.

Again, all I am saying is that arguments based on "we already support pinned pointers, so it's OK to add more" are not good arguments. We need different arguments.

[hnes]

How would we deal with the iovec struct during vectored I/O syscall if we have a GC that is based on moving pointers? Maybe the same solution could also be applied to the pointer pinning we are discussing?

A GC based on moving pointers may be completely blocked by a pinned pointer.

I'm afraid that would badly impact the GC latency or something else if it is true. Please consider the disk i/o syscall that may block a very long time.

[ansiwen]

@ianlancetaylor

when we will have a moving GC, there will always be also a possibility to pin pointer or pause the moving, so this needs to be implemented in any case. Is this correct?

In some manner, yes.

when people leave pointers pinned, the GC will behave like a non-moving GC, so there is no regression beyond our current status-quo, right? So, what exactly do you mean with "hard-to-diagnose garbage collection problems"?

A GC that is based on moving pointers is not the same as a GC that does not move pointers. A GC based on moving pointers may be completely blocked by a pinned pointer, whereas for a non-moving GC a pinned pointer is just the same as a live pointer.

Since you agreed that the pinning is required in the answer before, I don't understand how such an implementation could be used in Go.

Again, all I am saying is that arguments based on "we already support pinned pointers, so it's OK to add more" are not good arguments. We need different arguments.

I don't think "add more" is the right wording. It's more about exposing the pinning in a better way. And these are not arguments for doing it, but arguments against the supposed risks of doing it.

The argument for doing it should be clear by now: give people a zero-copy way to use APIs like iovec with Go data structures in a future proof way. At the moment, that's not possible.

In your answers you skipped the first part about the bounded pinning. If you have the time to comment on these too, I would be very interested. 😊

[ianlancetaylor]

Since you agreed that the pinning is required in the answer before, I don't understand how such an implementation could be used in Go.

The current system for pinning pointers doesn't permit pointers to be pinned indefinitely, if we discount the unusual case of a C function that does not return.

I agree that other systems that somehow ensure that pointers can't be pinned indefinitely are better. (I don't think that an implicit defer is a good approach for Go, though.)

[aclements]

@dot-asm, you're right that cgo already has pinning behavior. There's been some discussion of this above. It's spread across various comments, but this one is probably the most relevant.

"Go memory to which it points does not contain any Go pointers" is about both pinning and mutability. By surfacing the Go pointers clearly as cgo call arguments, the runtime has a clear place to hook automatic pinning (and unpinning). If we allow passing pointers to pointers, then the runtime may have to recursively traverse these data structures to pin all of the pointers they contain.

[ianlancetaylor]

@dot-asm There is a lot of background at https://go.googlesource.com/proposal/+/refs/heads/master/design/12416-cgo-pointers.md .

[dot-asm]

If we allow passing pointers to pointers, then the runtime may have to recursively traverse these data structures to pin all of the pointers they contain.

Here is the concern. There is unsafe interface and people shall use it each time they have a problem to solve. This is obviously suboptimal and arguably straight off unsustainable. And what you say above is that the recursion is unsustainable too. But this kind of asks for compromise, i.e. can we discuss and agree on which is less unsustainable? ;-) Or maybe you can compromise and support just one level of indirection? And specifically in a slice (as opposed to lists or something)?

Here I want to again apologize for a possible side track. Feel free to ignore, since it might be just my struggle:-) Anyway, I'd like to suggest to consider following a.go snippet

package foo

type iovec struct {
   base *byte
   len int
}

func bar(iov []iovec) {
   for i := range iov {
       *iov[i].base += 1
   }
}

and examine output from go tool compile -S a.go. We'll see that the inner loop looks as following:

        0x0009 00009 (a.go:10)  MOVQ    CX, DX
        0x000c 00012 (a.go:10)  SHLQ    $4, CX
        0x0010 00016 (a.go:10)  MOVQ    (AX)(CX*1), SI
        0x0014 00020 (a.go:10)  MOVBLZX (SI), DI
        0x0017 00023 (a.go:10)  INCL    DI
        0x0019 00025 (a.go:10)  MOVB    DIB, (SI)
        0x001c 00028 (a.go:9)   LEAQ    1(DX), CX
        0x0020 00032 (a.go:9)   CMPQ    BX, CX
        0x0023 00035 (a.go:9)   JGT     9

Essential to note that this is pretty much how the corresponding C subroutine would look like (when given &iov[0] as argument). More specifically as if no buffers are moved during its execution. But this is Go binary code, not C. In other words there are times when buffers appear pinned even to Go code(*). So that if a C call was made instead of the loop, things would just work out naturally (provided that immutability contract is honoured of course). Or is it so that C calls are not as straightforward as one would naively imagine and leave Go caller in a state that allows for the garbage collector to intervene? If so, then yes, explicit pinning would be in demand. Though at the same time one can probably argue that there is sufficient metadata available to arrange implicit one, at least in some specific cases... Or maybe one can arrange an option for application to tell runtime "treat this C call as if it's a tight loop in Go [similar to above]" so that garbage collector is held back? At least I for one would argue that it would be better option than having to resort for unsafe interface...

(*) My understanding is that this is the time prior the write-barrier thing is checked upon. But even after the barrier passed, and garbage collector is executed in parallel, it won't be free to move buffers as long as such loops are executed elsewhere, right? Is it safe to assume that movements would have to be performed during another stop-the-world?

[rsc]

@aclements it sounds like you are advocating for:

package runtime

type Pinner struct { ... }
func (p *Pinner) Pin(object interface{})
func (p *Pinner) Unpin()

which would get used as

var p runtime.Pinner
defer p.Unpin()
for lots of things {
    p.Pin(thing)
}

Is that right?

[Updated 10/20 - changed Pinned to Pinner.]
[Updated 10/25 - changed one last Pinned to Pinner.]

[aclements]

@rsc exactly (maybe it should be Pinner? but whatever)

@dot-asm, I think, at a high level, it's important to recognize that the Go runtime and the compiler are in cahoots here. The generated code can look like that because the compiler knows heap objects won't move and because it generates metadata telling the runtime how to find the pointers being manipulated by that code. The GC could in fact intervene during that code snippet, but the runtime and compiler have a contract that makes that safe (for example, the GC promises not to move the stack in the middle of that snippet, though at other times it can). If the GC moved heap objects, or were generational, etc, the compiler would have to produce different code. (Regarding your footnote, it is possible to have a moving GC that does not stop the world. For example, some of the early work on this was done by the very Rick Hudson who built Go's concurrent garbage collector.)

[balasanjay]

I'd also like to see some thought given in the API docs to reusing a runtime.Pinned instance multiple times, for GC efficiency.

As an example, I assume when we use this for low-level things (like io_uring) where performance matters, I imagine we'd want to reuse the actual submissions themselves, and presumably the submission struct would include a runtime.Pinned instance to keep stuff alive/pinned while a submission is pending in the kernel. Is that ok?

[dot-asm]

First of all, thanks! 👍

... it is possible to have a moving GC that does not stop the world.

But at the very least it would have to preempt the thread that works the objects to be moved(*). Then wouldn't it mean that making a goroutine in cgo call non-preemptable effectively pins its working set? If so, can it be offered as [a] run-time option for developer to opt for?

Anyway, could you straighten up one thing? Is it correct understanding that currently Go GC is not moving? So that the suggestion in question is rather about future possibilities?

With this in mind I wonder if unsafe.Pointer would make any sense. I mean it sounds like pinning would have to supersede unsafe.Pointer. But then what would it mean for backward compatibility? Maybe making unsafe.Pointer automatically pinned behind the curtains would be [a] better path forward?

(*) Well, it might be possible to pull it off with transactional memory, but it's not an universal option, hence we don't consider it.

[ianlancetaylor]

But at the very least it would have to preempt the thread that works the objects to be moved(*).

That is not the only approach, and while I am not an expert it doesn't strike me as a likely approach. I think a more likely approach is an optional read barrier, just as we already have an optional write barrier. If the read barrier is turned on, then memory loads from the heap would be coordinated with the GC.

Is it correct understanding that currently Go GC is not moving? So that the suggestion in question is rather about future possibilities?

That is correct: the current Go GC does not move objects. What we are discussing here is an API that will not prevent us from doing that in the future.

With this in mind I wonder if unsafe.Pointer would make any sense. I mean it sounds like pinning would have to supersede unsafe.Pointer. But then what would it mean for backward compatibility? Maybe making unsafe.Pointer automatically pinned behind the curtains would be [a] better path forward?

I'm not sure what you mean here. From the GC perspective an unsafe.Pointer is exactly like any other pointer. If we have a moving GC, then whatever we do to make ordinary pointers work will also work for unsafe.Pointer.

[dot-asm]

If the read barrier is turned on, then memory loads from the heap would be coordinated with the GC.

And the only way to coordinate the sample I suggested would be to claim a mutex in each iteration of the inner loop and block GC on it. I reckon it would be too costly. It would be more efficient to simply give control to GC upon barrier check and assume that when control is regained all the dust is settled. It can count as "preemption" too, a cooperative one.

I'm not sure what you mean here. [with unsafe.Pointer vs. pinning]

My view is probably skewed, but in my mind unsafe.Pointer is exclusively about passing it to outside Go. At least Go itself has no use for it, right? Now, this means that whenever we convert a pointer to unsafe, we actually assume that the object is not garbage-collected nor moved. And I'd argue that the last part of this assumed contract is sufficiently "natural" to commit to implicitly. So why would one need an additional interface to meet a requirement that is assumed to be met already? Or conversely, if there is a pinning interface, what would we need unsafe.Pointer for? Which is why I view it as unsafe.Pointer vs. pinning. With preference for former for better backward compatibility. (Yeah, I know, who am I to judge? Just a cent, feel free to ignore:-)

[kortschak]

in my mind unsafe.Pointer is exclusively about passing it to outside Go. At least Go itself has no use for it, right? Now, this means that whenever we convert a pointer to unsafe, we actually assume that the object is not garbage-collected nor moved.

unsafe.Pointer is used in many situations where no Cgo is involved.

[dot-asm]

unsafe.Pointer is used in many situations where no Cgo is involved.

OK. Can you give an example in which unsafe.Pointer would not be assumed to be pinned?

[kortschak]

In the context of the project, in the runtime, unsafe.Pointer conversion shows up >1500 times, an example is in the map iteration type which you would not expect to pin parts. Outside the project, I use unsafe regularly for type punning with no intention that the value be pinned.

[dot-asm]

Cool! Thanks! While it does address the "exclusively" part in the original "exclusively about passing it to outside Go," I don't feel that it invalidates the point I'm trying to get across. Indeed, let's flip the question and ask if there are occasions when you'd need to pin an object without having to pass its pointer to outside Go? If no, then wouldn't it be better if pinning was implicit, again, for backward compatibility sake. As mentioned earlier by @aclements, compiler and runtime are in cahoots, and it should be possible to figure it out. When pinning would be necessary, foremost in cgo call, and just make the arrangements behind the curtains that is... Just a thought...

Thoughts are going all over the place and it's late hour for me... But as for "behind the curtains" part. Can we at least agree that pinning of objects not containing Go pointers will remain implicit in cgo call? (Yeah, it's kind of "selfish" question, apologies for that:-)

[ianlancetaylor]

And the only way to coordinate the sample I suggested would be to claim a mutex in each iteration of the inner loop and block GC on it.

That turns out not to be the case. With both a read and a write barrier, there is no need for a mutex that blocks GC. A read barrier is certainly a performance cost. But it's not a mutex and it doesn't prevent parallel execution by the program and the GC.

ask if there are occasions when you'd need to pin an object without having to pass its pointer to outside Go?

I don't know of any. But note that "outside Go" isn't restricted to cgo. For example, using io_uring in Go programs.

wouldn't it be better if pinning was implicit, again, for backward compatibility sake

Certainly pointers passed directly to cgo are going to remain pinned. Otherwise, as you suggest, we would lose backward compatibility. What we are discussing here is pointers passed indirectly to cgo, or pointers that need to be pinned for other reasons.

[dot-asm]

Certainly pointers passed directly to cgo are going to remain pinned. Otherwise, as you suggest, we would lose backward compatibility.

Fantastic! Keep this thought;-)

What we are discussing here is pointers passed indirectly to cgo, or pointers that need to be pinned for other reasons.

Yes, absolutely! And with this in mind let's ask ourselves how does it work now? You invoke some unsafe magic and it works, works 100% reliably, as long as a) the other side, be it cgo, io_uring, or anything of the kind, doesn't mess up Go pointers; and b) GC is none-moving. Now, the moment b) is not true, no amount of the current unsafe magic will help. Programs will break, and will have to be modified, and in a none backward compatible fashion(*). And here is what I'm trying to get to. Unless the compiler and run-time figure it out (at least for most common cases) and just make corresponding arrangements. Figure out using unsafe.Pointer, or maybe some other backward-compatible idiom, as a hint.

(*) Let's also ask ourselves what would modifications look like given the suggestion? To me it sounds like one would omit all the unsafe.Pointers and pin the stuff. This is why I refer to them as "vs."

[ansiwen]

You invoke some unsafe magic and it works, works 100% reliably

What is this "magic" you are talking about? As far as I am aware, there is no magic involved in unsafe.Pointer. The "unsafe" only refers to type safety, a Go pointer stored in an unsafe.Pointer is still 100% safe regarding memory management. It's like a void shared pointer in C++, unsafe regarding type, safe regarding memory.

Now, the moment b) is not true, no amount of the current unsafe magic will help. Programs will break, and will have to be modified, and in a none backward compatible fashion(*).

I'm quite sure this is not accurate. The moment a moving GC would be introduced, all the "legal" places, where Go pointers are passed to non-Go code (that is for example as arguments of Cgo functions or functions with the go:uintptrescapes compiler directive) would also add implicit pinning, which is a completely Go internal change. All Go programs that are following the pointer passing rules would continue to work without any change.

What we are discussing here is adding a public API for explicit pinning, because the pointer passing rules are too restrictive for some C APIs that users would want to use: iovec, async APIs, etc.

[dot-asm]

What is this "magic" you are talking about?

The one you listed in the beginning of this thread. Admittedly, "magic" might be a too strong word, it's not as "magic" as I make it sound. Nevertheless, the point is that there are ways around the current limitations, and they (at least some) involve unsafe.Pointer transmutations. And they do work (due to b) on the Go side). And they will stop. And I'm wondering if they actually have to.

[ansiwen]

What is this "magic" you are talking about?

The one you listed in the beginning of this thread. Admittedly, "magic" might be a too strong word, it's not as "magic" as I make it sound. Nevertheless, the point is that there are ways around the current limitations, and they (at least some) involve unsafe.Pointer transmutations. And they do work (due to b) on the Go side). And they will stop. And I'm wondering if they actually have to.

Oh, now I see the misunderstanding. So, you are talking about the first three workarounds that start with "Break the rules..."? Of course they stop working when the GC becomes moving, because... they are breaking the rules. But the use of unsafe.Pointer() in these workarounds is purely for type punning, there is no other effect to it. You can perfectly break the rules also without using unsafe.Pointer, like in this example:

package main

/*
#include <stdio.h>

typedef struct {
        int *i;
} T;

T c_data;

inline void mycall(T* p) {
        printf("int: %d\n", *p->i);
        return;
}
*/
import "C"

func main() {
        p := &C.c_data
        i := C.int(42)
        p.i = &i
        C.mycall(p)
}

This will also break, once the GC is moving. No unsafe.Pointer involved.

[dot-asm]

You can perfectly break the rules also without using unsafe.Pointer, like in this example:

To be honest, I'm shocked. I would expect the compiler to actually reject the p.i = &i assignment(*). Or at least flag it as questionable during go vet... But let me get it straight. Is the suggestion to legitimize this kind of coding practice? If so, then I for one would argue that a more sustainable path forward would be rather to make this kind of assignment illegal and instead concentrate on facilitating passing Go pointers to Go pointers. Well, again, who am I to judge, just a thought :-) Thanks!

(*) more specifically without unsafe.Pointer conversion

[ansiwen]

To be honest, I'm shocked. I would expect the compiler to actually reject the p.i = &i assignment().
() more specifically without unsafe.Pointer conversion

Reject why? The types are matching. If you would cast it to unsafe.Pointer, the types would not match anymore, and the compiler would bail out. But if the types match, how can the compiler know, how the memory of c_data, which is a link to another package, is allocated by C and not by Go? The Go runtime can know though, that's why if you run this program with GODEBUG=cgocheck=2 then it panics with

write of Go pointer 0xc000186000 to non-Go memory 0x410e150
fatal error: Go pointer stored into non-Go memory

If so, then I for one would argue that a more sustainable path forward would be rather to make this kind of assignment illegal and instead concentrate on facilitating passing Go pointers to Go pointers.

This assignment is illegal at the moment. There is a difference what is illegal, and what a compiler or linter can catch. For example, if and how long an asynchronous C API is keeping a Go pointer for storing a future result in it, even the best compiler can not find out. And furthermore, we need a legal way for these kind of assignments for efficiently use certain C APIs. That's why there is no way around explicit pinning, if we want to keep the possibility to have a moving GC in the future.

[dot-asm]

Reject why? ... it panics with ["Go pointer stored into non-Go memory"]

That's why. I fail to imagine that compiler actually wouldn't be able to figure it out at compile (or at least vet) time. It apparently doesn't, and I'd say it's on compiler:-(

There is a difference what is illegal, and what a compiler or linter can catch.

I find this formulation really strange. Customarily compiler defines what's illegal. Well, specification does, but usually it's one of compiler's responsibility to "enforce the law", is it not?

we need a legal way for these kind of assignments for efficiently use certain C APIs

I for one would argue that yes, there definitely should be a legal way to use the said C APIs, but it doesn't actually have to be through these kind of assignments.

Note that it's not like I fail to see the value in explicit pinning. I just see great value even in extending the implicit pinning. By "extending" I mean that we already established that objects without Go pointers [passed by reference to cgo as argument] shall be pinned implicitly, and the question is if one can support other cases, presumably selected ones. I mean it's surely infeasible to just support a general case, but why not a slice of C.structs with pointers to Go objects without Go pointers? Thanks for listening! 👍

[rsc]

Lots of discussion about what unsafe.Pointer means, but I don't see any objections to the API in #46787 (comment).

Does anyone object to that runtime.Pinner API?

[phlogistonjohn]

One small question, based on the most recent edit I see (2021-10-20) is it to be called "Pinner" or "Pinned"? In the example it's now func (p *Pinned) Unpin() but still appears to be Pinner everywhere else?

[Merovius]

@rsc I find the sequence var p runtime.Pinner; defer p.Unpin(); p.Pin(…) a bit strange. It feels like the Pinner outlives the Unpin call, it begs the question if it is legal to re-use the Pinner and/or what happens if you call p.Pin after p.Unpin. It also reads weird as the "undo" action appears lexically before the action to be undone and it might require a bit of effort to parse which pins exactly will be unpinned.

Just FWIW (I have no strong opinions as I don't predict I'll be ever using this API), it would also be possible to allow multiple objects to be pinned in one go via

func Pin(obj ...interface{}) *Pinned
func (*Pinned) Unpin()

to be used as

p := runtime.Pin(manyThings...)
defer p.Unpin()

(or even defer runtime.Pin(manyThings...).Unpin())

The only argument against that I can see is that it might be less efficient, if it requires allocating a slice - but maybe that can be solved with inlining/escape analysis?

[dot-asm]

Just in case. Is it plausible to expect that pinned pointers won't trigger "cgo argument has
Go pointer to Go pointer" and similar panics? (BTW, since it's on it checking, what would prevent it from pinning objects as it goes?;-)

[aclements]

it begs the question if it is legal to re-use the Pinner and/or what happens if you call p.Pin after p.Unpin

I think it should be legal to reuse a Pinner, mostly because I don't see a reason it shouldn't be. :)

func Pin(obj ...interface{}) *Pinned

Explicit pinning (and having an object that represents the pinned set) seems particularly useful in situations where the number of objects to pin isn't known statically. For example, when you need to loop over a slice of objects and collect up all of the pointers in them. Certainly that would be possible with the API you proposed, but even a very clever compiler would have a hard time eliminating the slice allocation from that.

[ansiwen]

I can confirm that the proposed API in #46787 (comment) covers perfectly all the use-cases that I dealt with so far, which are:

• iovec syscalls, which require iterating over all the buffer pointers and pin them with the same Pinner object
• asynchronous C APIs, which require to store the Pinner object accessible from a callback that can release it later.

In both cases the Pinner must be stored. So the nice looking and concise expression from @bcmills proposal defer Pin(objPtr).Unpin() couldn't be used in either of them.

And in the end this is a niche API, that will be used in rare cases, and it's not so dramatic if its use is a bit more quirky than usual.

[ansiwen]

@phlogistonjohn

One small question, based on the most recent edit I see (2021-10-20) is it to be called "Pinner" or "Pinned"? In the example it's now func (p *Pinned) Unpin() but still appears to be Pinner everywhere else?

No, it's the other way around, @rsc changed it from Pinned to Pinner, according to @aclements proposal, but he forgot it in the last line, which still says Pinned. So, it should be Pinner everywhere.