shared

Decorators for operations on a resource shared by several owners.

An input and an output transport share a single client, so both set it up, both join its room, and both tear it down. Processors are set up and cleaned up concurrently, so those calls overlap.

Decorate the paired operations with acquires() and releases() and the work runs once: the first owner to acquire runs the body while the rest wait for it, and only the last owner to release runs the undo.

pipecat.utils.shared.acquires(name: str) → Callable[[Callable[[_P], Awaitable[_T]]], Callable[[_P], Coroutine[Any, Any, _T | None]]]

Run the decorated method for the first owner to acquire name.

Owners that arrive while the first is still running wait for it to finish, so no caller continues against a half-built resource. Later owners return None without running the method again.

A method that raises leaves the resource unbuilt, and every owner of it is told: the exception is re-raised to each one that arrives later, rather than the method being attempted again. So the owners of a resource share its verdict, and a pair of processors sharing a client either both come up or both fail.

Parameters:

name – The resource being acquired. Names are per instance, so paired operations on the same object (e.g. setup/cleanup and join/leave) count their owners separately.

Note

The lock is not reentrant, so a method must not call another method that acquires the same resource.

pipecat.utils.shared.releases(name: str) → Callable[[Callable[[_P], Awaitable[_T]]], Callable[[_P], Coroutine[Any, Any, _T | None]]]

Run the decorated method for the last owner to release name.

Every other owner returns None, as does a release that no acquire matched.

Parameters:

name – The resource being released, matching the acquires() name.

Note

The lock is not reentrant, so a method must not call another method that releases the same resource.