py/scheduler: Only run callbacks on the main thread if GIL is disabled.

Otherwise it's very difficult to reason about thread safety in a
scheduler callback, as it can run at any time on any thread - including
racing against any bytecode operation on any thread.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <angus@redyak.com.au>

1 files changed, 8 insertions, 0 deletions

diff --git a/docs/library/micropython.rst b/docs/library/micropython.rst
index b17dfa9a7..31b24903f 100644
--- a/docs/library/micropython.rst
+++ b/docs/library/micropython.rst
@@ -136,6 +136,14 @@ Functions
    the heap may be locked) and scheduling a function to call later will lift
    those restrictions.
 
+   On multi-threaded ports, the scheduled function's behaviour depends on
+   whether the Global Interpreter Lock (GIL) is enabled for the specific port:
+
+   - If GIL is enabled, the function can preempt any thread and run in its
+     context.
+   - If GIL is disabled, the function will only preempt the main thread and run
+     in its context.
+
    Note: If `schedule()` is called from a preempting IRQ, when memory
    allocation is not allowed and the callback to be passed to `schedule()` is
    a bound method, passing this directly will fail. This is because creating a