From 7e884bdfcea5b7b4374eb10a3684f8824da40c14 Mon Sep 17 00:00:00 2001 From: Griffin Milsap Date: Wed, 11 Feb 2026 16:39:37 -0500 Subject: [PATCH] added description for low-level api --- .../explanations/content-explanations.rst | 3 +- docs/source/explanations/low-level-api.rst | 66 +++++++++++++++++++ 2 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 docs/source/explanations/low-level-api.rst diff --git a/docs/source/explanations/content-explanations.rst b/docs/source/explanations/content-explanations.rst index c89d0fb..2e4e1c1 100644 --- a/docs/source/explanations/content-explanations.rst +++ b/docs/source/explanations/content-explanations.rst @@ -9,6 +9,7 @@ This section of the documentation aims to provide a comprehensive overview of th :maxdepth: 1 ezmsg-design + low-level-api axisarray Other ways to learn about `ezmsg` include following our :doc:`Tutorial <../tutorials/content-tutorials>`, checking the list of :doc:`HOW TO pages <../how-tos/content-howtos>` and the :doc:`reference documentation <../reference/content-reference>`. @@ -102,4 +103,4 @@ See :doc:`Extensions page <../extensions/content-extensions>` for more informati .. |ezmsg_logo_small| image:: ../_static/_images/ezmsg_logo.png :width: 40 - :alt: ezmsg logo \ No newline at end of file + :alt: ezmsg logo diff --git a/docs/source/explanations/low-level-api.rst b/docs/source/explanations/low-level-api.rst new file mode 100644 index 0000000..3162248 --- /dev/null +++ b/docs/source/explanations/low-level-api.rst @@ -0,0 +1,66 @@ +Low-level API +##################### + +`ezmsg` exposes two layers of API that build on the same pub/sub core: + +a **low-level API** that lets you create publishers and subscribers directly, and a **high-level API** that lets you describe a processing graph (a dataflow pipeline) and have ezmsg manage execution for you. + +This page explains the low-level model and how it differs from the high-level API so you can choose the right tool for the job. + + +|ezmsg_logo_small| The Low-level Model +**************************************** + +At its core, `ezmsg` is a publish/subscribe messaging system. + +- A **publisher** can send messages to **many subscribers**. +- A **subscriber** can listen to **many publishers**. +- **Channels** route messages between publishers and subscribers; they are **created and managed automatically** when you connect endpoints. +- Messages can be any Python object. `AxisArray` is optional, not required. + +The low-level API gives you direct access to these primitives. You decide **when** to publish, **how** to receive, and **how** to schedule your own control flow. This makes the low-level API a good fit when you want to integrate messaging into an existing application structure instead of adopting the full `ezmsg` pipeline runtime. + + +|ezmsg_logo_small| Relationship to the High-level API +****************************************************** + +The high-level API is a **stream-based dataflow runtime**. You define a graph of processing nodes (`Unit` and `Collection`) and connect their input/output streams. The graph is then executed by `ezmsg` (typically via `ez.run()`), which wraps your main entry point and manages scheduling, process layout, and message flow. + +Under the hood, the high-level API is **built on the same publisher/subscriber primitives**. Input/output streams are convenience wrappers around those low-level endpoints. + + +|ezmsg_logo_small| Choosing the Right API +******************************************* + +The **low-level API** is a good fit when: + +- You already have an application loop or framework you want to keep. +- You want explicit control over concurrency and scheduling. +- You only need a small number of pub/sub links instead of a full graph. +- You are integrating `ezmsg` into a larger system that already manages process lifetime. + +The **high-level API** is a good fit when: + +- You want to express a graph of processing steps and let `ezmsg` execute it. +- You want consistent dataflow semantics and standardized stream connections. +- You benefit from the pipeline tooling (graph visualization, CLI integration, etc.). +- You want a structured way to scale across threads/processes without managing it yourself. + + +|ezmsg_logo_small| Examples +******************************** + +The ezmsg repository includes example scripts that demonstrate the low-level API in both synchronous and asynchronous styles: + +- `ezmsg/examples/simple_publisher.py` +- `ezmsg/examples/simple_subscriber.py` +- `ezmsg/examples/simple_async_publisher.py` +- `ezmsg/examples/simple_async_subscriber.py` + +.. important:: The synchronous low-level API is a **convenience wrapper** around the async implementation. Internally it uses a threaded `asyncio` loop and calls like ``run_coroutine_threadsafe`` to bridge into the async backend. This is ergonomic (and familiar to users coming from ROS2-style semantics), but it comes with **throughput overhead**. For high data-rate paths, the async low-level API is recommended. + +.. note:: For a full introduction to the high-level API, see the :doc:`Tutorials <../tutorials/content-tutorials>` and the :doc:`Pipeline how-to <../how-tos/pipeline/content-pipeline>`. + +.. |ezmsg_logo_small| image:: ../_static/_images/ezmsg_logo.png + :width: 40 + :alt: ezmsg logo