Class StateProxy

nextpy/backend/state.py:1296–1447

Proxy of a state instance to control mutability of vars for a background task. Since a background task runs against a state instance without holding the state_manager lock for the token, the reference may become stale if the same state is modified by another event handler. The prox

class StateProxy(wrapt.ObjectProxy):
    """Proxy of a state instance to control mutability of vars for a background task.

    Since a background task runs against a state instance without holding the
    state_manager lock for the token, the reference may become stale if the same
    state is modified by another event handler.

    The proxy object ensures that writes to the state are blocked unless
    explicitly entering a context which refreshes the state from state_manager
    and holds the lock for the token until exiting the context. After exiting
    the context, a StateUpdate may be emitted to the frontend to notify the
    client of the state change.

    A background task will be passed the `StateProxy` as `self`, so mutability
    can be safely performed inside an `async with self` block.

        class State(xt.State):
            counter: int = 0

            @xt.background
            async def bg_increment(self):
                await asyncio.sleep(1)
                async with self:
                    self.counter += 1
    """

    def __init__(self, state_instance):
        """Create a proxy for a state instance.

        Args:
            state_instance: The state instance to proxy.
        """
        super().__init__(state_instance)
        # compile is not relevant to backend logic
        #TODO: We're currently using this weirdo mechanism for installing initial packages
        # gets to load_module -> compile -> get_frontend_packages -> install_frontend_packages
        # We can improve this
        self._self_app = getattr(prerequisites.get_app(), constants.CompileVars.APP)
        self._self_substate_path = state_instance.get_full_name().split(".")
        self._self_actx = None
        self._self_mutable = False

    async def __aenter__(self) -> StateProxy:
        """Enter the async context manager protocol.

        Sets mutability to True and enters the `App.modify_state` async context,
        which refreshes the state from state_manager and holds the lock for the
        given state token until exiting the context.

        Background tasks should avoid blocking calls while inside the context.

        Returns:
            This StateProxy instance in mutable mode.
        """
        self._self_actx = self._self_app.modify_state(
            self.__wrapped__.router.session.client_token
        )
        mutable_state = await self._self_actx.__aenter__()