From 8d48b91110bd2e603210c6eb96f55406196d0a35 Mon Sep 17 00:00:00 2001 From: Arpad Ryszka Date: Sat, 14 Mar 2026 21:55:50 +0100 Subject: [PATCH] readme --- lib.go | 22 ++++++++++------------ readme.md | 20 ++++++++++++++++++++ 2 files changed, 30 insertions(+), 12 deletions(-) diff --git a/lib.go b/lib.go index 8e50d2c..69ea972 100644 --- a/lib.go +++ b/lib.go @@ -22,7 +22,7 @@ type Stats struct { // Idle is the number of resources currently held by the pool. Idle int - // Active is the nubmer of resources that are currently in use as known by the pool. + // Active is the number of resources that are currently in use as known by the pool. Active int // Get is the number of get operations during the entire life cycle of the pool. @@ -70,7 +70,7 @@ const ( AllocateError // AllEvents can be used as a mask that includes all the event types. - AllEvents = GetOperation | PutOperation | AllocateOperation | FreeOperation | AllocateError + AllEvents = GetOperation | PutOperation | AllocateOperation | LoadOperation | FreeOperation | AllocateError ) // Event values are sent by the pool after various operations, if it is configured to use a channel the send the @@ -203,17 +203,15 @@ func (s Stats) String() string { // // It is based on exponential moving average of the active items and the deviation of it. This way it can react // to, and to some extent overbuild, on the perceived stress. It decays the number of idle items gradually, and -// on very sudden drops in traffic, it ensures the eventual release of all pooled items with a background job, -// that is timed based on the duration of the last active usage session, which is the time while there were -// active items. Together with the pool implementation, it always reuses the most recent items, as in LIFO for -// Get and FIFO for Free. +// on very sudden drops in traffic, it ensures the eventual release of all pooled items with an internal +// background job, that is timed based on the duration of the last active usage session, which is the time while +// there were active items. Together with the pool implementation, it always reuses the most recent items, as in +// LIFO for Get and FIFO for Free. // -// We need to be aware of some potential caveats due to its zero-config nature. It doesn't use any absolute -// values, like a timing parameter. It only considers the sequence of the pool states. This can result in -// behaviour that, without understanding this zero-config nature, might be unexpected. A trivial example is that -// the algorithm doesn't differentiate between periodic long grow/shrink/steady patterns and periodic short -// spikes/steady patterns. In short, it can happen that: __/\__/\__/\__ = _|_|_|_. Instead, it optimizes for -// having enough but no more 'capacity' (idle items) for the predicated 'load' (active items). +// We need to be aware of some potential caveats due to its zero-config nature. Because it relies on the +// sequence of operations rather than wall-clock thresholds for its core logic, the algorithm treats rapid +// spikes and gradual surges similarly if the sequence of pool states is identical. In short, it can happen +// that: __/\__/\__/\__ = _|_|_|_. It prioritize maintaining sufficient 'headroom' based on observed volatility. func Adaptive() Algo { return makeAdaptiveAlgo() } diff --git a/readme.md b/readme.md index e69de29..659fff7 100644 --- a/readme.md +++ b/readme.md @@ -0,0 +1,20 @@ +# pool + +The pool module provides a resource pool implementation that is safe to access from multiple goroutines. + +It supports: + +- finalizing items when shrinking the pool +- monitoring the pool usage and state with events and statistics +- max idle size and timeout based shrinking algorithms +- a zero-config adaptive algorithm that can automatically adapt to changing resource usage characteristics +- it also accepts custom algorithm implementations + +Find the documentation here: + +- [lib.go](lib.go) +- https://godocs.io/code.squareroundforest.org/arpio/buffer + +--- + +*Made in Berlin, DE*