docs: design proposal for run-anywhere compute tasks - #300
Draft
joe-redpanda wants to merge 9 commits into
Draft
Conversation
Design proposal for a core-unaffine, idle-priority task type: CPU-heavy work expressed as a dedicated coroutine type, pulled from a global queue by whichever shard has spare cycles, yielding back cooperatively when foreground work arrives, and completing to the submitting shard. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Lock-free MPMC queue of type-erased coroutine handles with a relaxed size counter for a cheap empty check, per the run-anywhere compute tasks design doc (v0 scope). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A second idle-handler seam consulted from the idle branch, gated on a bool so the unused feature costs one branch on the idle path and nothing on the busy path. Keeps the public set_idle_cpu_handler() available to applications. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
compute::task<T> is a coroutine with no core affinity, executed checkpoint-to-checkpoint by whichever shard has spare CPU via the reactor's compute idle handler, strictly below normal seastar work. The closed awaitable set (checkpoint() only) makes shard-affine seastar machinery unreachable at compile time. submit()/completion are shard-affine: the returned future resolves on the submitting shard, thread_pool-style, via smp::submit_to. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
With 2 of 4 shards saturated by foreground tasks, all compute iterations execute on the idle shards: the participant only runs from the idle branch, which a shard with a non-empty task queue never reaches. Validated in dev and debug modes (debug forces a yield at every checkpoint): 0 of 4000 iterations on the busy shards. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
joe-redpanda
commented
Jul 23, 2026
| }; | ||
|
|
||
| compute_queue& the_queue() { | ||
| static compute_queue instance; |
Author
There was a problem hiding this comment.
iirc singletons are sly mutex operations. This probably should be a static registration slot provided by the main method / on startup
joe-redpanda
commented
Jul 23, 2026
| auto& cq = the_queue(); | ||
| // push() only fails on node allocation failure, which is not | ||
| // recoverable here. | ||
| auto ok = cq.q.push(h.address()); |
Author
There was a problem hiding this comment.
these have to be some of the worst variable names I have ever seen
joe-redpanda
commented
Jul 23, 2026
|
|
||
| size_t queue_size() noexcept { | ||
| auto s = the_queue().size.load(std::memory_order_relaxed); | ||
| return s < 0 ? 0 : static_cast<size_t>(s); |
Author
There was a problem hiding this comment.
well that shouldn't happen
joe-redpanda
commented
Jul 23, 2026
| /// Install the run-anywhere compute participant (see seastar::compute). | ||
| /// Same contract as set_idle_cpu_handler; a separate slot so the public | ||
| /// idle handler remains available to applications. | ||
| void set_compute_idle_handler(idle_cpu_handler&& handler) { |
Author
There was a problem hiding this comment.
and why did we not simply use the set_idle_cpu_handler?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Design document for a new run-anywhere compute task type: CPU-heavy work with the opposite affinity contract to normal seastar tasks.
compute::task<T>) that is deliberately not aseastar::task— the closed awaitable set makes shard-affine machinery (futures,engine(), timers, I/O) unreachable at compile time, which is what makes migration safe.co_await compute::checkpoint()cooperatively yields the CPU back the moment the running shard has foreground work, returning the task to the global queue for another idle shard to pick up.submit()returns an ordinary future that resolves on the submitting shard; only the compute task itself migrates.The doc is structured with the human-readable design up top (problem, high-level design, API sketch, lifecycle), followed by checkpoint semantics, the wake protocol, perf-impact analysis, open questions, and a fully worked end-to-end trace as an addendum.
Design only — no implementation in this PR. Opening as a draft to gather feedback on the approach.
🤖 Generated with Claude Code