luagc

Documentation

Overview

Package luagc implements weak refs and weak ref pools to be used by the Golua runtime.

Two interfaces WeakRef and Pool are defined and the packages provides three implementations of Pool. The Golua runtime has a Pool instance that it uses to help with finalizing of Lua values and making sure finalizers do not run after the runtime has finished.

SafePool is a simple implementation whose strategy is to keep all values alive as long as they have live WeakRefs.

UnsafePool makes every effort to let values be GCed when they are only reachable via WeakRefs. It relies on casting interface{} to unsafe pointers and back again, which would break if Go were to have a moving GC.

ClonePool also lets values be GCed when they are unreachable outside of the pool and does so on any compliant Go implementation. However it does not support WeakRefs (i.e. Get(v) always returns nil).

Index

• type ClonePool
  • func NewClonePool() *ClonePool
  • func (p *ClonePool) ExtractAllMarkedFinalize() []Value
  • func (p *ClonePool) ExtractAllMarkedRelease() []Value
  • func (p *ClonePool) ExtractPendingFinalize() []Value
  • func (p *ClonePool) ExtractPendingRelease() []Value
  • func (p *ClonePool) Get(v Value) WeakRef
  • func (p *ClonePool) Mark(v Value, flags MarkFlags)
• type Key
• type MarkFlags
• type Pool
  • func NewDefaultPool() Pool
• type SafePool
  • func NewSafePool() *SafePool
  • func (p *SafePool) ExtractAllMarkedFinalize() []Value
  • func (p *SafePool) ExtractAllMarkedRelease() []Value
  • func (p *SafePool) ExtractPendingFinalize() []Value
  • func (p *SafePool) ExtractPendingRelease() []Value
  • func (p *SafePool) Get(v Value) WeakRef
  • func (p *SafePool) Mark(v Value, flags MarkFlags)
• type UnsafePool
  • func NewUnsafePool() *UnsafePool
  • func (p *UnsafePool) ExtractAllMarkedFinalize() []Value
  • func (p *UnsafePool) ExtractAllMarkedRelease() []Value
  • func (p *UnsafePool) ExtractPendingFinalize() []Value
  • func (p *UnsafePool) ExtractPendingRelease() []Value
  • func (p *UnsafePool) Get(v Value) WeakRef
  • func (p *UnsafePool) Mark(v Value, flags MarkFlags)
• type Value
• type WeakRef

Types

type ClonePool

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

ClonePool is an implementation of Pool that makes every effort to let values be GCed when they are only reachable via WeakRefs. Unlike UnsafePool, it doesn't rely on any undocumented properties of the Go runtime so it is safe to use in any compliant Go implementation. The downside of this implementation is that it cannot provide any WeakRefs.

func NewClonePool

func NewClonePool() *ClonePool

NewClonePool returns a new *ClonePool ready to be used.

func (*ClonePool) ExtractAllMarkedFinalize

func (p *ClonePool) ExtractAllMarkedFinalize() []Value

ExtractAllMarkedFinalized returns all the values that have been marked for finalizing, even if their go finalizer hasn't run yet. This is useful e.g. when closing a runtime, to run all pending finalizers.

func (*ClonePool) ExtractAllMarkedRelease

func (p *ClonePool) ExtractAllMarkedRelease() []Value

ExtractAllMarkedRelease returns all the values that have been marked for release, even if their go finalizer hasn't run yet. This is useful e.g. when closing a runtime, to release all resources.

func (*ClonePool) ExtractPendingFinalize

func (p *ClonePool) ExtractPendingFinalize() []Value

ExtractPendingFinalize returns the set of values which are being garbage collected and need their finalizer running, in the order that they should be run. The caller of this function has the responsibility to run all the finalizers. The values returned are removed from the pool and their weak refs are invalidated.

func (*ClonePool) ExtractPendingRelease

func (p *ClonePool) ExtractPendingRelease() []Value

func (*ClonePool) Get

func (p *ClonePool) Get(v Value) WeakRef

Get always returns nil because ClonePool doesn't support weak references.

func (*ClonePool) Mark

func (p *ClonePool) Mark(v Value, flags MarkFlags)

Mark marks v for finalizing, i.e. when v is garbage collected, its finalizer should be run.

type Key

type Key interface{}

Key is the type for value keys (see the Value interface).

type MarkFlags

type MarkFlags uint8

MarkFlags are passsed to the Pool.Mark method to signal to the pool how to deal with the value when it becomes unreachable.

const (
	Finalize MarkFlags = 1 << iota // Mark a value for finalizing
	Release                        // Mark a value for releasing
)

type Pool

