readme

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,
+// on very sudden drops in traffic, it ensures the eventual release of all pooled items with an internal
-// that is timed based on the duration of the last active usage session, which is the time while there were
+// background job, that is timed based on the duration of the last active usage session, which is the time while
-// active items. Together with the pool implementation, it always reuses the most recent items, as in LIFO for
+// there were active items. Together with the pool implementation, it always reuses the most recent items, as in
-// Get and FIFO for Free.
+// 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
+// We need to be aware of some potential caveats due to its zero-config nature. Because it relies on the
-// values, like a timing parameter. It only considers the sequence of the pool states. This can result in
+// sequence of operations rather than wall-clock thresholds for its core logic, the algorithm treats rapid
-// behaviour that, without understanding this zero-config nature, might be unexpected. A trivial example is that
+// spikes and gradual surges similarly if the sequence of pool states is identical. In short, it can happen
-// the algorithm doesn't differentiate between periodic long grow/shrink/steady patterns and periodic short
+// that: __/\__/\__/\__ = _|_|_|_. It prioritize maintaining sufficient 'headroom' based on observed volatility.
-// 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).
 func Adaptive() Algo {
 	return makeAdaptiveAlgo()
 }

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*