Repository navigation
refactor(reactive): Give each meaning of "flush" its own name - #2534
Merged
jat255 merged 3 commits intoOct 8, 2026
Merged
Conversation
…t flushes "Flush" referred to one drain of the reactive environment's queue, the machinery that schedules those drains, a session sending its outputs, and the public `reactive.flush()` that waits for all of it. Give each its own name, and define them in the `ReactiveEnvironment` docstring: - round: one drain of the reactive effect queue (`run_round()`, `wait_for_next_round()`, `request_round()`, `on_round_finished()`) - reactive effect queue: the process-wide queue a round drains (`_effect_queue`, `enqueue_effect()`) - idle: what `reactive.flush()` waits for (`wait_for_idle()`) - output flush: a session sending its outputs (`_request_output_flush()`, `_start_output_flush()`, ...) Public names (`reactive.flush()`, `reactive.on_flushed()`, `session.on_flush()`, `session.on_flushed()`) are unchanged. `Context`'s methods keep their names because `get_current_context()` exposes `Context` to user code.
jat255
added this pull request to stack #2535
October 8, 2026 15:18
jat255
commented
Oct 8, 2026
`wait_for_idle()` and `wait_for_next_round()` both start rounds themselves, so "wait" undersold them. Rename them to `run_until_idle()` (after asyncio's `run_until_complete()`) and `run_next_round()`. Rename `run_round()` to `start_round()`, since it returns right away when a round is already running and never waits for an effect's async part.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
In #2508, the word "flush" names four different things, so the code and its comments are hard to read. This PR gives each meaning its own name and defines the names in one place.
This PR is stacked on #2508 and targets its branch. It changes names, comments, and docstrings only. It does not change behavior.
Motivation
On
main, one flush did all the work in sequence: it ran every effect to completion, then sent each session's outputs. One word was enough for that.#2508 splits that work into parts that run separately, but all of the parts kept the name "flush". The same word now means four things:
ReactiveEnvironment.flush()). It starts each effect in a task and does not wait for it.request_flush(),_rerun_flush,_in_flush).AppSession._flush(),_request_flush()). This happens later, once per session.reactive.flush(). It waits until all of the above is complete, so its contract is the opposite ofReactiveEnvironment.flush().As a result, a reader cannot tell which meaning a comment or method name refers to. For example,
flush_pass()andflush_settled()look similar, but one waits for a single drain and the other waits until all work stops. Also,AppSession._request_flush()andReactiveEnvironment.request_flush()have almost the same name, but they request different things.The new vocabulary
The
ReactiveEnvironmentdocstring defines these terms. All comments and private names now use them.reactive.flush()runs rounds until idle.These terms nest. One cycle can span several rounds, because effects can invalidate other effects. One round can advance the cycles of several sessions.
The word "flush" alone now means only the public API:
reactive.flush(),reactive.on_flushed(),session.on_flush(), andsession.on_flushed().Renamed private names
ReactiveEnvironment.flush()start_round()flush_pass()run_next_round()flush_settled()run_until_idle()request_flush(),_start_requested_flush()request_round(),_start_requested_round()_in_flush,_rerun_flush,_flush_requested,_flush_pass_waiters_round_running,_rerun_round,_round_requested,_next_round_waiterson_flushed(),_flushed_callbacks(environment)on_round_finished(),_round_finished_callbacks_pending_flush_queue,add_pending_flush(ctx, ...)(environment)_effect_queue,enqueue_effect(ctx, ...)_flush_owner_enclosing_runApp._request_flush(),_sessions_needing_flush,_flush_pending_sessions(),_unregister_flush_sessions_request_output_flush(),_sessions_needing_output_flush,_start_output_flushes(),_unregister_output_flush_hookAppSession._request_flush(),_start_flush(),_run_flush(),_flush()_request_output_flush(),_start_output_flush(),_run_output_flush(),_output_flush()AppSession._flush_task,_flush_again,_flush_enabled,_disable_flush()_output_flush_task,_output_flush_again,_output_flush_enabled,_disable_output_flush()Review notes
start_round()starts a round and does not wait for the effects. If a round is already running, it returns right away.run_next_round()andrun_until_idle()start rounds themselves, so their names use "run" and not "wait".run_until_idle()follows asyncio'sloop.run_until_complete().reactive.flush()andreactive.on_flushed()now say what they wait for and when they run.Contextmethods keep their names.add_pending_flush(),on_flush(), andexecute_flush_callbacks()stay as they are, becauseget_current_context()gives user code access toContext. Their docstrings now use the new terms.74ca1306for per-sessionreactive_updatespans, anda45110cbfor the bookmark restore order). Changing the text here only adds rebase conflicts. Test names that refer to the publicreactive.flush()also keep their names.architecture.mdnow points to the glossary.Testing
black,isort,flake8,pyright, andpyreflyreport no errors.Refs #2508