refmgmt

Documentation

Overview

Package refmgmt provides a simple wrapper, which can be used to map a closable object type into an interface supporting reference counting and supporting a Dup() method.

The caller must provide an appropriate interface with the base object methods and additionally the Dup() (O, error) interface. Additionally, a struct type must be implemented hosting a View object (which implements the View.Close() and View.Dup() method) and the base object. It must implement the other interface methods by forwarding them to the base object. To create such a view object an appropriate creator function has to be provided.

The following example illustrates the usage:

 // Objectbase is the base interface for the
 // object type to be wrapped.
 type ObjectBase interface {
 	io.Closer

 	Value() (string, error)
 }

 ////////////////////////////////////////////////////////////////////////////////

 // Object is the final user facing interface.
 // It includes the base interface plus the Dup method.
 type Object interface {
 	ObjectBase
		Dup() (Object, error)
 }

 ////////////////////////////////////////////////////////////////////////////////

 // object is the implementation type for the bse object.
 type object struct {
 	lock   sync.Mutex
		closed bool
 	value  string
 }

 func (o *object) Value() (string, error) {
		if o.closed {
 		return "", fmt.Errorf("should not happen")
		}
 	return o.value, nil
 }

 func (o *object) Close() error {
		o.lock.Lock()
		defer o.lock.Unlock()

		if o.closed {
	 		return refmgmt.ErrClosed
		}
		o.closed = true
		return nil
 }

 ////////////////////////////////////////////////////////////////////////////////

 // view is the view object used to wrap the base object.
 // It forwards all methods to the base object using the
 // Execute function of the manager, to assure execution
 // on non-closed views, only.
 type view struct {
		*refmgmt.View[Object]
		obj ObjectBase
 }

 func (v *view) Value() (string, error) {
		value := ""

		err := v.Execute(func() (err error) {
	 		value, err = v.obj.Value() // forward to viewd object
	 		return
		})
		return value, err
 }

 // creator is the view object creator based on
 // the base object and the view manager.
 func creator(obj ObjectBase, v *refmgmt.View[Object]) Object {
 	return &view{v, obj}
 }

Index

• Variables
• func AsLazy[T any](o T) T
• func CloseTemporary(c io.Closer) error
• func Lazy(o interface{}) bool
• func PropagateCloseTemporary(errp *error, c io.Closer)
• func ReferenceCount(o interface{}) int
• func ToLazy[T any](o T, err error) (T, error)
• func WithView[O, V io.Closer](obj O, creator func(O, *View[V]) V, closer ...io.Closer) V
• type Allocatable
• type CleanupHandler
• type CleanupHandlerFunc
  • func (f CleanupHandlerFunc) Cleanup()
• type CloserFunc
  • func (c CloserFunc) Close() error
• type CloserView
• type Closers
  • func (c *Closers) Add(closers ...io.Closer)
  • func (c Closers) Close() error
  • func (c Closers) Effective() io.Closer
• type Dup
• type ExtendedAllocatable
• type LazyMode
• type RefCountProvider
• type RefMgmt
  • func NewAllocatable(cleanup func() error, unused ...bool) RefMgmt
• type ReferencableCloser
  • func NewRefCloser(closer io.Closer, unused ...bool) ReferencableCloser
• type View
  • func NewView[V io.Closer](mgr ViewManager[V], v CloserView) *View[V]
  • func (v *View[V]) Close() error
  • func (v *View[V]) Dup() (V, error)
  • func (v *View[V]) Execute(f func() error) error
  • func (v *View[V]) IsClosed() bool
• type ViewManager

Variables

var ALLOC_REALM = logging.DefineSubRealm("reference counting", "refcnt")

var AllocLog = logging.DynamicLogger(ALLOC_REALM)

var ErrClosed = errors.ErrClosed()

Functions

func AsLazy

func AsLazy[T any](o T) T

func CloseTemporary

func CloseTemporary(c io.Closer) error

func Lazy

func Lazy(o interface{}) bool

func PropagateCloseTemporary

func PropagateCloseTemporary(errp *error, c io.Closer)

func ReferenceCount

func ReferenceCount(o interface{}) int

func ToLazy

func ToLazy[T any](o T, err error) (T, error)

ToLazy resets the main view flag of closer views to enable dark release of resources even if the first/main view has been closed. Otherwise, closing the main view will fail, if there are still subsequent views.

func WithView

func WithView[O, V io.Closer](obj O, creator func(O, *View[V]) V, closer ...io.Closer) V

Types

type Allocatable

type Allocatable interface {
	Ref() error
	Unref() error
}

type CleanupHandler

type CleanupHandler interface {
	Cleanup()
}

type CleanupHandlerFunc

type CleanupHandlerFunc func()

func (CleanupHandlerFunc) Cleanup

func (f CleanupHandlerFunc) Cleanup()

type CloserFunc

type CloserFunc func() error

func (CloserFunc) Close

func (c CloserFunc) Close() error

type CloserView

type CloserView interface {
	io.Closer
	LazyMode
	RefCountProvider

	IsClosed() bool

	View() (CloserView, error)

	Release() error
	Finalize() error

	Closer() io.Closer

	Execute(f func() error) error
	Allocatable() ExtendedAllocatable
}

type Closers

type Closers []io.Closer

func (*Closers) Add

func (c *Closers) Add(closers ...io.Closer)

func (Closers) Close

func (c Closers) Close() error

func (Closers) Effective

func (c Closers) Effective() io.Closer

type Dup

type Dup[V io.Closer] interface {
	Dup() (V, error)
}

Dup is the common interface for all objects following the ref counting model. It will provide a new view to the underlying object. This will only be closed if there are no more views (created via Dup()).

type ExtendedAllocatable

type ExtendedAllocatable interface {
	BeforeCleanup(f CleanupHandler)
	Ref() error
	Unref() error
}

type LazyMode

type LazyMode interface {
	Lazy()
}

type RefCountProvider

type RefCountProvider interface {
	RefCount() int
}

type RefMgmt

type RefMgmt interface {
	UnrefLast() error
	ExtendedAllocatable
	IsClosed() bool
	RefCount() int

	WithName(name string) RefMgmt
}

func NewAllocatable

func NewAllocatable(cleanup func() error, unused ...bool) RefMgmt

type ReferencableCloser

type ReferencableCloser interface {
	ExtendedAllocatable

	RefCount() int
	UnrefLast() error
	IsClosed() bool

	Closer() io.Closer
	View(main ...bool) (CloserView, error)

	WithName(name string) ReferencableCloser
}

ReferencableCloser manages closable views to a basic closer. If the last view is closed, the basic closer is finally closed.

func NewRefCloser

func NewRefCloser(closer io.Closer, unused ...bool) ReferencableCloser

type View

type View[V io.Closer] struct {
	// contains filtered or unexported fields
}

func NewView

func NewView[V io.Closer](mgr ViewManager[V], v CloserView) *View[V]

func (*View[V]) Close

func (v *View[V]) Close() error

func (*View[V]) Dup

func (v *View[V]) Dup() (V, error)

func (*View[V]) Execute

func (v *View[V]) Execute(f func() error) error

func (*View[V]) IsClosed

func (v *View[V]) IsClosed() bool

type ViewManager

type ViewManager[V io.Closer] interface {
	View(closerView CloserView) (V, error)
}