rc

README

rc

import acln.ro/rc

Package rc provides reference-counted file descriptors.

The documentation is available at https://godoc.org/acln.ro/rc.

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.

Windows is supported too, where, for convenience, the package deals in handles instead of raw integers.

Package version

Package rc presents itself as a Go module, and is currently at v1.0.0.

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) Decref()
  • func (fd *FD) Incref() (sysfd int, err error)
  • func (fd *FD) Init(sysfd int) 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")
)

var CloseFunc = unix.Close

CloseFunc hooks the close(2) system call.

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.

Close cannot be called while holding a reference to the FD (i.e. between an Incref and a Decref).

func (*FD) Decref

func (fd *FD) Decref()

Decref decrements the reference count associated with the FD. Calls to to Decref must occur after corresponding calls to Incref.

func (*FD) Incref

func (fd *FD) Incref() (sysfd int, err error)

Incref increments the reference count associated with the FD, and returns the underlying file descriptor for the caller to use. The returned file descriptor is valid at least until the corresponding call to Decref.

Callers must call Decref when they are finished using the file descriptor. Callers must not retain the file descriptor returned by Incref beyond the corresponding call to Decref.

func (*FD) Init

func (fd *FD) Init(sysfd int) error

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

If the FD was already initialized, Init returns ErrMultipleInit.