resource

Documentation

Overview

Package resource provides support to implement closeable backing resources featuring multiple separately closeable references. The backing resource is finally closed, when the last reference is closed. The close method can then be used, for example, to release temporary external resources with the last released reference. Hereby, the reference implements the intended resource interface including the reference related part, which includes a Dup method, which can be used to gain a new additional reference to the backing object.

Those references are called Views in the package. The backing object implements the pure resource object interface plus the final Close method.

The final resource interface is described by a Go interface including the resource.ResourceView interface,

type MyResource interface {
   resource.ResourceView[MyResource]
   AdditionalMethods()...
}

The resource.ResourceView interface offers the view-related methods.

With NewResource a new view management and a first view is created for this object. This method is typically wrapped by a dedicated resource creator function:

func New(args...) MyResource {
   i := MyResourceImpl{
          ...
        }
   return resource.NewResource(i, myViewCreator)
}

The interface ResourceImplementation describes the minimal interface an implementation object has to implement to work with this view management package. It gets access to the ViewManager to be able to create new views/references for potential sub objects provided by the implementation, which need access to the implementation. In such a case those sub objects require a Close method again, are may even use an own view management.

The management as well as the view can be used to create additional views.

Therefore, the reference management uses a ResourceViewCreator function, which must be provided by the object implementation Its task is to create a new frontend view object implementing the desired pure backing object functionality plus the view-related interface.

This is done by creating an object with two embedded fields:

type MyReference struct {
   resource.ReferenceView[MyInterface]
   MyImplementation
}

the myViewCreator function creates a new resource reference using the resource.NewView function.

func myViewCreator(impl *ResourceImpl,
                   v resource.CloserView,
                   d resource.Dup[Resource]) MyResource {
  return &MyResource {
           resource.NewView(v, d),
           impl,
         }
}

A default resource base implementation is provided by ResourceImplBase. It implements the minimal implementation interface and offers with the method View a way to create additional views. It can just be instantiated for the base usage. Using the creator NewResourceImplBase it is possible to support

• nested use-cases, where an implementations hold a reference on a parent object
• additional closers are required.

Therefore, it provides a default Close method. If your implementation required an additional cleanup, you have to reimplement the Close method and call at least the base implementation method. Or you configure the optional closer for the base implementation.

Index

• Variables
• func NewResource[T any, I ResourceImplementation[T]](impl I, c ResourceViewCreator[T, I], name string, main ...bool) T
• type CloserView
  • func NoneRefCloserView[T io.Closer](d ViewManager[T]) CloserView
• type Dup
• type ResourceImplBase
  • func NewResourceImplBase[T any, M io.Closer](m ViewManager[M], closer ...io.Closer) (*ResourceImplBase[T], error)
  • func NewSimpleResourceImplBase[T any](closer ...io.Closer) *ResourceImplBase[T]
  • func (b *ResourceImplBase[T]) Allocatable() refmgmt.ExtendedAllocatable
  • func (b *ResourceImplBase[T]) Close() error
  • func (b *ResourceImplBase[T]) IsClosed() bool
  • func (b *ResourceImplBase[T]) RefCount() int
  • func (b *ResourceImplBase[T]) SetViewManager(m ViewManager[T])
  • func (b *ResourceImplBase[T]) View(main ...bool) (T, error)
  • func (b *ResourceImplBase[T]) ViewManager() ViewManager[T]
• type ResourceImplementation
• type ResourceView
• type ResourceViewCreator
• type ResourceViewInt
  • func NewNonRefView[T resourceViewInterface[T]](d ViewManager[T]) ResourceViewInt[T]
  • func NewView[T resourceViewInterface[T]](v CloserView, d ViewManager[T]) ResourceViewInt[T]
• type ViewManager

Variables

var ErrClosed = accessio.ErrClosed

Functions

func NewResource

