Clarify exception propagation behaviour

[michaelpj]

I had some questions reading the (generally good!) documentation.

• Exceptions propagated from child to parent and vice versa are presumably always thrown asynchronously? (I think this is the only possible thing, I just had to stop and think and I think it could be written down)
• Which exception is used to kill child threads? I think it's ScopeClosing, but it's not exported. Maybe you never need it? But I could imagine a situation where you want to catch various other async exceptions but not ScopeClosing.

[mitchellwrosen]

Hello, let's see...

Exceptions propagated from child to parent and vice versa are presumably always thrown asynchronously? (I think this is the only possible thing, I just had to stop and think and I think it could be written down)

Yes, (as you probably already know, but I will say anyway) there's just a throwTo primitive which raises an exception in a target thread and then returns; it is customary to only throw exceptions that are "instances of" (in the extensible exception hierarchy sense) SomeAsyncException, which is the root of what we call async exceptions.

Which exception is used to kill child threads? I think it's ScopeClosing, but it's not exported. Maybe you never need it? But I could imagine a situation where you want to catch various other async exceptions but not ScopeClosing.

When the parent is closing (due to an exception being raised in the parent, or due to the program reaching the end of a scoped block naturally), yes, it throws a ScopeClosing exception to each child, which is an async exception.

It is not exported because child threads are encouraged to follow async exception best practices: whenever one is raised, do any necessary cleanup, then re-raise the exception.

Not all async exceptions must be handled this way. For example, if you receive a HeapOverflow, maybe you want to release some memory and continue running. But ScopeClosing isn't one of these - if you disobey by catching and ignoring, the parent thread that is waiting for you to stop running will just block and be busted.

Hope that helps, let me know if you have any concrete doc suggestions!

[michaelpj]

Thanks, that's helpful!