Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Batch anywidget model updates like UI element updates (#8168)

Trevor Manze93ea4b25fec
diff --git a/marimo/_ipc/connection.py b/marimo/_ipc/connection.py
index 7e5e37244d..c8d9299d3b 100644
--- a/marimo/_ipc/connection.py
+++ b/marimo/_ipc/connection.py
@@ -18,9 +18,9 @@ if typing.TYPE_CHECKING:
from marimo._messaging.types import KernelMessage
from marimo._runtime.commands import (
+ BatchableCommand,
CodeCompletionCommand,
CommandMessage,
- UpdateUIElementCommand,
)
LOGGER = _loggers.marimo_logger()
@@ -86,7 +86,7 @@ class Connection:
context: zmq.Context[zmq.Socket[bytes]]
control: Channel[CommandMessage]
- ui_element: Channel[UpdateUIElementCommand]
+ ui_element: Channel[BatchableCommand]
completion: Channel[CodeCompletionCommand]
win32_interrupt: Channel[bool] | None
diff --git a/marimo/_ipc/queue_manager.py b/marimo/_ipc/queue_manager.py
index 0f3b6feccf..a00891e118 100644
--- a/marimo/_ipc/queue_manager.py
+++ b/marimo/_ipc/queue_manager.py
@@ -12,9 +12,9 @@ from marimo._ipc.types import ConnectionInfo
if typing.TYPE_CHECKING:
from marimo._messaging.types import KernelMessage
from marimo._runtime.commands import (
+ BatchableCommand,
CodeCompletionCommand,
CommandMessage,
- UpdateUIElementCommand,
)
from marimo._session.queue import QueueType
@@ -43,8 +43,8 @@ class QueueManager:
return self.conn.control.queue
@property
- def set_ui_element_queue(self) -> QueueType[UpdateUIElementCommand]:
- """Queue for UI element value updates."""
+ def set_ui_element_queue(self) -> QueueType[BatchableCommand]:
+ """Queue for batchable commands (UI element updates and model commands)."""
return self.conn.ui_element.queue
@property
diff --git a/marimo/_pyodide/pyodide_session.py b/marimo/_pyodide/pyodide_session.py
index cd12c46ce8..32f027d791 100644
--- a/marimo/_pyodide/pyodide_session.py
+++ b/marimo/_pyodide/pyodide_session.py
@@ -27,8 +27,10 @@ from marimo._pyodide.streams import (
from marimo._runtime import commands, handlers, patches
from marimo._runtime.commands import (
AppMetadata,
+ BatchableCommand,
CodeCompletionCommand,
CommandMessage,
+ ModelCommand,
UpdateUIElementCommand,
UpdateUserConfigCommand,
)
@@ -91,9 +93,7 @@ class AsyncQueueManager:
self.control_queue = asyncio.Queue[commands.CommandMessage]()
# set UI elements duplicated in another queue so they can be batched
- self.set_ui_element_queue = asyncio.Queue[
- commands.UpdateUIElementCommand
- ]()
+ self.set_ui_element_queue = asyncio.Queue[BatchableCommand]()
# Code completion requests are sent through a separate queue
self.completion_queue = asyncio.Queue[commands.CodeCompletionCommand]()
@@ -153,7 +153,10 @@ class PyodideSession:
def put_control_request(self, request: commands.CommandMessage) -> None:
self._queue_manager.control_queue.put_nowait(request)
- if isinstance(request, commands.UpdateUIElementCommand):
+ if isinstance(
+ request,
+ (commands.UpdateUIElementCommand, commands.ModelCommand),
+ ):
self._queue_manager.set_ui_element_queue.put_nowait(request)
def put_completion_request(
@@ -415,7 +418,7 @@ class PyodideBridge:
def _launch_pyodide_kernel(
control_queue: asyncio.Queue[CommandMessage],
- set_ui_element_queue: asyncio.Queue[UpdateUIElementCommand],
+ set_ui_element_queue: asyncio.Queue[BatchableCommand],
completion_queue: asyncio.Queue[CodeCompletionCommand],
input_queue: asyncio.Queue[str],
on_message: Callable[[KernelMessage], None],
@@ -448,7 +451,7 @@ def _launch_pyodide_kernel(
def _enqueue_control_request(req: CommandMessage) -> None:
control_queue.put_nowait(req)
- if isinstance(req, UpdateUIElementCommand):
+ if isinstance(req, (UpdateUIElementCommand, ModelCommand)):
set_ui_element_queue.put_nowait(req)
# Create hooks with mode-specific configuration
@@ -498,8 +501,14 @@ def _launch_pyodide_kernel(
while True:
request: CommandMessage | None = await control_queue.get()
LOGGER.debug("received request %s", request)
- if isinstance(request, commands.UpdateUIElementCommand):
- request = ui_element_request_mgr.process_request(request)
+ if isinstance(
+ request,
+ (commands.UpdateUIElementCommand, commands.ModelCommand),
+ ):
+ merged = ui_element_request_mgr.process_request(request)
+ for r in merged:
+ await kernel.handle_message(r)
+ continue
if request is not None:
await kernel.handle_message(request)
diff --git a/marimo/_runtime/commands.py b/marimo/_runtime/commands.py
index e2d03503f7..679847c09d 100644
--- a/marimo/_runtime/commands.py
+++ b/marimo/_runtime/commands.py
@@ -737,11 +737,13 @@ class ModelCommand(Command):
model_id: Widget model identifier.
message: Model message (update or custom).
buffers: Base64-encoded binary buffers.
+ token: Unique identifier for deduplication across dual queues.
"""
model_id: WidgetModelId
message: ModelMessage
buffers: list[bytes]
+ token: str = msgspec.field(default_factory=lambda: str(uuid4()))
def into_comm_payload(self) -> dict[str, Any]:
return {
@@ -750,6 +752,11 @@ class ModelCommand(Command):
}
+# Commands that can be batched and merged (last-write-wins) by the
+# SetUIElementRequestManager to avoid redundant cell re-executions.
+BatchableCommand = Union[UpdateUIElementCommand, ModelCommand]
+
+
class RefreshSecretsCommand(Command):
"""Refresh secrets from the secrets store.
diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.py
index cca08e4e78..18c683d518 100644
--- a/marimo/_runtime/runtime.py
+++ b/marimo/_runtime/runtime.py
@@ -105,6 +105,7 @@ from marimo._runtime import dataflow, handlers, marimo_pdb, patches
from marimo._runtime.app_meta import AppMeta
from marimo._runtime.commands import (
AppMetadata,
+ BatchableCommand,
ClearCacheCommand,
CodeCompletionCommand,
CommandMessage,
@@ -2264,8 +2265,11 @@ class Kernel:
request
)
- # If there's a ui_element_id, trigger a cell re-run
- # via the UI element path (which also processes state updates).
+ # Directly handle the UI element update instead of
+ # re-enqueuing it as a separate command. Re-enqueuing
+ # caused Model+UI interleaving that the batch merger
+ # couldn't collapse (different types), leading to every
+ # drag tick getting its own full cell re-execution.
if ui_element_id and state:
await self.set_ui_element_value(
UpdateUIElementCommand.from_ids_and_values(
@@ -3136,7 +3140,7 @@ class RequestHandler:
def launch_kernel(
control_queue: QueueType[CommandMessage],
- set_ui_element_queue: QueueType[UpdateUIElementCommand],
+ set_ui_element_queue: QueueType[BatchableCommand],
completion_queue: QueueType[CodeCompletionCommand],
input_queue: QueueType[str],
stream_queue: QueueType[KernelMessage] | None,
@@ -3229,7 +3233,7 @@ def launch_kernel(
def _enqueue_control_request(req: CommandMessage) -> None:
control_queue.put_nowait(req)
- if isinstance(req, UpdateUIElementCommand):
+ if isinstance(req, (UpdateUIElementCommand, ModelCommand)):
set_ui_element_queue.put_nowait(req)
# Create hooks with mode-specific configuration
@@ -3333,8 +3337,14 @@ def launch_kernel(
)
if isinstance(request, StopKernelCommand):
break
- elif isinstance(request, UpdateUIElementCommand):
- request = ui_element_request_mgr.process_request(request)
+ elif isinstance(request, (UpdateUIElementCommand, ModelCommand)):
+ # Drain the shared queue and merge pending requests:
+ # - UI element updates: last-write-wins per element ID
+ # - Model commands: last-write-wins per model ID
+ merged = ui_element_request_mgr.process_request(request)
+ for r in merged:
+ await kernel.handle_message(r)
+ continue
if request is not None:
await kernel.handle_message(request)
diff --git a/marimo/_runtime/utils/set_ui_element_request_manager.py b/marimo/_runtime/utils/set_ui_element_request_manager.py
index 974ff70894..0cc334a0df 100644
--- a/marimo/_runtime/utils/set_ui_element_request_manager.py
+++ b/marimo/_runtime/utils/set_ui_element_request_manager.py
@@ -1,62 +1,217 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Callable, Generic, TypeVar, Union
-from marimo._runtime.commands import UpdateUIElementCommand
+from marimo._runtime.commands import (
+ BatchableCommand,
+ ModelCommand,
+ ModelCustomMessage,
+ ModelUpdateMessage,
+ UpdateUIElementCommand,
+)
from marimo._session.queue import QueueType
-from marimo._types.ids import UIElementId
+from marimo._types.ids import UIElementId, WidgetModelId
if TYPE_CHECKING:
import asyncio
+A = TypeVar("A")
+B = TypeVar("B")
+
+
+class _RunAccumulator(Generic[A, B]):
+ """Merges contiguous runs of same-type commands.
+
+ Uses Generic[A, B] for precise merge function typing. If a third
+ command type is needed, this could be generalized to accept a
+ dict[type, Callable] instead.
+
+ Example::
+
+ A A A B B B A A B B → A(merged) B(merged) A(merged) B(merged)
+ """
+
+ def __init__(
+ self,
+ a: tuple[type[A], Callable[[list[A]], list[A]]],
+ b: tuple[type[B], Callable[[list[B]], list[B]]],
+ ) -> None:
+ self._type_a = a[0]
+ self._type_b = b[0]
+ self._merge_a = a[1]
+ self._merge_b = b[1]
+ self._current_run: list[A] | list[B] = []
+ self._current_type: type[A] | type[B] | None = None
+ self._result: list[A | B] = []
+
+ def push(self, cmd: A | B) -> None:
+ cmd_type = (
+ self._type_a if isinstance(cmd, self._type_a) else self._type_b
+ )
+ if (
+ self._current_type is not None
+ and cmd_type is not self._current_type
+ ):
+ self._flush()
+ self._current_type = cmd_type
+ self._current_run.append(cmd) # type: ignore[arg-type]
+
+ def _flush(self) -> None:
+ if not self._current_run:
+ return
+ if self._current_type is self._type_a:
+ self._result.extend(self._merge_a(self._current_run)) # type: ignore[arg-type]
+ else:
+ self._result.extend(self._merge_b(self._current_run)) # type: ignore[arg-type]
+ self._current_run = []
+ self._current_type = None
+
+ def finish(self) -> list[A | B]:
+ self._flush()
+ return self._result
+
+
+def _merge_ui_commands(
+ cmds: list[UpdateUIElementCommand],
+) -> list[UpdateUIElementCommand]:
+ """Merge UI element commands: last-write-wins per element ID."""
+ if not cmds:
+ return []
+
+ merged: dict[UIElementId, Any] = {}
+ last_cmd = cmds[-1]
+ for cmd in cmds:
+ for ui_id, value in cmd.ids_and_values:
+ merged[ui_id] = value
+
+ return [
+ UpdateUIElementCommand(
+ object_ids=list(merged.keys()),
+ values=list(merged.values()),
+ token=last_cmd.token,
+ request=last_cmd.request,
+ )
+ ]
+
+
+BufferPath = tuple[Union[str, int], ...]
+
+
+def _merge_model_commands(
+ cmds: list[ModelCommand],
+) -> list[ModelCommand]:
+ """Merge model commands: last-write-wins per model ID on state keys.
+
+ Custom messages pass through without merging. Uses the same merge
+ strategy as ModelReplayState.apply_update: when a state key is
+ overridden, drop any existing buffers whose root path component
+ matches that key.
+ """
+ result: list[ModelCommand] = []
+ model_state: dict[WidgetModelId, dict[str, Any]] = {}
+ model_buffers: dict[WidgetModelId, dict[BufferPath, bytes]] = {}
+
+ for cmd in cmds:
+ if isinstance(cmd.message, ModelCustomMessage):
+ result.append(cmd)
+ elif isinstance(cmd.message, ModelUpdateMessage):
+ mid = cmd.model_id
+ if mid not in model_state:
+ model_state[mid] = {}
+ model_buffers[mid] = {}
+
+ # Drop buffers whose root key is being overridden
+ updated_keys = set(cmd.message.state.keys())
+ model_buffers[mid] = {
+ path: buf
+ for path, buf in model_buffers[mid].items()
+ if path[0] not in updated_keys
+ }
+ # Merge state and buffers
+ model_state[mid].update(cmd.message.state)
+ for path, buf in zip(cmd.message.buffer_paths, cmd.buffers):
+ model_buffers[mid][tuple(path)] = buf
+
+ for mid in model_state:
+ paths = list(model_buffers[mid].keys())
+ bufs = list(model_buffers[mid].values())
+ result.append(
+ ModelCommand(
+ model_id=mid,
+ message=ModelUpdateMessage(
+ state=model_state[mid],
+ buffer_paths=[list(p) for p in paths],
+ ),
+ buffers=bufs,
+ )
+ )
+
+ return result
+
+
+def merge_batchable_commands(
+ commands: list[BatchableCommand],
+) -> list[BatchableCommand]:
+ if not commands:
+ return []
+
+ acc = _RunAccumulator(
+ a=(UpdateUIElementCommand, _merge_ui_commands),
+ b=(ModelCommand, _merge_model_commands),
+ )
+ for cmd in commands:
+ acc.push(cmd)
+ return acc.finish()
+
class SetUIElementRequestManager:
def __init__(
self,
set_ui_element_queue: (
- QueueType[UpdateUIElementCommand]
- | asyncio.Queue[UpdateUIElementCommand]
+ QueueType[BatchableCommand] | asyncio.Queue[BatchableCommand]
),
) -> None:
self._set_ui_element_queue = set_ui_element_queue
- self._processed_request_tokens: set[str] = set()
+ # Token-based dedup for both UI commands and model commands.
+ # Each command is placed on both control_queue and
+ # set_ui_element_queue; the token tracks which have already
+ # been processed via the drain so the control_queue copy
+ # can be skipped.
+ self._processed_tokens: set[str] = set()
- def process_request(
- self, request: UpdateUIElementCommand
- ) -> UpdateUIElementCommand | None:
- request_batch: list[UpdateUIElementCommand] = []
- if request.token not in self._processed_request_tokens:
- request_batch.append(request)
- self._processed_request_tokens.add(request.token)
+ def _dedup(
+ self,
+ cmd: BatchableCommand,
+ pending: list[BatchableCommand],
+ ) -> None:
+ token = cmd.token
+ if token not in self._processed_tokens:
+ pending.append(cmd)
+ self._processed_tokens.add(token)
else:
- self._processed_request_tokens.remove(request.token)
+ self._processed_tokens.discard(token)
- while not self._set_ui_element_queue.empty():
- r = self._set_ui_element_queue.get_nowait()
- if r.token not in self._processed_request_tokens:
- request_batch.append(r)
- self._processed_request_tokens.add(r.token)
- else:
- self._processed_request_tokens.remove(r.token)
+ def process_request(
+ self, request: BatchableCommand
+ ) -> list[BatchableCommand]:
+ """Drain the queue and merge pending requests.
- return self._merge_set_ui_element_requests(request_batch)
+ UpdateUIElementCommands are merged by UI element ID
+ (last-write-wins). ModelCommands with update messages are
+ merged by model ID (last-write-wins on state keys). Custom
+ model messages pass through without merging.
- def _merge_set_ui_element_requests(
- self,
- requests: list[UpdateUIElementCommand],
- ) -> UpdateUIElementCommand | None:
- if not requests:
- return None
-
- merged: dict[UIElementId, Any] = {}
- for request in requests:
- for ui_id, value in request.ids_and_values:
- merged[ui_id] = value
- last_request = requests[-1]
- return UpdateUIElementCommand(
- object_ids=list(merged.keys()),
- values=list(merged.values()),
- token=last_request.token,
- request=last_request.request,
- )
+ Contiguous runs of same-type commands are merged together while
+ preserving the relative interleaving order of different types.
+ """
+ pending: list[BatchableCommand] = []
+
+ # Add the triggering request (with token dedup)
+ self._dedup(request, pending)
+
+ # Drain everything currently in the queue
+ while not self._set_ui_element_queue.empty():
+ self._dedup(self._set_ui_element_queue.get_nowait(), pending)
+
+ return merge_batchable_commands(pending)
diff --git a/marimo/_session/managers/ipc.py b/marimo/_session/managers/ipc.py
index eca415a5a7..c4d8b11ae8 100644
--- a/marimo/_session/managers/ipc.py
+++ b/marimo/_session/managers/ipc.py
@@ -80,7 +80,7 @@ class IPCQueueManagerImpl(QueueManager):
@property
def set_ui_element_queue( # type: ignore[override]
self,
- ) -> QueueType[commands.UpdateUIElementCommand]:
+ ) -> QueueType[commands.BatchableCommand]:
return self._ipc.set_ui_element_queue
@property
diff --git a/marimo/_session/managers/queue.py b/marimo/_session/managers/queue.py
index 700f0bc3e8..dd7f9e2abe 100644
--- a/marimo/_session/managers/queue.py
+++ b/marimo/_session/managers/queue.py
@@ -27,12 +27,12 @@ class QueueManagerImpl(QueueManager):
queue.Queue[commands.CommandMessage],
] = context.Queue() if context is not None else queue.Queue()
- # Set UI element queues are stored in both the control queue and
- # this queue, so that the backend can merge/batch set-ui-element
- # requests.
+ # UI element updates and model commands are stored in both the
+ # control queue and this queue, so that the backend can
+ # merge/batch requests (last-write-wins per element/model ID).
self.set_ui_element_queue: Union[
- MPQueue[commands.UpdateUIElementCommand],
- queue.Queue[commands.UpdateUIElementCommand],
+ MPQueue[commands.BatchableCommand],
+ queue.Queue[commands.BatchableCommand],
] = context.Queue() if context is not None else queue.Queue()
# Code completion requests are sent through a separate queue
@@ -101,8 +101,12 @@ class QueueManagerImpl(QueueManager):
return
self.control_queue.put(request)
- # Update UI elements are on both queues so they can be batched
- if isinstance(request, commands.UpdateUIElementCommand):
+ # UI element updates and model commands are on both queues
+ # so they can be batched
+ if isinstance(
+ request,
+ (commands.UpdateUIElementCommand, commands.ModelCommand),
+ ):
self.set_ui_element_queue.put(request)
def put_input(self, text: str) -> None:
diff --git a/marimo/_session/types.py b/marimo/_session/types.py
index 6278654317..d224d14a32 100644
--- a/marimo/_session/types.py
+++ b/marimo/_session/types.py
@@ -35,7 +35,7 @@ class QueueManager(Protocol):
"""Protocol for queue management."""
control_queue: QueueType[commands.CommandMessage]
- set_ui_element_queue: QueueType[commands.UpdateUIElementCommand]
+ set_ui_element_queue: QueueType[commands.BatchableCommand]
completion_queue: QueueType[commands.CodeCompletionCommand]
input_queue: QueueType[str]
stream_queue: Optional[QueueType[Union[KernelMessage, None]]]
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 4b8e0d334b..48074bd3da 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -3048,7 +3048,8 @@ components:
description: "Widget model message command.\n\n Handles widget model communication\
\ between frontend and backend.\n\n Attributes:\n model_id: Widget\
\ model identifier.\n message: Model message (update or custom).\n\
- \ buffers: Base64-encoded binary buffers."
+ \ buffers: Base64-encoded binary buffers.\n token: Unique identifier\
+ \ for deduplication across dual queues."
properties:
buffers:
items:
@@ -3066,6 +3067,8 @@ components:
propertyName: method
modelId:
type: string
+ token:
+ type: string
type:
enum:
- model
@@ -3183,6 +3186,8 @@ components:
propertyName: method
modelId:
type: string
+ token:
+ type: string
required:
- modelId
- message
@@ -4839,7 +4844,7 @@ components:
type: object
info:
title: marimo API
- version: 0.19.7
+ version: 0.19.9
openapi: 3.1.0
paths:
/@file/{filename_and_length}:
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index adffc799ef..0448aa39d8 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -4874,6 +4874,7 @@ export interface components {
* model_id: Widget model identifier.
* message: Model message (update or custom).
* buffers: Base64-encoded binary buffers.
+ * token: Unique identifier for deduplication across dual queues.
*/
ModelCommand: {
buffers: string[];
@@ -4881,6 +4882,7 @@ export interface components {
| components["schemas"]["ModelUpdateMessage"]
| components["schemas"]["ModelCustomMessage"];
modelId: string;
+ token?: string;
/** @enum {unknown} */
type: "model";
};
@@ -4944,6 +4946,7 @@ export interface components {
| components["schemas"]["ModelUpdateMessage"]
| components["schemas"]["ModelCustomMessage"];
modelId: string;
+ token?: string;
};
/**
* ModelUpdate
diff --git a/tests/_runtime/utils/test_set_ui_element_request_manager.py b/tests/_runtime/utils/test_set_ui_element_request_manager.py
index 4c135acf50..a708d2fcec 100644
--- a/tests/_runtime/utils/test_set_ui_element_request_manager.py
+++ b/tests/_runtime/utils/test_set_ui_element_request_manager.py
@@ -6,15 +6,22 @@ import queue
import threading
import time
-from marimo._runtime.commands import UpdateUIElementCommand
+from marimo._runtime.commands import (
+ ModelCommand,
+ ModelCustomMessage,
+ ModelUpdateMessage,
+ UpdateUIElementCommand,
+)
from marimo._runtime.utils.set_ui_element_request_manager import (
+ BatchableCommand,
SetUIElementRequestManager,
+ merge_batchable_commands,
)
def test_process_request_dedupes_by_token() -> None:
"""Test that duplicate tokens are properly deduplicated."""
- q: queue.Queue[UpdateUIElementCommand] = queue.Queue()
+ q: queue.Queue[BatchableCommand] = queue.Queue()
manager = SetUIElementRequestManager(q)
# Create two requests with the same token
@@ -32,14 +39,16 @@ def test_process_request_dedupes_by_token() -> None:
result = manager.process_request(request1)
# Should only get one request (the second is a duplicate)
- assert result is not None
- assert len(result.object_ids) == 1
- assert result.object_ids[0] == "obj1"
+ assert len(result) == 1
+ cmd = result[0]
+ assert isinstance(cmd, UpdateUIElementCommand)
+ assert len(cmd.object_ids) == 1
+ assert cmd.object_ids[0] == "obj1"
def test_process_request_merges_different_tokens() -> None:
"""Test that requests with different tokens are merged."""
- q: queue.Queue[UpdateUIElementCommand] = queue.Queue()
+ q: queue.Queue[BatchableCommand] = queue.Queue()
manager = SetUIElementRequestManager(q)
request1 = UpdateUIElementCommand(
@@ -56,14 +65,16 @@ def test_process_request_merges_different_tokens() -> None:
result = manager.process_request(request1)
# Should merge both requests
- assert result is not None
- assert len(result.object_ids) == 2
- assert set(result.object_ids) == {"obj1", "obj2"}
+ assert len(result) == 1
+ cmd = result[0]
+ assert isinstance(cmd, UpdateUIElementCommand)
+ assert len(cmd.object_ids) == 2
+ assert set(cmd.object_ids) == {"obj1", "obj2"}
def test_process_request_keeps_latest_value_per_id() -> None:
"""Test that when multiple requests update the same UI element, the latest value wins."""
- q: queue.Queue[UpdateUIElementCommand] = queue.Queue()
+ q: queue.Queue[BatchableCommand] = queue.Queue()
manager = SetUIElementRequestManager(q)
request1 = UpdateUIElementCommand(
@@ -80,10 +91,12 @@ def test_process_request_keeps_latest_value_per_id() -> None:
result = manager.process_request(request1)
# Should keep the latest value (from request2)
- assert result is not None
- assert len(result.object_ids) == 1
- assert result.object_ids[0] == "obj1"
- assert result.values[0] == 2
+ assert len(result) == 1
+ cmd = result[0]
+ assert isinstance(cmd, UpdateUIElementCommand)
+ assert len(cmd.object_ids) == 1
+ assert cmd.object_ids[0] == "obj1"
+ assert cmd.values[0] == 2
def test_process_request_handles_concurrent_queue_updates() -> None:
@@ -92,7 +105,7 @@ def test_process_request_handles_concurrent_queue_updates() -> None:
This simulates the race condition that occurs with ZeroMQ IPC where a
receiver thread continuously adds messages to the queue.
"""
- q: queue.Queue[UpdateUIElementCommand] = queue.Queue()
+ q: queue.Queue[BatchableCommand] = queue.Queue()
manager = SetUIElementRequestManager(q)
# Track how many requests were added
@@ -131,10 +144,12 @@ def test_process_request_handles_concurrent_queue_updates() -> None:
stop_event.set()
producer_thread.join(timeout=1)
- # Verify that we got a merged result
- assert result is not None
- assert len(result.object_ids) > 1 # Should have merged multiple requests
- assert "obj_initial" in result.object_ids
+ # Verify that we got a merged result (all UI commands in a contiguous run)
+ assert len(result) >= 1
+ cmd = result[0]
+ assert isinstance(cmd, UpdateUIElementCommand)
+ assert len(cmd.object_ids) > 1 # Should have merged multiple requests
+ assert "obj_initial" in cmd.object_ids
# Verify the queue is actually empty after processing
# (small delay to let any in-flight messages arrive)
@@ -153,7 +168,7 @@ def test_process_request_handles_concurrent_queue_updates() -> None:
async def test_process_request_with_asyncio_queue() -> None:
"""Test that the manager works with asyncio.Queue."""
- q: asyncio.Queue[UpdateUIElementCommand] = asyncio.Queue()
+ q: asyncio.Queue[BatchableCommand] = asyncio.Queue()
manager = SetUIElementRequestManager(q)
request1 = UpdateUIElementCommand(
@@ -170,14 +185,16 @@ async def test_process_request_with_asyncio_queue() -> None:
result = manager.process_request(request1)
# Should merge both requests
- assert result is not None
- assert len(result.object_ids) == 2
- assert set(result.object_ids) == {"obj1", "obj2"}
+ assert len(result) == 1
+ cmd = result[0]
+ assert isinstance(cmd, UpdateUIElementCommand)
+ assert len(cmd.object_ids) == 2
+ assert set(cmd.object_ids) == {"obj1", "obj2"}
-def test_process_request_returns_none_for_empty_batch() -> None:
- """Test that None is returned when all requests are duplicates."""
- q: queue.Queue[UpdateUIElementCommand] = queue.Queue()
+def test_process_request_returns_empty_for_empty_batch() -> None:
+ """Test that an empty list is returned when all requests are duplicates."""
+ q: queue.Queue[BatchableCommand] = queue.Queue()
manager = SetUIElementRequestManager(q)
# Create a request and process it
@@ -185,9 +202,215 @@ def test_process_request_returns_none_for_empty_batch() -> None:
object_ids=["obj1"], values=[1], token="token1"
)
result1 = manager.process_request(request)
- assert result1 is not None
+ assert len(result1) == 1
# Process the same token again (duplicate)
result2 = manager.process_request(request)
- # Should return None since it's a duplicate
- assert result2 is None
+ # Should return empty list since it's a duplicate
+ assert result2 == []
+
+
+# --- Model command tests ---
+
+
+def test_model_update_merging_same_model() -> None:
+ """Test that model updates for the same model merge with last-write-wins."""
+ q: queue.Queue[BatchableCommand] = queue.Queue()
+ manager = SetUIElementRequestManager(q)
+
+ cmd1 = ModelCommand(
+ model_id="model-1",
+ message=ModelUpdateMessage(state={"x": 1, "y": 2}, buffer_paths=[]),
+ buffers=[],
+ )
+ cmd2 = ModelCommand(
+ model_id="model-1",
+ message=ModelUpdateMessage(state={"x": 10, "z": 3}, buffer_paths=[]),
+ buffers=[],
+ )
+ q.put(cmd2)
+
+ result = manager.process_request(cmd1)
+
+ assert len(result) == 1
+ cmd = result[0]
+ assert isinstance(cmd, ModelCommand)
+ assert cmd.model_id == "model-1"
+ assert isinstance(cmd.message, ModelUpdateMessage)
+ # x=10 from cmd2 (last-write-wins), y=2 from cmd1, z=3 from cmd2
+ assert cmd.message.state == {"x": 10, "y": 2, "z": 3}
+
+
+def test_model_update_different_models() -> None:
+ """Test that updates to different models produce separate commands."""
+ q: queue.Queue[BatchableCommand] = queue.Queue()
+ manager = SetUIElementRequestManager(q)
+
+ cmd1 = ModelCommand(
+ model_id="model-1",
+ message=ModelUpdateMessage(state={"x": 1}, buffer_paths=[]),
+ buffers=[],
+ )
+ cmd2 = ModelCommand(
+ model_id="model-2",
+ message=ModelUpdateMessage(state={"y": 2}, buffer_paths=[]),
+ buffers=[],
+ )
+ q.put(cmd2)
+
+ result = manager.process_request(cmd1)
+
+ assert len(result) == 2
+ ids = {r.model_id for r in result if isinstance(r, ModelCommand)}
+ assert ids == {"model-1", "model-2"}
+
+
+def test_custom_messages_pass_through() -> None:
+ """Test that custom messages are not merged and each appears individually."""
+ q: queue.Queue[BatchableCommand] = queue.Queue()
+ manager = SetUIElementRequestManager(q)
+
+ cmd1 = ModelCommand(
+ model_id="model-1",
+ message=ModelCustomMessage(content={"action": "ping"}),
+ buffers=[],
+ )
+ cmd2 = ModelCommand(
+ model_id="model-1",
+ message=ModelCustomMessage(content={"action": "pong"}),
+ buffers=[],
+ )
+ q.put(cmd2)
+
+ result = manager.process_request(cmd1)
+
+ assert len(result) == 2
+ assert all(isinstance(r, ModelCommand) for r in result)
+ msgs = [r.message for r in result if isinstance(r, ModelCommand)]
+ assert isinstance(msgs[0], ModelCustomMessage)
+ assert isinstance(msgs[1], ModelCustomMessage)
+ assert msgs[0].content == {"action": "ping"}
+ assert msgs[1].content == {"action": "pong"}
+
+
+def test_buffer_merging_drops_overridden_buffers() -> None:
+ """Test that buffers for overridden state keys are dropped."""
+ q: queue.Queue[BatchableCommand] = queue.Queue()
+ manager = SetUIElementRequestManager(q)
+
+ cmd1 = ModelCommand(
+ model_id="model-1",
+ message=ModelUpdateMessage(
+ state={"data": None},
+ buffer_paths=[["data"]],
+ ),
+ buffers=[b"old-buffer"],
+ )
+ cmd2 = ModelCommand(
+ model_id="model-1",
+ message=ModelUpdateMessage(
+ state={"data": None},
+ buffer_paths=[["data"]],
+ ),
+ buffers=[b"new-buffer"],
+ )
+ q.put(cmd2)
+
+ result = manager.process_request(cmd1)
+
+ assert len(result) == 1
+ cmd = result[0]
+ assert isinstance(cmd, ModelCommand)
+ assert isinstance(cmd.message, ModelUpdateMessage)
+ # Only the new buffer should remain
+ assert cmd.buffers == [b"new-buffer"]
+
+
+def test_mixed_ui_and_model_commands() -> None:
+ """Test that UI and model commands coexist in the result."""
+ q: queue.Queue[BatchableCommand] = queue.Queue()
+ manager = SetUIElementRequestManager(q)
+
+ ui_cmd = UpdateUIElementCommand(
+ object_ids=["obj1"], values=[1], token="token1"
+ )
+ model_cmd = ModelCommand(
+ model_id="model-1",
+ message=ModelUpdateMessage(state={"x": 1}, buffer_paths=[]),
+ buffers=[],
+ )
+ q.put(model_cmd)
+
+ result = manager.process_request(ui_cmd)
+
+ assert len(result) == 2
+ assert isinstance(result[0], UpdateUIElementCommand)
+ assert isinstance(result[1], ModelCommand)
+
+
+def test_contiguous_run_ordering() -> None:
+ """Test that [UI, Model, UI] produces 3 items in that order, not grouped by type."""
+ commands: list[BatchableCommand] = [
+ UpdateUIElementCommand(
+ object_ids=["obj1"], values=[1], token="token1"
+ ),
+ ModelCommand(
+ model_id="model-1",
+ message=ModelUpdateMessage(state={"x": 1}, buffer_paths=[]),
+ buffers=[],
+ ),
+ UpdateUIElementCommand(
+ object_ids=["obj2"], values=[2], token="token2"
+ ),
+ ]
+
+ result = merge_batchable_commands(commands)
+
+ assert len(result) == 3
+ assert isinstance(result[0], UpdateUIElementCommand)
+ assert isinstance(result[1], ModelCommand)
+ assert isinstance(result[2], UpdateUIElementCommand)
+ # Verify values preserved
+ assert result[0].object_ids == ["obj1"]
+ assert result[2].object_ids == ["obj2"]
+
+
+def test_contiguous_runs_merged_within_run() -> None:
+ """Test that contiguous same-type commands are merged within their run."""
+ commands: list[BatchableCommand] = [
+ UpdateUIElementCommand(
+ object_ids=["obj1"], values=[1], token="token1"
+ ),
+ UpdateUIElementCommand(
+ object_ids=["obj2"], values=[2], token="token2"
+ ),
+ ModelCommand(
+ model_id="model-1",
+ message=ModelUpdateMessage(state={"x": 1}, buffer_paths=[]),
+ buffers=[],
+ ),
+ ModelCommand(
+ model_id="model-1",
+ message=ModelUpdateMessage(state={"x": 2}, buffer_paths=[]),
+ buffers=[],
+ ),
+ UpdateUIElementCommand(
+ object_ids=["obj3"], values=[3], token="token3"
+ ),
+ ]
+
+ result = merge_batchable_commands(commands)
+
+ # UI(merged) Model(merged) UI
+ assert len(result) == 3
+ assert isinstance(result[0], UpdateUIElementCommand)
+ assert isinstance(result[1], ModelCommand)
+ assert isinstance(result[2], UpdateUIElementCommand)
+
+ # First UI run merged obj1 and obj2
+ assert set(result[0].object_ids) == {"obj1", "obj2"}
+ # Model run merged x=1 then x=2 → x=2
+ assert isinstance(result[1].message, ModelUpdateMessage)
+ assert result[1].message.state == {"x": 2}
+ # Last UI is standalone
+ assert result[2].object_ids == ["obj3"]