[reardonj]

This PR provides an alternate solution to #4641 to fix #4571 , #4489, #3474 and related issues.

This solution avoids adding a completely different cancelation mechanism by breaking the fundamental principles of cancelation, by letting us 'continue' instead of unconditionally canceling, allowing graceful cleanup:

def onCancelGraceful[A](fa: F[A], continue: F[A]): F[A] 

onCancelGraceful works like onCancel except:

1. if it errors, the fiber errors
2. the fiber continues with the value it returns instead of functioning as finalizer.

This let's us write idioms like:

poll(f.join).onCancelGraceful(f.cancel *> f.join)

To express that if the fiber is canceled, another fiber, f, should also be canceled, but still needs to be joined to the current fiber.

I've also included Poll syntax to capture the idiom, so we can just write poll.fiberGracefully(f). This is essentially joinOrCancel (#4620)

Implementation

onCancelGraceful is defined in MonadCancel, with a default implementation that degrades to onCancel. This results in fairly clean fallback behavior (no worse than in CE 3.7.x) for implementations that don't define their own onCancelGraceful.

This required some reworking of how cancelation works. There is no longer a separate stack of finalizers in IOFiber¹. Instead, the stack is unwound until an onCancelGraceful or onCancel is hit. In either case, the handler is then executed. Then in the onCancelGraceful case, the fiber continues executing instead of continuing cancelation. However, the fiber is still canceled! So we'll immediately continue unwinding unless cancellation is masked where onCancelGraceful's handler was run. If cancellation is masked, the fiber will continue running until unmasked, then start unwinding again.

I've also written async* equivalents that complete on cancelation and made use of them in a few places.

Compared to #4641

Since onCancelGraceful still requires poll, this design avoids the weirdness of #4641 where onCancelRequested didn't actually need poll, but it was needed to make things work with the bad default onCancelRequested.

This design is less powerful, as the stack has to get unwound to the handler before continuing, so state that was set up in the poll is lost before the handler goes off. This means usages tend to be a bit repetitive (eg. the join example above), where both the poll body and handler have similar content.

On the upside, laws for the new method are fairly obvious, as they mostly follow the onCancel laws.

What is Not Fixed

• This closes the cancelation gap in cancelable, but does not avoid the separate fiber. If anything, this probably pushes us further away from removing the fiber by removing the separate finalizer stack. Since cancelation plays out by unwinding the stack, we really can't run finalizers asynchronously.

TODO

• I haven't implemented this in PureConc, as PureConc not running finalizers #3430 makes this kind of hard
• I'm open to naming suggestions. I considered using 'delay' or 'defer' instead of 'continue' for brevity, but those are already CE terms.
• rebase onto series/3.x. This PR introduces new methods so it needs to be 3.8.0

AI Use

Some of this code was generated by Copilot, especially test updates.

Footnotes

1. As a bonus, under -XX:+UseCompactObjectHeaders / JVM 27, this fixes Can we push to make IOFiber fit in 64 bytes? #3584 by pushing the object size to 64 bytes! ↩