rc

README

acln.ro/rc

Package rc provides reference-counted file descriptors.

This package solves a very niche problem, namely managing the lifetime of a file descriptor which is not packaged and used as an *os.File, or as a net.Conn / net.PacketConn, in the presence of potential concurrent access.

I originally built package rc to help manage eBPF map file descriptors, but the code is generic enough that it can be used for other similar purposes just as well.

Package version

Package rc presents itself as a Go module, and is currently at v2.0.0. The update from v1 to v2 changed the API to be function-based, and removed special handling of Windows file descriptors.

License

Package rc is distributed under the ISC license. A copy of the license can be found in the LICENSE file.

Documentation

Overview

Package rc provides reference counted file descriptors.

FD is a low level construct, and is useful only under very specific circumstances. In most use cases, managing file descriptors using the standard library os or net packages is a better choice.

Index

• Variables
• type FD
  • func (fd *FD) Close() error
  • func (fd *FD) Do(fn func(rawfd int) error) error
  • func (fd *FD) Init(rawfd int, closeFunc func(int) error) error

Variables

var (
	// ErrUninitializedFD is the error returned by FD methods when called
	// on a file descriptor which has not been initialized.
	ErrUninitializedFD = errors.New("rc: use of uninitialized file descriptor")

	// ErrClosedFD is the error returned by FD methods when called on
	// a file descriptor which has been closed.
	ErrClosedFD = errors.New("rc: use of closed file descriptor")

	// ErrMultipleInit is the error returned by (*FD).Init when called
	// for at least the second time on a specific FD.
	ErrMultipleInit = errors.New("rc: multiple calls to (*FD).Init")
)

Types

type FD

type FD struct {
	// contains filtered or unexported fields
}

FD is a reference counted file descriptor.

The zero value for FD is not usable. Values of type FD must be initialized by calling the Init method, and must not be copied.

Once initialized, it is safe to call methods on an FD from multiple goroutines.

Once an FD is closed, its methods return errors, and it may not be re-initialized.

func (*FD) Close

func (fd *FD) Close() error

Close waits for the reference count associated with the FD to reach zero, unsets the finalizer associated with fd, then closes the file descriptor.

Calling Close from inside a Do block causes a deadlock, so it is forbidden.

func (*FD) Do

func (fd *FD) Do(fn func(rawfd int) error) error

Do executes fn against the file descriptor. If Do does not return an error, the file descriptor is guaranteed to be valid for the duration of the call to fn.

func (*FD) Init

func (fd *FD) Init(rawfd int, closeFunc func(int) error) error

Init initializes the file descriptor and sets a finalizer for fd, which may call closeFunc if the FD goes out of scope without being closed explicitly.

If the FD was already initialized, Init returns ErrMultipleInit.