Skip to content

fix: make Session.schedule_update() and schedule_effect() thread-safe - #7113

Open
joaoaracheski wants to merge 6 commits into
flet-dev:mainfrom
joaoaracheski:fix-schedule-update-thread-safe
Open

joaoaracheski wants to merge 6 commits into
flet-dev:mainfrom
joaoaracheski:fix-schedule-update-thread-safe

Conversation

@joaoaracheski

@joaoaracheski joaoaracheski commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Description

Fixes #7108.

Session.schedule_update() and schedule_effect() changed the pending queues and called asyncio.Event.set() on the calling thread. In a components app that's reachable from a worker thread: state changed in a page.run_thread() handler notifies the component, which calls schedule_update() there.

What happens today when that runs on a worker thread:

  • Normal mode: Event.set() doesn't wake an idle loop, so the update sits there until something else wakes it (a message from the client, a timer). In my test the update didn't arrive in 5 s.
  • asyncio debug mode: it raises RuntimeError: Non-thread-safe operation invoked on an event loop other than the current one, the update is lost and the scheduler task stays stuck, so no later update of that session goes out. asyncio.run() even hangs on shutdown.

The fix hands calls from other threads to the scheduler's loop with call_soon_threadsafe(). The queues and the Event are only touched on the loop, so there's no race between add and the scheduler's clear(), and no lock is needed. On the loop thread nothing changes: the control is queued right away. If the loop is already closed (a worker that outlives the session), the call is dropped instead of raising.

schedule_effect() had the same problem, so it goes through the same path.

Test code

import asyncio, threading, time
from flet.messaging.connection import Connection
from flet.messaging.session import Session
from flet.pubsub.pubsub_hub import PubSubHub


class Conn(Connection):
    def send_message(self, message):
        pass


async def main():
    conn = Conn()
    conn.pubsubhub = PubSubHub()
    conn.loop = asyncio.get_running_loop()
    session = Session(conn)
    session.start_updates_scheduler()
    await asyncio.sleep(0)

    applied = asyncio.Event()

    class Control:
        def update(self):
            applied.set()

    def worker():
        time.sleep(0.2)  # the loop is idle by now
        session.schedule_update(Control())

    threading.Thread(target=worker).start()
    try:
        await asyncio.wait_for(applied.wait(), 5)
        print("applied")
    except TimeoutError:
        print("not applied in 5 s")


asyncio.run(main())

Before: not applied in 5 s
After: applied (right away)

