peffect 0.1.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- peffect/__init__.py +223 -0
- peffect/cause.py +177 -0
- peffect/clock.py +130 -0
- peffect/console.py +99 -0
- peffect/context.py +258 -0
- peffect/core.py +1273 -0
- peffect/deferred.py +99 -0
- peffect/duration.py +497 -0
- peffect/fiber.py +1082 -0
- peffect/latch.py +120 -0
- peffect/layer.py +789 -0
- peffect/logger.py +166 -0
- peffect/managed_runtime.py +325 -0
- peffect/option.py +50 -0
- peffect/pull.py +116 -0
- peffect/py.typed +0 -0
- peffect/queue.py +670 -0
- peffect/ref.py +133 -0
- peffect/resources.py +113 -0
- peffect/scheduler.py +55 -0
- peffect/scope.py +394 -0
- peffect/semaphore.py +255 -0
- peffect/synchronized_ref.py +183 -0
- peffect/testing/__init__.py +7 -0
- peffect/testing/_clock.py +453 -0
- peffect/testing/_console.py +105 -0
- peffect/timeout.py +67 -0
- peffect-0.1.2.dist-info/METADATA +6 -0
- peffect-0.1.2.dist-info/RECORD +30 -0
- peffect-0.1.2.dist-info/WHEEL +4 -0
peffect/fiber.py
ADDED
|
@@ -0,0 +1,1082 @@
|
|
|
1
|
+
"""Fiber: one running effect. Owns the stack, the interrupt state, and the children it forked.
|
|
2
|
+
|
|
3
|
+
The run loop is `evaluate`: evaluate a node, get the next node, repeat. It stops when a node
|
|
4
|
+
returns None, which means one of three things: the fiber parked on an Async, it queued its next
|
|
5
|
+
step on its dispatcher (YieldNow or the op budget), or it finished. Resuming a park, interrupting a
|
|
6
|
+
fiber that is not running, and starting a root all call `evaluate` at once, inside the caller.
|
|
7
|
+
Effect v4: internal/effect.ts:567-803 (FiberImpl), Scheduler.ts (MixedScheduler).
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import asyncio
|
|
13
|
+
import itertools
|
|
14
|
+
import math
|
|
15
|
+
import sys
|
|
16
|
+
from collections.abc import Callable, Iterable, Iterator
|
|
17
|
+
from typing import Any, Final, Generic, Literal, Never, Protocol, TypeVar, final
|
|
18
|
+
|
|
19
|
+
from peffect.cause import Cause, Interrupt
|
|
20
|
+
from peffect.core import (
|
|
21
|
+
ANY,
|
|
22
|
+
EMPTY_CONTEXT,
|
|
23
|
+
ERR,
|
|
24
|
+
OK,
|
|
25
|
+
UNIT,
|
|
26
|
+
AnyEffect,
|
|
27
|
+
Async,
|
|
28
|
+
ContextMap,
|
|
29
|
+
Effect,
|
|
30
|
+
Exit,
|
|
31
|
+
Failure,
|
|
32
|
+
Frame,
|
|
33
|
+
OnExit,
|
|
34
|
+
Park,
|
|
35
|
+
Resume,
|
|
36
|
+
Success,
|
|
37
|
+
Suspend,
|
|
38
|
+
Sync,
|
|
39
|
+
Then,
|
|
40
|
+
WithFiber,
|
|
41
|
+
uninterruptible,
|
|
42
|
+
)
|
|
43
|
+
|
|
44
|
+
A_co = TypeVar("A_co", covariant=True)
|
|
45
|
+
E_co = TypeVar("E_co", covariant=True)
|
|
46
|
+
|
|
47
|
+
_ids = itertools.count(1)
|
|
48
|
+
|
|
49
|
+
type Observer = Callable[[Exit[Any, Any]], None]
|
|
50
|
+
type Task = Callable[[], None]
|
|
51
|
+
|
|
52
|
+
# The References live in scheduler.py; the kernel reads their keys (Scheduler.ts:82, :294, :321).
|
|
53
|
+
_SCHEDULER_KEY = "effect/Scheduler"
|
|
54
|
+
_MAX_OPS_KEY = "effect/Scheduler/MaxOpsBeforeYield"
|
|
55
|
+
_PREVENT_YIELD_KEY = "effect/Scheduler/PreventSchedulerYield"
|
|
56
|
+
_MAX_OPS_DEFAULT = 2048
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
# ================================================================================================
|
|
60
|
+
# Scheduler (Effect v4 Scheduler.ts)
|
|
61
|
+
# ================================================================================================
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class SchedulerDispatcher(Protocol):
|
|
65
|
+
"""Runs queued tasks later, lowest priority first, FIFO within one (Scheduler.ts:60-63)."""
|
|
66
|
+
|
|
67
|
+
def schedule_task(self, task: Task, priority: int) -> None: ...
|
|
68
|
+
def flush(self) -> None: ...
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
class SchedulerService(Protocol):
|
|
72
|
+
"""What the Scheduler Reference provides (Scheduler.ts:33-48). ``should_yield`` is asked
|
|
73
|
+
once per op unless PreventSchedulerYield is set; each fiber makes one dispatcher, lazily."""
|
|
74
|
+
|
|
75
|
+
@property
|
|
76
|
+
def execution_mode(self) -> Literal["sync", "async"]: ...
|
|
77
|
+
def should_yield(self, fiber: Fiber[Any, Any]) -> bool: ...
|
|
78
|
+
def make_dispatcher(self) -> SchedulerDispatcher: ...
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def _call_soon(task: Task) -> Task:
|
|
82
|
+
return asyncio.get_running_loop().call_soon(task).cancel
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
@final
|
|
86
|
+
class MixedScheduler:
|
|
87
|
+
"""The default scheduler: yield after MaxOpsBeforeYield ops, run each dispatcher's queue as
|
|
88
|
+
one batch on the next loop turn (Scheduler.ts:176-215). ``set_immediate(f)`` arms a batch and
|
|
89
|
+
returns its canceller. Platform adaptation: asyncio has no microtask queue, so "sync" mode
|
|
90
|
+
also arms with ``loop.call_soon``; the mode is only reported."""
|
|
91
|
+
|
|
92
|
+
__slots__ = ("execution_mode", "set_immediate")
|
|
93
|
+
|
|
94
|
+
def __init__(
|
|
95
|
+
self,
|
|
96
|
+
execution_mode: Literal["sync", "async"] = "async",
|
|
97
|
+
set_immediate: Callable[[Task], Task] | None = None,
|
|
98
|
+
) -> None:
|
|
99
|
+
self.execution_mode: Literal["sync", "async"] = execution_mode
|
|
100
|
+
self.set_immediate = set_immediate or _call_soon
|
|
101
|
+
|
|
102
|
+
def should_yield(self, fiber: Fiber[Any, Any]) -> bool:
|
|
103
|
+
return fiber.current_op_count >= fiber.context.get(_MAX_OPS_KEY, _MAX_OPS_DEFAULT)
|
|
104
|
+
|
|
105
|
+
def make_dispatcher(self) -> SchedulerDispatcher:
|
|
106
|
+
return _MixedDispatcher(self.set_immediate)
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
@final
|
|
110
|
+
class _MixedDispatcher:
|
|
111
|
+
"""MixedSchedulerDispatcher (Scheduler.ts:119-145, :217-271): priority buckets, one armed
|
|
112
|
+
batch at a time. A task scheduled while a batch runs waits for the next batch."""
|
|
113
|
+
|
|
114
|
+
__slots__ = ("_buckets", "_running", "_set_immediate")
|
|
115
|
+
|
|
116
|
+
def __init__(self, set_immediate: Callable[[Task], Task]) -> None:
|
|
117
|
+
self._buckets: list[tuple[int, list[Task]]] = []
|
|
118
|
+
self._running: Task | None = None
|
|
119
|
+
self._set_immediate = set_immediate
|
|
120
|
+
|
|
121
|
+
def schedule_task(self, task: Task, priority: int) -> None:
|
|
122
|
+
buckets = self._buckets
|
|
123
|
+
index = next((i for i, (p, _) in enumerate(buckets) if p > priority), len(buckets))
|
|
124
|
+
if index and buckets[index - 1][0] == priority:
|
|
125
|
+
buckets[index - 1][1].append(task)
|
|
126
|
+
else:
|
|
127
|
+
buckets.insert(index, (priority, [task]))
|
|
128
|
+
if self._running is None:
|
|
129
|
+
self._running = self._set_immediate(self._after_scheduled)
|
|
130
|
+
|
|
131
|
+
def _after_scheduled(self) -> None:
|
|
132
|
+
self._running = None
|
|
133
|
+
self._run_tasks()
|
|
134
|
+
|
|
135
|
+
def _run_tasks(self) -> None:
|
|
136
|
+
buckets, self._buckets = self._buckets, []
|
|
137
|
+
for _, tasks in buckets:
|
|
138
|
+
for task in tasks:
|
|
139
|
+
task()
|
|
140
|
+
|
|
141
|
+
def flush(self) -> None:
|
|
142
|
+
while self._buckets:
|
|
143
|
+
if self._running is not None:
|
|
144
|
+
self._running()
|
|
145
|
+
self._running = None
|
|
146
|
+
self._run_tasks()
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
DEFAULT_SCHEDULER: Final[SchedulerService] = MixedScheduler()
|
|
150
|
+
"""The Scheduler Reference's default (scheduler.py returns this one), shared by every fiber
|
|
151
|
+
that has none provided, as upstream caches one default per Reference (Context.ts:1091-1096)."""
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def with_dispatcher[A, E, R](
|
|
155
|
+
f: Callable[[SchedulerDispatcher], Effect[A, E, R]],
|
|
156
|
+
) -> Effect[A, E, R]:
|
|
157
|
+
"""Run ``f`` with the executing fiber's dispatcher: the one its yields and scheduled forks
|
|
158
|
+
use (internal/effect.ts:567-570), so work queued on it is ordered with theirs."""
|
|
159
|
+
return WithFiber(lambda fiber: f(fiber.current_dispatcher))
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
@final
|
|
163
|
+
class Fiber(Generic[A_co, E_co]):
|
|
164
|
+
__slots__ = (
|
|
165
|
+
"__weakref__", # runtimes track fibers in WeakSets (ManagedRuntime.ts:338-339)
|
|
166
|
+
"_ask_scheduler",
|
|
167
|
+
"_auto_yielded",
|
|
168
|
+
"_context",
|
|
169
|
+
"_deferred",
|
|
170
|
+
"_dispatcher",
|
|
171
|
+
"_ending",
|
|
172
|
+
"_exit",
|
|
173
|
+
"_observers",
|
|
174
|
+
"_parent",
|
|
175
|
+
"_parked",
|
|
176
|
+
"_scheduler",
|
|
177
|
+
"_yield_at",
|
|
178
|
+
"children",
|
|
179
|
+
"current_op_count",
|
|
180
|
+
"id",
|
|
181
|
+
"interrupted",
|
|
182
|
+
"interruptible",
|
|
183
|
+
"running",
|
|
184
|
+
"stack",
|
|
185
|
+
)
|
|
186
|
+
|
|
187
|
+
def __init__(self, context: ContextMap, parent: Fiber[Any, Any] | None = None) -> None:
|
|
188
|
+
self.id = next(_ids)
|
|
189
|
+
self.stack: list[Frame] = []
|
|
190
|
+
self.interruptible = True
|
|
191
|
+
self.interrupted: Cause[Never] | None = None
|
|
192
|
+
self.running = False
|
|
193
|
+
self.children: set[Fiber[Any, Any]] = set()
|
|
194
|
+
self.current_op_count = 0 # ops in this slice, read by should_yield (Fiber.ts:77)
|
|
195
|
+
self._parent = parent
|
|
196
|
+
self._ending: Exit[Any, Any] | None = None # body exit, kept while children finish
|
|
197
|
+
self._deferred = False # an interrupt arrived while running; deliver at the next step
|
|
198
|
+
self._parked: Park | None = None # the Async or queued step a wake must claim first
|
|
199
|
+
self._exit: Exit[Any, Any] | None = None
|
|
200
|
+
self._observers: list[Observer] = []
|
|
201
|
+
self._auto_yielded = False # this slice resumes a budget yield: run one op unchecked
|
|
202
|
+
self._dispatcher: SchedulerDispatcher | None = None
|
|
203
|
+
self._scheduler: SchedulerService | None = None
|
|
204
|
+
self._context = context
|
|
205
|
+
self._read_scheduler()
|
|
206
|
+
|
|
207
|
+
def __repr__(self) -> str:
|
|
208
|
+
return f"Fiber#{self.id}"
|
|
209
|
+
|
|
210
|
+
@property
|
|
211
|
+
def context(self) -> ContextMap:
|
|
212
|
+
"""The services this fiber sees. Read-only: change it with update_context."""
|
|
213
|
+
return self._context
|
|
214
|
+
|
|
215
|
+
def swap_context(self, context: ContextMap) -> ContextMap:
|
|
216
|
+
"""Kernel only (update_context, RestoreContext): install ``context``, return the old one."""
|
|
217
|
+
old, self._context = self._context, context
|
|
218
|
+
self._read_scheduler()
|
|
219
|
+
return old
|
|
220
|
+
|
|
221
|
+
def _read_scheduler(self) -> None:
|
|
222
|
+
"""setContext's cache (internal/effect.ts:794-828): a new scheduler drops the dispatcher,
|
|
223
|
+
so the next dispatch makes one from it."""
|
|
224
|
+
ctx = self._context
|
|
225
|
+
scheduler: SchedulerService = ctx.get(_SCHEDULER_KEY, DEFAULT_SCHEDULER)
|
|
226
|
+
if scheduler is not self._scheduler:
|
|
227
|
+
self._dispatcher = None
|
|
228
|
+
self._scheduler = scheduler
|
|
229
|
+
# One compare per op: the loop asks only once current_op_count reaches _yield_at.
|
|
230
|
+
# PreventSchedulerYield never asks; MixedScheduler's answer is that compare itself.
|
|
231
|
+
self._ask_scheduler = False
|
|
232
|
+
if ctx.get(_PREVENT_YIELD_KEY, False):
|
|
233
|
+
self._yield_at = sys.maxsize
|
|
234
|
+
elif type(scheduler) is MixedScheduler:
|
|
235
|
+
self._yield_at: int = ctx.get(_MAX_OPS_KEY, _MAX_OPS_DEFAULT)
|
|
236
|
+
else:
|
|
237
|
+
self._yield_at, self._ask_scheduler = 0, True
|
|
238
|
+
|
|
239
|
+
@property
|
|
240
|
+
def current_dispatcher(self) -> SchedulerDispatcher:
|
|
241
|
+
"""Made on first use and kept until the scheduler changes (internal/effect.ts:567-570)."""
|
|
242
|
+
if self._dispatcher is None:
|
|
243
|
+
assert self._scheduler is not None
|
|
244
|
+
self._dispatcher = self._scheduler.make_dispatcher()
|
|
245
|
+
return self._dispatcher
|
|
246
|
+
|
|
247
|
+
# -- the run loop ------------------------------------------------------------------------------
|
|
248
|
+
|
|
249
|
+
def evaluate(self, eff: AnyEffect) -> None:
|
|
250
|
+
"""Kernel only: run this fiber from ``eff`` until it parks, queues a step, or ends.
|
|
251
|
+
Called by the starter, a resume, a queued step, or an interrupt; a no-op once exited.
|
|
252
|
+
Effect v4: evaluate and runLoop, internal/effect.ts:615-728."""
|
|
253
|
+
if self._exit is not None:
|
|
254
|
+
return
|
|
255
|
+
self._parked = None
|
|
256
|
+
was_running, self.running = self.running, True
|
|
257
|
+
resuming, self._auto_yielded = self._auto_yielded, False
|
|
258
|
+
yielding = False # a budget yield was tried this slice; don't retry if dispatch failed
|
|
259
|
+
self.current_op_count = 1 if resuming else 0 # the resumption counts as the op it replaces
|
|
260
|
+
cur: AnyEffect | None = eff
|
|
261
|
+
try:
|
|
262
|
+
while cur is not None:
|
|
263
|
+
if self._deferred and self.interruptible:
|
|
264
|
+
cur = Failure(self.take_interrupt())
|
|
265
|
+
ops = self.current_op_count = self.current_op_count + 1
|
|
266
|
+
try:
|
|
267
|
+
if (
|
|
268
|
+
ops >= self._yield_at
|
|
269
|
+
and not resuming
|
|
270
|
+
and not yielding
|
|
271
|
+
and (not self._ask_scheduler or self._should_yield())
|
|
272
|
+
):
|
|
273
|
+
yielding = True
|
|
274
|
+
self.yield_now(cur, automatic=True)
|
|
275
|
+
break
|
|
276
|
+
resuming = False
|
|
277
|
+
cur = cur._eval(self) # pyright: ignore[reportPrivateUsage]
|
|
278
|
+
except Exception as e: # a bug in user code, a combinator, or a dispatcher
|
|
279
|
+
cur = Failure(Cause.die(e))
|
|
280
|
+
finally:
|
|
281
|
+
self.running = was_running
|
|
282
|
+
# Parked while an interrupt was waiting (it arrived during register): deliver it now.
|
|
283
|
+
if self._deferred and self.interruptible and self._parked is not None:
|
|
284
|
+
self._interrupt_now()
|
|
285
|
+
|
|
286
|
+
def _should_yield(self) -> bool:
|
|
287
|
+
assert self._scheduler is not None
|
|
288
|
+
return self._scheduler.should_yield(self)
|
|
289
|
+
|
|
290
|
+
def _pop(self, ok: bool) -> Frame | None:
|
|
291
|
+
"""Pop to the next frame that handles this outcome; on_any runs on every frame popped."""
|
|
292
|
+
want = OK if ok else ERR
|
|
293
|
+
stack = self.stack
|
|
294
|
+
while stack:
|
|
295
|
+
frame = stack.pop()
|
|
296
|
+
if frame.kind & ANY and (eff := frame.on_any(self, ok)) is not None:
|
|
297
|
+
return Then(eff)
|
|
298
|
+
if frame.kind & want:
|
|
299
|
+
return frame
|
|
300
|
+
return None
|
|
301
|
+
|
|
302
|
+
def yield_now(self, eff: AnyEffect, priority: int = 0, automatic: bool = False) -> None:
|
|
303
|
+
"""Kernel only: queue ``eff`` as this fiber's next step on its dispatcher, then park on
|
|
304
|
+
the queued step. An interrupt that claims the park first runs at once and the step is
|
|
305
|
+
dropped (internal/effect.ts:773-781). A raising dispatcher parks nothing."""
|
|
306
|
+
park = Park()
|
|
307
|
+
|
|
308
|
+
def step() -> None:
|
|
309
|
+
if park.done:
|
|
310
|
+
return
|
|
311
|
+
park.done = True
|
|
312
|
+
self._auto_yielded = automatic
|
|
313
|
+
self.evaluate(eff)
|
|
314
|
+
|
|
315
|
+
self.current_dispatcher.schedule_task(step, priority)
|
|
316
|
+
self._parked = park
|
|
317
|
+
|
|
318
|
+
def _park(self, park: Park) -> None:
|
|
319
|
+
self._parked = park
|
|
320
|
+
|
|
321
|
+
# -- interruption ------------------------------------------------------------------------------
|
|
322
|
+
|
|
323
|
+
def interrupt_unsafe(self, by: int | None = None) -> None:
|
|
324
|
+
"""Ask the fiber to stop. If it is interruptible and not running (parked, queued, or not
|
|
325
|
+
started yet), the interrupt runs now, before this returns (internal/effect.ts:590-611);
|
|
326
|
+
use `interrupt()` to also wait for a running or masked fiber."""
|
|
327
|
+
if self._exit is not None:
|
|
328
|
+
return
|
|
329
|
+
cause = Cause.interrupt(by)
|
|
330
|
+
self.interrupted = cause if self.interrupted is None else self.interrupted + cause
|
|
331
|
+
if self.running or not self.interruptible:
|
|
332
|
+
self._deferred = True # picked up at the next step, or when the mask ends
|
|
333
|
+
else:
|
|
334
|
+
self._interrupt_now()
|
|
335
|
+
|
|
336
|
+
def take_interrupt(self) -> Cause[Never]:
|
|
337
|
+
"""Deliver the pending interrupt: the one place `_deferred` is cleared, so an interrupt
|
|
338
|
+
is delivered once however it is picked up (loop top, mask end, unwind, parked wake)."""
|
|
339
|
+
self._deferred = False
|
|
340
|
+
return self.interrupted or Cause.interrupt()
|
|
341
|
+
|
|
342
|
+
def _interrupt_now(self) -> None:
|
|
343
|
+
if self._parked is not None:
|
|
344
|
+
self._parked.done = True # a late resume, or the queued step, is now ignored
|
|
345
|
+
self.evaluate(Failure(self.take_interrupt()))
|
|
346
|
+
|
|
347
|
+
# -- finishing ---------------------------------------------------------------------------------
|
|
348
|
+
|
|
349
|
+
def _done(self, exit_: Exit[Any, Any]) -> AnyEffect | None:
|
|
350
|
+
"""The stack is empty. Interrupt live children and wait for them, then publish once.
|
|
351
|
+
|
|
352
|
+
Like v4 (internal/effect.ts:643-648), the wait runs inside the run loop as an Async, so an
|
|
353
|
+
interrupt sent while waiting is still delivered (K7). v4 then drops the body's exit; here
|
|
354
|
+
the interrupt is added to it instead, so a body's defects survive (K9).
|
|
355
|
+
"""
|
|
356
|
+
if self._ending is not None: # back from waiting: Success, or the interrupt that landed
|
|
357
|
+
ending = self._ending
|
|
358
|
+
if isinstance(exit_, Failure):
|
|
359
|
+
exit_ = Failure(
|
|
360
|
+
ending.cause + exit_.cause if isinstance(ending, Failure) else exit_.cause
|
|
361
|
+
)
|
|
362
|
+
else:
|
|
363
|
+
exit_ = ending
|
|
364
|
+
live = [c for c in self.children if c._exit is None]
|
|
365
|
+
if not live:
|
|
366
|
+
self._publish(exit_)
|
|
367
|
+
return None
|
|
368
|
+
self._ending = exit_
|
|
369
|
+
for c in live:
|
|
370
|
+
c.interrupt_unsafe(self.id)
|
|
371
|
+
return _await_all(live)
|
|
372
|
+
|
|
373
|
+
def _publish(self, exit_: Exit[Any, Any]) -> None:
|
|
374
|
+
self._exit = exit_
|
|
375
|
+
if self._parent is not None: # cleared before observers run (internal/effect.ts:652-655)
|
|
376
|
+
self._parent.children.discard(self)
|
|
377
|
+
self._parent = None
|
|
378
|
+
observers, self._observers = self._observers, []
|
|
379
|
+
for cb in observers:
|
|
380
|
+
cb(exit_)
|
|
381
|
+
|
|
382
|
+
@property
|
|
383
|
+
def exit(self) -> Exit[A_co, E_co] | None:
|
|
384
|
+
return self._exit
|
|
385
|
+
|
|
386
|
+
@property
|
|
387
|
+
def parent(self) -> Fiber[Any, Any] | None:
|
|
388
|
+
"""The supervising fiber while this one is live: None for a root or daemon, and once
|
|
389
|
+
this fiber has exited (FiberImpl._parent, internal/effect.ts:5624-5627, :652-655)."""
|
|
390
|
+
return self._parent
|
|
391
|
+
|
|
392
|
+
def add_observer(self, cb: Observer) -> Callable[[], None]:
|
|
393
|
+
"""Call cb with the exit when the fiber is done (now, if it is). Returns remove()."""
|
|
394
|
+
if self._exit is not None:
|
|
395
|
+
cb(self._exit)
|
|
396
|
+
return lambda: None
|
|
397
|
+
self._observers.append(cb)
|
|
398
|
+
return lambda: self._observers.remove(cb) if cb in self._observers else None
|
|
399
|
+
|
|
400
|
+
# -- effects on this fiber ---------------------------------------------------------------------
|
|
401
|
+
|
|
402
|
+
def await_(self) -> Effect[Exit[A_co, E_co], Never, Never]:
|
|
403
|
+
"""Wait for the fiber; succeed with its Exit (never fails)."""
|
|
404
|
+
|
|
405
|
+
def register(resume: Resume[Exit[A_co, E_co], Never, Never]) -> AnyEffect:
|
|
406
|
+
remove = self.add_observer(lambda ex: resume(Success(ex)))
|
|
407
|
+
return Sync(remove)
|
|
408
|
+
|
|
409
|
+
return Async(register)
|
|
410
|
+
|
|
411
|
+
def join(self) -> Effect[A_co, E_co, Never]:
|
|
412
|
+
"""Wait for the fiber and continue as it ended: its value, or its failure."""
|
|
413
|
+
|
|
414
|
+
def register(resume: Resume[A_co, E_co, Never]) -> AnyEffect:
|
|
415
|
+
remove = self.add_observer(resume) # an Exit is an effect: resume with it directly
|
|
416
|
+
return Sync(remove)
|
|
417
|
+
|
|
418
|
+
return Async(register)
|
|
419
|
+
|
|
420
|
+
def interrupt(self) -> Effect[None, Never, Never]:
|
|
421
|
+
"""Interrupt and wait until it has finished (its finalizers have run)."""
|
|
422
|
+
|
|
423
|
+
def go(me: Fiber[Any, Any]) -> AnyEffect:
|
|
424
|
+
self.interrupt_unsafe(me.id)
|
|
425
|
+
return self.await_().as_(None)
|
|
426
|
+
|
|
427
|
+
return WithFiber(go)
|
|
428
|
+
|
|
429
|
+
|
|
430
|
+
def await_all[A, E](fibers: Iterable[Fiber[A, E]]) -> Effect[list[Exit[A, E]], Never, Never]:
|
|
431
|
+
"""Wait in input order, returning target failures as Exits. Cancellation removes the
|
|
432
|
+
current observer without interrupting targets (Effect v4 internal/effect.ts:876-908)."""
|
|
433
|
+
|
|
434
|
+
def register(resume: Resume[list[Exit[A, E]], Never, Never]) -> AnyEffect:
|
|
435
|
+
iterator = iter(fibers)
|
|
436
|
+
exits: list[Exit[A, E]] = []
|
|
437
|
+
cancel: Callable[[], None] | None = None
|
|
438
|
+
|
|
439
|
+
def loop() -> None:
|
|
440
|
+
nonlocal cancel
|
|
441
|
+
while True:
|
|
442
|
+
try:
|
|
443
|
+
fiber = next(iterator, None)
|
|
444
|
+
except Exception as error:
|
|
445
|
+
resume(Failure(Cause.die(error)))
|
|
446
|
+
return
|
|
447
|
+
if fiber is None:
|
|
448
|
+
resume(Success(exits))
|
|
449
|
+
return
|
|
450
|
+
exit_ = fiber.exit
|
|
451
|
+
if exit_ is not None:
|
|
452
|
+
exits.append(exit_)
|
|
453
|
+
continue
|
|
454
|
+
cancel = fiber.add_observer(one_done)
|
|
455
|
+
return
|
|
456
|
+
|
|
457
|
+
def one_done(exit_: Exit[A, E]) -> None:
|
|
458
|
+
exits.append(exit_)
|
|
459
|
+
loop()
|
|
460
|
+
|
|
461
|
+
def cleanup() -> None:
|
|
462
|
+
if cancel is not None:
|
|
463
|
+
cancel()
|
|
464
|
+
|
|
465
|
+
loop()
|
|
466
|
+
return Sync(cleanup)
|
|
467
|
+
|
|
468
|
+
return Async(register)
|
|
469
|
+
|
|
470
|
+
|
|
471
|
+
def interrupt_all[A, E](fibers: Iterable[Fiber[A, E]]) -> Effect[None, Never, Never]:
|
|
472
|
+
"""Signal every target with the executing caller's id before awaiting any cleanup.
|
|
473
|
+
Consume the iterable once (Effect v4 internal/effect.ts:992-1003)."""
|
|
474
|
+
|
|
475
|
+
def go(parent: Fiber[Any, Any]) -> Effect[None, Never, Never]:
|
|
476
|
+
targets: list[Fiber[A, E]] = []
|
|
477
|
+
for fiber in fibers:
|
|
478
|
+
fiber.interrupt_unsafe(parent.id)
|
|
479
|
+
targets.append(fiber)
|
|
480
|
+
return await_all(targets).as_(None)
|
|
481
|
+
|
|
482
|
+
return WithFiber(go)
|
|
483
|
+
|
|
484
|
+
|
|
485
|
+
def _await_all(fibers: list[Fiber[Any, Any]]) -> AnyEffect:
|
|
486
|
+
"""Park until every fiber has published. Interruptible: cancelling removes the observers."""
|
|
487
|
+
|
|
488
|
+
def register(resume: Resume[None, Never, Never]) -> AnyEffect:
|
|
489
|
+
remaining = len(fibers)
|
|
490
|
+
|
|
491
|
+
def one_done(_: Exit[Any, Any]) -> None:
|
|
492
|
+
nonlocal remaining
|
|
493
|
+
remaining -= 1
|
|
494
|
+
if remaining == 0:
|
|
495
|
+
resume(UNIT)
|
|
496
|
+
|
|
497
|
+
removes = [f.add_observer(one_done) for f in fibers]
|
|
498
|
+
|
|
499
|
+
def cancel() -> None:
|
|
500
|
+
for r in removes:
|
|
501
|
+
r()
|
|
502
|
+
|
|
503
|
+
return Sync(cancel)
|
|
504
|
+
|
|
505
|
+
return Async(register)
|
|
506
|
+
|
|
507
|
+
|
|
508
|
+
# ================================================================================================
|
|
509
|
+
# Forking and running
|
|
510
|
+
# ================================================================================================
|
|
511
|
+
|
|
512
|
+
|
|
513
|
+
def _start[A, E](
|
|
514
|
+
parent: Fiber[Any, Any] | None,
|
|
515
|
+
eff: Effect[A, E, Any],
|
|
516
|
+
ctx: ContextMap,
|
|
517
|
+
spawner: Fiber[Any, Any] | None = None,
|
|
518
|
+
immediate: bool = True,
|
|
519
|
+
interruptible: bool = True,
|
|
520
|
+
) -> Fiber[A, E]:
|
|
521
|
+
"""Effect v4: forkUnsafe, internal/effect.ts:5614-5637. ``immediate`` runs the child's first
|
|
522
|
+
slice now, inside the caller's drive, until it parks or ends; otherwise its start is queued
|
|
523
|
+
at priority 0 on the ``spawner``'s dispatcher (the forking fiber, parent or not)."""
|
|
524
|
+
child: Fiber[A, E] = Fiber(ctx, parent)
|
|
525
|
+
child.interruptible = interruptible
|
|
526
|
+
if parent is not None:
|
|
527
|
+
parent.children.add(child)
|
|
528
|
+
if immediate or spawner is None:
|
|
529
|
+
child.evaluate(eff)
|
|
530
|
+
else:
|
|
531
|
+
spawner.current_dispatcher.schedule_task(lambda: child.evaluate(eff), 0)
|
|
532
|
+
return child
|
|
533
|
+
|
|
534
|
+
|
|
535
|
+
def fork[A, E, R](
|
|
536
|
+
eff: Effect[A, E, R],
|
|
537
|
+
*,
|
|
538
|
+
start_immediately: bool = False,
|
|
539
|
+
uninterruptible: Literal["inherit"] | None = None,
|
|
540
|
+
) -> Effect[Fiber[A, E], Never, R]:
|
|
541
|
+
"""Run eff concurrently. The child is supervised: when the parent ends, the child is
|
|
542
|
+
interrupted and the parent waits for it. ``start_immediately`` runs the child until it first
|
|
543
|
+
parks or ends before ``fork`` returns (Effect v4: forkChild's ``startImmediately``).
|
|
544
|
+
Only ``uninterruptible="inherit"`` copies the caller's mask; the default is interruptible."""
|
|
545
|
+
if uninterruptible is not None and uninterruptible != "inherit":
|
|
546
|
+
raise ValueError('uninterruptible must be None or "inherit"')
|
|
547
|
+
return WithFiber(
|
|
548
|
+
lambda p: Success(
|
|
549
|
+
_start(
|
|
550
|
+
p,
|
|
551
|
+
eff,
|
|
552
|
+
p.context,
|
|
553
|
+
p,
|
|
554
|
+
start_immediately,
|
|
555
|
+
p.interruptible if uninterruptible == "inherit" else True,
|
|
556
|
+
)
|
|
557
|
+
)
|
|
558
|
+
)
|
|
559
|
+
|
|
560
|
+
|
|
561
|
+
def fork_daemon[A, E, R](
|
|
562
|
+
eff: Effect[A, E, R],
|
|
563
|
+
*,
|
|
564
|
+
start_immediately: bool = False,
|
|
565
|
+
uninterruptible: Literal["inherit"] | None = None,
|
|
566
|
+
) -> Effect[Fiber[A, E], Never, R]:
|
|
567
|
+
"""Run eff concurrently with no parent: it outlives the fiber that started it.
|
|
568
|
+
``start_immediately`` and ``uninterruptible="inherit"`` work as for ``fork``
|
|
569
|
+
(Effect v4: forkDetach, internal/effect.ts:5728)."""
|
|
570
|
+
if uninterruptible is not None and uninterruptible != "inherit":
|
|
571
|
+
raise ValueError('uninterruptible must be None or "inherit"')
|
|
572
|
+
return WithFiber(
|
|
573
|
+
lambda p: Success(
|
|
574
|
+
_start(
|
|
575
|
+
None,
|
|
576
|
+
eff,
|
|
577
|
+
p.context,
|
|
578
|
+
p,
|
|
579
|
+
start_immediately,
|
|
580
|
+
p.interruptible if uninterruptible == "inherit" else True,
|
|
581
|
+
)
|
|
582
|
+
)
|
|
583
|
+
)
|
|
584
|
+
|
|
585
|
+
|
|
586
|
+
class FiberOwner(Protocol):
|
|
587
|
+
"""What `run_in_owner` and `fork_in_owner` need from a Scope: whether it is closed, and
|
|
588
|
+
adding or removing the fiber's own finalizer, keyed by the fiber (scope.py's adapter)."""
|
|
589
|
+
|
|
590
|
+
def is_closed(self) -> bool: ...
|
|
591
|
+
def attach(self, fiber: Fiber[Any, Any]) -> None: ...
|
|
592
|
+
def detach(self, fiber: Fiber[Any, Any]) -> None: ...
|
|
593
|
+
|
|
594
|
+
|
|
595
|
+
def run_in_owner[A, E](fiber: Fiber[A, E], owner: FiberOwner) -> Fiber[A, E]:
|
|
596
|
+
"""fiberRunIn, internal/effect.ts:5801-5822: re-attach the fiber as the owner's newest
|
|
597
|
+
finalizer and detach it when it exits. A closed owner interrupts it with its own id."""
|
|
598
|
+
if fiber.exit is not None:
|
|
599
|
+
return fiber
|
|
600
|
+
if owner.is_closed():
|
|
601
|
+
fiber.interrupt_unsafe(fiber.id)
|
|
602
|
+
return fiber
|
|
603
|
+
owner.detach(fiber)
|
|
604
|
+
owner.attach(fiber)
|
|
605
|
+
fiber.add_observer(lambda _: owner.detach(fiber))
|
|
606
|
+
return fiber
|
|
607
|
+
|
|
608
|
+
|
|
609
|
+
def fork_in_owner[A, E, R](
|
|
610
|
+
eff: Effect[A, E, R],
|
|
611
|
+
owner: FiberOwner,
|
|
612
|
+
*,
|
|
613
|
+
start_immediately: bool = False,
|
|
614
|
+
uninterruptible: bool | Literal["inherit"] = False,
|
|
615
|
+
) -> Effect[Fiber[A, E], Never, R]:
|
|
616
|
+
"""forkIn, internal/effect.ts:5717-5737: fork a daemon and attach it in one step. A closed
|
|
617
|
+
owner gets an unstarted fiber; one that closed during an immediate start is re-checked.
|
|
618
|
+
Either is interrupted with the forker's id."""
|
|
619
|
+
|
|
620
|
+
def go(parent: Fiber[Any, Any]) -> Effect[Fiber[A, E], Never, R]:
|
|
621
|
+
if owner.is_closed():
|
|
622
|
+
fiber: Fiber[A, E] = Fiber(parent.context)
|
|
623
|
+
else:
|
|
624
|
+
mask = parent.interruptible if uninterruptible == "inherit" else not uninterruptible
|
|
625
|
+
fiber = _start(None, eff, parent.context, parent, start_immediately, mask)
|
|
626
|
+
if fiber.exit is None:
|
|
627
|
+
if not owner.is_closed():
|
|
628
|
+
owner.attach(fiber)
|
|
629
|
+
fiber.add_observer(lambda _: owner.detach(fiber))
|
|
630
|
+
else:
|
|
631
|
+
fiber.interrupt_unsafe(parent.id)
|
|
632
|
+
return Success(fiber)
|
|
633
|
+
|
|
634
|
+
return WithFiber(go)
|
|
635
|
+
|
|
636
|
+
|
|
637
|
+
# ================================================================================================
|
|
638
|
+
# Traversal
|
|
639
|
+
# ================================================================================================
|
|
640
|
+
|
|
641
|
+
|
|
642
|
+
def for_each[A, B, E, R](
|
|
643
|
+
items: Iterable[A],
|
|
644
|
+
f: Callable[[A, int], Effect[B, E, R]],
|
|
645
|
+
*,
|
|
646
|
+
concurrency: int | Literal["unbounded"] = 1,
|
|
647
|
+
) -> Effect[list[B], E, R]:
|
|
648
|
+
"""Map each item and its index to an effect; succeed with the values in input order.
|
|
649
|
+
|
|
650
|
+
Concurrency 1 (the default; below 1 also means 1) runs one item at a time, reading the
|
|
651
|
+
iterable lazily. Higher runs up to that many items at once as traversal-owned daemon workers
|
|
652
|
+
that inherit the caller's mask. The first failure interrupts the rest; cleanup defects are kept.
|
|
653
|
+
Each run starts afresh. Effect v4: forEach, internal/effect.ts:5030-5112."""
|
|
654
|
+
limit = math.inf if concurrency == "unbounded" else max(1, concurrency)
|
|
655
|
+
|
|
656
|
+
def start() -> Effect[list[B], E, R]:
|
|
657
|
+
if limit == 1:
|
|
658
|
+
return _for_each_sequential(iter(items), f)
|
|
659
|
+
array = list(items)
|
|
660
|
+
if not array:
|
|
661
|
+
return Success([])
|
|
662
|
+
out: list[Any] = [None] * len(array)
|
|
663
|
+
eff = _for_each_concurrent(array, f, out, limit)
|
|
664
|
+
return Success(out) if eff is None else eff.as_(out)
|
|
665
|
+
|
|
666
|
+
return Suspend(start)
|
|
667
|
+
|
|
668
|
+
|
|
669
|
+
def _for_each_sequential[A, B, E, R](
|
|
670
|
+
iterator: Iterator[A], f: Callable[[A, int], Effect[B, E, R]]
|
|
671
|
+
) -> Effect[list[B], E, R]:
|
|
672
|
+
"""forEachSequential, internal/effect.ts:5085-5108: the next item is read after a step."""
|
|
673
|
+
out: list[B] = []
|
|
674
|
+
|
|
675
|
+
def next_(index: int) -> Effect[list[B], E, R]:
|
|
676
|
+
for item in iterator:
|
|
677
|
+
|
|
678
|
+
def keep(b: B) -> Effect[list[B], E, R]:
|
|
679
|
+
out.append(b)
|
|
680
|
+
return next_(index + 1)
|
|
681
|
+
|
|
682
|
+
return f(item, index).flat_map(keep)
|
|
683
|
+
return Success(out)
|
|
684
|
+
|
|
685
|
+
return next_(0)
|
|
686
|
+
|
|
687
|
+
|
|
688
|
+
def _for_each_concurrent[A, B, E, R](
|
|
689
|
+
items: list[A], f: Callable[[A, int], Effect[B, E, R]], out: list[Any], concurrency: float
|
|
690
|
+
) -> Effect[None, E, R] | None:
|
|
691
|
+
"""iterateConcurrentImpl with forEachConcurrent's step, internal/effect.ts:5160-5320.
|
|
692
|
+
|
|
693
|
+
Ready Exits are stepped inline, with no fiber. The first effect that is not one moves the
|
|
694
|
+
rest of the traversal onto the caller as an Async (`_run_window`). None means every item
|
|
695
|
+
finished inline with no failure."""
|
|
696
|
+
|
|
697
|
+
def on_caller(index: int, first: Effect[B, E, R]) -> Effect[None, E, R]:
|
|
698
|
+
return WithFiber(
|
|
699
|
+
lambda parent: Async(
|
|
700
|
+
lambda resume: _run_window(items, f, out, concurrency, index, first, parent, resume)
|
|
701
|
+
)
|
|
702
|
+
)
|
|
703
|
+
|
|
704
|
+
for index, item in enumerate(items):
|
|
705
|
+
eff = f(item, index)
|
|
706
|
+
if not isinstance(eff, (Success, Failure)):
|
|
707
|
+
return on_caller(index, eff)
|
|
708
|
+
if (failure := _step(out, index, eff)) is not None:
|
|
709
|
+
return failure
|
|
710
|
+
return None
|
|
711
|
+
|
|
712
|
+
|
|
713
|
+
def _step[B, E](out: list[Any], index: int, exit_: Exit[B, E]) -> Failure[E] | None:
|
|
714
|
+
"""forEachConcurrent's step: keep a value at its input index; a failure is the terminal."""
|
|
715
|
+
if isinstance(exit_, Failure):
|
|
716
|
+
return exit_
|
|
717
|
+
out[index] = exit_.value
|
|
718
|
+
return None
|
|
719
|
+
|
|
720
|
+
|
|
721
|
+
def _run_window[A, B, E, R](
|
|
722
|
+
items: list[A],
|
|
723
|
+
f: Callable[[A, int], Effect[B, E, R]],
|
|
724
|
+
out: list[Any],
|
|
725
|
+
concurrency: float,
|
|
726
|
+
start: int,
|
|
727
|
+
first: Effect[B, E, R],
|
|
728
|
+
parent: Fiber[Any, Any],
|
|
729
|
+
resume: Resume[None, E, R],
|
|
730
|
+
) -> Effect[None, E, R] | None:
|
|
731
|
+
"""The Async register of a concurrent traversal, on the caller `parent`, from item `start`
|
|
732
|
+
whose effect `first` is already built. Returns the cancel effect, or None once resumed.
|
|
733
|
+
|
|
734
|
+
State: `index` is the next item to start, `live` the workers still running, `terminal` the
|
|
735
|
+
first failure (or UNIT after a cancel) with later non-interrupt reasons folded in, and
|
|
736
|
+
`done` says no more items will start. `pump` starts items, each a child forked with the
|
|
737
|
+
caller's mask, until the window is full. A worker's observer records its Exit, then refills
|
|
738
|
+
the window if its pump paused. The caller resumes once `done` and no worker is live."""
|
|
739
|
+
index = start
|
|
740
|
+
end = len(items)
|
|
741
|
+
pending: Effect[B, E, R] | None = first
|
|
742
|
+
live: dict[Fiber[Any, Any], None] = {}
|
|
743
|
+
terminal: Exit[None, E] | None = None
|
|
744
|
+
done = False
|
|
745
|
+
|
|
746
|
+
def pump() -> bool:
|
|
747
|
+
"""Start items until the window is full (True) or no more will start (False)."""
|
|
748
|
+
nonlocal index, terminal, pending
|
|
749
|
+
paused = [False] # this call's: its observers refill only once it has paused
|
|
750
|
+
while terminal is None and index < end:
|
|
751
|
+
eff = pending if pending is not None else f(items[index], index)
|
|
752
|
+
pending = None
|
|
753
|
+
if isinstance(eff, (Success, Failure)):
|
|
754
|
+
terminal = _step(out, index, eff)
|
|
755
|
+
else:
|
|
756
|
+
fiber = _start(None, eff, parent.context, interruptible=parent.interruptible)
|
|
757
|
+
if fiber.exit is not None:
|
|
758
|
+
terminal = _step(out, index, fiber.exit)
|
|
759
|
+
else:
|
|
760
|
+
live[fiber] = None
|
|
761
|
+
fiber.add_observer(observe(fiber, index, paused))
|
|
762
|
+
if len(live) >= concurrency:
|
|
763
|
+
paused[0] = True
|
|
764
|
+
index += 1
|
|
765
|
+
return True
|
|
766
|
+
index += 1
|
|
767
|
+
return False
|
|
768
|
+
|
|
769
|
+
def finish() -> Exit[None, E] | None:
|
|
770
|
+
"""No more items will start. After a terminal, interrupt the live workers. Returns the
|
|
771
|
+
Exit to resume the caller with, or None while a worker is still live."""
|
|
772
|
+
nonlocal done
|
|
773
|
+
done = True
|
|
774
|
+
if live:
|
|
775
|
+
if terminal is not None:
|
|
776
|
+
for fiber in list(live):
|
|
777
|
+
fiber.interrupt_unsafe(parent.id)
|
|
778
|
+
return None
|
|
779
|
+
return UNIT if terminal is None else terminal
|
|
780
|
+
|
|
781
|
+
def go() -> Exit[None, E] | None:
|
|
782
|
+
return None if pump() else finish()
|
|
783
|
+
|
|
784
|
+
def record(exit_: Exit[B, E], i: int) -> None:
|
|
785
|
+
"""Fold one worker's Exit into the run: keep its value, or make its failure the
|
|
786
|
+
terminal and stop the rest. After a terminal, only its non-interrupt reasons count."""
|
|
787
|
+
nonlocal terminal
|
|
788
|
+
if terminal is None:
|
|
789
|
+
terminal = _step(out, i, exit_)
|
|
790
|
+
if terminal is not None:
|
|
791
|
+
finish()
|
|
792
|
+
elif isinstance(exit_, Failure):
|
|
793
|
+
kept = tuple(r for r in exit_.cause.reasons if not isinstance(r, Interrupt))
|
|
794
|
+
if kept:
|
|
795
|
+
cause = Cause(kept)
|
|
796
|
+
terminal = Failure(
|
|
797
|
+
(terminal.cause + cause).elect_defects()
|
|
798
|
+
if isinstance(terminal, Failure)
|
|
799
|
+
else cause
|
|
800
|
+
)
|
|
801
|
+
|
|
802
|
+
def observe(fiber: Fiber[B, E], i: int, paused: list[bool]) -> Observer:
|
|
803
|
+
def on_exit(exit_: Exit[B, E]) -> None:
|
|
804
|
+
live.pop(fiber, None)
|
|
805
|
+
try:
|
|
806
|
+
record(exit_, i)
|
|
807
|
+
if paused[0]:
|
|
808
|
+
if (result := go()) is not None:
|
|
809
|
+
resume(result)
|
|
810
|
+
elif done and not live:
|
|
811
|
+
resume(UNIT if terminal is None else terminal)
|
|
812
|
+
except Exception as error:
|
|
813
|
+
resume(fail_defect(error))
|
|
814
|
+
|
|
815
|
+
return on_exit
|
|
816
|
+
|
|
817
|
+
def fail_defect(error: Exception) -> Effect[None, E, R]:
|
|
818
|
+
nonlocal terminal, done
|
|
819
|
+
defect: Failure[E] = Failure(Cause.die(error))
|
|
820
|
+
terminal = defect
|
|
821
|
+
done = True
|
|
822
|
+
if not live:
|
|
823
|
+
return defect
|
|
824
|
+
return uninterruptible(interrupt_all(list(live))).flat_map(
|
|
825
|
+
lambda _: defect if terminal is None else terminal
|
|
826
|
+
)
|
|
827
|
+
|
|
828
|
+
def on_cancel() -> Effect[None, E, R]:
|
|
829
|
+
nonlocal terminal
|
|
830
|
+
if terminal is None:
|
|
831
|
+
terminal = UNIT
|
|
832
|
+
return interrupt_all(list(live)).flat_map(
|
|
833
|
+
lambda _: terminal if isinstance(terminal, Failure) else UNIT
|
|
834
|
+
)
|
|
835
|
+
|
|
836
|
+
try:
|
|
837
|
+
result = go()
|
|
838
|
+
except Exception as error:
|
|
839
|
+
resume(fail_defect(error))
|
|
840
|
+
return None
|
|
841
|
+
if result is not None:
|
|
842
|
+
resume(result)
|
|
843
|
+
return None
|
|
844
|
+
return Suspend(on_cancel)
|
|
845
|
+
|
|
846
|
+
|
|
847
|
+
# ================================================================================================
|
|
848
|
+
# Racing
|
|
849
|
+
# ================================================================================================
|
|
850
|
+
|
|
851
|
+
|
|
852
|
+
def race_all[A, E, R](effects: Iterable[Effect[A, E, R]]) -> Effect[A, E, R]:
|
|
853
|
+
"""Run every effect at once; continue with the first success. If all fail, fail with every
|
|
854
|
+
reason in completion order, defects elected. The rest are interrupted as soon as one wins.
|
|
855
|
+
Effect v4: raceAll, internal/effect.ts:1688-1740."""
|
|
856
|
+
|
|
857
|
+
def start(parent: Fiber[Any, Any], live: _Racers[A, E], resume: Resume[A, E, R]) -> None:
|
|
858
|
+
racers = list(effects) # every effect is read before the first fork (Arr.fromIterable)
|
|
859
|
+
failures: list[Cause[E]] = []
|
|
860
|
+
exited = 0
|
|
861
|
+
won = False
|
|
862
|
+
|
|
863
|
+
def on_exit(exit_: Exit[A, E]) -> None:
|
|
864
|
+
nonlocal exited, won
|
|
865
|
+
exited += 1
|
|
866
|
+
if isinstance(exit_, Failure):
|
|
867
|
+
failures.append(exit_.cause)
|
|
868
|
+
if exited >= len(racers):
|
|
869
|
+
reasons = tuple(r for c in failures for r in c.reasons)
|
|
870
|
+
resume(Failure(Cause(reasons).elect_defects()))
|
|
871
|
+
return
|
|
872
|
+
winner, won = not won, True
|
|
873
|
+
resume(exit_)
|
|
874
|
+
if winner:
|
|
875
|
+
_interrupt_losers(live, parent)
|
|
876
|
+
|
|
877
|
+
for eff in racers:
|
|
878
|
+
_fork_racer(parent, live, eff, on_exit)
|
|
879
|
+
if won: # a racer won while the racers start: fork no more
|
|
880
|
+
break
|
|
881
|
+
|
|
882
|
+
return _racing(start)
|
|
883
|
+
|
|
884
|
+
|
|
885
|
+
def race_all_first[A, E, R](effects: Iterable[Effect[A, E, R]]) -> Effect[A, E, R]:
|
|
886
|
+
"""Run every effect at once; continue as the first one ends, success or failure.
|
|
887
|
+
Effect v4: raceAllFirst, internal/effect.ts:1743-1774."""
|
|
888
|
+
|
|
889
|
+
def start(parent: Fiber[Any, Any], live: _Racers[A, E], resume: Resume[A, E, R]) -> None:
|
|
890
|
+
done = False
|
|
891
|
+
|
|
892
|
+
def on_exit(exit_: Exit[A, E]) -> None:
|
|
893
|
+
nonlocal done
|
|
894
|
+
winner, done = not done, True
|
|
895
|
+
resume(exit_)
|
|
896
|
+
if winner:
|
|
897
|
+
_interrupt_losers(live, parent)
|
|
898
|
+
|
|
899
|
+
# Read lazily; one extra item may be read after settlement, but is not forked.
|
|
900
|
+
iterator = iter(effects)
|
|
901
|
+
for eff in iterator:
|
|
902
|
+
if done:
|
|
903
|
+
# JS for-of closes the iterator on break (IteratorClose).
|
|
904
|
+
close = getattr(iterator, "close", None)
|
|
905
|
+
if close is not None:
|
|
906
|
+
close()
|
|
907
|
+
break
|
|
908
|
+
_fork_racer(parent, live, eff, on_exit)
|
|
909
|
+
|
|
910
|
+
return _racing(start)
|
|
911
|
+
|
|
912
|
+
|
|
913
|
+
def race[A, E, R](self: Effect[A, E, R], that: Effect[A, E, R]) -> Effect[A, E, R]:
|
|
914
|
+
"""``race_all([self, that])``: the first success wins (internal/effect.ts:1794).
|
|
915
|
+
|
|
916
|
+
One type variable per channel: pyright joins both sides' types into a union per channel."""
|
|
917
|
+
return race_all((self, that))
|
|
918
|
+
|
|
919
|
+
|
|
920
|
+
def race_first[A, E, R](self: Effect[A, E, R], that: Effect[A, E, R]) -> Effect[A, E, R]:
|
|
921
|
+
"""``race_all_first([self, that])``: the first exit wins (internal/effect.ts:1834)."""
|
|
922
|
+
return race_all_first((self, that))
|
|
923
|
+
|
|
924
|
+
|
|
925
|
+
type _Racers[A, E] = dict[Fiber[A, E], None] # live racers in fork order
|
|
926
|
+
|
|
927
|
+
|
|
928
|
+
def _racing[A, E, R](
|
|
929
|
+
start: Callable[[Fiber[Any, Any], _Racers[A, E], Resume[A, E, R]], None],
|
|
930
|
+
) -> Effect[A, E, R]:
|
|
931
|
+
"""The frame both races share: `start` forks the racers from an Async on the caller, and an
|
|
932
|
+
OnExit frame under it interrupts and awaits whatever racers are still live when the race
|
|
933
|
+
ends, masked, so the race returns only after its losers' cleanup (:1704). The frame reads
|
|
934
|
+
`live` on exit, so it includes racers forked after the race settled."""
|
|
935
|
+
|
|
936
|
+
def go(parent: Fiber[Any, Any]) -> Effect[A, E, R]:
|
|
937
|
+
live: _Racers[A, E] = {}
|
|
938
|
+
|
|
939
|
+
def cleanup(_exit: Exit[Any, Any], _fiber: Fiber[Any, Any]) -> AnyEffect | None:
|
|
940
|
+
return interrupt_all(list(live)) if live else None
|
|
941
|
+
|
|
942
|
+
return OnExit(Async(lambda resume: start(parent, live, resume)), cleanup)
|
|
943
|
+
|
|
944
|
+
return WithFiber(go)
|
|
945
|
+
|
|
946
|
+
|
|
947
|
+
def _fork_racer[A, E, R](
|
|
948
|
+
parent: Fiber[Any, Any],
|
|
949
|
+
live: _Racers[A, E],
|
|
950
|
+
eff: Effect[A, E, R],
|
|
951
|
+
on_exit: Callable[[Exit[A, E]], None],
|
|
952
|
+
) -> None:
|
|
953
|
+
"""Start a racer: a daemon, interruptible whatever the caller's mask, in the caller's
|
|
954
|
+
context (forkUnsafe(parent, eff, true, true, false), :5614). It leaves `live` before
|
|
955
|
+
`on_exit` sees its Exit."""
|
|
956
|
+
fiber = _start(None, eff, parent.context, parent, True, True)
|
|
957
|
+
live[fiber] = None
|
|
958
|
+
|
|
959
|
+
def observer(exit_: Exit[A, E]) -> None:
|
|
960
|
+
live.pop(fiber, None)
|
|
961
|
+
on_exit(exit_)
|
|
962
|
+
|
|
963
|
+
fiber.add_observer(observer)
|
|
964
|
+
|
|
965
|
+
|
|
966
|
+
def _interrupt_losers(live: _Racers[Any, Any], parent: Fiber[Any, Any]) -> None:
|
|
967
|
+
"""Interrupt the losers as soon as the race settles. Callers resume the winner first, so a
|
|
968
|
+
loser's interrupt can't settle the race (interruptRaceLosers, :1776-1786)."""
|
|
969
|
+
for loser in list(live):
|
|
970
|
+
loser.interrupt_unsafe(parent.id)
|
|
971
|
+
|
|
972
|
+
|
|
973
|
+
type FiberStartHook = Callable[[Fiber[Any, Any]], object]
|
|
974
|
+
|
|
975
|
+
|
|
976
|
+
@final
|
|
977
|
+
class RootRunner:
|
|
978
|
+
"""``run_fork_with(context)``: start roots over a raw context map. The map carries no
|
|
979
|
+
requirement types; a typed ``Context[R]`` front belongs outside the kernel."""
|
|
980
|
+
|
|
981
|
+
__slots__ = ("_context",)
|
|
982
|
+
|
|
983
|
+
def __init__(self, context: ContextMap) -> None:
|
|
984
|
+
self._context: Final = context
|
|
985
|
+
|
|
986
|
+
def __call__[A, E](
|
|
987
|
+
self,
|
|
988
|
+
eff: Effect[A, E, Any],
|
|
989
|
+
*,
|
|
990
|
+
scheduler: SchedulerService | None = None,
|
|
991
|
+
uninterruptible: bool = False,
|
|
992
|
+
on_fiber_start: FiberStartHook | None = None,
|
|
993
|
+
) -> Fiber[A, E]:
|
|
994
|
+
"""runForkWith, internal/effect.ts:5773-5799: evaluate at once; only a fiber still live
|
|
995
|
+
after that first slice reaches ``on_fiber_start``. ``scheduler`` replaces the context's."""
|
|
996
|
+
ctx = self._context if scheduler is None else {**self._context, _SCHEDULER_KEY: scheduler}
|
|
997
|
+
fiber: Fiber[A, E] = Fiber(ctx)
|
|
998
|
+
fiber.interruptible = uninterruptible is not True
|
|
999
|
+
fiber.evaluate(eff)
|
|
1000
|
+
if fiber.exit is None and on_fiber_start is not None:
|
|
1001
|
+
on_fiber_start(fiber)
|
|
1002
|
+
return fiber
|
|
1003
|
+
|
|
1004
|
+
|
|
1005
|
+
def run_fork_with(context: ContextMap) -> RootRunner:
|
|
1006
|
+
return RootRunner(context)
|
|
1007
|
+
|
|
1008
|
+
|
|
1009
|
+
def run_fork[A, E](
|
|
1010
|
+
eff: Effect[A, E, Never],
|
|
1011
|
+
*,
|
|
1012
|
+
scheduler: SchedulerService | None = None,
|
|
1013
|
+
uninterruptible: bool = False,
|
|
1014
|
+
on_fiber_start: FiberStartHook | None = None,
|
|
1015
|
+
) -> Fiber[A, E]:
|
|
1016
|
+
"""runFork, internal/effect.ts:5824-5827: ``run_fork_with`` over the empty context. The
|
|
1017
|
+
fiber's synchronous prefix has run when this returns."""
|
|
1018
|
+
return RootRunner(EMPTY_CONTEXT)(
|
|
1019
|
+
eff, scheduler=scheduler, uninterruptible=uninterruptible, on_fiber_start=on_fiber_start
|
|
1020
|
+
)
|
|
1021
|
+
|
|
1022
|
+
|
|
1023
|
+
async def await_exit[A, E](fiber: Fiber[A, E]) -> Exit[A, E]:
|
|
1024
|
+
"""Wait on the current asyncio loop for ``fiber``'s Exit through an observer, with no second
|
|
1025
|
+
fiber (runPromiseExitWith, internal/effect.ts:5854-5866). Cancelling the awaiting task
|
|
1026
|
+
interrupts the fiber with no interruptor (signal abort, :5785-5793) and waits for its
|
|
1027
|
+
finalizers before re-raising CancelledError; a second cancel during that wait stops waiting
|
|
1028
|
+
and leaves the fiber to finish."""
|
|
1029
|
+
fut: asyncio.Future[Exit[A, E]] = asyncio.get_running_loop().create_future()
|
|
1030
|
+
fiber.add_observer(lambda ex: None if fut.done() else fut.set_result(ex))
|
|
1031
|
+
try:
|
|
1032
|
+
return await asyncio.shield(fut)
|
|
1033
|
+
except asyncio.CancelledError:
|
|
1034
|
+
fiber.interrupt_unsafe()
|
|
1035
|
+
await fut
|
|
1036
|
+
raise
|
|
1037
|
+
|
|
1038
|
+
|
|
1039
|
+
async def run_exit[A, E](eff: Effect[A, E, Never]) -> Exit[A, E]:
|
|
1040
|
+
"""Run on the current asyncio loop and return the Exit. The fiber starts at once, so its
|
|
1041
|
+
synchronous prefix runs before this first awaits (internal/effect.ts:5777, runForkWith).
|
|
1042
|
+
Cancelling the awaiting task interrupts the fiber and waits for its finalizers before
|
|
1043
|
+
re-raising CancelledError (``await_exit``)."""
|
|
1044
|
+
return await await_exit(_start(None, eff, EMPTY_CONTEXT))
|
|
1045
|
+
|
|
1046
|
+
|
|
1047
|
+
async def run[A](eff: Effect[A, Never, Never]) -> A:
|
|
1048
|
+
"""Run and return the value; a failure raises cause.squash()."""
|
|
1049
|
+
exit_ = await run_exit(eff)
|
|
1050
|
+
if isinstance(exit_, Success):
|
|
1051
|
+
return exit_.value
|
|
1052
|
+
raise exit_.cause.squash()
|
|
1053
|
+
|
|
1054
|
+
|
|
1055
|
+
__all__ = [
|
|
1056
|
+
"DEFAULT_SCHEDULER",
|
|
1057
|
+
"UNIT",
|
|
1058
|
+
"Fiber",
|
|
1059
|
+
"FiberOwner",
|
|
1060
|
+
"FiberStartHook",
|
|
1061
|
+
"MixedScheduler",
|
|
1062
|
+
"RootRunner",
|
|
1063
|
+
"SchedulerDispatcher",
|
|
1064
|
+
"SchedulerService",
|
|
1065
|
+
"await_all",
|
|
1066
|
+
"await_exit",
|
|
1067
|
+
"for_each",
|
|
1068
|
+
"fork",
|
|
1069
|
+
"fork_daemon",
|
|
1070
|
+
"fork_in_owner",
|
|
1071
|
+
"interrupt_all",
|
|
1072
|
+
"race",
|
|
1073
|
+
"race_all",
|
|
1074
|
+
"race_all_first",
|
|
1075
|
+
"race_first",
|
|
1076
|
+
"run",
|
|
1077
|
+
"run_exit",
|
|
1078
|
+
"run_fork",
|
|
1079
|
+
"run_fork_with",
|
|
1080
|
+
"run_in_owner",
|
|
1081
|
+
"with_dispatcher",
|
|
1082
|
+
]
|