Add cede() for yielding the current virtual thread (#481)

Adds `cede()` to `ox.control`, next to `checkInterrupt()`:

```scala
inline def cede(): Unit =
  checkInterrupt()
  Thread.`yield`()
```

Virtual threads are not preempted, so a CPU-bound loop can starve other
virtual threads (in an experiment with 2x-cores busy-looping VTs, half
of them received *zero* CPU time). `cede()` gives compute-intensive code
a way to cooperate with the scheduler — and, since it also checks the
interrupt flag, with the cancellation protocol: a busy loop calling
`cede()` becomes both fair and cancellable.

## Why `checkInterrupt + Thread.yield`

Based on experiments comparing yielding techniques on virtual threads
(JDK 21 & 26, Linux, 8 cores), following up on [this
gist](https://gist.github.com/lbialy/9f3732ce9901ba76ee2da9dd86f7df33):

* `Thread.yield` genuinely unmounts and resubmits the continuation to
the back of the scheduler's queue (external submit when the carrier's
local queue is empty) — it reliably prevents starvation (89–93%
liveness-probe capture vs 2% baseline), at ~1µs per call.
* `LockSupport.parkNanos(1)` gives near-perfect round-robin fairness,
but costs ~40–46µs per call (timer round-trip), stalls the caller for
that time, and silently degrades to a no-op when the interrupt flag is
set — i.e. exactly when the enclosing scope is being cancelled. Since
`Thread.yield` is ~50x cheaper, calling it more frequently (every ~1ms
of computation) matches `parkNanos(1)`'s liveness at a quarter of the
overhead. The trade-off is mentioned in the scaladoc.
* `LockSupport.parkNanos(0)` is a true no-op.
* `Thread.sleep(0)` behaves identically to `checkInterrupt +
Thread.yield` (that's literally its JDK implementation for virtual
threads), but only as an `@implNote` — the explicit version doesn't rely
on unspecified behaviour.

The interrupt check makes `cede()` a cancellation boundary, consistent
with e.g. cats-effect's `IO.cede`.

Includes tests and a docs entry in `utils/control-flow.md`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: adamw

core/src/main/scala/ox/control.scala

@@ -31,3 +31,21 @@ inline def never: Nothing = forever {
   */
 inline def checkInterrupt(): Unit =
   if Thread.interrupted() then throw new InterruptedException()
+
+/** Yields the current (virtual) thread back to the scheduler, allowing other threads to run. Useful in compute-intensive code, which
+  * doesn't otherwise call any blocking operations: virtual threads are not preempted, so without yielding, a CPU-bound loop can starve
+  * other virtual threads. As a rule of thumb, call `cede()` about once every millisecond of computation (a single call costs about 1µs).
+  *
+  * Additionally, checks if the current thread is interrupted (as [[checkInterrupt]] does), making the surrounding computation cooperate in
+  * the cancellation protocol, e.g. when run in a [[supervised]] scope.
+  *
+  * Yielding is implemented using `Thread.yield`, which prevents complete starvation of other threads, but doesn't guarantee a fair
+  * distribution of CPU time. If strict fairness between CPU-bound threads is required, `LockSupport.parkNanos(1)` yields near-round-robin
+  * scheduling, at a much higher cost (about 40µs per call, as it involves a timer round-trip).
+  *
+  * @throws InterruptedException
+  *   if the current thread is interrupted.
+  */
+inline def cede(): Unit =
+  checkInterrupt()
+  Thread.`yield`()

core/src/test/scala/ox/ControlTest.scala

@@ -68,6 +68,27 @@ class ControlTest extends AnyFlatSpec with Matchers:
     trail.get shouldBe Vector("done")
   }
 
+  "cede" should "throw InterruptedException and clear the interrupt flag when the thread is interrupted" in {
+    Thread.currentThread().interrupt()
+    intercept[InterruptedException](cede())
+    Thread.currentThread().isInterrupted() shouldBe false
+  }
+
+  it should "return normally when the thread is not interrupted" in {
+    noException should be thrownBy cede()
+  }
+
+  it should "make a compute-intensive fork responsive to cancellation" in {
+    val r = supervised {
+      val f = forkCancellable {
+        forever(cede())
+      }
+      sleep(100.millis) // making sure the fork starts
+      f.cancel()
+    }
+    r should matchPattern { case Left(_: InterruptedException) => }
+  }
+
   "timeoutOption" should "pass through the exception of failed computation" in {
     val myException = new Throwable("failed computation")
 

doc/utils/control-flow.md

@@ -8,5 +8,9 @@ There are some helper methods which might be useful when writing code using ox's
 * `never` blocks the current thread indefinitely, until it is interrupted
 * `checkInterrupt()` checks if the current thread is interrupted, and if so, throws an `InterruptedException`. Useful in
   compute-intensive code, which wants to cooperate in the cancellation protocol
+* `cede()` yields the current (virtual) thread back to the scheduler, allowing other threads to run, and checks for
+  interruption (as `checkInterrupt()` does). Useful in compute-intensive code, which doesn't otherwise call any blocking
+  operations: virtual threads are not preempted, so without yielding, a CPU-bound loop can starve other virtual threads.
+  As a rule of thumb, call `cede()` about once every millisecond of computation (a single call costs about 1µs)
 
 All of these are `inline` methods, imposing no runtime overhead.