[FarhanAliRaza]

All Submissions:

• Have you followed the guidelines stated in CONTRIBUTING.md file?
• Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

New Feature Submission:

• Does your submission pass the tests?
• Have you linted your code locally prior to submission?

Changes To Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you successfully ran tests with your changes locally?

What this does

Implements ENG-9162 (EventHandler redesign: awaitable semantics).

@rx.event is the registration point. The decorator returns the EventHandler itself. EventHandler.__set_name__ binds a method's handler to the state class whose body declares it, before BaseState.__init_subclass__ collects the class's handlers and RegistrationContext.register_base_state registers them under the final class name, so local classes and hot reload behave as before. A mixin's handler is bound to the mixin and copied per concrete state (including rx.ComponentState). Undecorated public methods are still wrapped as today. A decorator stacked above @rx.event now raises TypeError at class creation (it would otherwise chain the handler forever). @rx.event on a function without a state parameter registers a stateless handler (states=()) that runs with no state, no lock, and outside the per-token FIFO of BaseStateEventProcessor.

Handlers are awaitable. EventHandler and EventSpec implement __await__; calling still only binds arguments (returns an EventSpec), so return rx.redirect(...) and yield State.x(1) are unchanged. execute_event_inline decides how an await runs from EventContext.locked_root, which the processor, StateProxy.__aenter__/__aexit__ and App.modify_state set while the token's state lock is held:

Caller holds the state lock	Target	Behaviour
yes (foreground handler, async with self, app.modify_state)	state handler	runs inline on the locked tree under the caller's context: its yields emit deltas, the events it yields chain under the caller's EventFuture
no (background task outside async with self, API route)	state handler	enqueued, its EventFuture awaited
either	stateless handler	runs inline
yes	background handler	EventHandlerTypeError (would wait for the lock); yield it instead
any	frontend-only (rx.redirect, …) or upload spec	EventHandlerTypeError
no EventContext	any	EventHandlerTypeError

Return values. A handler's non-event return value resolves await and the EventFuture (EventContext.enqueue now returns the futures). Returned events still chain; a returned coroutine still raises. Yielded non-events still raise; streaming values to the frontend is ENG-13447. EventProcessor._execute_event awaits only coroutines now, so a bare handler returning a spec no longer executes it.

self.handler() on a state instance keeps calling the plain method as before; the new form is await type(self).handler(x).

Verification

• Unit suite: 13,396 passed. The only failures are tests/units/reflex_bench/drivers/test_browser.py, which needs a Playwright browser download the sandbox cannot fetch.
• ruff check, ruff format, pyright reflex tests and pre-commit run --all-files are clean.
• New Selenium scenarios were added to tests/integration/test_event_chain.py (await inline, return value, callee's yield chained after the caller) and tests/integration/test_background_task.py (await through the queue, then inline inside async with self). Selenium could not download chromedriver in the sandbox, so both apps were driven with Playwright against the installed Chromium instead; both pass. CI runs the Selenium versions.
• tests/benchmarks/test_event_processing.py passes; repeated A/B runs of the per-event cases against main are within noise (for example process_event[counter] 0.60/0.58 ms base vs 0.58/0.66 ms head).

Review notes

1. EventSpec.__hash__ is identity-based while the dataclass __eq__ stays field-wise: asyncio.gather hashes awaitables, and the bound Var args make field-wise hashing and equality unusable.
2. locked_root is shared by reference with tasks a handler spawns, so a gathered sibling runs inline instead of enqueuing behind its own parent. A task outliving the handler sees None and enqueues.
3. An awaited child that supersession cancels raises CancelledError into the caller.
4. Stateless handlers run concurrently with each other and with the same client's foreground events.
5. reflex-enterprise should be checked for inspect.isawaitable on handler results and for code expecting rx.event(...) to return a plain function (the function is at .fn, markers still on it).
6. await State.h() is typed Any; a return TypeVar would mean rewriting the EventCallback.__call__ overloads.

Follow-ups

• Wire transport of return values and the frontend promise: ENG-13447.
• Precompiled per-parameter payload coercers (resolved once at registration), gated on the event processing benchmark.
• Carrying raw args on EventSpec to skip the LiteralVar encode/decode round trip on inline awaits.

closes #6223

https://claude.ai/code/session_01LwJUCVfbdzZayfSZMiP8GJ

---

Generated by Claude Code

[linear-code]

ENG-9162

[cubic-dev-ai]

All reported issues were addressed across 22 files

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[greptile-apps]

Confidence Score: 5/5

[High impact] The PR appears safe to merge; the previously reported quote example is fixed.

Summary

Makes event handlers awaitable and registers them through @rx.event.

• The @rx.event decorator registers handlers directly on state classes and as stateless functions.
• Awaited handlers run inline under a held state lock or through the event queue when no lock is held.
• Awaited handlers return ordinary values while event chains continue to run.
• Literal values wrapped in state proxies keep their own type-based encoding.

_{Reviews (7) · Last reviewed commit: "Fetch the quote outside the state lock i..." · Reviewed by Greptile}

[codspeed]

Merging this PR will degrade performance by 4.18%

2 warnings

⚠️ 15 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚠️ Base and head ran on different runner types

Some benchmarks with significant performance changes were compared across different runner types, so the changes might not come from the code. Run base and head on the same runner type, or use CodSpeed Macro Runners for more stable results.

Learn more about Macro Runners

Open the report in CodSpeed to investigate

❌ 1 regressed benchmark
✅ 147 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	test_proxy_list_mutation	9.6 ms	10 ms	-4.18%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing farhan/nice-maxwell-bmch7a (2dff931) with main (17370c2)}

[cubic-dev-ai]

All reported issues were addressed across 16 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[FarhanAliRaza]

On the CodSpeed check (not in the required set; performance-tests-gate is): each run on this branch flags exactly one benchmark at roughly -5%, and the benchmark changes from head to head:

head	flagged benchmark	base → head
daeb277	test_process_event_burst_independent_tokens[1], test_modify_state[private]	2.9 → 3.1 ms, 7.5 → 7.9 ms
80e1d44, ad34033, ff91379, f87f474	test_modify_state[private]	7.5 → 7.9 ms
42c7239 (current)	test_route_argument_extraction	117.5 → 123.4 µs

The current flag is route-argument parsing, which this PR does not touch. For the earlier modify_state figure: a local wall-time A/B against main (two alternating rounds each) gives 0.762/0.729 ms base vs 0.712/0.753 ms head, within noise, and a deterministic call-count profile shows the head adds exactly four Python calls per modify_state (set_locked_root twice, release_lock, _get_root_state), about 1.3% of calls. Every report also carries CodSpeed's own warning that base and head ran on different runner types. I'm not acknowledging the regression on CodSpeed myself; leaving that to a maintainer.

---

Generated by Claude Code

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>