package puddle

Import Path
	github.com/jackc/puddle/v2 (on go.dev)

Dependency Relation
	imports 8 packages, and imported by one package

Involved Source Files

	    context.go
	  d doc.go
		Package puddle is a generic resource pool with type-parametrized api.
		
		Puddle is a tiny generic resource pool library for Go that uses the standard
		context library to signal cancellation of acquires. It is designed to contain
		the minimum functionality a resource pool needs that cannot be implemented
		without concurrency concerns. For example, a database connection pool may use
		puddle internally and implement health checks and keep-alive behavior without
		needing to implement any concurrent code of its own.

	    log.go
	    nanotime.go
	    pool.go
	    resource_list.go
Package-Level Type Names (total 9, in which 6 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Config[T] (struct)

		Type Parameters:
			T: any

		Fields (total 3, all are exported)
			Constructor Constructor[T]
			Destructor Destructor[T]
			MaxSize int32
		As Inputs Of (at least one exported)
			func NewPool[T](config *Config[T]) (*Pool[T], error)

	 type Constructor[T] (func)

		Type Parameters:
			T: any

		Constructor is a function called by the pool to construct a resource.

	 type Destructor[T] (func)

		Type Parameters:
			T: any

		Destructor is a function called by the pool to destroy a resource.

	 type Pool[T] (struct)

		Type Parameters:
			T: any

		Pool is a concurrency-safe resource pool.

		Fields (total 17, none are exported)
			/* 17 unexporteds ... *//* 17 unexporteds: */
			acquireCount int64
			acquireDuration time.Duration
			acquireSem *semaphore.Weighted
				acquireSem provides an allowance to acquire a resource.
				
				Releases are allowed only when caller holds mux. Acquires have to
				happen before mux is locked (doesn't apply to semaphore.TryAcquire in
				AcquireAllIdle).

			allResources resList[T]
			baseAcquireCtx context.Context
			cancelBaseAcquireCtx context.CancelFunc
			canceledAcquireCount atomic.Int64
			closed bool
			constructor Constructor[T]
			destructWG sync.WaitGroup
			destructor Destructor[T]
			emptyAcquireCount int64
			emptyAcquireWaitTime time.Duration
			idleResources *genstack.GenStack[*Resource[T]]
			maxSize int32
			mux sync.Mutex
				mux is the pool internal lock. Any modification of shared state of
				the pool (but Acquires of acquireSem) must be performed only by
				holder of the lock. Long running operations are not allowed when mux
				is held.

			resetCount int
		Methods (total 15, in which 7 are exported)
			(*Pool[T]) Acquire(ctx context.Context) (_ *Resource[T], err error)
				Acquire gets a resource from the pool. If no resources are available and the pool is not at maximum capacity it will
				create a new resource. If the pool is at maximum capacity it will block until a resource is available. ctx can be
				used to cancel the Acquire.
				
				If Acquire creates a new resource the resource constructor function will receive a context that delegates Value() to
				ctx. Canceling ctx will cause Acquire to return immediately but it will not cancel the resource creation. This avoids
				the problem of it being impossible to create resources when the time to create a resource is greater than any one
				caller of Acquire is willing to wait.

			(*Pool[T]) AcquireAllIdle() []*Resource[T]
				AcquireAllIdle acquires all currently idle resources. Its intended use is for
				health check and keep-alive functionality. It does not update pool
				statistics.

			(*Pool[T]) Close()
				Close destroys all resources in the pool and rejects future Acquire calls.
				Blocks until all resources are returned to pool and destroyed.

			(*Pool[T]) CreateResource(ctx context.Context) error
				CreateResource constructs a new resource without acquiring it. It goes straight in the IdlePool. If the pool is full
				it returns an error. It can be useful to maintain warm resources under little load.

			(*Pool[T]) Reset()
				Reset destroys all resources, but leaves the pool open. It is intended for use when an error is detected that would
				disrupt all resources (such as a network interruption or a server state change).
				
				It is safe to reset a pool while resources are checked out. Those resources will be destroyed when they are returned
				to the pool.

			(*Pool[T]) Stat() *Stat
				Stat returns the current pool statistics.

			(*Pool[T]) TryAcquire(ctx context.Context) (*Resource[T], error)
				TryAcquire gets a resource from the pool if one is immediately available. If not, it returns ErrNotAvailable. If no
				resources are available but the pool has room to grow, a resource will be created in the background. ctx is only
				used to cancel the background creation.

			/* 8 unexporteds ... *//* 8 unexporteds: */
			(*Pool[T]) acquire(ctx context.Context) (*Resource[T], error)
				acquire is a continuation of Acquire function that doesn't check context
				validity.
				
				This function exists solely only for benchmarking purposes.

			(*Pool[T]) createNewResource() *Resource[T]
				createNewResource creates a new resource and inserts it into list of pool
				resources.
				
				WARNING: Caller of this method must hold the pool mutex!

			(*Pool[T]) destroyAcquiredResource(res *Resource[T])
				Remove removes res from the pool and closes it. If res is not part of the
				pool Remove will panic.

			(*Pool[T]) destructResourceValue(value T)
			(*Pool[T]) hijackAcquiredResource(res *Resource[T])
			(*Pool[T]) initResourceValue(ctx context.Context, res *Resource[T]) (*Resource[T], error)
			(*Pool[T]) releaseAcquiredResource(res *Resource[T], lastUsedNano int64)
				releaseAcquiredResource returns res to the the pool.

			(*Pool[T]) tryAcquireIdleResource() *Resource[T]
				tryAcquireIdleResource checks if there is any idle resource. If there is
				some, this method removes it from idle list and returns it. If the idle pool
				is empty, this method returns nil and doesn't modify the idleResources slice.
				
				WARNING: Caller of this method must hold the pool mutex!

		As Outputs Of (at least one exported)
			func NewPool[T](config *Config[T]) (*Pool[T], error)

	 type Resource[T] (struct)

		Type Parameters:
			T: any

		Resource is the resource handle returned by acquiring from the pool.

		Fields (total 6, none are exported)
			/* 6 unexporteds ... *//* 6 unexporteds: */
			creationTime time.Time
			lastUsedNano int64
			pool *Pool[T]
			poolResetCount int
			status byte
			value T
		Methods (total 8, all are exported)
			(*Resource[T]) CreationTime() time.Time
				CreationTime returns when the resource was created by the pool.

			(*Resource[T]) Destroy()
				Destroy returns the resource to the pool for destruction. res must not be
				subsequently used.

			(*Resource[T]) Hijack()
				Hijack assumes ownership of the resource from the pool. Caller is responsible
				for cleanup of resource value.

			(*Resource[T]) IdleDuration() time.Duration
				IdleDuration returns the duration since Release was last called on the resource. This is equivalent to subtracting
				LastUsedNanotime to the current nanotime.

			(*Resource[T]) LastUsedNanotime() int64
				LastUsedNanotime returns when Release was last called on the resource measured in nanoseconds from an arbitrary time
				(a monotonic time). Returns creation time if Release has never been called. This is only useful to compare with
				other calls to LastUsedNanotime. In almost all cases, IdleDuration should be used instead.

			(*Resource[T]) Release()
				Release returns the resource to the pool. res must not be subsequently used.

			(*Resource[T]) ReleaseUnused()
				ReleaseUnused returns the resource to the pool without updating when it was last used used. i.e. LastUsedNanotime
				will not change. res must not be subsequently used.

			(*Resource[T]) Value() T
				Value returns the resource value.

		As Outputs Of (at least 7, in which 3 are exported)
			func (*Pool)[T].Acquire(ctx context.Context) (_ *Resource[T], err error)
			func (*Pool)[T].AcquireAllIdle() []*Resource[T]
			func (*Pool)[T].TryAcquire(ctx context.Context) (*Resource[T], error)
			/* 4+ unexporteds ... *//* 4+ unexporteds: */
			func (*Pool)[T].acquire(ctx context.Context) (*Resource[T], error)
			func (*Pool)[T].createNewResource() *Resource[T]
			func (*Pool)[T].initResourceValue(ctx context.Context, res *Resource[T]) (*Resource[T], error)
			func (*Pool)[T].tryAcquireIdleResource() *Resource[T]
		As Inputs Of (at least 5, none are exported)
			/* 5+ unexporteds ... *//* 5+ unexporteds: */
			func (*Pool)[T].destroyAcquiredResource(res *Resource[T])
			func (*Pool)[T].hijackAcquiredResource(res *Resource[T])
			func (*Pool)[T].initResourceValue(ctx context.Context, res *Resource[T]) (*Resource[T], error)
			func (*Pool)[T].releaseAcquiredResource(res *Resource[T], lastUsedNano int64)
			func github.com/jackc/pgx/v5/pgxpool.(*Pool).isExpired(res *Resource[*pgxpool.connResource]) bool

	 type Stat (struct)
		Stat is a snapshot of Pool statistics.

		Fields (total 9, none are exported)
			/* 9 unexporteds ... *//* 9 unexporteds: */
			acquireCount int64
			acquireDuration time.Duration
			acquiredResources int32
			canceledAcquireCount int64
			constructingResources int32
			emptyAcquireCount int64
			emptyAcquireWaitTime time.Duration
			idleResources int32
			maxResources int32
		Methods (total 10, all are exported)
			(*Stat) AcquireCount() int64
				AcquireCount returns the cumulative count of successful acquires from the pool.

			(*Stat) AcquireDuration() time.Duration
				AcquireDuration returns the total duration of all successful acquires from
				the pool.

			(*Stat) AcquiredResources() int32
				AcquiredResources returns the number of currently acquired resources in the pool.

			(*Stat) CanceledAcquireCount() int64
				CanceledAcquireCount returns the cumulative count of acquires from the pool
				that were canceled by a context.

			(*Stat) ConstructingResources() int32
				ConstructingResources returns the number of resources with construction in progress in
				the pool.

			(*Stat) EmptyAcquireCount() int64
				EmptyAcquireCount returns the cumulative count of successful acquires from the pool
				that waited for a resource to be released or constructed because the pool was
				empty.

			(*Stat) EmptyAcquireWaitTime() time.Duration
				EmptyAcquireWaitTime returns the cumulative time waited for successful acquires
				from the pool for a resource to be released or constructed because the pool was
				empty.

			(*Stat) IdleResources() int32
				IdleResources returns the number of currently idle resources in the pool.

			(*Stat) MaxResources() int32
				MaxResources returns the maximum size of the pool.

			(*Stat) TotalResources() int32
				TotalResources returns the total number of resources currently in the pool.
				The value is the sum of ConstructingResources, AcquiredResources, and
				IdleResources.

		As Outputs Of (at least one exported)
			func (*Pool)[T].Stat() *Stat

	/* 3 unexporteds ... *//* 3 unexporteds: */
	 type ints (interface)
	 type resList[T] ([])

		Type Parameters:
			T: any

		Methods (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			(*resList[T]) append(val *Resource[T])
			(*resList[T]) popBack() *Resource[T]
			(*resList[T]) remove(val *Resource[T])

	 type valueCancelCtx (struct)
		valueCancelCtx combines two contexts into one. One context is used for values and the other is used for cancellation.

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			cancelCtx context.Context
			valueCtx context.Context
		Methods (total 4, all are exported)
			(*valueCancelCtx) Deadline() (time.Time, bool)
			(*valueCancelCtx) Done() <-chan struct{}
			(*valueCancelCtx) Err() error
			(*valueCancelCtx) Value(key any) any
		Implements (at least one exported)
			*valueCancelCtx : context.Context


Package-Level Functions (total 6, in which 1 is exported)

	 func NewPool[T](config *Config[T]) (*Pool[T], error)

		Type Parameters:
			T: any

		NewPool creates a new pool. Returns an error iff MaxSize is less than 1.

	/* 5 unexporteds ... *//* 5 unexporteds: */
	 func acquireSemAll(sem *semaphore.Weighted, num int) int
		acquireSemAll tries to acquire num free tokens from sem. This function is
		guaranteed to acquire at least the lowest number of tokens that has been
		available in the semaphore during runtime of this function.
		
		For the time being, semaphore doesn't allow to acquire all tokens atomically
		(see https://github.com/golang/sync/pull/19). We simulate this by trying all
		powers of 2 that are less or equal to num.
		
		For example, let's immagine we have 19 free tokens in the semaphore which in
		total has 24 tokens (i.e. the maxSize of the pool is 24 resources). Then if
		num is 24, the log2Uint(24) is 4 and we try to acquire 16, 8, 4, 2 and 1
		tokens. Out of those, the acquire of 16, 2 and 1 tokens will succeed.
		
		Naturally, Acquires and Releases of the semaphore might take place
		concurrently. For this reason, it's not guaranteed that absolutely all free
		tokens in the semaphore will be acquired. But it's guaranteed that at least
		the minimal number of tokens that has been present over the whole process
		will be acquired. This is sufficient for the use-case we have in this
		package.
		
		TODO: Replace this with acquireSem.TryAcquireAll() if it gets to
		upstream. https://github.com/golang/sync/pull/19

	 func log2Int[T](val T) uint8

		Type Parameters:
			T: ints

		log2Int returns log2 of an integer. This function panics if val < 0. For val
		== 0, returns 0.

	 func log2IntRange[T](val T, begin, end uint8) uint8

		Type Parameters:
			T: ints

	 func nanotime() int64
		nanotime returns the time in nanoseconds since process start.
		
		This approach, described at
		https://github.com/golang/go/issues/61765#issuecomment-1672090302,
		is fast, monotonic, and portable, and avoids the previous
		dependence on runtime.nanotime using the (unsafe) linkname hack.
		In particular, time.Since does less work than time.Now.

	 func newValueCancelCtx(valueCtx, cancelContext context.Context) context.Context
Package-Level Variables (total 3, in which 2 are exported)

	  var ErrClosedPool error
		ErrClosedPool occurs on an attempt to acquire a connection from a closed pool
		or a pool that is closed while the acquire is waiting.

	  var ErrNotAvailable error
		ErrNotAvailable occurs on an attempt to acquire a resource from a pool
		that is at maximum capacity and has no available resources.

	/* one unexported ... *//* one unexported: */
	  var globalStart time.Time
Package-Level Constants (total 4, none are exported)

	/* 4 unexporteds ... *//* 4 unexporteds: */
	const resourceStatusAcquired = 2
	const resourceStatusConstructing = 0
	const resourceStatusHijacked = 3
	const resourceStatusIdle = 1

The pages are generated with Golds v0.7.6. (GOOS=linux GOARCH=amd64)