New tests/test_schedule_update_threads.py:

  • update from a worker thread wakes an idle loop (no debug mode, no polling): fails before, passes after;
  • update and effect from a worker thread, in debug mode: fail before, pass after;
  • 8 threads x 100 updates at once, none lost (scenario 1 from @daneeller's comment);
  • worker calling after the loop closed doesn't raise (scenario 2);
  • on the loop thread the control is still queued right away.

flet: 565 passed, 8 skipped. ruff check and format clean.

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update

Checklist

  • I signed the CLA.
  • I have performed a self-review of my own code.
  • My code follows the style guidelines of this project.
  • I have commented my code, particularly in hard-to-understand areas.
  • My changes generate no new warnings.
  • New and existing tests pass locally with my changes.
  • I have made corresponding documentation changes, if applicable.
  • I have added changelog entries for user-facing changes, if applicable.
  • I have updated release guide pages and website/sidebars.yml for breaking changes, removals, and deprecations, if applicable.

Additional details

This covers the scheduler on main. It doesn't make page.update() itself thread-safe: that one still runs patch_control() on the calling thread, which is #7107. Kept it out to keep this PR small.

Before the scheduler starts (no components mode yet), calls still run directly like before, since nothing is draining the queues at that point.

Summary by Sourcery

Make session scheduling and component state updates safe and reliable when invoked from worker threads.

Bug Fixes:

  • Make component updates and effects scheduled from worker threads reliably wake the session scheduler, avoid asyncio thread-safety errors, prevent lost or racy updates, and safely ignore work submitted after session shutdown.

Enhancements:

  • Apply component state changes from worker threads on the component's event loop to preserve render ordering and prevent concurrent state races.

Tests:

  • Add comprehensive coverage for cross-thread updates and effects, concurrent submissions, scheduler wakeups, session lifecycle transitions, closed event loops, and thread-safe component state changes.

Both changed the pending queues and called asyncio.Event.set() on the
calling thread. From a worker thread (e.g. state changed in a
page.run_thread() handler) the set() doesn't wake an idle loop, so the
update waited for something else to wake it, and in asyncio debug mode
it raised and left the scheduler stuck for the rest of the session.

Calls from other threads are now handed to the scheduler's loop with
call_soon_threadsafe(), so the queues are only touched on the loop and
no lock is needed.

Fixes flet-dev#7108
Copilot AI balanced review requested due to automatic review settings November 20, 2026 17:00

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've reviewed your changes and they look great!


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

@daneeller

Copy link
Copy Markdown
Contributor

Hey @joaoaracheski — I had some free time and came across your PR here, so I ran it against the scenarios I mentioned in #7108. Thought you'd want the results.

I set up an isolated env with stock flet 1.1.2 and ran your test file both before and after the patch:

  • Stock 1.1.2 (unpatched): the first test FAILED, and test_update_from_a_worker_thread_wakes_an_idle_loop hung indefinitely — I had to kill it at a 90s hard timeout (exit 124). The loop never wakes up, so even the wait_for(..., 2) timeout doesn't fire.
  • With your patch applied: all 6 tests PASSED in 0.47s, no hangs.

So call_soon_threadsafe() is the right fix here — nice work, and thanks for putting my scenarios into the tests.

While I was in there, I spotted a few edge paths that could use a bit of hardening:

  1. close() sets __closed and cancels the scheduler, but leaves __updates_loop pointing at a still-live loop. A worker calling schedule_update() after session close will queue updates that nobody drains — silent accumulation.
  2. disconnect() clears the queues on the loop thread, but the conn/expires_at guard in schedule_update() is checked on the caller thread. A callback queued right before disconnect can repopulate the cleared queues.
  3. The __updates_loop is None branch (scheduler not started yet) still runs the callback inline on the worker thread — the original race, in a small window.

None of these are blockers — the core fix is solid. Since I was already in there, I'd be glad to put together a small patch with regression tests for these three and tack it onto your branch if you'd like — just say the word. Or if you'd rather handle them yourself, the descriptions are all above. Totally your call.

Thanks again for picking this up!

…sconnects

Co-authored-by: daneeller <283215001+daneeller@users.noreply.github.com>
@joaoaracheski

joaoaracheski commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor Author

@daneeller good catches, and the run against stock 1.1.2 is a nice confirmation.

1 and 2 are fixed now. schedule_update() and schedule_effect() check that the session isn't closed or disconnected, and the same check runs again on the loop thread right before queuing. So an update that was handed to the loop just before disconnect() or close() gets dropped instead of refilling the queues. Three new tests cover it (update after close, effect after close, update in flight during disconnect), and all three fail without the change. Since 1 and 2 were your findings, I added you as co-author on that commit (b490b70).

I left 3 out on purpose. Before start_updates_scheduler() runs, nothing drains the queues yet, so there's no race there, only a thread touching the set before the session is live. That's rare enough that changing the startup order didn't seem worth it in this PR.

…keups

- set_state called off the event loop posts the change to the loop, in the
  render's context, so it can't race a render of the component.
- Worker threads post at most one scheduler wakeup at a time, outside the
  queue lock.
- Queuing work on the loop starts the scheduler, so apps that don't render
  components don't keep queued updates forever.
- One __accepting_work() check for queuing and for effects waiting on async
  cleanups; the queue lock now also covers conn on disconnect.
- Use the connection's loop instead of a separate __updates_loop.
- close() and disconnect() drop the queued work after releasing the lock, so
  a finalizer that queues work can't deadlock.
- Tests: wait for the close task in teardown; cover coalesced wakeups,
  scheduler start, finalizers and set_state from worker threads.
- Changelog entry from the app developer's perspective.
@FeodorFitsner

Copy link
Copy Markdown
Contributor

Thanks for this! I reviewed the PR and pushed a commit on top (a6f7dff) that addresses what I found. Summary below.

Review findings and fixes

  1. set_state from a worker thread was still racy. Only the session queue was locked. The rest of set_state (the hook.value write, update_subscription(), hook.version += 1, the is_dirty write) still ran on the worker while the loop could be rendering the same component, which detaches and re-attaches observable subscriptions. Fix: set_state called off the event loop now posts the change to the loop, in the context of the render that created the hook (so the page is set even for a plain threading.Thread). Changes are applied in call order, so functional updaters like lambda c: c + 1 don't lose increments.

  2. Queued work never drained without components. start_updates_scheduler() is only called from Page.render(), so in an app that doesn't render components, page.schedule_update() / session.schedule_update() queued controls that nothing ever processed or released. Fix: queuing work on the loop starts the scheduler if it isn't running.

  3. One call_soon_threadsafe per worker call, made while holding the lock. Fix: a worker posts at most one wakeup at a time (a __wakeup_pending flag, cleared when the wakeup runs on the loop), and the post happens after the lock is released.

  4. Possible deadlock on close/disconnect. .clear() under the non-reentrant lock could drop the last reference to a control or hook whose finalizer queues work, which takes the lock again on the same thread. Fix: the queues are swapped out under the lock and released after it.

  5. Cleanup and readability:

    • One __accepting_work() check, used both for queuing and for effects waiting on async cleanups (they had drifted apart).
    • The lock now consistently covers conn, expires_at, closed and the queues (disconnect() sets conn = None under it).
    • The loop comes from conn.loop instead of a separate __updates_loop, which removes the special startup path.
    • The wakeup helper no longer mixes the "accepting" check with the side effect.
  6. Tests: teardown now waits for the close dispatch task instead of a single sleep(0). The closed-loop test also checks that nothing was queued. New tests cover:

    • coalesced wakeups;
    • the scheduler starting on first use;
    • finalizers during close/disconnect;
    • 400 set_state calls from 4 threads all landing, with every updater running on the loop thread.

    Three of the new tests fail against the previous commit. The finalizer test would deadlock there instead.

  7. Changelog: reworded from the app developer's perspective. Session.schedule_update() is internal, so the entry now describes what users see.

One thing I left as is: mutating an Observable from a worker still calls Component._schedule_update() on that thread. That path only touches simple flags before reaching the (now thread-safe) session queue.

Performance

Best of several runs, Python 3.14, macOS arm64:

Before this PR PR before my commit Now
schedule_update on the loop 144 ns 326 ns 383 ns
schedule_effect on the loop 206 ns 391 ns 454 ns
set_state on the loop 526 ns 713 ns 812 ns
Re-render, component with 20 use_state hooks 37.6 µs 38.3 µs 43.7 µs
200k schedule_update from a worker, until applied 35 ms (broken: no wakeup, no lock) 568 ms 82 ms
  • Loop path: a few hundred ns per call, which is small next to the render it triggers. set_state calls are merged into one update per component.
  • Re-render: about 0.3 µs more per use_state call, from one extra closure per render. The first version of my change also made set_state reference itself, which turned every render's setters into reference cycles and cost about 17 µs per render with GC on. That's fixed: the body is a separate function.
  • Worker bursts: about 7x faster than the PR before my commit, thanks to the coalesced wakeups.
  • running_loop() (new, in flet/utils/event_loop.py) is asyncio._get_running_loop. It returns None instead of raising, which keeps the hot paths cheap. It's underscore-prefixed but has been stable since Python 3.7.

…hread-safe

# Conflicts:
#	CHANGELOG.md
#	sdk/python/packages/flet/src/flet/messaging/session.py

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Session.schedule_update() uses asyncio.Event.set(), which is not thread-safe if called from a worker thread

4 participants