pyfect-dev 0.1.0__py3-none-any.whl

pyfect/stream/_error_methods.py

@@ -0,0 +1,254 @@
+"""``Stream`` methods that handle failures: recovering with another
+stream, tapping, mapping and dropping errors, and retrying.
+
+Recovery from typed errors goes through the cause's recoverable error, so
+a defect always wins over a typed error. To remove the caught errors from
+the stream's type, use ``pyfect.stream.catch_tag`` / ``catch_if`` with
+``.pipe``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Never, overload
+
+from pyfect._tags import Tags
+from pyfect.result import Err, Ok, Result
+from pyfect.stream._base import A_co, E_co, R_co, StreamBase
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect.cause import Cause
+    from pyfect.logger import Severity
+    from pyfect.schedule import Schedule
+    from pyfect.schedule._model import SetInputType
+    from pyfect.stream._stream import Stream
+
+
+class ErrorMethods(StreamBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    # --- recovering -----------------------------------------------------------
+
+    def catch_cause[B, E2 = Never, R2 = Never](
+        self, f: Callable[[Cause[E_co]], Stream[B, E2, R2]]
+    ) -> Stream[A_co | B, E2, R_co | R2]:
+        """On any failure, defects included, release this stream's resources
+        and go on with ``f(cause)``."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.catch_cause(lambda cause: f(cause)._channel))
+
+    def catch_cause_if[B, E2 = Never, R2 = Never](
+        self,
+        predicate: Callable[[Cause[E_co]], bool],
+        f: Callable[[Cause[E_co]], Stream[B, E2, R2]],
+    ) -> Stream[A_co | B, E_co | E2, R_co | R2]:
+        """``catch_cause`` for the causes that pass ``predicate``."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.catch_cause_if(predicate, lambda cause: f(cause)._channel))
+
+    def catch_all[B, E2 = Never, R2 = Never](
+        self, f: Callable[[E_co], Stream[B, E2, R2]]
+    ) -> Stream[A_co | B, E2, R_co | R2]:
+        """Go on with ``f(error)`` after a typed failure (Effect's
+        ``Stream.catch``). Defects and interruptions pass through."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.catch_all(lambda error: f(error)._channel))
+
+    @overload
+    def catch_if[B, E2 = Never, R2 = Never](
+        self, predicate: Callable[[E_co], bool], f: Callable[[E_co], Stream[B, E2, R2]]
+    ) -> Stream[A_co | B, E_co | E2, R_co | R2]: ...
+    @overload
+    def catch_if[B, C, EE = Never, RR = Never](
+        self,
+        predicate: Callable[[E_co], bool],
+        f: Callable[[E_co], Stream[B, EE, RR]],
+        *,
+        or_else: Callable[[E_co], Stream[C, EE, RR]],
+    ) -> Stream[A_co | B | C, EE, R_co | RR]: ...
+    def catch_if(
+        self,
+        predicate: Callable[[Any], bool],
+        f: Callable[[Any], Stream[Any, Any, Any]],
+        *,
+        or_else: Callable[[Any], Stream[Any, Any, Any]] | None = None,
+    ) -> Stream[Any, Any, Any]:
+        """Go on with ``f(error)`` after a typed failure that passes
+        ``predicate``; ``or_else``, if given, handles the rest. To remove the
+        caught errors from the type, use ``pipe(stream.catch_if(...))`` with
+        a ``TypeIs`` refinement."""
+        from pyfect.stream import _catch
+
+        return _catch.catch_if(self, predicate, f, or_else)
+
+    @overload
+    def catch_filter[EB, X, B, E2 = Never, R2 = Never](
+        self, filter: Callable[[E_co], Result[EB, X]], f: Callable[[EB], Stream[B, E2, R2]]
+    ) -> Stream[A_co | B, X | E2, R_co | R2]: ...
+    @overload
+    def catch_filter[EB, X, B, C, EE = Never, RR = Never](
+        self,
+        filter: Callable[[E_co], Result[EB, X]],
+        f: Callable[[EB], Stream[B, EE, RR]],
+        *,
+        or_else: Callable[[X], Stream[C, EE, RR]],
+    ) -> Stream[A_co | B | C, EE, R_co | RR]: ...
+    def catch_filter(
+        self,
+        filter: Callable[[Any], Result[Any, Any]],
+        f: Callable[[Any], Stream[Any, Any, Any]],
+        *,
+        or_else: Callable[[Any], Stream[Any, Any, Any]] | None = None,
+    ) -> Stream[Any, Any, Any]:
+        """Go on with ``f(value)`` after a typed failure ``filter`` maps to
+        ``Ok(value)``. One it maps to ``Err(x)`` goes to ``or_else(x)``, or
+        fails with ``x``."""
+        from pyfect.stream._constructors import fail
+        from pyfect.stream._stream import Stream
+
+        def handle(error: Any) -> Any:
+            match filter(error):
+                case Ok(value):
+                    return f(value)._channel
+                case Err(rest):
+                    return (fail(rest) if or_else is None else or_else(rest))._channel
+
+        return Stream(self._channel.catch_all(handle))
+
+    def catch_cause_filter[EB, X, B, E2 = Never, R2 = Never](
+        self,
+        filter: Callable[[Cause[E_co]], Result[EB, Cause[X]]],
+        f: Callable[[EB, Cause[E_co]], Stream[B, E2, R2]],
+    ) -> Stream[A_co | B, X | E2, R_co | R2]:
+        """Go on with ``f(value, cause)`` after a failure ``filter`` maps to
+        ``Ok(value)``; one it maps to ``Err(rest)`` fails with ``rest``."""
+        from pyfect.stream._constructors import fail_cause
+        from pyfect.stream._stream import Stream
+
+        def handle(cause: Cause[E_co]) -> Any:
+            match filter(cause):
+                case Ok(value):
+                    return f(value, cause)._channel
+                case Err(rest):
+                    return fail_cause(rest)._channel
+
+        return Stream(self._channel.catch_cause(handle))
+
+    def catch_defect[B, E2 = Never, R2 = Never](
+        self, f: Callable[[object], Stream[B, E2, R2]]
+    ) -> Stream[A_co | B, E_co | E2, R_co | R2]:
+        """Go on with ``f(defect)`` after a failure with a defect. Typed
+        errors pass through."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.catch_defect(lambda defect: f(defect)._channel))
+
+    def or_else_if_empty[B, E2 = Never, R2 = Never](
+        self, or_else: Callable[[], Stream[B, E2, R2]]
+    ) -> Stream[A_co | B, E_co | E2, R_co | R2]:
+        """Go on with ``or_else()`` if this stream ends without writing."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.or_else_if_empty(lambda _: or_else()._channel))
+
+    def or_else_succeed[B](self, f: Callable[[E_co], B]) -> Stream[A_co | B, Never, R_co]:
+        """Write ``f(error)`` and end instead of failing with a typed error."""
+        from pyfect.stream._constructors import succeed
+
+        return self.catch_all(lambda error: succeed(f(error)))
+
+    # --- tapping --------------------------------------------------------------
+
+    def tap_cause[E2 = Never, R2 = Never](
+        self, f: Callable[[Cause[E_co]], Effect[object, E2, R2]]
+    ) -> Stream[A_co, E_co | E2, R_co | R2]:
+        """Run ``f(cause)`` when the stream fails, then fail the same way."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.tap_cause(f))
+
+    def tap_error[E2 = Never, R2 = Never](
+        self, f: Callable[[E_co], Effect[object, E2, R2]]
+    ) -> Stream[A_co, E_co | E2, R_co | R2]:
+        """Run ``f(error)`` when the stream fails with a typed error."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.tap_error(f))
+
+    def tap_error_tag[T, E2 = Never, R2 = Never](
+        self, tag: Tags[T], f: Callable[[T], Effect[object, E2, R2]]
+    ) -> Stream[A_co, E_co | E2, R_co | R2]:
+        """``tap_error`` for the errors that are instances of ``tag`` (a
+        class or a tuple of classes)."""
+        from pyfect.effect import void
+
+        return self.tap_error(lambda e: f(e) if isinstance(e, tag) else void)
+
+    def tap_defect[E2 = Never, R2 = Never](
+        self, f: Callable[[object], Effect[object, E2, R2]]
+    ) -> Stream[A_co, E_co | E2, R_co | R2]:
+        """Run ``f(defect)`` when the stream fails with a defect."""
+        from pyfect.effect import void
+
+        def tap(cause: Cause[E_co]) -> Effect[object, E2, R2]:
+            defect = cause.find_defect()
+            return f(defect.value) if isinstance(defect, Ok) else void
+
+        return self.tap_cause(tap)
+
+    # --- mapping and dropping errors ------------------------------------------
+
+    def map_error[E2](self, f: Callable[[E_co], E2]) -> Stream[A_co, E2, R_co]:
+        """Apply ``f`` to the typed error. Defects and interruptions stay."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.map_error(f))
+
+    def or_die(self) -> Stream[A_co, Never, R_co]:
+        """Die with the typed error instead of failing with it."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.or_die())
+
+    def ignore(self, *, log: bool | Severity = False) -> Stream[A_co, Never, R_co]:
+        """End instead of failing with a typed error. With ``log``, log the
+        cause first, at the current log level (``True``) or the level
+        given."""
+        from pyfect.stream._stream import Stream
+
+        ignored: Any = self._channel.ignore(log=log)
+        return Stream(ignored)
+
+    def ignore_cause(self, *, log: bool | Severity = False) -> Stream[A_co, Never, R_co]:
+        """End instead of failing in any way. ``log`` as for ``ignore``."""
+        from pyfect.stream._stream import Stream
+
+        ignored: Any = self._channel.ignore_cause(log=log)
+        return Stream(ignored)
+
+    # --- retrying -------------------------------------------------------------
+
+    @overload
+    def retry[EE = Never, RR = Never](
+        self, policy: Schedule[object, E_co, EE, RR], /
+    ) -> Stream[A_co, E_co | EE, R_co | RR]: ...
+    @overload
+    def retry[A, E, R, EE = Never, RR = Never](
+        self: ErrorMethods[A, E, R],
+        builder: Callable[[SetInputType[E]], Schedule[object, E, EE, RR]],
+        /,
+    ) -> Stream[A, E | EE, R | RR]: ...
+    def retry(
+        self, policy: Schedule[Any, Any, Any, Any] | Callable[[Any], Any], /
+    ) -> Stream[Any, Any, Any]:
+        """Run the stream again from the start after each typed failure,
+        while ``policy`` recurs; then fail with the last error. Items
+        already written stay written. A run that writes an item resets the
+        policy; each run sees its step's ``schedule.CurrentMetadata``."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.retry(policy))

pyfect/stream/_execution_plan.py

@@ -0,0 +1,199 @@
+"""``stream.with_execution_plan``: run a stream under an ``ExecutionPlan``
+(Effect's ``Stream.withExecutionPlan``)."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from typing import Any, Generic, Never, TypeVar, overload
+
+from pyfect._core import Effect, _Succeed
+from pyfect.effect import sync, yield_now
+from pyfect.execution_plan._events import AttemptState, OnEvent
+from pyfect.execution_plan._events import CurrentMetadata as PlanMetadata
+from pyfect.execution_plan._model import ExecutionPlan, Step
+from pyfect.execution_plan._run import PlanRun, fallback_schedule, first_schedule
+from pyfect.exit import Exit
+from pyfect.schedule import CurrentMetadata, Metadata, Schedule, Stop
+from pyfect.schedule._model import to_step_with_metadata
+from pyfect.stream._base import AnyStream, StreamBase
+from pyfect.stream._constructors import fail, suspend, unwrap
+from pyfect.stream._context import provide, provide_service_effect
+from pyfect.stream._stream import Stream
+
+P_contra = TypeVar("P_contra", contravariant=True)
+In_contra = TypeVar("In_contra", contravariant=True)
+PE_co = TypeVar("PE_co", covariant=True)
+PR_co = TypeVar("PR_co", covariant=True)
+
+type _AnyStream = Stream[Any, Any, Any]
+_VOID: Effect[None] = _Succeed(None)
+
+
+def _retry_without_reset(self: AnyStream, schedule: Schedule[Any, Any, Any, Any]) -> _AnyStream:
+    """Rerun ``self`` after each failure while ``schedule`` recurs. Unlike
+    ``Stream.retry``, items written before a failure do not reset the
+    schedule, so a stream that always fails part-way still stops."""
+
+    def build(step: Any) -> _AnyStream:
+        meta: Metadata[Any, Any] = CurrentMetadata.default()
+
+        def loop() -> _AnyStream:
+            return self.pipe(provide_service_effect(CurrentMetadata, sync(lambda: meta))).catch_all(
+                again
+            )
+
+        def again(error: Any) -> _AnyStream:
+            def decided(decision: Metadata[Any, Any] | Stop[Any]) -> _AnyStream:
+                nonlocal meta
+                if isinstance(decision, Stop):
+                    return fail(error)
+                meta = decision
+                return unwrap(yield_now().as_(suspend(loop)))
+
+            return unwrap(step(error).map(decided))
+
+        return loop()
+
+    return unwrap(to_step_with_metadata(schedule).map(build))
+
+
+class _StreamPlanRun(PlanRun):
+    __slots__ = ("attempt", "last_error")
+
+    def __init__(self, on_event: OnEvent[Any, Any] | None) -> None:
+        super().__init__(on_event)
+        self.attempt: AttemptState | None = None
+        self.last_error: tuple[Any] | None = None
+
+    def instrument(self, stream: _AnyStream) -> _AnyStream:
+        emitter = self.emitter
+        if emitter is None:
+            return stream
+
+        def started(state: AttemptState) -> None:
+            self.attempt = state
+
+        def ended(ex: Exit[Any, Any]) -> Effect[None, Never, Any]:
+            state = self.attempt
+            if state is None:
+                return _VOID
+            self.attempt = None
+            return emitter.end(state, ex)
+
+        return stream.on_start(emitter.begin().map(started)).on_exit(ended)
+
+
+def _run_plan(
+    self: AnyStream,
+    plan: ExecutionPlan[Any, Any, Any, Any],
+    prevent_fallback_on_partial_stream: bool,
+    on_event: OnEvent[Any, Any] | None,
+) -> _AnyStream:
+    def start() -> _AnyStream:
+        run = _StreamPlanRun(on_event)
+
+        def step_stream(step: Step[Any, Any, Any, Any]) -> _AnyStream:
+            provided = run.instrument(provide(step.provide)(self))
+            attempt = provided.pipe(provide_service_effect(PlanMetadata, sync(run.next_meta)))
+            if run.last_error is None:
+                policy = first_schedule(step)
+                return attempt if policy is None else _retry_without_reset(attempt, policy)
+            (error,) = run.last_error
+            replayed = False
+
+            def next_run() -> AnyStream:
+                nonlocal replayed
+                if replayed:
+                    return attempt
+                replayed = True
+                return fail(error)
+
+            return _retry_without_reset(suspend(next_run), fallback_schedule(step))
+
+        def loop() -> _AnyStream:
+            received = False
+
+            def first_item(_: Any) -> Effect[None]:
+                nonlocal received
+                received = True
+                return _VOID
+
+            def on_error(error: Any) -> _AnyStream:
+                run.index += 1
+                partial = prevent_fallback_on_partial_stream and received
+                if partial or run.index >= len(plan.steps):
+                    return fail(error)
+                run.last_error = (error,)
+                return suspend(loop)
+
+            attempt = step_stream(plan.steps[run.index])
+            if prevent_fallback_on_partial_stream:
+                attempt = attempt.on_first(first_item)
+            return attempt.catch_all(on_error)
+
+        return suspend(loop)
+
+    return suspend(start)
+
+
+class _WithExecutionPlan(Generic[P_contra, In_contra, PE_co, PR_co]):
+    """Runs a stream under a plan, removing ``P`` from its services. When
+    the plan's predicates or schedules read the errors (``In`` is not
+    ``object``), the stream's errors must be ``In`` and are typed as ``In``."""
+
+    __slots__ = ("on_event", "plan", "prevent_fallback_on_partial_stream")
+
+    def __init__(
+        self,
+        plan: ExecutionPlan[Any, Any, Any, Any],
+        prevent_fallback_on_partial_stream: bool,
+        on_event: OnEvent[Any, Any] | None,
+    ) -> None:
+        self.plan = plan
+        self.prevent_fallback_on_partial_stream = prevent_fallback_on_partial_stream
+        self.on_event = on_event
+
+    @overload
+    def __call__[A, E](
+        self: _WithExecutionPlan[P_contra, object, PE_co, PR_co], stream: StreamBase[A, E, P_contra]
+    ) -> Stream[A, E | PE_co, PR_co]: ...
+    @overload
+    def __call__[A, E, R](
+        self: _WithExecutionPlan[P_contra, object, PE_co, PR_co],
+        stream: StreamBase[A, E, P_contra | R],
+    ) -> Stream[A, E | PE_co, R | PR_co]: ...
+    @overload
+    def __call__[A](
+        self, stream: StreamBase[A, In_contra, P_contra]
+    ) -> Stream[A, In_contra | PE_co, PR_co]: ...
+    @overload
+    def __call__[A, R](
+        self, stream: StreamBase[A, In_contra, P_contra | R]
+    ) -> Stream[A, In_contra | PE_co, R | PR_co]: ...
+    def __call__(self, stream: AnyStream) -> _AnyStream:
+        return _run_plan(stream, self.plan, self.prevent_fallback_on_partial_stream, self.on_event)
+
+
+@overload
+def with_execution_plan[P, In, PE, PR](
+    plan: ExecutionPlan[P, In, PE, PR], *, prevent_fallback_on_partial_stream: bool = False
+) -> _WithExecutionPlan[P, In, PE, PR]: ...
+@overload
+def with_execution_plan[P, In, PE, RR](
+    plan: ExecutionPlan[P, In, PE, RR],
+    *,
+    prevent_fallback_on_partial_stream: bool = False,
+    on_event: OnEvent[In | PE, RR],
+) -> _WithExecutionPlan[P, In, PE, RR]: ...
+def with_execution_plan(
+    plan: ExecutionPlan[Any, Any, Any, Any],
+    *,
+    prevent_fallback_on_partial_stream: bool = False,
+    on_event: OnEvent[Any, Any] | None = None,
+) -> _WithExecutionPlan[Any, Any, Any, Any]:
+    """Run a stream under ``plan``, as ``pyfect.with_execution_plan`` runs
+    an effect: a failing step falls back to the next, even after writing
+    items, unless ``prevent_fallback_on_partial_stream`` (then it fails).
+    Use with ``.pipe``. A downstream consumer that stops early ends the
+    attempt with ``AttemptSuccess``."""
+    return _WithExecutionPlan(plan, prevent_fallback_on_partial_stream, on_event)

pyfect/stream/_fanout.py

@@ -0,0 +1,154 @@
+"""The work behind ``Stream``'s ``partition`` family, ``broadcast``,
+``broadcast_n`` and ``share``: one upstream run feeding several readers.
+
+The partitions run the upstream on a fiber in the caller's scope, writing
+into two queues; the broadcasts publish its chunks to a pubsub of
+``Take`` values that every reader subscribes to.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator
+from typing import Any, Literal
+
+from pyfect import channel
+from pyfect._concurrency import Concurrency
+from pyfect._core import Effect, _Gen, _Succeed
+from pyfect._fiber import Fiber
+from pyfect.cause import Cause
+from pyfect.channel._sinks import make_pubsub
+from pyfect.duration import Duration
+from pyfect.effect import provide_service
+from pyfect.queue import Queue, Strategy
+from pyfect.rc_ref import RcRef
+from pyfect.result import Err, Result
+from pyfect.scope import Scope, fork_in, fork_scoped
+from pyfect.stream._base import AnyStream, as_stream
+from pyfect.stream._grouping import from_queue_shutdown_on_end
+from pyfect.stream._stream import Stream
+
+type AnyEffect = Effect[Any, Any, Any]
+type AnyStream_ = Stream[Any, Any, Any]
+type Capacity = int | Literal["unbounded"]
+
+_VOID: AnyEffect = _Succeed(None)
+
+
+# --- partitions ------------------------------------------------------------------
+
+
+def partition_queue(
+    self: AnyStream, f: Callable[[Any], Result[Any, Any]], capacity: Capacity
+) -> AnyEffect:
+    bound = None if capacity == "unbounded" else capacity
+
+    def body() -> Generator[AnyEffect, Any, tuple[Queue[Any, Any], Queue[Any, Any]]]:
+        scope = yield Scope()
+        pull = yield self._channel.to_pull_scoped(scope)
+        passes: Queue[Any, Any] = Queue(bound)
+        fails: Queue[Any, Any] = Queue(bound)
+
+        def feed() -> Generator[AnyEffect, Any]:
+            while True:
+                chunk = yield pull
+                passed: list[Any] = []
+                failed: list[Any] = []
+                for item in chunk:
+                    match f(item):
+                        case Err(error):
+                            failed.append(error)
+                        case ok:
+                            passed.append(ok.value)
+                pass_fiber: Fiber[Any, Any] | None = None
+                if passed and (rest := passes.offer_all_unsafe(passed)):
+                    pass_fiber = yield passes.offer_all(rest).fork()
+                if failed and (rest := fails.offer_all_unsafe(failed)):
+                    yield fails.offer_all(rest)
+                if pass_fiber is not None:
+                    yield pass_fiber.join()
+
+        def fail_both(cause: Cause[Any]) -> AnyEffect:
+            passes.fail_cause_unsafe(cause)
+            fails.fail_cause_unsafe(cause)
+            return _VOID
+
+        yield fork_in(_Gen(feed).on_error(fail_both), scope)
+        return passes, fails
+
+    return _Gen(body)
+
+
+def _as_streams(queues: tuple[Queue[Any, Any], Queue[Any, Any]]) -> tuple[AnyStream_, AnyStream_]:
+    passes, fails = queues
+    return from_queue_shutdown_on_end(passes), from_queue_shutdown_on_end(fails)
+
+
+def partition(
+    self: AnyStream, f: Callable[[Any], Result[Any, Any]], capacity: Capacity
+) -> AnyEffect:
+    return partition_queue(self, f, capacity).map(_as_streams)
+
+
+def partition_effect(
+    self: AnyStream,
+    f: Callable[[Any], Effect[Result[Any, Any], Any, Any]],
+    capacity: Capacity,
+    concurrency: Concurrency,
+) -> AnyEffect:
+    mapped = as_stream(self).map_effect(f, concurrency=concurrency)
+    return partition_queue(mapped, _identity, capacity).map(_as_streams)
+
+
+def _identity[T](value: T) -> T:
+    return value
+
+
+# --- broadcasts ------------------------------------------------------------------
+
+
+def broadcast(
+    self: AnyStream, capacity: Capacity, strategy: Strategy, replay: int | None
+) -> AnyEffect:
+    from pyfect.stream._sources import from_pubsub_take
+
+    takes: AnyEffect = (
+        self._channel.to_pubsub_take(capacity=capacity, replay=replay)
+        if capacity == "unbounded"
+        else self._channel.to_pubsub_take(capacity=capacity, strategy=strategy, replay=replay)
+    )
+    return takes.map(from_pubsub_take)
+
+
+def broadcast_n(
+    self: AnyStream, n: int, capacity: Capacity, strategy: Strategy, replay: int | None
+) -> AnyEffect:
+    def body() -> Generator[AnyEffect, Any, tuple[AnyStream_, ...]]:
+        pubsub = yield make_pubsub(capacity, strategy, replay)
+        parent = yield Scope()
+        streams: list[AnyStream_] = []
+        for _ in range(max(0, n)):
+            scope = parent.fork_unsafe()
+            subscription = yield pubsub.subscribe().pipe(provide_service(Scope, scope))
+            reader: Any = channel.from_effect_take(subscription.take()).on_exit(scope.close)
+            streams.append(Stream(reader))
+        yield fork_scoped(self._channel.run_for_each(pubsub.publish).on_exit(pubsub.end))
+        return tuple(streams)
+
+    return _Gen(body)
+
+
+def share(
+    self: AnyStream,
+    capacity: Capacity,
+    strategy: Strategy,
+    replay: int | None,
+    idle_time_to_live: Duration | None,
+) -> AnyEffect:
+    from pyfect.stream._constructors import unwrap
+
+    def reader(ref: RcRef[AnyStream_, Any]) -> AnyStream_:
+        return unwrap(ref.get())
+
+    acquire = broadcast(self, capacity, strategy, replay)
+    return RcRef.make(acquire, idle_time_to_live=idle_time_to_live).map(reader)