[I] design(scope): define boundaries for pools, future concurrency, and schedulers [asyncband]

["tisonkun (via GitHub)" <gi...@apache.org>]

tisonkun opened a new issue, #176:
URL: https://github.com/apache/asyncband/issues/176

   ## Motivation
   
   Asyncband currently describes itself as a library of essential, runtime-agnostic synchronization primitives. Its API already spans both lower-level mechanisms (`Mutex`, `Semaphore`, channels) and composed coordination protocols (`shutdown`, `singleflight`). Possible future work includes admission control, future concurrency, and schedulers.
   
   We need a durable scope boundary before deciding on individual additions. Implementation complexity, internal composition, and whether an abstraction holds state are not useful boundaries by themselves: many caller-facing primitives are implemented from lower-level ones and maintain substantial state.
   
   [Fastpool](https://github.com/fast/fastpool) is a useful concrete test case. It provides generic bounded and unbounded object pools while preserving runtime independence:
   
   - object creation and recycling are caller-provided futures;
   - acquisition makes progress only while the returned future is polled;
   - acquired objects return through RAII;
   - timeout is composed around the complete `get()` future by the caller rather than configured inside the pool;
   - the pool does not obtain a concrete executor, timer, reactor, or background task.
   
   The question is therefore not only whether an object pool is more complex than a mutex. It is whether reusable-resource leasing and lifecycle coordination belong among Asyncband's concurrency building blocks.
   
   ## Working hypothesis
   
   A possible project-level definition is:
   
   > Asyncband provides runtime-agnostic, explicitly driven building blocks for asynchronous concurrency. Components may coordinate state, ownership, lifecycle, and scheduling, but must not implicitly acquire an executor, clock, reactor, or worker threads.
   
   Under this definition, a candidate would need to satisfy all of the following:
   
   1. Its primary contract expresses generic concurrency semantics rather than a domain-specific integration.
   2. Progress is explicit: it results from polling a returned future, stream, or driver, or from an explicit method call or `Drop`.
   3. It does not depend on an ambient runtime capability such as a current executor, concrete timer, I/O reactor, or implicitly started worker.
   4. Orthogonal behavior that can be expressed by wrapping a future, such as timeout or retry, remains outside the abstraction.
   5. Cancellation, drop, ownership, and wake-up behavior form a clear cross-runtime contract.
   
   Runtime independence would be necessary but not sufficient: many libraries are runtime-independent without being concurrency building blocks.
   
   ## Scheduling is not one category
   
   The word "scheduler" covers several materially different abstractions:
   
   - **Coordination policy:** admission, fairness, or priority determines which caller receives permission next, without polling the admitted work.
   - **Parent-future scheduling:** a `join`, `race`, future group, or concurrent stream polls child futures only when its own parent future is polled.
   - **Explicit executor scheduling:** detached tasks are queued and polled through an explicitly driven `tick()` or `run()` API, without bundling I/O or timers.
   - **Ambient runtime:** workers, timers, I/O drivers, and task execution are bundled or obtained implicitly.
   
   The first two appear compatible with the working hypothesis. An explicitly driven executor may fit the project while deserving a separate package or API category. A bundled ambient runtime appears to be a non-goal. This boundary needs validation rather than assumption.
   
   ## Questions to resolve
   
   - Should Asyncband continue to describe all exported APIs as "synchronization primitives," or use a broader term such as "composable concurrency building blocks"?
   - Is a generic object pool a resource-coordination primitive or protocol within the core scope?
   - If it is in scope, do both bounded leasing and unbounded concurrent reuse belong?
   - Should an accepted pool live behind an `asyncband::pool` feature, or remain a separate crate within the same project? Package placement should be decided independently from conceptual scope.
   - Which future-concurrency operations would add distinct semantics rather than duplicate `futures` or `futures-concurrency`?
   - Where should Asyncband draw the boundary between scheduling policy, explicitly driven executors, and runtimes?
   - Is the current `shutdown` API best understood and named as a specific graceful-shutdown protocol, or as part of a more general lifecycle/cancellation category?
   - Should keeping timeout, retry, hooks, and similar orthogonal policies externally composable become an explicit project design rule?
   - How should the project distinguish "fits the scope" from "is sufficiently useful and differentiated to implement"?
   
   ## Expected outcome
   
   This issue should first produce a short, reviewable scope statement and an inclusion test that can be applied consistently. Only after that should it decide whether and how Fastpool, future-concurrency APIs, or scheduler APIs are incorporated.
   
   Implementation details, version migration, release mechanics, and code-import procedure are intentionally out of scope until the technical boundary is understood.
   
   ## References
   
   - Current project overview: https://github.com/apache/asyncband#overview
   - Earlier scope discussion during the ASF donation proposal: https://github.com/apache/asyncband/issues/140#issuecomment-5205093195
   - Fastpool design and timeout rationale: https://docs.rs/fastpool/latest/fastpool/#why-does-fastpool-have-no-timeout-config
   - Go `sync.Pool`: https://pkg.go.dev/sync#Pool
   - Go `x/sync/singleflight`: https://pkg.go.dev/golang.org/x/sync/singleflight
   - Poll-driven future groups: https://docs.rs/futures/latest/futures/stream/struct.FuturesUnordered.html
   - Explicitly driven executor example: https://docs.rs/async-executor/latest/async_executor/struct.Executor.html
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@asyncband.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@asyncband.apache.org
For additional commands, e-mail: commits-help@asyncband.apache.org

Re: [I] design(scope): define boundaries for pools, future concurrency, and schedulers [asyncband]

["tisonkun (via GitHub)" <gi...@apache.org>]

tisonkun closed issue #176: design(scope): define boundaries for pools, future concurrency, and schedulers
URL: https://github.com/apache/asyncband/issues/176


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@asyncband.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@asyncband.apache.org
For additional commands, e-mail: commits-help@asyncband.apache.org