Function lignin::callback_registry::when_unlocked_locally

pub fn when_unlocked_locally(continuation: impl 'static + FnOnce())

Causes a continuation to be called when the callback registry is not locked (anymore) by the current thread.

Warning:

Spawning a thread that calls this function and then joining on it from a callback handler is an easy path towards deadlocks, so please avoid doing that.

More specifically: This function has one of two effects, depending on whether it is called in scope of (and on the same thread as!) a callback managed by lignin:

• If no callback is currently running on this thread, the continuation is invoked immediately.

• If such a callback is currently running on the current thread, continuation is scheduled for later execution.

  As soon as the registry becomes unlocked, all such scheduled continuations are run, in order of their respective when_unlocked_locally calls.

  The current implementation of this is somewhat inefficient and will always allocate.

  I have a more efficient scheduler in mind, but that particular model would require set_ptr_value at least std::alloc::Allocator to be stabilized first in order to construct a consumable box pointing to an allocation arena.

  If you have a better suggestion that works on stable Rust, feel free to send it my way (with permission to actually implement it here if it’s extensive enough to warrant that)!

Panic Notes

While this function won’t panic by itself (except due to memory limits), it’s still possible that a callback handler panics while continuations are pending.

Should this happen, all pending continuations are dropped without being executed.