rc

README

rc

import acln.ro/rc

Package rc provides reference-counted file descriptors.

See the documentation at https://godoc.org/acln.ro/rc.

TODO(acln): add an example

Documentation

Overview

Package rc provides reference counted file descriptors.

FD is a low level construct, and is useful only under very specific, rare circumstances. More often than not, callers should use the standard library os package to manage raw file descriptors instead.

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.

func (*FD) Decref

func (fd *FD) Decref()

Decref decrements the reference count associated with the FD. Each call to Decref must occur after a corresponding call 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.

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.