package refs

import "gvisor.dev/gvisor/pkg/refs"

Package refs defines an interface for reference counted objects.

Package refs_template defines a template that can be used by reference counted objects. The template comes with leak checking capabilities.

Index ¶

• Variables
• func DoLeakCheck()
• func DoRepeatedLeakCheck()
• func FormatStack(pcs []uintptr) string
• func LeakCheckEnabled() bool
• func LogDecRef(obj CheckedObject, refs int64)
• func LogIncRef(obj CheckedObject, refs int64)
• func LogTryIncRef(obj CheckedObject, refs int64)
• func OnExit()
• func RecordStack() []uintptr
• func Register(obj CheckedObject)
• func SetLeakMode(mode LeakMode)
• func Unregister(obj CheckedObject)
• type CheckedObject
• type LeakMode
• func GetLeakMode() LeakMode
• func (l *LeakMode) Get() any
• func (l *LeakMode) Set(v string) error
• func (l LeakMode) String() string
• type RefCounter
• type Refs
• func (r *Refs) DecRef(destroy func())
• func (r *Refs) IncRef()
• func (r *Refs) InitRefs()
• func (r *Refs) LeakMessage() string
• func (r *Refs) LogRefs() bool
• func (r *Refs) ReadRefs() int64
• func (r *Refs) RefType() string
• func (r *Refs) TryIncRef() bool
• type T
• type TryRefCounter

Variables ¶

var CleanupSync sync.WaitGroup

CleanupSync is used to wait for async cleanup actions.

Functions ¶

func DoLeakCheck ¶

func DoLeakCheck()

DoLeakCheck iterates through the live object map and logs a message for each object. It should be called when no reference-counted objects are reachable anymore, at which point anything left in the map is considered a leak. On multiple calls, only the first call will perform the leak check.

func DoRepeatedLeakCheck ¶

func DoRepeatedLeakCheck()

DoRepeatedLeakCheck is the same as DoLeakCheck except that it can be called multiple times by the caller to incrementally perform leak checking.

func FormatStack ¶

func FormatStack(pcs []uintptr) string

FormatStack converts the given stack into a readable format.

func LeakCheckEnabled ¶

func LeakCheckEnabled() bool

LeakCheckEnabled returns whether leak checking is enabled. The following functions should only be called if it returns true.

func LogDecRef ¶

func LogDecRef(obj CheckedObject, refs int64)

LogDecRef logs a reference decrement.

func LogIncRef ¶

func LogIncRef(obj CheckedObject, refs int64)

LogIncRef logs a reference increment.

func LogTryIncRef ¶

func LogTryIncRef(obj CheckedObject, refs int64)

LogTryIncRef logs a successful TryIncRef call.

func OnExit ¶

func OnExit()

OnExit is called on sandbox exit. It runs GC to enqueue refcount finalizers, which check for reference leaks. There is no way to guarantee that every finalizer will run before exiting, but this at least ensures that they will be discovered/enqueued by GC.

func RecordStack ¶

func RecordStack() []uintptr

RecordStack constructs and returns the PCs on the current stack.

func Register ¶

func Register(obj CheckedObject)

Register adds obj to the live object map.

func SetLeakMode ¶

func SetLeakMode(mode LeakMode)

SetLeakMode configures the reference leak checker.

func Unregister ¶

func Unregister(obj CheckedObject)

Unregister removes obj from the live object map.

Types ¶

type CheckedObject ¶

type CheckedObject interface {
	// RefType is the type of the reference-counted object.
	RefType() string

	// LeakMessage supplies a warning to be printed upon leak detection.
	LeakMessage() string

	// LogRefs indicates whether reference-related events should be logged.
	LogRefs() bool
}

CheckedObject represents a reference-counted object with an informative leak detection message.

type LeakMode ¶

type LeakMode uint32

LeakMode configures the leak checker.

const (
	// NoLeakChecking indicates that no effort should be made to check for
	// leaks.
	NoLeakChecking LeakMode = iota

	// LeaksLogWarning indicates that a warning should be logged when leaks
	// are found.
	LeaksLogWarning

	// LeaksPanic indidcates that a panic should be issued when leaks are found.
	LeaksPanic
)

func GetLeakMode ¶

func GetLeakMode() LeakMode

GetLeakMode returns the current leak mode.

func (*LeakMode) Get ¶

func (l *LeakMode) Get() any

Get implements flag.Value.

func (*LeakMode) Set ¶

func (l *LeakMode) Set(v string) error

Set implements flag.Value.

func (LeakMode) String ¶

func (l LeakMode) String() string

String implements flag.Value.

type RefCounter ¶

type RefCounter interface {
	// IncRef increments the reference counter on the object.
	IncRef()

	// DecRef decrements the object's reference count. Users of refs_template.Refs
	// may specify a destructor to be called once the reference count reaches zero.
	DecRef(ctx context.Context)
}

RefCounter is the interface to be implemented by objects that are reference counted.

type Refs ¶

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

Refs implements refs.RefCounter. It keeps a reference count using atomic operations and calls the destructor when the count reaches zero.

NOTE: Do not introduce additional fields to the Refs struct. It is used by many filesystem objects, and we want to keep it as small as possible (i.e., the same size as using an int64 directly) to avoid taking up extra cache space. In general, this template should not be extended at the cost of performance. If it does not offer enough flexibility for a particular object (example: b/187877947), we should implement the RefCounter/CheckedObject interfaces manually.

+stateify savable

func (*Refs) DecRef ¶

func (r *Refs) DecRef(destroy func())

DecRef implements refs.RefCounter.DecRef.

Note that speculative references are counted here. Since they were added prior to real references reaching zero, they will successfully convert to real references. In other words, we see speculative references only in the following case:

A: TryIncRef [speculative increase => sees non-negative references]
B: DecRef [real decrease]
A: TryIncRef [transform speculative to real]

func (*Refs) IncRef ¶

func (r *Refs) IncRef()

IncRef implements refs.RefCounter.IncRef.

func (*Refs) InitRefs ¶

func (r *Refs) InitRefs()

InitRefs initializes r with one reference and, if enabled, activates leak checking.

func (*Refs) LeakMessage ¶

func (r *Refs) LeakMessage() string

LeakMessage implements refs.CheckedObject.LeakMessage.

func (*Refs) LogRefs ¶

func (r *Refs) LogRefs() bool

LogRefs implements refs.CheckedObject.LogRefs.

func (*Refs) ReadRefs ¶

func (r *Refs) ReadRefs() int64

ReadRefs returns the current number of references. The returned count is inherently racy and is unsafe to use without external synchronization.

func (*Refs) RefType ¶

func (r *Refs) RefType() string

RefType implements refs.CheckedObject.RefType.

func (*Refs) TryIncRef ¶

func (r *Refs) TryIncRef() bool

TryIncRef implements refs.TryRefCounter.TryIncRef.

To do this safely without a loop, a speculative reference is first acquired on the object. This allows multiple concurrent TryIncRef calls to distinguish other TryIncRef calls from genuine references held.

type T ¶

type T any

T is the type of the reference counted object. It is only used to customize debug output when leak checking.

type TryRefCounter ¶

type TryRefCounter interface {
	RefCounter

	// TryIncRef attempts to increment the reference count, but may fail if all
	// references have already been dropped, in which case it returns false. If
	// true is returned, then a valid reference is now held on the object.
	TryIncRef() bool
}

TryRefCounter is like RefCounter but allow the ref increment to be tried.

Source Files ¶

refcounter.go refs_map.go refs_template.go