rc: acln.ro/rc Index | Files

package rc

import "acln.ro/rc"

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

Package Files

rc.go registry.go

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
    // Init was already called on FD.
    ErrMultipleInit = errors.New("rc: multiple calls to (*FD).Init")
)

func WrapSyscallError Uses

func WrapSyscallError(syscall string, err error) error

WrapSyscallError wraps an error from a call to (*FD).Do or (*FD).Close, with a few special cases taken into consideration:

The sentinel error values ErrUninitializedFD and ErrClosedFD are returned without wrapping. If err is nil, WrapSyscallError returns nil. Any other error is wrapped using os.NewSyscallError.

type FD Uses

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.

FD is not suitable for use with blocking system calls: its internal locking scheme assumes that calls to Do do not block for very long.

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

func (*FD) Close Uses

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 Uses

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 Uses

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.

func (*FD) TrackLifetime Uses

func (fd *FD) TrackLifetime(lr *LifetimeRegistry)

TrackLifetime instructs the FD to reports its lifetime cycle to the specified LifetimeRegistry. For accurate results, TrackLifetime must be called before Init.

type FDStats Uses

type FDStats struct {
    // Initialized is the number of initialized file descriptors.
    Initialized int

    // Closed is the number of closed file descriptors.
    Closed int

    // CloseFailed is the number of file descriptors for which
    // the Close method failed.
    CloseFailed int

    // InFlightStacks maps file descriptor numbers to goroutine stack
    // traces taken their initialization sites.
    InFlightStacks map[int]string
}

FDStats is a set of file descriptor statistics.

func (FDStats) Report Uses

func (stats FDStats) Report() string

Report returns a report of file descriptor stats. If no file descriptors were leaked, then Report returns the empty string. Otherwise, it returns a message suitable for usage when failing a test.

type LifetimeRegistry Uses

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

A LifetimeRegistry keeps track of file descriptor lifetimes for the purpose of testing. The zero value is ready to use.

func (*LifetimeRegistry) FDStats Uses

func (lr *LifetimeRegistry) FDStats() FDStats

FDStats returns the statistics collected by the LifetimeRegistry. For accurate results, FDStats should be called after no more file descriptors are created or closed by the code under test.

Package rc imports 6 packages (graph). Updated 2019-05-29. Refresh now. Tools for package owners.