func NewResource[T any, I ResourceImplementation[T]](impl I, c ResourceViewCreator[T, I], name string, main ...bool) T

NewResource creates a resource based on an implementation and a ResourceViewCreator. function.

Types

type CloserView

type CloserView interface {
	Close() error
	IsClosed() bool
	Execute(func() error) error
	Allocatable() refmgmt.ExtendedAllocatable
	refmgmt.LazyMode
	refmgmt.RefCountProvider
}

func NoneRefCloserView

func NoneRefCloserView[T io.Closer](d ViewManager[T]) CloserView

type Dup

type Dup[T any] interface {
	Dup() (T, error)
}

type ResourceImplBase

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

func NewResourceImplBase

func NewResourceImplBase[T any, M io.Closer](m ViewManager[M], closer ...io.Closer) (*ResourceImplBase[T], error)

NewResourceImplBase creates an implementation base for a resource T referencing another resource M.

func NewSimpleResourceImplBase

func NewSimpleResourceImplBase[T any](closer ...io.Closer) *ResourceImplBase[T]

func (*ResourceImplBase[T]) Allocatable

func (b *ResourceImplBase[T]) Allocatable() refmgmt.ExtendedAllocatable

func (*ResourceImplBase[T]) Close

func (b *ResourceImplBase[T]) Close() error

func (*ResourceImplBase[T]) IsClosed

func (b *ResourceImplBase[T]) IsClosed() bool

func (*ResourceImplBase[T]) RefCount

func (b *ResourceImplBase[T]) RefCount() int

func (*ResourceImplBase[T]) SetViewManager

func (b *ResourceImplBase[T]) SetViewManager(m ViewManager[T])

func (*ResourceImplBase[T]) View

func (b *ResourceImplBase[T]) View(main ...bool) (T, error)

func (*ResourceImplBase[T]) ViewManager

func (b *ResourceImplBase[T]) ViewManager() ViewManager[T]

type ResourceImplementation

type ResourceImplementation[T any] interface {
	io.Closer
	SetViewManager(m ViewManager[T])
	ViewManager[T]
}

ResourceImplementation is the minimal interface for an implementation a resource with managed views.

type ResourceView

type ResourceView[T resourceViewInterface[T]] interface {
	// contains filtered or unexported methods
}

ResourceView is the view related part of a resource interface T. T must incorporate ResourceView[T], which cannot directly be expressed in go, but with the helper interface defining the API.

type ResourceViewCreator

type ResourceViewCreator[T any, I io.Closer] func(I, CloserView, ViewManager[T]) T

ResourceViewCreator is a function which must be provided by the resource provider to map an implementation to the resource interface T. It must use NewView to create the view related part of a resource.

type ResourceViewInt

type ResourceViewInt[T resourceViewInterface[T]] interface {
	refmgmt.LazyMode
	refmgmt.RefCountProvider

	Execute(func() error) error
	Allocatable() refmgmt.ExtendedAllocatable
	// contains filtered or unexported methods
}

ResourceViewInt can be used to execute an operation on a non-closed view. Execute call a synchronized function on a non-closed view.

func NewNonRefView

func NewNonRefView[T resourceViewInterface[T]](d ViewManager[T]) ResourceViewInt[T]

NewNonRefView provides a reference-less view directly for the reference manager. It is valid as long as the reference manager is not closed with the last regular reference.

func NewView

func NewView[T resourceViewInterface[T]](v CloserView, d ViewManager[T]) ResourceViewInt[T]

NewView is to be called by a resource view creator to map the given resource implementation to complete resource interface. It should create an object with two local embedded fields:

• the returned ResourceView and the
• given resource implementation.

type ViewManager

type ViewManager[T any] interface {
	RefCount() int
	Allocatable() refmgmt.ExtendedAllocatable
	View(main ...bool) (T, error)
	IsClosed() bool
}

ViewManager is the interface of the reference manager, which can be used to gain new views to a managed resource.