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/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
+ ]