resource_pool

package
v0.0.0-...-0b345dd Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 6, 2022 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

A generic resource pool for managing resources such as network connections.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ManagedHandle

type ManagedHandle interface {
	// This returns the handle's resource location.
	ResourceLocation() string

	// This returns the underlying resource handle (or error if the handle
	// is no longer active).
	Handle() (interface{}, error)

	// This returns the resource pool which owns this handle.
	Owner() ResourcePool

	// The releases the underlying resource handle to the caller and marks the
	// managed handle as inactive.  The caller is responsible for cleaning up
	// the released handle.  This returns nil if the managed handle no longer
	// owns the resource.
	ReleaseUnderlyingHandle() interface{}

	// This indictes a user is done with the handle and releases the handle
	// back to the resource pool.
	Release() error

	// This indicates the handle is an invalid state, and that the
	// connection should be discarded from the connection pool.
	Discard() error
}

A resource handle managed by a resource pool.

func NewManagedHandle

func NewManagedHandle(
	resourceLocation string,
	handle interface{},
	pool ResourcePool,
	options Options) ManagedHandle

This creates a managed handle wrapper.

type OpenHandleError

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

func (OpenHandleError) Error

func (o OpenHandleError) Error() string

type Options

type Options struct {
	// The maximum number of active resource handles per resource location.  (A
	// non-positive value indicates the number of active resource handles is
	// unbounded).
	MaxActiveHandles int32

	// The maximum number of idle resource handles per resource location that
	// are kept alive by the resource pool.
	MaxIdleHandles uint32

	// The maximum amount of time an idle resource handle can remain alive (if
	// specified).
	MaxIdleTime *time.Duration

	// This limits the number of concurrent Open calls (there's no limit when
	// OpenMaxConcurrency is non-positive).
	OpenMaxConcurrency int

	// This function creates a resource handle (e.g., a connection) for a
	// resource location.  The function must be thread-safe.
	Open func(resourceLocation string) (
		handle interface{},
		err error)

	// This function destroys a resource handle and performs the necessary
	// cleanup to free up resources.  The function must be thread-safe.
	Close func(handle interface{}) error

	// This specifies the now time function.  When the function is non-nil, the
	// resource pool will use the specified function instead of time.Now to
	// generate the current time.
	NowFunc func() time.Time
}

type ResourcePool

type ResourcePool interface {
	// This returns the number of active resource handles.
	NumActive() int32

	// This returns the highest number of actives handles for the entire
	// lifetime of the pool.  If the pool contains multiple sub-pools, the
	// high water mark is the max of the sub-pools' high water marks.
	ActiveHighWaterMark() int32

	// This returns the number of alive idle handles.  NOTE: This is only used
	// for testing.
	NumIdle() int

	// This associates a resource location to the resource pool; afterwhich,
	// the user can get resource handles for the resource location.
	Register(resourceLocation string) error

	// This dissociates a resource location from the resource pool; afterwhich,
	// the user can no longer get resource handles for the resource location.
	// If the given resource location corresponds to a sub-pool, the unregistered
	// sub-pool will enter lame duck mode.
	Unregister(resourceLocation string) error

	// This returns the list of registered resource location entries.
	ListRegistered() []string

	// This gets an active resource handle from the resource pool.  The
	// handle will remain active until one of the following is called:
	//  1. handle.Release()
	//  2. handle.Discard()
	//  3. pool.Release(handle)
	//  4. pool.Discard(handle)
	Get(key string) (ManagedHandle, error)

	// This releases an active resource handle back to the resource pool.
	Release(handle ManagedHandle) error

	// This discards an active resource from the resource pool.
	Discard(handle ManagedHandle) error

	// Enter the resource pool into lame duck mode.  The resource pool
	// will no longer return resource handles, and all idle resource handles
	// are closed immediately (including active resource handles that are
	// released back to the pool afterward).
	EnterLameDuckMode()
}

A generic interface for managed resource pool. All resource pool implementations must be threadsafe.

func NewMultiResourcePool

func NewMultiResourcePool(
	options Options,
	createPool func(Options) ResourcePool) ResourcePool

This returns a MultiResourcePool, which manages multiple resource location entries. The handles to each resource location entry acts independently.

When createPool is nil, NewSimpleResourcePool is used as default.

func NewSimpleResourcePool

func NewSimpleResourcePool(options Options) ResourcePool

This returns a SimpleResourcePool, where all handles are associated to a single resource location.

type Semaphore

type Semaphore interface {
	// Increment the semaphore counter by one.
	Release()

	// Decrement the semaphore counter by one, and block if counter < 0
	Acquire()

	// Decrement the semaphore counter by one, and block if counter < 0
	// Wait for up to the given duration.  Returns true if did not timeout
	TryAcquire(timeout time.Duration) bool
}

func NewBoundedSemaphore

func NewBoundedSemaphore(count uint) Semaphore

Create a bounded semaphore. The count parameter must be a positive number. NOTE: The bounded semaphore will panic if the user tries to Release beyond the specified count.

func NewUnboundedSemaphore

func NewUnboundedSemaphore(initialCount int) Semaphore

This returns an unbound counting semaphore with the specified initial count. The semaphore counter can be arbitrary large (i.e., Release can be called unlimited amount of times).

NOTE: In general, users should use bounded semaphore since it is more efficient than unbounded semaphore.

type TooManyHandles

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

func (TooManyHandles) Error

func (t TooManyHandles) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL