https://github.com/ansiwen/ptrguard

Go package for using Go pointers in external code
https://github.com/ansiwen/ptrguard

cgo cgo-bindings go golang

Last synced: about 1 year ago
JSON representation

Go package for using Go pointers in external code

• Host: GitHub
• URL: https://github.com/ansiwen/ptrguard
• Owner: ansiwen
• License: mit
• Created: 2021-05-26T21:34:08.000Z (about 5 years ago)
• Default Branch: master
• Last Pushed: 2021-10-30T14:13:24.000Z (over 4 years ago)
• Last Synced: 2025-03-27T09:51:59.264Z (over 1 year ago)
• Topics: cgo, cgo-bindings, go, golang
• Language: Go
• Homepage:
• Size: 45.9 KB
• Stars: 14
• Watchers: 5
• Forks: 3
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# PtrGuard

[![Build Status](https://github.com/ansiwen/ptrguard/actions/workflows/go.yml/badge.svg)](https://github.com/ansiwen/ptrguard/actions)

[![Go Reference](https://pkg.go.dev/badge/github.com/ansiwen/ptrguard.svg)](https://pkg.go.dev/github.com/ansiwen/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](https://golang.org/cmd/cgo/#hdr-Passing_pointers). 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](https://en.wikipedia.org/wiki/Vectored_I/O), like the

[`readv()`](https://pubs.opengroup.org/onlinepubs/000095399/functions/readv.html)

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