apache / apache/asyncband

Explore a higher-level task group primitive

Open
#272 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
269
Forks
38
Avg merge
16h 44m
Merged PRs (30d)
102

Description

## Context

`WaitGroup` is a low-level lifetime barrier: cloned RAII handles represent outstanding work, and waiters observe when all handles are gone. It deliberately does not own tasks, collect results, propagate errors, or define cancellation and parent-child relationships.

Some use cases need a higher-level abstraction for a group of related asynchronous tasks. That should be designed as a separate primitive rather than changing `WaitGroup`. `ForkJoin` was an initial placeholder, not a proposed public name.

## Ecosystem survey

- Rust's [`tokio::task::JoinSet`](https://docs.rs/tokio/latest/tokio/task/struct.JoinSet.html) owns runtime-spawned tasks, yields homogeneous results in completion order, and aborts remaining tasks when dropped. It is primarily controlled by one mutable collection owner.
- Rust's [`tokio_util::task::TaskTracker`](https://docs.rs/tokio-util/latest/tokio_util/task/task_tracker/struct.TaskTracker.html) is cloneable and supports registration without mutable access. Waiting requires the tracker to be both closed and empty; completed tasks release their storage immediately, results are not retained, and dropping the tracker does not abort tasks.
- Go's [`errgroup.Group`](https://pkg.go.dev/golang.org/x/sync/errgroup) groups goroutines belonging to one operation, waits for them, returns the first non-nil error, can cancel a derived context on failure, and optionally limits concurrency.
- Java's [`StructuredTaskScope`](https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/concurrent/StructuredTaskScope.html) makes one owner responsible for a lexical task scope. It forks subtasks, joins them under an explicit policy, prevents new forks after joining, and closes by cancelling and waiting for unfinished subtasks.
- Swift's [`TaskGroup`](https://developer.apple.com/documentation/swift/taskgroup) is a non-escaping structured scope for dynamically created child tasks. Children inherit parent context, results form an asynchronous sequence, and the scope cannot return while children remain.
- Kotlin's [`coroutineScope`](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html) establishes a parent-child task tree: the parent waits for children, while failure and cancellation propagate through the scope.

These examples separate into at least three families: result-owning task collections (`JoinSet`), shareable lifecycle trackers (`TaskTracker`), and structured lexical scopes (`StructuredTaskScope`, Swift `TaskGroup`, Kotlin `coroutineScope`). Go's `errgroup` combines lifecycle tracking with failure policy.

## Questions to answer

1. Is the target a runtime-agnostic future tracker, or may it spawn and therefore depend on a runtime?
2. Is registration shareable with child tasks, restricted to one owner, or lexically scoped so handles cannot escape?
3. Does joining only signal quiescence, return one result at a time, collect all results, or reduce them through a policy?
4. How are task errors and panics represented, and should the first failure cancel siblings?
5. What does dropping the owner do: detach, cancel, abort, or synchronously/asynchronously wait?
6. Is there an explicit `close` transition that prevents new top-level work? Can running children register nested work after close?
7. Is bounded concurrency part of this primitive or an orthogonal concern?
8. Does the design require one join owner, or are multiple completion observers meaningful?

## Naming

The name should follow the selected contract rather than lead it:

- `TaskGroup` suggests structured child ownership and possibly result collection.
- `JoinSet` suggests an owned collection with per-task results.
- `TaskTracker` suggests shared lifecycle observation without task ownership.
- `TaskScope` suggests lexical structure and non-escaping children.

No name or API is proposed yet. The next step is to identify concrete Asyncband use cases and choose which semantic family, if any, belongs in a runtime-agnostic synchronization crate.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by identifying concrete Asyncband use cases, then compare them with the JoinSet, TaskTracker, errgroup, StructuredTaskScope, TaskGroup, and coroutineScope models surveyed here. Done means selecting a semantic family and contract—or rejecting the need for a new primitive—with answers to the eight listed questions and a name derived from that contract.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
distributed-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.