Skip to content

refactor(pool): simplify lifecycle and maintenance semantics - #180

Merged
tisonkun merged 5 commits into
mainfrom
codex/pool-polish
Aug 23, 2026
Merged

refactor(pool): simplify lifecycle and maintenance semantics#180
tisonkun merged 5 commits into
mainfrom
codex/pool-polish

Conversation

@tisonkun

Copy link
Copy Markdown
Member

Summary

  • Simplify bounded and unbounded pools around one private state implementation, remove approximate waiter accounting and duplicate mutex/retain helpers, and allocate bounded idle storage lazily.
  • Make lifecycle semantics precise: last_used advances when a checkout is returned, retain invokes on_detached after releasing the pool lock, and status snapshots report exact tracked and idle object counts.
  • Replace the spinning replenish path with fallible replenish_to, which reserves up to the immediately available capacity in one operation and reports manager creation errors.
  • Add synchronous try_get for manually populated unbounded pools and support managed values that are Send without also requiring Sync.
  • Add deterministic coverage for return timestamps, retention hooks and panic safety, queue order, cancellation policies, capacity under interleaved checkout/replenishment, lazy allocation, and trait bounds, plus focused Pool benchmarks.
  • Reframe Asyncband in the README, crate docs, and package metadata as composable, runtime-agnostic concurrency building blocks. The documented boundary is reusable mechanism versus caller-owned execution and timing policy.

API notes

  • bounded::PoolStatus::wait_count is removed because it was approximate and required bookkeeping on every checkout.
  • bounded::Pool::replenish becomes replenish_to and returns Result<usize, M::Error>.
  • unbounded::Pool<T>::try_get provides the non-waiting manual-pool path.

These APIs were introduced in the current unreleased cycle by #177, so this PR refines them before their first release.

Timeouts, task spawning, periodic retention/replenishment, and other runtime policy remain outside the pool and compose around its futures. This is a follow-up to #177 and is related to the broader scope discussion in #176.

Validation

  • cargo x check
  • cargo x test
  • cargo x lint
  • cargo bench -p benchmarks --bench benchmarks -- pool --test
  • cargo package -p asyncband
  • cargo tree -p asyncband --no-default-features --features pool -e normal (no normal dependencies)

@tisonkun
tisonkun merged commit c67c237 into main Aug 23, 2026
9 checks passed
@tisonkun
tisonkun deleted the codex/pool-polish branch August 23, 2026 19:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant