refactor: harden library ergonomics and test contracts

[tisonkun]

Summary

• Remove latch future types that callers could neither construct nor obtain through the public async methods.
• Reject zero-sized bounded pools instead of allowing checkouts that can never complete.
• Replace debug-string assertions, scheduler sleeps, and pseudo pressure benchmarks with deterministic tests of observable behavior.
• Clarify lifecycle, cancellation, capacity, and ownership contracts across the public documentation, and correct misleading examples.

Design Notes

The audit treats Asyncband as a foundational published crate: public surface area must be usable, examples must teach sound async patterns, and tests should defend stable behavior rather than formatting or scheduler timing. Each concern is isolated in a small commit so it can be reviewed or dropped independently.

The patch removes 1,190 net lines. The only runtime behavior change is rejecting a bounded pool whose maximum size is zero; the rest narrows unusable API surface, strengthens the default-feature test workflow, or improves tests and documentation.

Validation

• cargo x check
• cargo x test
• cargo x lint
• cargo package -p asyncband --allow-dirty

[Copilot]

Pull request overview

This pull request refactors Asyncband’s public-facing ergonomics and contracts by trimming unusable public types, tightening invalid configuration behavior, and replacing timing-/format-dependent tests and examples with deterministic assertions that better defend observable behavior.

Changes:

• Reject zero-capacity bounded pools at construction time and add coverage for the panic contract.
• Replace stress/timing/debug-string assertions in integration tests with deterministic, contract-focused tests using direct polling where needed.
• Clarify and harden public documentation/examples across multiple primitives (feature-gated doctests, lifecycle/ownership semantics, cancellation expectations).

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
xtask/src/main.rs	Adds a dedicated doc-test command to the cargo x test workflow (with a naming mismatch noted).
tests-integration/tests/waitgroup_test.rs	Replaces runtime/sleep-based tests with deterministic polling and explicit task joins.
tests-integration/tests/semaphore_test.rs	Removes a timing-based stress test.
tests-integration/tests/rwlock_test.rs	Replaces broad stress/panic-safety/debug-string tests with deterministic concurrency and ownership-contract assertions.
tests-integration/tests/pool_behavior_test.rs	Adds coverage that bounded pools reject max_size = 0.
tests-integration/tests/once_test.rs	Reworks Once tests to validate cancellation/panic retry and concurrent initialization deterministically.
tests-integration/tests/once_map_test.rs	Removes debug-string assertion in constructors test.
tests-integration/tests/once_cell_test.rs	Replaces sleep-based initialization tests with deterministic cancellation/retry and single-publication assertions.
tests-integration/tests/mpsc_test.rs	Replaces pressure benchmarks with deterministic ordering/capacity/state tests.
tests-integration/tests/latch_test.rs	Replaces timing assertions with deterministic waker-tracking and concurrency tests.
tests-integration/tests/broadcast_mpmc_unbounded_test.rs	Replaces spin/sleep completion detection with a bounded blocking wait via recv_timeout.
CHANGELOG.md	Documents removal of unconstructible latch wait types from the public API.
asyncband/src/waitgroup/mod.rs	Updates docs to clarify coordinator/worker handle semantics and wait-future cloning behavior.
asyncband/src/shutdown/mod.rs	Clarifies shutdown/guard lifecycle and improves example correctness (task joining/observable results).
asyncband/src/semaphore/mod.rs	Tightens module docs and corrects owned-permit examples and wording.
asyncband/src/pool/unbounded.rs	Updates internal safety comments from “SAFETY” to explicit invariants.
asyncband/src/pool/bounded.rs	Enforces max_size > 0 at runtime and updates related docs/invariants.
asyncband/src/once/once_cell/mod.rs	Improves docs to state retry semantics and clarifies example behavior deterministically.
asyncband/src/mpsc/unbounded.rs	Clarifies doc wording (“waits” vs “sleeps”) and updates safety commentary to invariants.
asyncband/src/mpsc/mod.rs	Expands module-level docs with bounded vs unbounded tradeoffs.
asyncband/src/mpsc/bounded.rs	Documents panic contract for zero buffer and updates wording/invariants.
asyncband/src/lib.rs	Feature-gates the mutex doctest so docs build under minimal/no-feature configurations.
asyncband/src/latch/mod.rs	Clarifies latch semantics/contracts, improves examples, and makes internal wait-future types non-public.
asyncband/src/condvar/mod.rs	Improves examples to await spawned tasks and uses wait_while patterns more directly.
asyncband/src/barrier/mod.rs	Rewrites docs/examples to emphasize barrier generations and leader selection more clearly.

Suppressed comments (1)

xtask/src/main.rs:398

• This command is built with --no-default-features, but the function name suggests it's testing the default feature set. Renaming the helper to make_no_default_features_doc_test_cmd would better match the actual cargo invocation.

fn make_default_feature_doc_test_cmd() -> StdCommand {

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.