pyfect-dev 0.1.0__py3-none-any.whl

pyfect/channel/_concurrent_map.py

@@ -0,0 +1,118 @@
+"""``map_effect`` with ``concurrency`` above 1 (Effect's
+``mapEffectConcurrent``).
+
+A producer fiber pulls upstream and forks ``f(item)`` for each item, at
+most ``concurrency`` at a time; results go through a rendezvous queue to
+the channel's pull. In order, the producer queues each fiber's ``join``
+and a consumer fiber hands the results on in that order; unordered, each
+fiber offers its own result. Every fiber lives in the channel's forked
+scope, so ending the channel interrupts what is still running.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pyfect._concurrency import Concurrency
+from pyfect._core import Effect, _FailCause, _Suspend
+from pyfect._fiber import Fiber
+from pyfect.cause import Cause
+from pyfect.channel._base import AnyChannel, AnyPull
+from pyfect.channel._channel import Channel
+from pyfect.channel._combinators import UNBOUNDED, permits_of
+from pyfect.channel._constructors import bracket
+from pyfect.exit import Exit, Failure
+from pyfect.queue import Queue
+from pyfect.scope import CloseableScope, fork_in
+from pyfect.semaphore import Semaphore
+
+
+def map_effect_concurrent(
+    self: AnyChannel,
+    f: Callable[[Any], Effect[Any, Any, Any]],
+    concurrency: Concurrency,
+    *,
+    unordered: bool,
+) -> Channel[Any, Any, Any, Any, Any, Any, Any]:
+    n = permits_of(concurrency)
+
+    def build(
+        upstream: AnyPull, scope: CloseableScope, forked: CloseableScope
+    ) -> Effect[AnyPull, Any, Any]:
+        def with_pull(pull: AnyPull) -> Effect[AnyPull, Any, Any]:
+            results: Queue[Any, Any] = Queue(0)
+            start = unordered_producer if unordered else ordered_producer
+            return (
+                forked.add_finalizer(lambda _: results.shutdown())
+                .and_then(start(pull, results))
+                .as_(results.take())
+            )
+
+        def unordered_producer(pull: AnyPull, results: Queue[Any, Any]) -> Effect[Any]:
+            permits = Semaphore(n)
+            release = permits.release(1)
+
+            def run(item: Any) -> Effect[Any]:
+                handled = (
+                    _Suspend(lambda: f(item))
+                    .match_cause_effect(on_failure=results.fail_cause, on_success=results.offer)
+                    .and_then(release)
+                )
+                return fork_in(handled, forked, start_immediately=True).as_void()
+
+            loop = permits.take(1).and_then(pull).flat_map(run).forever(disable_yield=True)
+            stopped = loop.catch_cause(
+                lambda cause: permits.with_permits(results.fail_cause(cause), n - 1)
+            )
+            return fork_in(stopped, forked)
+
+        def ordered_producer(pull: AnyPull, results: Queue[Any, Any]) -> Effect[Any]:
+            # Room for n - 2 joins: one more waits in the offer after its
+            # fiber starts, and the consumer holds the one it is joining.
+            joins: Queue[Effect[Any, Any, Any], Any] = Queue(
+                None if n == UNBOUNDED else max(0, n - 2)
+            )
+            failed: list[Cause[Any]] = []
+
+            def on_exit(ex: Exit[Any, Any]) -> None:
+                if isinstance(ex, Failure):
+                    failed.append(ex.cause)
+                    results.fail_cause_unsafe(ex.cause)
+
+            def run(item: Any) -> Effect[Any, Any, Any]:
+                if failed:
+                    return _FailCause(failed[0])
+
+                def started(fiber: Fiber[Any, Any]) -> Effect[Any]:
+                    fiber.add_observer_unsafe(on_exit)
+                    return joins.offer(fiber.join())
+
+                return fork_in(_Suspend(lambda: f(item)), forked, start_immediately=True).flat_map(
+                    started
+                )
+
+            consumer = (
+                joins.take()
+                .flatten()
+                .flat_map(results.offer)
+                .forever(disable_yield=True)
+                .catch_cause(results.fail_cause)
+            )
+            producer = (
+                pull.flat_map(run)
+                .forever(disable_yield=True)
+                .catch_cause(
+                    lambda cause: joins.offer(_FailCause(cause)).and_then(joins.fail_cause(cause))
+                )
+            )
+            return (
+                forked.add_finalizer(lambda _: joins.shutdown())
+                .and_then(fork_in(consumer, forked))
+                .and_then(fork_in(producer, forked))
+            )
+
+        return self._transform(upstream, scope).flat_map(with_pull)
+
+    return bracket(build)

pyfect/channel/_constructors.py

@@ -0,0 +1,349 @@
+"""Channel constructors: single values, failures, effects, iterables,
+deferred and resource-managed channels."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator, Iterable, Iterator
+from typing import Any, Never, overload
+
+from pyfect._core import Effect, _Callback, _FailCause, _Succeed, _Suspend, _Sync
+from pyfect._effect_args import require_effect
+from pyfect.cause import Cause
+from pyfect.cause import die as die_cause
+from pyfect.cause import fail as fail_cause_of
+from pyfect.channel._base import AnyChannel, AnyPull, end_with
+from pyfect.channel._channel import Channel, from_transform
+from pyfect.channel._loop import ChunkPull, IteratorPull
+from pyfect.channel._run import ENDED
+from pyfect.effect import provide_service
+from pyfect.errors import Done
+from pyfect.exit import Exit
+from pyfect.option import Option, Some
+from pyfect.pull import done_exit_from_cause
+from pyfect.scope import CloseableScope, Scope
+from pyfect.scope import acquire_release as _acquire_release
+from pyfect.take import Take
+from pyfect.take import to_pull as take_to_pull
+
+DEFAULT_CHUNK_SIZE = 4096
+"""How many items ``from_iterable_array`` puts in a tuple by default."""
+
+type _AnyChannel = Channel[Any, Any, Any, Any, Any, Any, Any]
+
+
+# --- values and failures -------------------------------------------------------
+
+
+def from_effect[A, E = Never, R = Never](
+    eff: Effect[A, E, R],
+) -> Channel[A, E, None, object, object, object, R]:
+    """Write what ``eff`` succeeds with, then end."""
+    require_effect(eff, "eff")
+
+    def make() -> AnyPull:
+        ran = False
+
+        def pull() -> AnyPull:
+            nonlocal ran
+            if ran:
+                return ENDED
+            ran = True
+            return eff
+
+        return _Suspend(pull)
+
+    return Channel(lambda _upstream, _scope: _Sync(make))
+
+
+def from_effect_done[A, E = Never, R = Never](
+    eff: Effect[A, E, R],
+) -> Channel[Never, E, A, object, object, object, R]:
+    """Write nothing and end with what ``eff`` succeeds with."""
+    require_effect(eff, "eff")
+    pull = eff.flat_map(end_with)
+    return Channel(lambda _upstream, _scope: _Succeed(pull))
+
+
+def from_effect_drain[A, E = Never, R = Never](
+    eff: Effect[A, E, R],
+) -> Channel[Never, E, None, object, object, object, R]:
+    """Run ``eff`` when the channel starts, write nothing, and end."""
+    require_effect(eff, "eff")
+    drained: Channel[Never, E, None, object, object, object, R] = Channel(
+        lambda _upstream, _scope: eff.as_(ENDED)
+    )
+    return drained
+
+
+def from_effect_take[A, L = None, EE = Never, RR = Never](
+    eff: Effect[Take[A, EE, L], EE, RR],
+) -> Channel[tuple[A, ...], EE, L, object, object, object, RR]:
+    """Pull by running ``eff`` and replaying the ``Take`` it succeeds with."""
+    require_effect(eff, "eff")
+    pull = eff.flat_map(take_to_pull)
+    return Channel(lambda _upstream, _scope: _Succeed(pull))
+
+
+def succeed[A](value: A) -> Channel[A]:
+    """Write ``value``, then end."""
+    return from_effect(_Succeed(value))
+
+
+def sync[A](thunk: Callable[[], A]) -> Channel[A]:
+    """Write ``thunk()``, computed when the channel runs, then end."""
+    return from_effect(_Sync(thunk))
+
+
+def end[L](value: L) -> Channel[Never, Never, L]:
+    """Write nothing and end with ``value``."""
+    pull = end_with(value)
+    return Channel(lambda _upstream, _scope: _Succeed(pull))
+
+
+def end_sync[L](thunk: Callable[[], L]) -> Channel[Never, Never, L]:
+    """Write nothing and end with ``thunk()``, computed when the channel
+    runs."""
+    return Channel(lambda _upstream, _scope: _Sync(lambda: end_with(thunk())))
+
+
+empty: Channel[Never] = end(None)
+"""Write nothing and end."""
+
+never: Channel[Never, Never, Never] = Channel(
+    lambda _upstream, _scope: _Succeed(_Callback(lambda _resume: None))
+)
+"""Never write and never end. Can be interrupted."""
+
+
+def fail[E](error: E) -> Channel[Never, E, Never]:
+    """Fail with ``error``."""
+    return fail_cause(fail_cause_of(error))
+
+
+def fail_sync[E](thunk: Callable[[], E]) -> Channel[Never, E, Never]:
+    """Fail with ``thunk()``, computed when the channel runs."""
+    return Channel(lambda _upstream, _scope: _Sync(lambda: _FailCause(fail_cause_of(thunk()))))
+
+
+def fail_cause[E](cause: Cause[E]) -> Channel[Never, E, Never]:
+    """Fail with ``cause``."""
+    pull = _FailCause(cause)
+    return Channel(lambda _upstream, _scope: _Succeed(pull))
+
+
+def fail_cause_sync[E](thunk: Callable[[], Cause[E]]) -> Channel[Never, E, Never]:
+    """Fail with ``thunk()``, computed when the channel runs."""
+    return Channel(lambda _upstream, _scope: _Sync(lambda: _FailCause(thunk())))
+
+
+def die(defect: BaseException) -> Channel[Never, Never, Never]:
+    """Fail with the defect ``defect``."""
+    return fail_cause(die_cause(defect))
+
+
+# --- iterables -----------------------------------------------------------------
+
+
+@overload
+def from_iterator[A, L](  # pyright: ignore[reportOverlappingOverload]
+    make: Callable[[], Generator[A, Any, L]],
+) -> Channel[A, Never, L]: ...
+@overload
+def from_iterator[A](make: Callable[[], Iterator[A]]) -> Channel[A]: ...
+def from_iterator(make: Callable[[], Iterator[Any]]) -> Channel[Any, Never, Any]:
+    """Write the items of the iterator ``make()`` returns each run. A
+    generator's return value is what the channel ends with; an exception
+    from the iterator is a defect."""
+    return Channel(lambda _upstream, _scope: _Sync(lambda: IteratorPull(make())))
+
+
+@overload
+def from_iterable[A, L](  # pyright: ignore[reportOverlappingOverload]
+    iterable: Generator[A, Any, L],
+) -> Channel[A, Never, L]: ...
+@overload
+def from_iterable[A](iterable: Iterable[A]) -> Channel[A]: ...
+def from_iterable(iterable: Iterable[Any]) -> Channel[Any, Never, Any]:
+    """Write the items of ``iterable``, iterating it anew each run (a
+    generator or iterator can only be read once)."""
+    return from_iterator(lambda: iter(iterable))
+
+
+@overload
+def from_iterator_array[A, L](  # pyright: ignore[reportOverlappingOverload]
+    make: Callable[[], Generator[A, Any, L]], chunk_size: int = DEFAULT_CHUNK_SIZE
+) -> Channel[tuple[A, ...], Never, L]: ...
+@overload
+def from_iterator_array[A](
+    make: Callable[[], Iterator[A]], chunk_size: int = DEFAULT_CHUNK_SIZE
+) -> Channel[tuple[A, ...]]: ...
+def from_iterator_array(
+    make: Callable[[], Iterator[Any]], chunk_size: int = DEFAULT_CHUNK_SIZE
+) -> Channel[tuple[Any, ...], Never, Any]:
+    """``from_iterator``, writing the items as non-empty tuples of up to
+    ``chunk_size`` (at least 1)."""
+    size = max(1, chunk_size)
+    return Channel(lambda _upstream, _scope: _Sync(lambda: ChunkPull(make(), size)))
+
+
+@overload
+def from_iterable_array[A, L](  # pyright: ignore[reportOverlappingOverload]
+    iterable: Generator[A, Any, L], chunk_size: int = DEFAULT_CHUNK_SIZE
+) -> Channel[tuple[A, ...], Never, L]: ...
+@overload
+def from_iterable_array[A](
+    iterable: Iterable[A], chunk_size: int = DEFAULT_CHUNK_SIZE
+) -> Channel[tuple[A, ...]]: ...
+def from_iterable_array(
+    iterable: Iterable[Any], chunk_size: int = DEFAULT_CHUNK_SIZE
+) -> Channel[tuple[Any, ...], Never, Any]:
+    """``from_iterable``, writing the items as non-empty tuples of up to
+    ``chunk_size`` (at least 1)."""
+    return from_iterator_array(lambda: iter(iterable), chunk_size)
+
+
+# --- deferred channels ---------------------------------------------------------
+
+
+def suspend[O, E, D, I, IE, ID, R](
+    thunk: Callable[[], Channel[O, E, D, I, IE, ID, R]],
+) -> Channel[O, E, D, I, IE, ID, R]:
+    """The channel ``thunk()`` returns, built each time it runs."""
+    return Channel(lambda upstream, scope: thunk()._transform(upstream, scope))
+
+
+@overload
+def unwrap[O, D, I, IE, ID, EE = Never, RR = Never](
+    eff: Effect[Channel[O, EE, D, I, IE, ID, RR], EE, Scope],
+) -> Channel[O, EE, D, I, IE, ID, RR]: ...
+@overload
+def unwrap[O, D, I, IE, ID, EE = Never, RR = Never](
+    eff: Effect[Channel[O, EE, D, I, IE, ID, RR], EE, Scope | RR],
+) -> Channel[O, EE, D, I, IE, ID, RR]: ...
+def unwrap(eff: Effect[_AnyChannel, Any, Any]) -> _AnyChannel:
+    """The channel ``eff`` succeeds with, built on the first pull. ``eff``
+    runs with the channel's ``Scope``, so its resources live as long as
+    the channel's."""
+    require_effect(eff, "eff")
+    return unwrap_effect(eff)
+
+
+def unwrap_effect(eff: Effect[AnyChannel, Any, Any]) -> _AnyChannel:
+    def transform(upstream: AnyPull, scope: CloseableScope) -> Effect[AnyPull]:
+        pull: AnyPull | None = None
+
+        def keep(built: AnyPull) -> AnyPull:
+            nonlocal pull
+            pull = built
+            return built
+
+        build = (
+            eff.pipe(provide_service(Scope, scope))
+            .flat_map(lambda channel: channel._transform(upstream, scope))
+            .flat_map(keep)
+        )
+        return _Succeed(_Suspend(lambda: build if pull is None else pull))
+
+    return Channel(transform)
+
+
+def identity[A, E = Never, D = None]() -> Channel[A, E, D, A, E, D]:
+    """Write what upstream writes; fail and end as it does."""
+    return Channel(lambda upstream, _scope: _Succeed(upstream))
+
+
+# --- resources -----------------------------------------------------------------
+
+
+@overload
+def from_transform_bracket[A, InElem, InErr, InDone, L = None, EE = Never, RR = Never](
+    f: Callable[
+        [Effect[InElem, InErr | Done[InDone]], CloseableScope, CloseableScope],
+        Effect[Effect[A, Done[L], RR], EE, RR],
+    ],
+) -> Channel[A, EE, L, InElem, InErr, InDone, RR]: ...
+@overload
+def from_transform_bracket[A, InElem, InErr, InDone, L = None, EE = Never, RR = Never](
+    f: Callable[
+        [Effect[InElem, InErr | Done[InDone]], CloseableScope, CloseableScope],
+        Effect[Effect[A, EE | Done[L], RR], EE, RR],
+    ],
+) -> Channel[A, EE, L, InElem, InErr, InDone, RR]: ...
+@overload
+def from_transform_bracket[A, InElem, InDone, L = None, EE = Never, RR = Never](
+    f: Callable[
+        [Effect[InElem, Done[InDone]], CloseableScope, CloseableScope],
+        Effect[Effect[A, Done[L], RR], EE, RR],
+    ],
+) -> Channel[A, EE, L, InElem, Never, InDone, RR]: ...
+@overload
+def from_transform_bracket[A, InElem, InDone, L = None, EE = Never, RR = Never](
+    f: Callable[
+        [Effect[InElem, Done[InDone]], CloseableScope, CloseableScope],
+        Effect[Effect[A, EE | Done[L], RR], EE, RR],
+    ],
+) -> Channel[A, EE, L, InElem, Never, InDone, RR]: ...
+def from_transform_bracket(
+    f: Callable[[Any, CloseableScope, CloseableScope], Effect[Any, Any, Any]],
+) -> Any:
+    """``from_transform`` with a third argument: a child of the channel's
+    scope, closed as soon as the channel fails or ends (with the end's
+    leftover as a success), so resources can go before the run ends."""
+    return bracket(f)
+
+
+def bracket(
+    f: Callable[[AnyPull, CloseableScope, CloseableScope], Effect[AnyPull, Any, Any]],
+) -> _AnyChannel:
+
+    def transform(upstream: AnyPull, scope: CloseableScope) -> Effect[AnyPull, Any, Any]:
+        forked = scope.fork_unsafe()
+
+        def close(cause: Cause[Any]) -> Effect[None]:
+            return forked.close(done_exit_from_cause(cause))
+
+        return f(upstream, scope, forked).on_error(close).map(lambda pull: pull.on_error(close))
+
+    channel: _AnyChannel = from_transform(transform)
+    return channel
+
+
+def acquire_use_release[A, O, D, I, IE, ID, EE = Never, RR = Never](
+    acquire: Effect[A, EE, RR],
+    use: Callable[[A], Channel[O, EE, D, I, IE, ID, RR]],
+    release: Callable[[A, Exit[D, EE]], Effect[object, Never, RR]],
+) -> Channel[O, EE, D, I, IE, ID, RR]:
+    """Acquire uninterruptibly, write ``use(resource)``'s items, and
+    release with its exit as soon as it fails or ends (or the run ends)."""
+    require_effect(acquire, "acquire")
+
+    def build(
+        upstream: AnyPull, scope: CloseableScope, forked: CloseableScope
+    ) -> Effect[AnyPull, Any, Any]:
+        resource: Option[A] = None
+
+        def keep(value: A) -> A:
+            nonlocal resource
+            resource = Some(value)
+            return value
+
+        def finalizer(ex: Exit[Any, Any]) -> Effect[object, Never, Any]:
+            return _Succeed(None) if resource is None else release(resource.value, ex)
+
+        return (
+            forked.add_finalizer(finalizer)
+            .and_then(acquire.map(keep).uninterruptible())
+            .flat_map(lambda value: use(value)._transform(upstream, scope))
+        )
+
+    return bracket(build)
+
+
+def acquire_release[A, E = Never, RR = Never](
+    acquire: Effect[A, E, RR],
+    release: Callable[[A, Exit[Any, Any]], Effect[object, Never, RR]],
+) -> Channel[A, E, None, object, object, object, RR]:
+    """Write the acquired resource, then end; ``release`` runs when the
+    channel's scope closes."""
+    return unwrap_effect(_acquire_release(acquire, release).map(succeed))