type Pool interface {

	// Get returns a WeakRef for the given value v.  Calling Get several times
	// with the same value should return the same WeakRef.
	//
	// An implementation of Pool may return nil if it is unable to make a
	// WeakRef for the passed-in value.
	Get(v Value) WeakRef

	// Mark indicates that the pool should keep a copy of v when it becomes
	// unreachable.  It can then notify the Golua runtime via the
	// ExtractPendingFinalize() and ExtractPendingRelease() methods (depending
	// on the flags passed in).
	//
	// The associated Golua Runtime marks all values which have a __gc
	// metamethod with the Finalize flag, and all values which implement the
	// ResourceReleaser interface with the Release flag (this is contextual
	// info, this package is unaware of this).
	//
	// Note: "Mark" is the terminology used in the Lua docs, it is unrelated to
	// "Mark and Sweep".
	Mark(v Value, flags MarkFlags)

	// ExtractPendingFinalize returns all marked values which are no longer reachable
	// and haven't been returned yet, so that some finalizing code can be run
	// with them.  The returned values are ordered in reverse order of marking
	// (i.e. if v1 was marked before v2, then v2 comes before v1 in the returned
	// list). Further calls should not return the same values again.
	//
	// This is called periodically by the Golua Runtime to run Lua finalizers on
	// GCed values.
	ExtractPendingFinalize() []Value

	// ExtractPendingRelease returns all marked values which are no longer
	// reachable, no longer need to be finalized and haven't been returned yet,
	// so that their associated resources can be released.  The returned values
	// are ordered in reverse order of marking (i.e. if v1 was marked before v2,
	// then v2 comes before v1 in the returned list). Further calls should not
	// return the same values again.
	//
	// This is called periodically by the Golua Runtime to release resources
	// associated with GCed values.
	ExtractPendingRelease() []Value

	// ExtractAllMarkedFinalize returns all values marked for Lua finalizing,
	// following the same order as ExtractPendingFinalize.  All marked values
	// are cleared in the pool so that they will no longer be returned by this
	// method or ExtractPendingFinalize.
	//
	// Typically this method will be called when the associated Golua Runtime is
	// being closed so that all outstanding Lua finalizers can be called (even
	// if their values might get GCed later).
	ExtractAllMarkedFinalize() []Value

	// ExtractAllMarkedRelease returns all values marked for releasing,
	// following the same order as ExtractPendingRelease.  All values marked for
	// Finalize or Release are cleared in the pool so that they will no longer
	// be returned by any Extract* method.  This means this method should be
	// called as the last action before discarding the pool.
	//
	// Typically this method will be called when the associated Golua Runtime is
	// being closed so that all outstanding Lua finalizers can be called (even
	// if their values might get GCed later).
	ExtractAllMarkedRelease() []Value
}

A Pool maintains a set of weak references to values. Its methods are not required to be thread-safe insofar as they should not get called concurrently.

Each Golua Runtime has a Pool instance to help it manage weak references and finalizers.

func NewDefaultPool

func NewDefaultPool() Pool

NewDefaultPool returns a new WeakRefPool with an appropriate implementation.

type SafePool

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

SafePool is an implementation of Pool that keeps alive all the values it is given.

func NewSafePool

func NewSafePool() *SafePool

func (*SafePool) ExtractAllMarkedFinalize

func (p *SafePool) ExtractAllMarkedFinalize() []Value

ExtractAllMarkedFinalize returns all values marked for finalizing in reverse order, clearing them.

func (*SafePool) ExtractAllMarkedRelease

func (p *SafePool) ExtractAllMarkedRelease() []Value

ExtractAllMarkedRelease returns all values marked for release in reverse order, clearing them.

func (*SafePool) ExtractPendingFinalize

func (p *SafePool) ExtractPendingFinalize() []Value

ExtractPendingFinalize returns nil because all marked values are kept alive by the pool.

func (*SafePool) ExtractPendingRelease

func (p *SafePool) ExtractPendingRelease() []Value

ExtractPendingRelease returns nil because all marked values are kept alive by the pool.

func (*SafePool) Get

func (p *SafePool) Get(v Value) WeakRef

Get returns a WeakRef with the given value. That WeakRef will keep the value alive!

func (*SafePool) Mark

func (p *SafePool) Mark(v Value, flags MarkFlags)

Mark adds iface to the list of marked values.

type UnsafePool

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

UnsafePool is an implementation of Pool that makes every effort to let values be GCed when they are only reachable via WeakRefs. It relies on casting interface{} to unsafe pointers and back again, which would break if Go were to have a moving GC.

func NewUnsafePool

func NewUnsafePool() *UnsafePool

NewUnsafePool returns a new *UnsafeWeakRefPool ready to be used.

func (*UnsafePool) ExtractAllMarkedFinalize

func (p *UnsafePool) ExtractAllMarkedFinalize() []Value

ExtractAllMarkedFinalized returns all the values that have been marked for finalizing, even if their go finalizer hasn't run yet. This is useful e.g. when closing a runtime, to run all pending finalizers.

func (*UnsafePool) ExtractAllMarkedRelease

func (p *UnsafePool) ExtractAllMarkedRelease() []Value

ExtractAllMarkedRelease returns all the values that have been marked for release, even if their go finalizer hasn't run yet. This is useful e.g. when closing a runtime, to release all resources.

func (*UnsafePool) ExtractPendingFinalize

func (p *UnsafePool) ExtractPendingFinalize() []Value

ExtractPendingFinalize returns the set of values which are being garbage collected and need their finalizer running, in the order that they should be run. The caller of this function has the responsibility to run all the finalizers. The values returned are removed from the pool and their weak refs are invalidated.

func (*UnsafePool) ExtractPendingRelease

func (p *UnsafePool) ExtractPendingRelease() []Value

func (*UnsafePool) Get

func (p *UnsafePool) Get(v Value) WeakRef

Get returns a WeakRef for v if possible.

func (*UnsafePool) Mark

func (p *UnsafePool) Mark(v Value, flags MarkFlags)

Mark marks v for finalizing, i.e. when v is garbage collected, its finalizer should be run. It only takes effect if v can have a weak ref.

type Value

type Value interface {

	// Key returns a Key instance that is unique to a Value and its clones (i.e.
	// v.Key() == v.Clone().Key(), but two independent values should have
	// distinct keys)
	Key() Key

	// Clone() returns a copy of the value that behaves like the original value
	// (in particular it shares its state).
	Clone() Value
}

Value is the interface that must be implemented by values managed by a Pool.

type WeakRef

type WeakRef interface {
	Value() Value
}

A WeakRef is a weak reference to a value. Its Value() method returns the value if it is not dead (meaning that the value is still reachable), otherwise it returns nil.

Note that it is valid for a WeakRef to keep its value alive while it is alive, although not very efficient.