.. _stdlib_imgui_transport:

===========================================================
Transport — pluggable lambda-based IPC for imgui commands
===========================================================

.. das:module:: imgui_transport

Lambda-typed transport for dasImgui live commands. ``Transport`` is a
closure ``(action, payload) → JsonValue?``; ``live_api_transport(url)``
returns a transport that POSTs ``{"name": action, "args": payload}`` to
``<url>/command`` and parses the JSON response. Users substitute mocks,
in-process buses, or alternative transports without changing call sites.

Wait helpers — ``await_imgui``, ``await_imgui_frame``, ``send_with_await``
— drive client-side polling against the host's ``imgui_await`` endpoint.
Server-side blocking is incompatible with the GLFW-main-thread invariant
(the dispatch handler runs on the same thread that advances frames), so
waits are always client-side; ``send_with_await`` dispatches on
``await_frames`` / ``await_until: "quiescent"`` / ``fire_and_forget`` and
default-polls quiescence otherwise.



++++++++++++
Type aliases
++++++++++++

.. _alias-Transport:

.. das:attribute:: Transport = lambda<(action:string const;var payload:JsonValue?):JsonValue?>

typedef Transport = lambda<(action:string const;var payload:json::JsonValue? -const):json::JsonValue?> aka Transport


+++++++++
Constants
+++++++++

.. _global-imgui_transport-DEFAULT_AWAIT_POLL_MS:

.. das:attribute:: DEFAULT_AWAIT_POLL_MS = 0x32

DEFAULT_AWAIT_POLL_MS:uint const

.. _global-imgui_transport-DEFAULT_AWAIT_TIMEOUT_SEC:

.. das:attribute:: DEFAULT_AWAIT_TIMEOUT_SEC = 5f

DEFAULT_AWAIT_TIMEOUT_SEC:float const


++++++++++++++++++++++
Transport construction
++++++++++++++++++++++

  *  :ref:`live_api_transport (url: string) : Transport <function-imgui_transport_live_api_transport_string>`

.. _function-imgui_transport_live_api_transport_string:

.. das:function:: live_api_transport(url: string) : Transport

Default transport: POSTs ``{"name": action, "args": payload}`` to ``<url>/command`` and parses the JSON response. ``url`` is captured by value, so the returned lambda is safe to reuse.


:Arguments: * **url** : string


++++++++++++++
Send / receive
++++++++++++++

  *  :ref:`send_imgui_command (transport: Transport; action: string; var payload: JsonValue?) : JsonValue? <function-imgui_transport_send_imgui_command_Transport_string_JsonValue_q_>`

.. _function-imgui_transport_send_imgui_command_Transport_string_JsonValue_q_:

.. das:function:: send_imgui_command(transport: Transport; action: string; payload: JsonValue?) : JsonValue?

Send one command through ``transport`` and return the parsed JSON response.


:Arguments: * **transport** :  :ref:`Transport <alias-Transport>`

            * **action** : string

            * **payload** :  :ref:`JsonValue <struct-json-JsonValue>`?


+++++++++++++
Uncategorized
+++++++++++++

.. _function-imgui_transport_receive_imgui_snapshot_Transport:

.. das:function:: receive_imgui_snapshot(transport: Transport) : JsonValue?

Convenience for ``send_imgui_command(transport, "imgui_snapshot", null)`` — fetches the full widget snapshot.


:Arguments: * **transport** :  :ref:`Transport <alias-Transport>`

.. _function-imgui_transport_await_imgui_Transport_string_float:

.. das:function:: await_imgui(transport: Transport; until: string = "quiescent"; timeout_sec: float = DEFAULT_AWAIT_TIMEOUT_SEC) : bool

Poll ``imgui_await`` until ``value.quiescent`` flips true; returns true on quiescence, false on timeout.


:Arguments: * **transport** :  :ref:`Transport <alias-Transport>`

            * **until** : string

            * **timeout_sec** : float

.. _function-imgui_transport_await_imgui_frame_Transport_int_float:

.. das:function:: await_imgui_frame(transport: Transport; target_frame: int; timeout_sec: float = DEFAULT_AWAIT_TIMEOUT_SEC) : bool

Poll ``imgui_await`` until server-side ``value.frame >= target_frame``; reuses the ``frame:`` arg so server flips ``quiescent`` at the right tick.


:Arguments: * **transport** :  :ref:`Transport <alias-Transport>`

            * **target_frame** : int

            * **timeout_sec** : float

.. _function-imgui_transport_send_with_await_Transport_string_JsonValue_q__float:

.. das:function:: send_with_await(transport: Transport; action: string; payload: JsonValue?; timeout_sec: float = DEFAULT_AWAIT_TIMEOUT_SEC) : JsonValue?

Send ``action``/``payload`` and honor any ``await_*`` modifier the server merged into the response.
Dispatches on ``await_frames`` / ``await_until: "quiescent"`` / ``fire_and_forget``; otherwise default-polls quiescence with ``timeout_sec``.


:Arguments: * **transport** :  :ref:`Transport <alias-Transport>`

            * **action** : string

            * **payload** :  :ref:`JsonValue <struct-json-JsonValue>`?

            * **timeout_sec** : float