From 884a6ba737a3eecc4cc393b5a93eceb1e7dffe23 Mon Sep 17 00:00:00 2001 From: "Sean T. Allen" Date: Wed, 4 Mar 2026 16:52:37 -0500 Subject: [PATCH 1/2] Link to Batch and Yield pattern from scheduler docs The Batch Processing section explains the runtime's internal batching mechanism. Adding a bridge to the Batch and Yield pattern shows readers how to apply the same idea in their own code. Closes #575 --- docs/runtime-basics/scheduler.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/runtime-basics/scheduler.md b/docs/runtime-basics/scheduler.md index 5db44576..52ee089f 100644 --- a/docs/runtime-basics/scheduler.md +++ b/docs/runtime-basics/scheduler.md @@ -25,3 +25,5 @@ Actors with pending messages are placed on per-thread run queues. When a schedul ## Batch Processing When an actor gets scheduled, it doesn't just process one message. It processes a batch of messages from its queue before yielding, which reduces scheduling overhead. After the batch, the actor goes back onto the run queue if it still has pending messages, giving other actors a chance to run. + +This batch-then-yield mechanism is also something you can apply deliberately in your own code. When you have a large amount of work to do, you can break it into batches and send yourself a message between each batch, giving other actors a chance to run. The [Batch and Yield](https://patterns.ponylang.io/async/batch-and-yield) pattern covers this technique in detail. From ea1901c526322f49bace9278522e1594ff9bc3dc Mon Sep 17 00:00:00 2001 From: "Sean T. Allen" Date: Wed, 4 Mar 2026 16:53:49 -0500 Subject: [PATCH 2/2] Move pattern link to Cooperative, Not Preemptive section The Batch and Yield pattern is about avoiding long-running behaviors, which is the concern of the cooperative scheduling section, not the runtime's internal batch processing mechanism. --- docs/runtime-basics/scheduler.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/runtime-basics/scheduler.md b/docs/runtime-basics/scheduler.md index 52ee089f..112149be 100644 --- a/docs/runtime-basics/scheduler.md +++ b/docs/runtime-basics/scheduler.md @@ -10,6 +10,8 @@ This is different from preemptive schedulers (like OS thread schedulers), which This is why the [scheduling gotcha](../gotchas/scheduling.md) warns against long-running behaviors. A behavior that loops for a long time (or calls FFI code that blocks) monopolizes a scheduler thread and prevents other actors from making progress on that thread. +When you have a large amount of work to do, you can break it into batches and send yourself a message between each batch, giving other actors a chance to run. The [Batch and Yield](https://patterns.ponylang.io/async/batch-and-yield) pattern covers this technique in detail. + ## Scheduler Threads By default, the Pony runtime creates one scheduler thread per physical CPU core. Each scheduler thread can execute one actor behavior at a time. If you have 4 cores, you get 4 scheduler threads, and up to 4 actors can execute behaviors simultaneously. @@ -25,5 +27,3 @@ Actors with pending messages are placed on per-thread run queues. When a schedul ## Batch Processing When an actor gets scheduled, it doesn't just process one message. It processes a batch of messages from its queue before yielding, which reduces scheduling overhead. After the batch, the actor goes back onto the run queue if it still has pending messages, giving other actors a chance to run. - -This batch-then-yield mechanism is also something you can apply deliberately in your own code. When you have a large amount of work to do, you can break it into batches and send yourself a message between each batch, giving other actors a chance to run. The [Batch and Yield](https://patterns.ponylang.io/async/batch-and-yield) pattern covers this technique in detail.