rc

Documentation

Overview

Package rc provides reference-counted cells.

Index

• type Ref
  • func NewRef[T any](value T, release func()) *Ref[T]
  • func NewRefInPlace[T any](mk func(v *T) (release func())) *Ref[T]
  • func (r *Ref[T]) AddRef() *Ref[T]
  • func (r *Ref[T]) IsValid() bool
  • func (r *Ref[T]) Release()
  • func (r *Ref[T]) Steal() *Ref[T]
  • func (r *Ref[T]) Value() *T
  • func (r *Ref[T]) Weak() *WeakRef[T]
• type WeakRef
  • func (r *WeakRef[T]) AddRef() (_ *Ref[T], ok bool)

Types

type Ref

type Ref[T any] struct {
	// contains filtered or unexported fields
}

A Ref is a reference to a refcounted cell containing a T. It must not be moved after it is first used (but it is ok to move the return values of NewRef/AddRef *before* using them). The zero value is an already-released reference to some non-existant cell; it is not useful.

func NewRef

func NewRef[T any](value T, release func()) *Ref[T]

NewRef returns a Ref pointing to value. When all references are released, the function release will be called.

func NewRefInPlace

func NewRefInPlace[T any](mk func(v *T) (release func())) *Ref[T]

NewRefInPlace returns a ref pointing at a value. It constructs the value by passing a pointer to the zero value to the mk callback, which should return the function to run on release.

This is useful when the value cannot be moved after construction, but otherwise you will likely find NewRef more convinenet.

func (*Ref[T]) AddRef

func (r *Ref[T]) AddRef() *Ref[T]

AddRef returns a new reference to the same underlying data as the receiver. The references are not interchangable: to release the underlying data you must call Release on each Ref separately, and you cannot access the value through a released Ref even if you know there are other live references to it.

Panics if this reference has already been released.

func (*Ref[T]) IsValid

func (r *Ref[T]) IsValid() bool

Return true iff this is a valid ref, i.e. Value() will return without panicking. You may call this on a nil reference.

func (*Ref[T]) Release

func (r *Ref[T]) Release()

Release this reference to the value. If this is the last reference, this calls the release function that was passed to NewRef.

Release is idempotent: calling it twice on the same reference has no effect. This is handy as it allows you to defer a call to Release and then still have the option of a releasing a reference early.

func (*Ref[T]) Steal

func (r *Ref[T]) Steal() *Ref[T]

Steal steals the receiver, releasing it and returning a different reference to the same cell. The refcount is unchanged, but this is useful to enforce ownership invariants.

func (*Ref[T]) Value

func (r *Ref[T]) Value() *T

Return a pointer to the value. Panics if the reference has already been released.

func (*Ref[T]) Weak

func (r *Ref[T]) Weak() *WeakRef[T]

Weak returns a weak reference to the value.

type WeakRef

type WeakRef[T any] cell[T]

A WeakRef is a reference that does not keep the value alive. It can be used to obtain a (strong) Ref to the value if it has not yet been released.

func (*WeakRef[T]) AddRef

func (r *WeakRef[T]) AddRef() (_ *Ref[T], ok bool)

AddRef returns a (strong) Ref to the value, with ok indicating whether the operation was successfull -- if ok is false, this indicates that underlying cell had already been released, and the returned Ref will be nil.