pyfect/channel/_context.py

@@ -0,0 +1,232 @@
+"""Services for channels: the curried providers (used with ``.pipe``, since
+they remove what they provide from ``Env``), ``scoped``, and the context
+updates behind ``update_service`` and ``with_span``.
+
+A provided service reaches both the build of the channel's pull and every
+pull, so resources acquired while building and effects run per item see
+the same services.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Never, overload
+
+from pyfect._core import Effect, _Locally, _WithFiber
+from pyfect._effect_args import require_effect
+from pyfect._layer_core import require_layer
+from pyfect.channel._base import AnyChannel, AnyPull, ChannelBase
+from pyfect.channel._channel import Channel, from_transform
+from pyfect.channel._constructors import bracket
+from pyfect.context import Context, TagLike, tag_class
+from pyfect.layer import Layer, MemoMap
+from pyfect.scope import CloseableScope, Scope
+
+type Channel_ = Channel[Any, Any, Any, Any, Any, Any, Any]
+type Update = Callable[[Context[Any]], Context[Any]]
+
+
+def _locally(self: AnyChannel, update: Update) -> Channel_:
+    def provided(pull: AnyPull) -> AnyPull:
+        return _Locally(pull, update)
+
+    def transform(upstream: AnyPull, scope: CloseableScope) -> Effect[AnyPull]:
+        built: Effect[AnyPull] = _Locally(self._transform(upstream, scope), update)
+        return built.map(provided)
+
+    return from_transform(transform)
+
+
+def update_context_with(self: AnyChannel, f: Update) -> Channel_:
+    """The channel with the services ``f(context)``, where ``context`` is
+    the services the channel is built with."""
+
+    def transform(upstream: AnyPull, scope: CloseableScope) -> Effect[AnyPull]:
+        def build(fiber: Any) -> Effect[AnyPull]:
+            provided = f(fiber._context)
+            return _locally(self, lambda current: current.merge(provided))._transform(
+                upstream, scope
+            )
+
+        return _WithFiber(build)
+
+    return from_transform(transform)
+
+
+class _ProvideService[T]:
+    __slots__ = ("service", "tag")
+
+    def __init__(self, tag: type[Any], service: object) -> None:
+        self.tag = tag
+        self.service = service
+
+    @overload
+    def __call__[O, E, D, I, IE, ID](
+        self, channel: ChannelBase[O, E, D, I, IE, ID, T]
+    ) -> Channel[O, E, D, I, IE, ID]: ...
+    @overload
+    def __call__[O, E, D, I, IE, ID, R](
+        self, channel: ChannelBase[O, E, D, I, IE, ID, T | R]
+    ) -> Channel[O, E, D, I, IE, ID, R]: ...
+    def __call__(self, channel: AnyChannel) -> Channel_:
+        tag, service = self.tag, self.service
+        return _locally(channel, lambda ctx: ctx.add(tag, service))
+
+
+def provide_service[S, T](tag: TagLike[S, T], service: S) -> _ProvideService[T]:
+    """Provide one service to a channel and remove it from ``Env``::
+
+    channel.pipe(provide_service(Database, InMemoryDb()))
+    """
+    return _ProvideService(tag_class(tag), service)
+
+
+class _ProvideServiceEffect[T, E2, R2]:
+    __slots__ = ("acquire", "tag")
+
+    def __init__(self, tag: type[Any], acquire: Effect[Any, E2, R2]) -> None:
+        self.tag = tag
+        self.acquire = acquire
+
+    @overload
+    def __call__[O, E, D, I, IE, ID](
+        self, channel: ChannelBase[O, E, D, I, IE, ID, T]
+    ) -> Channel[O, E | E2, D, I, IE, ID, R2]: ...
+    @overload
+    def __call__[O, E, D, I, IE, ID, R](
+        self, channel: ChannelBase[O, E, D, I, IE, ID, T | R]
+    ) -> Channel[O, E | E2, D, I, IE, ID, R | R2]: ...
+    def __call__(self, channel: AnyChannel) -> Channel_:
+        tag, acquire = self.tag, self.acquire
+
+        def transform(upstream: AnyPull, scope: CloseableScope) -> Effect[AnyPull, Any, Any]:
+            return acquire.flat_map(
+                lambda service: _locally(channel, lambda ctx: ctx.add(tag, service))._transform(
+                    upstream, scope
+                )
+            )
+
+        return from_transform(transform)
+
+
+def provide_service_effect[S, T, E2 = Never, R2 = Never](
+    tag: TagLike[S, T], acquire: Effect[S, E2, R2]
+) -> _ProvideServiceEffect[T, E2, R2]:
+    """Run ``acquire`` each time the channel runs and provide its value as
+    ``tag``'s service, removing ``tag`` from ``Env``."""
+    require_effect(acquire, "acquire")
+    return _ProvideServiceEffect(tag_class(tag), acquire)
+
+
+class _ProvideContext[RO]:
+    __slots__ = ("ctx",)
+
+    def __init__(self, ctx: Context[RO]) -> None:
+        self.ctx = ctx
+
+    @overload
+    def __call__[O, E, D, I, IE, ID](
+        self, channel: ChannelBase[O, E, D, I, IE, ID, RO]
+    ) -> Channel[O, E, D, I, IE, ID]: ...
+    @overload
+    def __call__[O, E, D, I, IE, ID, R](
+        self, channel: ChannelBase[O, E, D, I, IE, ID, RO | R]
+    ) -> Channel[O, E, D, I, IE, ID, R]: ...
+    def __call__(self, channel: AnyChannel) -> Channel_:
+        ctx = self.ctx
+        return _locally(channel, lambda current: current.merge(ctx))
+
+
+def provide_context[RO](ctx: Context[RO]) -> _ProvideContext[RO]:
+    """Provide every service of ``ctx`` to a channel and remove them from
+    ``Env``."""
+    return _ProvideContext(ctx)
+
+
+class _ProvideLayer[RO, E2, RI]:
+    __slots__ = ("layer", "local")
+
+    def __init__(self, layer: Layer[RO, E2, RI], local: bool) -> None:
+        self.layer = layer
+        self.local = local
+
+    @overload
+    def __call__[O, E, D, I, IE, ID](
+        self, channel: ChannelBase[O, E, D, I, IE, ID, RO]
+    ) -> Channel[O, E | E2, D, I, IE, ID, RI]: ...
+    @overload
+    def __call__[O, E, D, I, IE, ID, R](
+        self, channel: ChannelBase[O, E, D, I, IE, ID, RO | R]
+    ) -> Channel[O, E | E2, D, I, IE, ID, R | RI]: ...
+    def __call__(self, channel: AnyChannel) -> Channel_:
+        layer, local = self.layer, self.local
+
+        def transform(upstream: AnyPull, scope: CloseableScope) -> Effect[AnyPull, Any, Any]:
+            built = (
+                layer.build_with_memo_map(MemoMap(), scope)
+                if local
+                else layer.build_with_scope(scope)
+            )
+            return built.flat_map(
+                lambda ctx: _locally(channel, lambda current: current.merge(ctx))._transform(
+                    upstream, scope
+                )
+            )
+
+        return from_transform(transform)
+
+
+@overload
+def provide[RO](source: Context[RO], /) -> _ProvideContext[RO]: ...
+@overload
+def provide[RO, E2 = Never, RI = Never](
+    source: Layer[RO, E2, RI], /, *, local: bool = False
+) -> _ProvideLayer[RO, E2, RI]: ...
+def provide(
+    source: Layer[Any, Any, Any] | Context[Any], /, *, local: bool = False
+) -> _ProvideLayer[Any, Any, Any] | _ProvideContext[Any]:
+    """Provide a context's services, or build a layer each time the channel
+    runs (its resources released when the run ends) and provide what it
+    builds. Layers an enclosing ``provide`` built are reused unless
+    ``local``."""
+    if isinstance(source, Context):
+        return _ProvideContext(source)
+    require_layer(source, "source", "a Layer or a Context")
+    return _ProvideLayer(source, local)
+
+
+class _UpdateContext[R2, RO]:
+    __slots__ = ("f",)
+
+    def __init__(self, f: Callable[[Context[R2]], Context[RO]]) -> None:
+        self.f = f
+
+    def __call__[O, E, D, I, IE, ID](
+        self, channel: ChannelBase[O, E, D, I, IE, ID, RO]
+    ) -> Channel[O, E, D, I, IE, ID, R2]:
+        return update_context_with(channel, self.f)
+
+
+def update_context[R2, RO](f: Callable[[Context[R2]], Context[RO]]) -> _UpdateContext[R2, RO]:
+    """Build the channel with the services ``f(context)`` instead of
+    ``context``, so it needs ``R2`` instead of what it needed."""
+    return _UpdateContext(f)
+
+
+@overload
+def scoped[O, E, D, I, IE, ID](
+    channel: ChannelBase[O, E, D, I, IE, ID, Scope],
+) -> Channel[O, E, D, I, IE, ID]: ...
+@overload
+def scoped[O, E, D, I, IE, ID, R](
+    channel: ChannelBase[O, E, D, I, IE, ID, Scope | R],
+) -> Channel[O, E, D, I, IE, ID, R]: ...
+def scoped(channel: AnyChannel) -> Channel_:
+    """Give the channel a ``Scope`` of its own, closed as soon as it fails
+    or ends (or its run ends), and remove ``Scope`` from ``Env``."""
+
+    def build(upstream: AnyPull, scope: CloseableScope, forked: CloseableScope) -> Effect[AnyPull]:
+        return _locally(channel, lambda ctx: ctx.add(Scope, forked))._transform(upstream, scope)
+
+    return bracket(build)