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.

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.)