Does Invoke always run in a thread?

[spacemanspiff2007]

I'm reading the Execution model section and I'm unsure if I understand everything correctly. It seems from the docs it's impossible to use a coroutine function as an invoke target.
It's also not easy to spawn a new asyncio Task from the IInvoke protocol because the event loop is not available in the thread.
Is spawning an asyncio Task with a coroutine not possible?

Also I am not sure about this sentence in Execution model
"If the owning state is exited before the handler finishes, the invocation is cancelled".
Canceling the thread does not work at all so cancellation would only work when the user provides a IInvoke protocol object. Correct?

[fgmacedo]

Thanks for the report, @spacemanspiff2007! Great questions.

Does invoke always run in a thread?

Yes, currently both engines use threads:

• Sync engine: spawns a daemon threading.Thread
• Async engine: runs the handler via loop.run_in_executor() wrapped in an asyncio.Task

The rationale is that invoke handlers are expected to perform blocking I/O that would freeze the event loop if run directly.

Can I use a coroutine function as an invoke target?

Not yet — and we just confirmed this is a bug. When you pass an async function as invoke target, the callback system detects it as async and selects the AsyncEngine, but the invoke execution path still runs it through run_in_executor(), which calls it synchronously. The result is a coroutine object that is never awaited. No error, no warning from the library, just silent wrong behavior.

We're going to fix this so that coroutine functions are properly detected and awaited in the async engine, running directly on the event loop instead of in a thread executor. This makes invoke usable for non-blocking async work (e.g., aiohttp calls, async DB queries).

Cancellation and threads

You're right that Python threads can't be forcefully cancelled. The mechanism is cooperative:

1. ctx.cancelled (threading.Event) is set — handlers should poll this to exit gracefully
2. on_cancel() is called on IInvoke handlers for cleanup
3. The thread is joined with a 2-second timeout

For plain callables (not IInvoke), the thread runs to completion, but events sent after cancellation are silently ignored — so the machine state remains consistent even if the thread lingers.

For the async engine, the wrapping asyncio.Task is also cancelled via task.cancel(), which raises CancelledError at the next await point. With native coroutine support, this will give you proper cancellation semantics without cooperative polling.

[spacemanspiff2007]

Thank you for the quick feedback! 🚀

[spacemanspiff2007]

Just a small remark: I'm reading State timeouts and it does not mention asyncio. I'm guessing with the implemented fix a Task will be properly canceled?
If this is the case would it be possible to add a small section to the docs to make clear how a timeout works with coroutines?