Initial stable release.

Added #

Core:

• ObjectPool<T> — generic object pool with O(1) acquire/release via an embedded free-list data structure.
• Poolable — optional abstract interface class for objects that participate in pool lifecycle (onAcquire, onRelease, isValid).
• PoolMetrics — immutable snapshot of pool performance statistics (utilizationRate, hitRate, acquiresPerSecond, leakEstimate, etc.).

Overflow Strategies:

• PoolOverflowStrategy<T> — abstract interface for custom strategies.
• ExpandStrategy — grows the pool when exhausted; respects maxSize and supports growthIncrement for bulk expansion.
• DiscardStrategy — returns null silently when exhausted; pool size never grows.
• ReplaceStrategy — forcibly reclaims the oldest in-use object when exhausted; never returns null for non-empty pools.

API Methods:

• acquire() → T? — O(1) acquire; returns null if exhausted and strategy cannot provide.
• acquireOrThrow() → T — acquire or throw PoolExhaustedException.
• release(T) — O(1) release with double-release and foreign-object detection.
• releaseIfNotNull(T?) — convenience null-safe release.
• use<R>(R Function(T)) — RAII-style scoped acquire/release (sync).
• useAsync<R>(Future<R> Function(T)) — RAII-style scoped acquire/release (async). Guaranteed release even when the Future throws.
• prewarm(int) — ensure at least N objects are ready (no-op if already large).
• drain() — remove all idle objects to reclaim memory.
• dispose() — destroy the pool; calls onRelease on any in-use Poolable objects.

Exceptions:

• PoolExhaustedException — thrown by acquireOrThrow() on exhaustion.
• PoolInvalidReleaseException — thrown by release() on foreign-object or double-release errors.

Test Suite (1,162 lines, 40+ test cases):

• object_pool_test.dart — initialization, acquire, release, Poolable lifecycle, use()/useAsync(), prewarm()/drain()/dispose(), metrics, edge cases.
• strategies_test.dart — ExpandStrategy, DiscardStrategy, ReplaceStrategy behaviour including growth limits, no-growth invariants, and forced reclaim.
• pool_metrics_test.dart — all derived metric properties.
• concurrency_test.dart — async interleaving, concurrent exhaustion with both ExpandStrategy and DiscardStrategy, exception safety.

Examples:

• example/main.dart — five self-contained examples (basic, scoped, overflow strategies, prewarm/drain, metrics dashboard).
• example/particle_system_example.dart — full 120-frame particle simulation with radial emission, physics, lifecycle, and pool metrics.
• example/connection_pool_example.dart — database connection pool with validateOnAcquire, async queries, concurrent batch execution, and health-check simulation.

Benchmarks:

• benchmark/pool_vs_new_benchmark.dart — four micro-benchmarks using benchmark_harness: direct allocation, pool acquire/release, pool use(), and high-frequency 100-particle-per-frame cycling.
• benchmark/gc_pressure_benchmark.dart — macro-benchmark comparing wall-clock time of a 300-frame game loop with and without pooling, demonstrating cumulative GC pressure elimination.

Documentation:

• doc/getting_started.md — step-by-step guide for new users.
• Comprehensive /// dartdoc comments on every public symbol.
• README.md with API table, use-case examples, common mistakes, internal architecture diagram, and performance expectations.

Added #

• Initial development preview.
• Basic ObjectPool<T> with fixed size and simple acquire/release.