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/semaphore.py ADDED
@@ -0,0 +1,255 @@
1
+ """A semaphore: a resizable count of permits that fibers take, wait for, and release.
2
+
3
+ Pinned Effect v4 src/Semaphore.ts:234-387. A request takes at once only when enough permits are
4
+ free and no queued request fits (:256); otherwise it queues. A release wakes, on the releasing
5
+ fiber's dispatcher, the queued requests the free permits cover; a woken request re-checks and
6
+ may queue again. A smaller later request can overtake a larger earlier one (:243-247): the queue
7
+ is not FIFO. Upstream's module-level duals only delegate to these methods and are not ported.
8
+
9
+ Leaving the queue and returning permits on exit happen as the exit frame pops, in one step with
10
+ queueing the follow-up wake on the running fiber's dispatcher, like upstream's synchronous onExit
11
+ callbacks (:263-268, :365-368, :380-383): core.on_exit_with_dispatcher. No yield can fall between
12
+ the state change and its wake.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ from collections.abc import Callable
18
+ from typing import Never, Protocol, final
19
+
20
+ from .core import (
21
+ Effect,
22
+ async_,
23
+ on_exit_with_dispatcher,
24
+ succeed,
25
+ suspend,
26
+ sync,
27
+ uninterruptible_mask,
28
+ )
29
+ from .fiber import SchedulerDispatcher, with_dispatcher
30
+ from .option import Option, Some
31
+ from .scope import Scope, scope
32
+
33
+ type _Resume = Callable[[Effect[None, Never, Never]], None]
34
+
35
+ _unit: Effect[None, Never, Never] = succeed(None)
36
+
37
+
38
+ class _Restore(Protocol):
39
+ def __call__[A, E, R](self, eff: Effect[A, E, R], /) -> Effect[A, E, R]: ...
40
+
41
+
42
+ def _unmasked[A, E, R](eff: Effect[A, E, R]) -> Effect[A, E, R]:
43
+ return eff
44
+
45
+
46
+ class WithPermits(Protocol):
47
+ """``sem.with_permits(n)``: run an effect while holding n permits."""
48
+
49
+ def __call__[A, E, R](self, eff: Effect[A, E, R], /) -> Effect[A, E, R]: ...
50
+
51
+
52
+ class WithPermitsIfAvailable(Protocol):
53
+ """``sem.with_permits_if_available(n)``: Some(result), or None without running when short."""
54
+
55
+ def __call__[A, E, R](self, eff: Effect[A, E, R], /) -> Effect[Option[A], E, R]: ...
56
+
57
+
58
+ @final
59
+ class _Waiter:
60
+ """One queued request (:236-239). A wake clears ``resume``; it reserves nothing."""
61
+
62
+ __slots__ = ("permits", "resume")
63
+
64
+ def __init__(self, permits: int) -> None:
65
+ self.permits = permits
66
+ self.resume: _Resume | None = None
67
+
68
+
69
+ @final
70
+ class Semaphore:
71
+ """``waiters`` keeps insertion order, like upstream's Set; ``free`` may go negative after a
72
+ resize, or above ``permits`` after release_all (:177-190)."""
73
+
74
+ __slots__ = ("permits", "taken", "waiters")
75
+
76
+ def __init__(self, permits: int) -> None:
77
+ self.waiters: dict[_Waiter, None] = {}
78
+ self.taken = 0
79
+ self.permits = permits
80
+
81
+ @classmethod
82
+ def make_unsafe(cls, permits: int) -> Semaphore:
83
+ """:234."""
84
+ return cls(permits)
85
+
86
+ @classmethod
87
+ def make(cls, permits: int) -> Effect[Semaphore, Never, Never]:
88
+ """A fresh semaphore each time this effect runs (:424)."""
89
+ return sync(lambda: cls(permits))
90
+
91
+ @property
92
+ def free(self) -> int:
93
+ return self.permits - self.taken
94
+
95
+ def _first_available(self) -> _Waiter | None:
96
+ """firstAvailableWaiter, :241-247."""
97
+ for waiter in self.waiters:
98
+ if waiter.permits <= self.free:
99
+ return waiter
100
+ return None
101
+
102
+ def _wake(self) -> None:
103
+ """The task releaseUnsafe queues (:323-336): wake every request the free permits cover,
104
+ counting already-woken ones, over a snapshot because resumed fibers run inline."""
105
+ remaining = self.free
106
+ for waiter in list(self.waiters):
107
+ if waiter not in self.waiters or waiter.permits > remaining:
108
+ continue
109
+ remaining -= waiter.permits
110
+ resume, waiter.resume = waiter.resume, None
111
+ if resume is not None:
112
+ resume(_unit)
113
+
114
+ def _release_unsafe(self, dispatcher: SchedulerDispatcher, permits: int) -> int:
115
+ """releaseUnsafe, :320-339."""
116
+ self.taken -= permits
117
+ if self.waiters:
118
+ dispatcher.schedule_task(self._wake, 0)
119
+ return self.free
120
+
121
+ def _release_on_exit(self, permits: int) -> Callable[[object, SchedulerDispatcher], None]:
122
+ """The exit callback of withPermits/withPermitsIfAvailable (:365-368, :380-383)."""
123
+
124
+ def release(_: object, dispatcher: SchedulerDispatcher) -> None:
125
+ self._release_unsafe(dispatcher, permits)
126
+
127
+ return release
128
+
129
+ def _leave_unsafe(self, waiter: _Waiter, dispatcher: SchedulerDispatcher) -> None:
130
+ """`remove`, :263-266: leave the queue and let the others re-check, in one step."""
131
+ if waiter in self.waiters:
132
+ del self.waiters[waiter]
133
+ self._release_unsafe(dispatcher, 0)
134
+
135
+ def _take_permits[A, E, R](
136
+ self, n: int, on_acquire: Callable[[], Effect[A, E, R]], restore: _Restore = _unmasked
137
+ ) -> Effect[A, E, R]:
138
+ """takePermits, :249-284. Upstream queues the waiter and pushes its exit frame in one
139
+ step (onExitUnsafe puts a continuation frame on the fiber's stack, internal/effect.ts:
140
+ 4324-4329). Here the frame is pushed first and the waiter queued inside it, so no
141
+ interrupt can fall between queueing and the frame; see
142
+ test_queued_take_interrupted_at_any_operation_leaves_no_queue_entry."""
143
+
144
+ def run() -> Effect[A, E, R]:
145
+ waiter = _Waiter(n)
146
+
147
+ def start() -> Effect[A, E, R]:
148
+ if self.free >= n and self._first_available() is None:
149
+ self.taken += n
150
+ return on_acquire()
151
+ self.waiters[waiter] = None
152
+ return loop
153
+
154
+ def register(resume: _Resume) -> None:
155
+ # The fiber may have yielded since the last check, missing a wake (:270).
156
+ if self._first_available() is waiter:
157
+ resume(_unit)
158
+ else:
159
+ waiter.resume = resume
160
+
161
+ def after(dispatcher: SchedulerDispatcher) -> Effect[A, E, R]:
162
+ if self._first_available() is not waiter:
163
+ return loop
164
+ self.taken += n
165
+ self._leave_unsafe(waiter, dispatcher)
166
+ return on_acquire()
167
+
168
+ def leave(_: object, dispatcher: SchedulerDispatcher) -> None:
169
+ self._leave_unsafe(waiter, dispatcher)
170
+
171
+ loop = restore(async_(register)).flat_map(lambda _: with_dispatcher(after))
172
+ return on_exit_with_dispatcher(suspend(start), leave)
173
+
174
+ return suspend(run)
175
+
176
+ def take(self, permits: int) -> Effect[int, Never, Never]:
177
+ """Wait for and take permits; not released on interruption after taking (:299-301)."""
178
+ return self._take_permits(permits, lambda: succeed(permits))
179
+
180
+ def take_scoped(self, permits: int) -> Effect[None, Never, Scope]:
181
+ """Take permits and release them when the scope closes (:303-310)."""
182
+ return uninterruptible_mask(
183
+ lambda restore: scope.flat_map(
184
+ lambda s: self._take_permits(
185
+ permits, lambda: Scope.add_finalizer(s, self.release(permits)), restore
186
+ )
187
+ )
188
+ )
189
+
190
+ def take_if_available(self, permits: int) -> Effect[bool, Never, Never]:
191
+ """Take only if free now, ignoring queued requests (:312-318)."""
192
+
193
+ def go() -> Effect[bool, Never, Never]:
194
+ if self.free < permits:
195
+ return succeed(False)
196
+ self.taken += permits
197
+ return succeed(True)
198
+
199
+ return suspend(go)
200
+
201
+ def release(self, permits: int) -> Effect[int, Never, Never]:
202
+ """Release permits and return how many are free (:350-352)."""
203
+ return with_dispatcher(lambda d: succeed(self._release_unsafe(d, permits)))
204
+
205
+ def release_all(self) -> Effect[int, Never, Never]:
206
+ """Release everything taken, including permits other holders will still release
207
+ (:354-356; documented at :177-190)."""
208
+ return with_dispatcher(lambda d: succeed(self._release_unsafe(d, self.taken)))
209
+
210
+ def resize(self, permits: int) -> Effect[None, Never, Never]:
211
+ """Change the total; wakes queued requests only if none is over-taken (:341-348)."""
212
+
213
+ def go(dispatcher: SchedulerDispatcher) -> Effect[None, Never, Never]:
214
+ self.permits = permits
215
+ if self.free >= 0:
216
+ self._release_unsafe(dispatcher, 0)
217
+ return _unit
218
+
219
+ return with_dispatcher(go)
220
+
221
+ def with_permits(self, permits: int) -> WithPermits:
222
+ """Run an effect holding permits, released however it ends (:358-372)."""
223
+
224
+ def gate[A, E, R](eff: Effect[A, E, R]) -> Effect[A, E, R]:
225
+ return uninterruptible_mask(
226
+ lambda restore: self._take_permits(
227
+ permits,
228
+ lambda: on_exit_with_dispatcher(restore(eff), self._release_on_exit(permits)),
229
+ restore,
230
+ )
231
+ )
232
+
233
+ return gate
234
+
235
+ def with_permit[A, E, R](self, eff: Effect[A, E, R]) -> Effect[A, E, R]:
236
+ """:374."""
237
+ return self.with_permits(1)(eff)
238
+
239
+ def with_permits_if_available(self, permits: int) -> WithPermitsIfAvailable:
240
+ """Some(result) holding permits, or None at once when short (:376-386)."""
241
+
242
+ def gate[A, E, R](eff: Effect[A, E, R]) -> Effect[Option[A], E, R]:
243
+ def body(restore: _Restore) -> Effect[Option[A], E, R]:
244
+ def go() -> Effect[Option[A], E, R]:
245
+ if self.free < permits:
246
+ return succeed(None)
247
+ self.taken += permits
248
+ held = restore(eff.map(Some[A]))
249
+ return on_exit_with_dispatcher(held, self._release_on_exit(permits))
250
+
251
+ return suspend(go)
252
+
253
+ return uninterruptible_mask(body)
254
+
255
+ return gate
@@ -0,0 +1,183 @@
1
+ """A Ref whose updates may run effects, serialized by a one-permit semaphore.
2
+
3
+ Pinned Effect v4 src/SynchronizedRef.ts. Every update holds `semaphore.with_permit`: the pure
4
+ ones run the Ref operation on `backing` under it, and each effectful one reads the value inside
5
+ `suspend` once it holds the permit, runs the user effect, and writes only in the continuation of
6
+ that effect's success. A failure, defect, or interruption before that continuation writes
7
+ nothing; the permit is released however the update ends (Semaphore.ts:358-372). `get` and
8
+ `get_unsafe` read without the permit.
9
+
10
+ The semaphore is not reentrant: an update whose function runs an update on the same ref waits
11
+ for the permit its own caller holds, and parks until interrupted.
12
+
13
+ Upstream's data-first/data-last duals only select the receiver and are not separate API; the
14
+ Pipeable/Inspectable protocol and toJSON are not ported. Option is `Some[A] | None`, and
15
+ `Some(None)` is a present value (`Option.isNone` tests the tag).
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ from collections.abc import Callable
21
+ from typing import Never, final
22
+
23
+ from .core import Effect, succeed, suspend, sync
24
+ from .option import Option
25
+ from .ref import Ref
26
+ from .semaphore import Semaphore
27
+
28
+
29
+ @final
30
+ class SynchronizedRef[A]:
31
+ """`backing` and `semaphore` are public, as in upstream's interface. Invariant in A."""
32
+
33
+ __slots__ = ("backing", "semaphore")
34
+
35
+ def __init__(self, value: A) -> None:
36
+ self.semaphore: Semaphore = Semaphore.make_unsafe(1)
37
+ self.backing: Ref[A] = Ref[A].make_unsafe(value)
38
+
39
+ @classmethod
40
+ def make_unsafe(cls, value: A) -> SynchronizedRef[A]:
41
+ """SynchronizedRef.ts makeUnsafe."""
42
+ return cls(value)
43
+
44
+ @classmethod
45
+ def make(cls, value: A) -> Effect[SynchronizedRef[A], Never, Never]:
46
+ """A fresh ref and semaphore each time this effect runs (SynchronizedRef.ts make)."""
47
+ return sync(lambda: cls(value))
48
+
49
+ def get_unsafe(self) -> A:
50
+ return self.backing.current
51
+
52
+ def get(self) -> Effect[A, Never, Never]:
53
+ """Not synchronized: reads without the permit (SynchronizedRef.ts get)."""
54
+ return sync(self.get_unsafe)
55
+
56
+ # -- pure updates: withPermit(Ref.op(backing, ...)) --------------------------------------------
57
+
58
+ def set(self, value: A) -> Effect[None, Never, Never]:
59
+ return self.semaphore.with_permit(self.backing.set(value))
60
+
61
+ def get_and_set(self, value: A) -> Effect[A, Never, Never]:
62
+ return self.semaphore.with_permit(self.backing.get_and_set(value))
63
+
64
+ def set_and_get(self, value: A) -> Effect[A, Never, Never]:
65
+ return self.semaphore.with_permit(self.backing.set_and_get(value))
66
+
67
+ def get_and_update(self, f: Callable[[A], A]) -> Effect[A, Never, Never]:
68
+ return self.semaphore.with_permit(self.backing.get_and_update(f))
69
+
70
+ def get_and_update_some(self, pf: Callable[[A], Option[A]]) -> Effect[A, Never, Never]:
71
+ return self.semaphore.with_permit(self.backing.get_and_update_some(pf))
72
+
73
+ def modify[B](self, f: Callable[[A], tuple[B, A]]) -> Effect[B, Never, Never]:
74
+ return self.semaphore.with_permit(self.backing.modify(f))
75
+
76
+ def modify_some[B](self, pf: Callable[[A], tuple[B, Option[A]]]) -> Effect[B, Never, Never]:
77
+ return self.semaphore.with_permit(self.backing.modify_some(pf))
78
+
79
+ def update(self, f: Callable[[A], A]) -> Effect[None, Never, Never]:
80
+ return self.semaphore.with_permit(self.backing.update(f))
81
+
82
+ def update_and_get(self, f: Callable[[A], A]) -> Effect[A, Never, Never]:
83
+ return self.semaphore.with_permit(self.backing.update_and_get(f))
84
+
85
+ def update_some(self, f: Callable[[A], Option[A]]) -> Effect[None, Never, Never]:
86
+ return self.semaphore.with_permit(self.backing.update_some(f))
87
+
88
+ def update_some_and_get(self, pf: Callable[[A], Option[A]]) -> Effect[A, Never, Never]:
89
+ return self.semaphore.with_permit(self.backing.update_some_and_get(pf))
90
+
91
+ # -- effectful updates: withPermit(suspend(read, run f, write on its success)) ---------------
92
+
93
+ def _locked[T, E, R](self, body: Callable[[A], Effect[T, E, R]]) -> Effect[T, E, R]:
94
+ """`semaphore.withPermit(Effect.suspend(() => body(getUnsafe(self))))`."""
95
+ return self.semaphore.with_permit(suspend(lambda: body(self.get_unsafe())))
96
+
97
+ def _write(self, value: A) -> None:
98
+ self.backing.current = value
99
+
100
+ def get_and_update_effect[E, R](self, f: Callable[[A], Effect[A, E, R]]) -> Effect[A, E, R]:
101
+ def body(value: A) -> Effect[A, E, R]:
102
+ def write(new_value: A) -> A:
103
+ self._write(new_value)
104
+ return value
105
+
106
+ return f(value).map(write)
107
+
108
+ return self._locked(body)
109
+
110
+ def get_and_update_some_effect[E, R](
111
+ self, pf: Callable[[A], Effect[Option[A], E, R]]
112
+ ) -> Effect[A, E, R]:
113
+ def body(value: A) -> Effect[A, E, R]:
114
+ def write(option: Option[A]) -> Effect[A, Never, Never]:
115
+ if option is None:
116
+ return succeed(value)
117
+ self._write(option.value)
118
+ return succeed(value)
119
+
120
+ return pf(value).flat_map(write)
121
+
122
+ return self._locked(body)
123
+
124
+ def modify_effect[B, E, R](
125
+ self, f: Callable[[A], Effect[tuple[B, A], E, R]]
126
+ ) -> Effect[B, E, R]:
127
+ def body(value: A) -> Effect[B, E, R]:
128
+ def write(result: tuple[B, A]) -> B:
129
+ b, a = result
130
+ self._write(a)
131
+ return b
132
+
133
+ return f(value).map(write)
134
+
135
+ return self._locked(body)
136
+
137
+ def modify_some_effect[B, E, R](
138
+ self, pf: Callable[[A], Effect[tuple[B, Option[A]], E, R]]
139
+ ) -> Effect[B, E, R]:
140
+ def body(value: A) -> Effect[B, E, R]:
141
+ def write(result: tuple[B, Option[A]]) -> Effect[B, Never, Never]:
142
+ b, maybe_a = result
143
+ if maybe_a is None:
144
+ return succeed(b)
145
+ self._write(maybe_a.value)
146
+ return succeed(b)
147
+
148
+ return pf(value).flat_map(write)
149
+
150
+ return self._locked(body)
151
+
152
+ def update_effect[E, R](self, f: Callable[[A], Effect[A, E, R]]) -> Effect[None, E, R]:
153
+ return self._locked(lambda value: f(value).map(self._write))
154
+
155
+ def update_and_get_effect[E, R](self, f: Callable[[A], Effect[A, E, R]]) -> Effect[A, E, R]:
156
+ def write(new_value: A) -> A:
157
+ self._write(new_value)
158
+ return new_value
159
+
160
+ return self._locked(lambda value: f(value).map(write))
161
+
162
+ def update_some_effect[E, R](
163
+ self, pf: Callable[[A], Effect[Option[A], E, R]]
164
+ ) -> Effect[None, E, R]:
165
+ def write(option: Option[A]) -> None:
166
+ if option is not None:
167
+ self._write(option.value)
168
+
169
+ return self._locked(lambda value: pf(value).map(write))
170
+
171
+ def update_some_and_get_effect[E, R](
172
+ self, pf: Callable[[A], Effect[Option[A], E, R]]
173
+ ) -> Effect[A, E, R]:
174
+ def body(value: A) -> Effect[A, E, R]:
175
+ def write(option: Option[A]) -> Effect[A, Never, Never]:
176
+ if option is None:
177
+ return succeed(value)
178
+ self._write(option.value)
179
+ return succeed(option.value)
180
+
181
+ return pf(value).flat_map(write)
182
+
183
+ return self._locked(body)
@@ -0,0 +1,7 @@
1
+ """Test services: TestClock (time moves only when the test moves it) and TestConsole (records
2
+ what a program prints). Effect v4: src/testing/."""
3
+
4
+ from ._clock import TestClock, TestClockService
5
+ from ._console import TestConsole, TestConsoleService
6
+
7
+ __all__ = ["TestClock", "TestClockService", "TestConsole", "TestConsoleService"]