PtrGuard

PtrGuard is a small Go package that allows to pin objects referenced by a Go pointer (that is pointing to memory allocated by the Go runtime) so that it will not be touched by the garbage collector. This is done by creating a Pinner object that has a Pin() method, which accepts a pointer of any type and pins the referenced object, until the Unpin() method of the same Pinner is called. A Pinner can be used to pin more than one object, in which case Unpin() releases all the pinned objects of a Pinner.

Go pointers to pinned objects can either be directly stored in C memory with the Store() method, or are allowed to be contained in Go memory that is passed to C functions, which both usually violates the pointer passing rules. In the second case you might need the NoCheck() helper function to call the C function in a context, where the cgocheck debug feature is disabled. This is necessary because PtrGuard doesn't have any possibility to tell cgocheck, that certain pointers are pinned.

Example

Let's say we want to use a C API that uses vectored I/O, like the readv() POSIX system call, in order to read data into an array of buffers. Because we want to avoid making a copy of the data, we want to read directly into Go buffers. The pointer passing rules wouldn't allow that, because

• either we can allocate the buffer array in C memory, but then we can't store the pointers of the Go buffers in it. (Storing Go pointers in C memory is forbidden.)
• or we would allocate the buffer array in Go memory and store the Go buffers in it. But then we can't pass the pointer to that buffer array to a C function. (Passing a Go pointer that points to memory containing other Go pointers to a C function is forbidden.)

With PtrGuard both is still possible. (See examples.)