From 5f1b91bb893a9d534f3fe5edf50bc6fe8d404b2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Fri, 15 May 2026 08:46:42 -0700 Subject: [PATCH] Clarify PipelineRunner.run() docstring for the no-task form Spell out that spawned tasks finishing on their own does not unblock ``runner.run()`` when called without a ``task`` argument. The form is for hosts (e.g. FastAPI servers) that have no single "main" pipeline and want to stay up across many spawned sessions; callers who want the runner to finish when a specific pipeline finishes should pass that pipeline as ``task``. --- src/pipecat/pipeline/runner.py | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/src/pipecat/pipeline/runner.py b/src/pipecat/pipeline/runner.py index 2d7c98c98..18a1979e8 100644 --- a/src/pipecat/pipeline/runner.py +++ b/src/pipecat/pipeline/runner.py @@ -12,20 +12,29 @@ also acts as the host for spawned :class:`~pipecat.pipeline.base_task.BaseTask` instances — owning the shared :class:`~pipecat.bus.TaskBus`, the task registry, and the task manager that backs the entire session. -For a typical single-pipeline bot, use :meth:`PipelineRunner.run`: +For a typical single-pipeline bot, use :meth:`PipelineRunner.run` with the +task: .. code-block:: python runner = PipelineRunner() await runner.run(task) -For multi-task setups, additionally spawn workers: +``run()`` returns when ``task`` finishes. + +For multi-task setups, spawn the additional tasks alongside the main one: .. code-block:: python runner = PipelineRunner() - await runner.spawn(CodeWorker("code_worker", bus=runner.bus, ...)) - await runner.run(main_task) + await runner.spawn(CodeWorker("code_worker", ...)) + await runner.run(task) + +Optionally, ``spawn`` every task (including the main pipeline) and call +``run()`` with no argument. In that form ``run()`` blocks until +:meth:`PipelineRunner.end` / :meth:`PipelineRunner.cancel` is called (or an +incoming ``BusEndMessage`` / ``BusCancelMessage`` triggers the same path) — +spawned tasks finishing on their own does **not** unblock it. """ import asyncio @@ -176,8 +185,13 @@ class PipelineRunner(BaseObject, BusSubscriber): when the main task finishes. If ``task`` is None, blocks until :meth:`end` or :meth:`cancel` - is called. Useful for hosts that only spawn tasks and have no - single "main" pipeline. + is called (or until an incoming ``BusEndMessage`` / + ``BusCancelMessage`` triggers the same path). Spawned tasks + finishing on their own does **not** unblock the runner — use + this form for hosts that have no single "main" pipeline and + want to stay up across many spawned sessions (e.g. a FastAPI + server). If you want the runner to finish when a specific + pipeline finishes, pass that pipeline as ``task``. Args: task: The pipeline task to run, or None.