peffect 0.1.2__tar.gz
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-0.1.2/.agents/README.md +24 -0
- peffect-0.1.2/.agents/setup +69 -0
- peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_no_loop_top.cfg +4 -0
- peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_no_mask_check.cfg +4 -0
- peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_no_notify.cfg +4 -0
- peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_no_park_done.cfg +4 -0
- peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_no_token_claim.cfg +4 -0
- peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_no_wait.cfg +4 -0
- peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_old_done.cfg +4 -0
- peffect-0.1.2/.claude/skills/verify-formal-kernel/FiberKernel.cfg +4 -0
- peffect-0.1.2/.claude/skills/verify-formal-kernel/FiberKernel.tla +294 -0
- peffect-0.1.2/.claude/skills/verify-formal-kernel/SKILL.md +221 -0
- peffect-0.1.2/.claude/skills/verify-formal-kernel/run.sh +12 -0
- peffect-0.1.2/.claude/skills/verify-formal-kernel/tlc_chart.py +939 -0
- peffect-0.1.2/.claude/skills/verify-peffect/SKILL.md +60 -0
- peffect-0.1.2/.claude/skills/verify-peffect/features/README.md +24 -0
- peffect-0.1.2/.claude/skills/verify-peffect/features/boundary-lint.md +40 -0
- peffect-0.1.2/.claude/skills/verify-peffect/features/clock.md +50 -0
- peffect-0.1.2/.claude/skills/verify-peffect/features/context.md +46 -0
- peffect-0.1.2/.claude/skills/verify-peffect/features/parity.md +27 -0
- peffect-0.1.2/.claude/skills/verify-peffect/features/quickstart.md +44 -0
- peffect-0.1.2/.claude/skills/verify-peffect/features/scope.md +42 -0
- peffect-0.1.2/.claude/skills/verify-peffect/run.sh +58 -0
- peffect-0.1.2/.github/workflows/release.yml +67 -0
- peffect-0.1.2/.gitignore +5 -0
- peffect-0.1.2/.gitmodules +3 -0
- peffect-0.1.2/AGENTS.md +133 -0
- peffect-0.1.2/CHANGELOG.md +31 -0
- peffect-0.1.2/PKG-INFO +6 -0
- peffect-0.1.2/docs/APPLICATION_PATTERN_AUDIT.md +69 -0
- peffect-0.1.2/docs/DESIGN.md +133 -0
- peffect-0.1.2/docs/FIRST_USABLE_SLICE.md +81 -0
- peffect-0.1.2/docs/INVARIANTS.md +581 -0
- peffect-0.1.2/docs/QUEUE_SOURCE_MAP.md +171 -0
- peffect-0.1.2/docs/RELEASING.md +53 -0
- peffect-0.1.2/docs/ROADMAP.md +241 -0
- peffect-0.1.2/docs/UPSTREAM_TESTS.md +510 -0
- peffect-0.1.2/docs/lessons/01-kernel.html +60 -0
- peffect-0.1.2/docs/lessons/02-verification.html +55 -0
- peffect-0.1.2/docs/lessons/03-boundaries.html +51 -0
- peffect-0.1.2/docs/lessons/04-context.html +38 -0
- peffect-0.1.2/docs/lessons/05-clock.html +37 -0
- peffect-0.1.2/docs/lessons/06-testclock.html +35 -0
- peffect-0.1.2/docs/lessons/07-ref.html +16 -0
- peffect-0.1.2/docs/lessons/08-queue.html +38 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/README.md +28 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/REPORT.md +252 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/optional-packages.html +1 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/optional-packages.md +62 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/scout-1.md +27 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/scout-2.md +19 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/scout-3.md +27 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/scout-4.md +32 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/scout-5.md +22 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/scout-6.md +25 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/scout-7.md +15 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/scout-8.md +26 -0
- peffect-0.1.2/docs/research/2026-11-15-roi/waves.html +70 -0
- peffect-0.1.2/docs/scouts/cause-exit.md +70 -0
- peffect-0.1.2/docs/scouts/config-data.md +53 -0
- peffect-0.1.2/docs/scouts/context.md +63 -0
- peffect-0.1.2/docs/scouts/fibers.md +90 -0
- peffect-0.1.2/docs/scouts/kernel.md +97 -0
- peffect-0.1.2/docs/scouts/layer-scope.md +71 -0
- peffect-0.1.2/docs/scouts/observability.md +40 -0
- peffect-0.1.2/docs/scouts/schedule-clock.md +44 -0
- peffect-0.1.2/docs/scouts/schema.md +64 -0
- peffect-0.1.2/docs/scouts/stream.md +37 -0
- peffect-0.1.2/examples/clock.py +107 -0
- peffect-0.1.2/examples/context.py +80 -0
- peffect-0.1.2/examples/parity/.gitignore +1 -0
- peffect-0.1.2/examples/parity/README.md +211 -0
- peffect-0.1.2/examples/parity/app.ts +158 -0
- peffect-0.1.2/examples/parity/batch.ts +94 -0
- peffect-0.1.2/examples/parity/batch_scenarios.ts +42 -0
- peffect-0.1.2/examples/parity/bun.lock +15 -0
- peffect-0.1.2/examples/parity/compare.py +146 -0
- peffect-0.1.2/examples/parity/composed.ts +87 -0
- peffect-0.1.2/examples/parity/composed_scenarios.ts +61 -0
- peffect-0.1.2/examples/parity/fixtures/check.output.json +60 -0
- peffect-0.1.2/examples/parity/fixtures/check.ts +51 -0
- peffect-0.1.2/examples/parity/fixtures/negative.ts +40 -0
- peffect-0.1.2/examples/parity/fixtures/positive.ts +23 -0
- peffect-0.1.2/examples/parity/outcomes.ts +31 -0
- peffect-0.1.2/examples/parity/package.json +13 -0
- peffect-0.1.2/examples/parity/python_app.py +204 -0
- peffect-0.1.2/examples/parity/python_batch.py +172 -0
- peffect-0.1.2/examples/parity/python_batch_scenarios.py +58 -0
- peffect-0.1.2/examples/parity/python_composed.py +177 -0
- peffect-0.1.2/examples/parity/python_reference.py +160 -0
- peffect-0.1.2/examples/parity/python_scenarios.py +103 -0
- peffect-0.1.2/examples/parity/reference.output.json +664 -0
- peffect-0.1.2/examples/parity/reference.ts +88 -0
- peffect-0.1.2/examples/parity/tsconfig.json +20 -0
- peffect-0.1.2/examples/queue_worker.py +219 -0
- peffect-0.1.2/examples/quickstart.py +84 -0
- peffect-0.1.2/examples/scope.py +91 -0
- peffect-0.1.2/prototypes/pfx/docs/overview.html +60 -0
- peffect-0.1.2/prototypes/pfx/examples/__init__.py +0 -0
- peffect-0.1.2/prototypes/pfx/examples/app.py +162 -0
- peffect-0.1.2/prototypes/pfx/pyproject.toml +46 -0
- peffect-0.1.2/prototypes/pfx/src/pfx/__init__.py +40 -0
- peffect-0.1.2/prototypes/pfx/src/pfx/core.py +307 -0
- peffect-0.1.2/prototypes/pfx/src/pfx/layer.py +189 -0
- peffect-0.1.2/prototypes/pfx/src/pfx/py.typed +0 -0
- peffect-0.1.2/prototypes/pfx/src/pfx/schema.py +72 -0
- peffect-0.1.2/prototypes/pfx/tests/test_runtime.py +126 -0
- peffect-0.1.2/prototypes/pfx/tests/test_types.py +31 -0
- peffect-0.1.2/prototypes/pfx/typetests/declared.py +39 -0
- peffect-0.1.2/prototypes/pfx/typetests/should_fail.py +48 -0
- peffect-0.1.2/prototypes/pfx/typetests/should_pass.py +39 -0
- peffect-0.1.2/prototypes/pfx/typetests/syntax/alternatives.py +68 -0
- peffect-0.1.2/prototypes/pfx/uv.lock +571 -0
- peffect-0.1.2/pyproject.toml +52 -0
- peffect-0.1.2/scripts/check_boundaries.py +350 -0
- peffect-0.1.2/src/peffect/__init__.py +223 -0
- peffect-0.1.2/src/peffect/cause.py +177 -0
- peffect-0.1.2/src/peffect/clock.py +130 -0
- peffect-0.1.2/src/peffect/console.py +99 -0
- peffect-0.1.2/src/peffect/context.py +258 -0
- peffect-0.1.2/src/peffect/core.py +1273 -0
- peffect-0.1.2/src/peffect/deferred.py +99 -0
- peffect-0.1.2/src/peffect/duration.py +497 -0
- peffect-0.1.2/src/peffect/fiber.py +1082 -0
- peffect-0.1.2/src/peffect/latch.py +120 -0
- peffect-0.1.2/src/peffect/layer.py +789 -0
- peffect-0.1.2/src/peffect/logger.py +166 -0
- peffect-0.1.2/src/peffect/managed_runtime.py +325 -0
- peffect-0.1.2/src/peffect/option.py +50 -0
- peffect-0.1.2/src/peffect/pull.py +116 -0
- peffect-0.1.2/src/peffect/py.typed +0 -0
- peffect-0.1.2/src/peffect/queue.py +670 -0
- peffect-0.1.2/src/peffect/ref.py +133 -0
- peffect-0.1.2/src/peffect/resources.py +113 -0
- peffect-0.1.2/src/peffect/scheduler.py +55 -0
- peffect-0.1.2/src/peffect/scope.py +394 -0
- peffect-0.1.2/src/peffect/semaphore.py +255 -0
- peffect-0.1.2/src/peffect/synchronized_ref.py +183 -0
- peffect-0.1.2/src/peffect/testing/__init__.py +7 -0
- peffect-0.1.2/src/peffect/testing/_clock.py +453 -0
- peffect-0.1.2/src/peffect/testing/_console.py +105 -0
- peffect-0.1.2/src/peffect/timeout.py +67 -0
- peffect-0.1.2/tests/conftest.py +9 -0
- peffect-0.1.2/tests/test_application_parity.py +234 -0
- peffect-0.1.2/tests/test_boundaries.py +260 -0
- peffect-0.1.2/tests/test_clock.py +48 -0
- peffect-0.1.2/tests/test_clock_duration_upstream.py +217 -0
- peffect-0.1.2/tests/test_clock_sleep.py +176 -0
- peffect-0.1.2/tests/test_composition_upstream.py +370 -0
- peffect-0.1.2/tests/test_console_logger.py +413 -0
- peffect-0.1.2/tests/test_context.py +330 -0
- peffect-0.1.2/tests/test_context_identity_upstream.py +243 -0
- peffect-0.1.2/tests/test_context_upstream.py +242 -0
- peffect-0.1.2/tests/test_deferred_upstream.py +240 -0
- peffect-0.1.2/tests/test_duration_format_upstream.py +119 -0
- peffect-0.1.2/tests/test_duration_upstream.py +416 -0
- peffect-0.1.2/tests/test_fiber_bulk_upstream.py +254 -0
- peffect-0.1.2/tests/test_fiber_lifecycle_upstream.py +438 -0
- peffect-0.1.2/tests/test_fiber_resume_upstream.py +247 -0
- peffect-0.1.2/tests/test_fiber_start_upstream.py +270 -0
- peffect-0.1.2/tests/test_finalization_upstream.py +139 -0
- peffect-0.1.2/tests/test_fork_scoped_upstream.py +85 -0
- peffect-0.1.2/tests/test_gen_cleanup.py +197 -0
- peffect-0.1.2/tests/test_kernel.py +322 -0
- peffect-0.1.2/tests/test_kernel_props.py +361 -0
- peffect-0.1.2/tests/test_latch_upstream.py +460 -0
- peffect-0.1.2/tests/test_layer_upstream.py +528 -0
- peffect-0.1.2/tests/test_managed_runtime_interleavings.py +363 -0
- peffect-0.1.2/tests/test_managed_runtime_upstream.py +842 -0
- peffect-0.1.2/tests/test_option.py +100 -0
- peffect-0.1.2/tests/test_pull_upstream.py +254 -0
- peffect-0.1.2/tests/test_queue_interleavings.py +290 -0
- peffect-0.1.2/tests/test_queue_props.py +446 -0
- peffect-0.1.2/tests/test_queue_upstream.py +722 -0
- peffect-0.1.2/tests/test_queue_worker.py +17 -0
- peffect-0.1.2/tests/test_race_review_regressions.py +52 -0
- peffect-0.1.2/tests/test_race_timeout_upstream.py +1141 -0
- peffect-0.1.2/tests/test_ref_props.py +456 -0
- peffect-0.1.2/tests/test_ref_upstream.py +345 -0
- peffect-0.1.2/tests/test_resources_upstream.py +367 -0
- peffect-0.1.2/tests/test_root_context.py +28 -0
- peffect-0.1.2/tests/test_scheduler_upstream.py +311 -0
- peffect-0.1.2/tests/test_scope.py +521 -0
- peffect-0.1.2/tests/test_scope_add_finalizer_unsafe.py +42 -0
- peffect-0.1.2/tests/test_scope_parallel.py +233 -0
- peffect-0.1.2/tests/test_semaphore_upstream.py +1037 -0
- peffect-0.1.2/tests/test_suspend_exit.py +281 -0
- peffect-0.1.2/tests/test_synchronized_ref_upstream.py +611 -0
- peffect-0.1.2/tests/test_testclock.py +894 -0
- peffect-0.1.2/tests/test_traversal_upstream.py +541 -0
- peffect-0.1.2/tests/test_types.py +58 -0
- peffect-0.1.2/typetests/declared.py +39 -0
- peffect-0.1.2/typetests/should_fail.py +731 -0
- peffect-0.1.2/typetests/should_pass.py +858 -0
- peffect-0.1.2/untangle-log.md +79 -0
- peffect-0.1.2/uv.lock +651 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Development setup
|
|
2
|
+
|
|
3
|
+
Run `./.agents/setup` from any directory. Re-run after a Scotty session resumes:
|
|
4
|
+
dependencies and installed tools are not preserved by its workspace snapshot.
|
|
5
|
+
|
|
6
|
+
The script targets Scotty's Debian image (passwordless sudo or root) and existing
|
|
7
|
+
macOS development hosts. It installs missing Debian prerequisites, uv 0.11.10,
|
|
8
|
+
Bun 1.3.13, managed Python 3.13, and dependencies from `uv.lock` and the parity
|
|
9
|
+
`bun.lock`. Python patch releases and Debian packages follow their repositories;
|
|
10
|
+
this is a repeatable setup, not a hermetic image. macOS requires git, curl, unzip,
|
|
11
|
+
Node and Java already installed. Formal verification requires Java 11 or newer;
|
|
12
|
+
Debian setup installs Java 17 when missing.
|
|
13
|
+
|
|
14
|
+
Only an absent vendor submodule is initialized. An existing checkout at a different
|
|
15
|
+
revision fails without resetting it. No source files or lockfiles are rewritten.
|
|
16
|
+
Linux links uv and Bun into `/usr/local/bin` for subsequent agent turns. On macOS,
|
|
17
|
+
newly installed tools live in `~/.local/share/peffect-tools`; add its `bin` and
|
|
18
|
+
`bun/bin` directories to PATH if they were not already available.
|
|
19
|
+
|
|
20
|
+
peffect is a library: setup starts no server and requires no hatch URL.
|
|
21
|
+
Run `.claude/skills/verify-peffect/run.sh` for application parity, tests, lint and
|
|
22
|
+
types; `.claude/skills/verify-formal-kernel/run.sh` for bounded kernel verification;
|
|
23
|
+
and `uv build` for wheel and source distributions. Setup itself only checks tools
|
|
24
|
+
and the editable package import; it does not claim those verification suites pass.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Idempotent development setup for Scotty's Debian/Node image and existing macOS hosts.
|
|
3
|
+
set -euo pipefail
|
|
4
|
+
root="$(cd "$(dirname "$0")/.." && pwd)"
|
|
5
|
+
cd "$root"
|
|
6
|
+
uv_version=0.11.10
|
|
7
|
+
bun_version=1.3.13
|
|
8
|
+
python_version=3.13
|
|
9
|
+
tools_dir="${HOME}/.local/share/peffect-tools"
|
|
10
|
+
export PATH="$tools_dir/bin:$tools_dir/bun/bin:$PATH"
|
|
11
|
+
|
|
12
|
+
as_root() {
|
|
13
|
+
if [ "$(id -u)" -eq 0 ]; then "$@"; else sudo -n "$@"; fi
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
if [ "$(uname -s)" = Linux ] && command -v apt-get >/dev/null; then
|
|
17
|
+
missing=()
|
|
18
|
+
for pair in curl:curl unzip:unzip git:git node:nodejs java:openjdk-17-jre-headless; do
|
|
19
|
+
command -v "${pair%%:*}" >/dev/null || missing+=("${pair#*:}")
|
|
20
|
+
done
|
|
21
|
+
if [ "${#missing[@]}" -gt 0 ]; then
|
|
22
|
+
as_root apt-get update
|
|
23
|
+
as_root env DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends ca-certificates "${missing[@]}"
|
|
24
|
+
fi
|
|
25
|
+
fi
|
|
26
|
+
for tool in curl unzip git node java; do
|
|
27
|
+
command -v "$tool" >/dev/null || { echo "Missing $tool; install it and rerun .agents/setup" >&2; exit 1; }
|
|
28
|
+
done
|
|
29
|
+
# java may exist as a macOS launcher without an installed JRE.
|
|
30
|
+
java -version
|
|
31
|
+
mkdir -p "$tools_dir/bin"
|
|
32
|
+
setup_tmp="$(mktemp -d)"
|
|
33
|
+
trap 'rm -rf "$setup_tmp"' EXIT
|
|
34
|
+
if ! uv --version 2>/dev/null | grep -q "^uv $uv_version\( \|$\)"; then
|
|
35
|
+
curl -fsSL "https://astral.sh/uv/$uv_version/install.sh" -o "$setup_tmp/uv.sh"
|
|
36
|
+
UV_UNMANAGED_INSTALL="$tools_dir/bin" sh "$setup_tmp/uv.sh"
|
|
37
|
+
fi
|
|
38
|
+
if [ "$(bun --version 2>/dev/null || true)" != "$bun_version" ]; then
|
|
39
|
+
curl -fsSL https://bun.com/install -o "$setup_tmp/bun.sh"
|
|
40
|
+
BUN_INSTALL="$tools_dir/bun" bash "$setup_tmp/bun.sh" "bun-v$bun_version"
|
|
41
|
+
fi
|
|
42
|
+
# Make tools visible to later Scotty turns, not just this script's child processes.
|
|
43
|
+
if [ "$(uname -s)" = Linux ]; then
|
|
44
|
+
for tool in uv bun; do
|
|
45
|
+
tool_path="$(command -v "$tool")"
|
|
46
|
+
if [ "$tool_path" != "/usr/local/bin/$tool" ]; then
|
|
47
|
+
as_root ln -sfn "$tool_path" "/usr/local/bin/$tool"
|
|
48
|
+
fi
|
|
49
|
+
done
|
|
50
|
+
fi
|
|
51
|
+
|
|
52
|
+
# Initialize only a missing vendor checkout. Never reset an existing vendor tree.
|
|
53
|
+
if [ ! -f vendor/effect-v4/packages/effect/package.json ]; then
|
|
54
|
+
git submodule update --init vendor/effect-v4
|
|
55
|
+
fi
|
|
56
|
+
expected_vendor="$(git ls-tree HEAD vendor/effect-v4 | awk '{print $3}')"
|
|
57
|
+
actual_vendor="$(git -C vendor/effect-v4 rev-parse HEAD)"
|
|
58
|
+
[ "$actual_vendor" = "$expected_vendor" ] || { echo "Vendor differs from gitlink; refusing to reset it" >&2; exit 1; }
|
|
59
|
+
uv python install "$python_version"
|
|
60
|
+
uv sync --locked --python "$python_version"
|
|
61
|
+
(cd examples/parity && bun install --frozen-lockfile)
|
|
62
|
+
uv run --no-sync python -c 'import pathlib, peffect, sys; assert sys.version_info[:2] == (3, 13); assert pathlib.Path(peffect.__file__).resolve() == pathlib.Path("src/peffect/__init__.py").resolve(); print("Python", sys.version.split()[0], "| peffect import OK")'
|
|
63
|
+
uv --version
|
|
64
|
+
bun --version
|
|
65
|
+
node --version
|
|
66
|
+
echo 'Ready: peffect library environment (no server or public URL required).'
|
|
67
|
+
echo 'Verify: .claude/skills/verify-peffect/run.sh'
|
|
68
|
+
echo 'Formal: .claude/skills/verify-formal-kernel/run.sh'
|
|
69
|
+
echo 'Build: uv build'
|
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
---------------------------- MODULE FiberKernel ----------------------------
|
|
2
|
+
(* The fiber kernel's park / resume / interrupt / yield / children protocol.
|
|
3
|
+
|
|
4
|
+
Code: src/peffect/fiber.py (Fiber.evaluate, yield_now, interrupt_unsafe, _done, _await_all,
|
|
5
|
+
_start), src/peffect/core.py (Async, Failure, SetInterruptible). Effect v4 runs a fiber
|
|
6
|
+
synchronously inside whoever wakes it: a resume, an interrupt of a fiber that is not running,
|
|
7
|
+
an immediate fork and a root start all call `evaluate` before returning. So drives nest:
|
|
8
|
+
`cur` is the innermost running drive and `stk` the drives suspended under it, outermost
|
|
9
|
+
first. Every action is atomic: one asyncio loop, and `evaluate` never awaits.
|
|
10
|
+
|
|
11
|
+
Wakers may act at any point, nested in whatever drive is running (user code can call a
|
|
12
|
+
resume, `interrupt_unsafe` or a dispatcher `flush` from any node) or from the loop:
|
|
13
|
+
ExtResume, Interrupt and Drive (a dispatcher task) carry no `cur = "none"` guard.
|
|
14
|
+
|
|
15
|
+
Two fibers. P (the root, started at once) forks C with default or inherited mask, yields,
|
|
16
|
+
explicitly enables interruption, parks, and ends while C may still run. C yields, parks,
|
|
17
|
+
explicitly enables interruption, masks, parks inside the mask, and unmasks. Both regain
|
|
18
|
+
interruption before finishing: K7 does not cover permanently masked completion. An
|
|
19
|
+
interrupter interrupts P once. Async completions arrive at any point, late ones included. *)
|
|
20
|
+
EXTENDS Naturals, Sequences, FiniteSets
|
|
21
|
+
|
|
22
|
+
CONSTANT Break \* "none" = the code as it is; the other values mirror scratch breaks (SKILL.md)
|
|
23
|
+
|
|
24
|
+
Fibers == {"P", "C"}
|
|
25
|
+
Prog == [f \in Fibers |->
|
|
26
|
+
IF f = "P" THEN <<"fork", "yield", "enable", "park">>
|
|
27
|
+
ELSE <<"yield", "park", "enable", "mask", "park", "unmask">>]
|
|
28
|
+
End(f) == Len(Prog[f]) + 1
|
|
29
|
+
WAIT == 99 \* pc and park id while P is parked on _await_all in Fiber._done
|
|
30
|
+
|
|
31
|
+
VARIABLES
|
|
32
|
+
cur, \* the fiber whose evaluate is innermost, or "none" (no drive is running)
|
|
33
|
+
stk, \* drives suspended under cur's (nested evaluate), outermost first
|
|
34
|
+
fb, \* per-fiber state, fields below
|
|
35
|
+
started, \* C has been forked (fiber._start)
|
|
36
|
+
obs, \* P's _await_all observer is registered on C (Fiber.add_observer)
|
|
37
|
+
sent, \* the interrupter has called P.interrupt_unsafe
|
|
38
|
+
selfUsed \* a register has interrupted its own fiber (bounded to once)
|
|
39
|
+
vars == <<cur, stk, fb, started, obs, sent, selfUsed>>
|
|
40
|
+
|
|
41
|
+
(* fb[f] fields and the Fiber field each models:
|
|
42
|
+
pc next instruction (straight-line Prog), WAIT while waiting on children
|
|
43
|
+
node the node the running drive evaluates next: "start" | "ok" | "int" | "await" | "none"
|
|
44
|
+
intr Fiber.interruptible irq Fiber.interrupted is not None
|
|
45
|
+
dfr Fiber._deferred parked Fiber._parked is not None
|
|
46
|
+
pid id of the current Park (an Async, or a queued yield step) pdone Park.done
|
|
47
|
+
wakes claims of the current Park: resume, queued step or interrupt (K2)
|
|
48
|
+
ext ids of Async Parks whose completion is still pending (resume callbacks)
|
|
49
|
+
drv dispatcher tasks queued for this fiber: <<"start", 0>> (scheduled fork, a no-op
|
|
50
|
+
once exited) or <<"y", id>> (yield_now's step, a no-op once its Park is done)
|
|
51
|
+
st the fiber's first evaluate has run (an unstarted one has an empty stack)
|
|
52
|
+
ending Fiber._ending exit Fiber._exit ("none" | "ok" | "int")
|
|
53
|
+
pubs times _publish ran (K1) req an interrupt was requested before the exit *)
|
|
54
|
+
|
|
55
|
+
Init ==
|
|
56
|
+
\E parentIntr \in BOOLEAN :
|
|
57
|
+
/\ cur = "P" /\ stk = <<>> \* run_exit -> _start(None, ...): the root's evaluate runs at once
|
|
58
|
+
/\ fb = [f \in Fibers |->
|
|
59
|
+
[pc |-> 1, node |-> IF f = "P" THEN "start" ELSE "none",
|
|
60
|
+
intr |-> IF f = "P" THEN parentIntr ELSE TRUE, irq |-> FALSE, dfr |-> FALSE,
|
|
61
|
+
parked |-> FALSE, pid |-> 0, pdone |-> TRUE, wakes |-> 0, ext |-> {}, drv |-> <<>>,
|
|
62
|
+
st |-> f = "P",
|
|
63
|
+
ending |-> "none", exit |-> "none", pubs |-> 0, req |-> FALSE]]
|
|
64
|
+
/\ started = FALSE /\ obs = FALSE /\ sent = FALSE /\ selfUsed = FALSE
|
|
65
|
+
|
|
66
|
+
InStk(f) == \E i \in 1..Len(stk) : stk[i] = f
|
|
67
|
+
Running(f) == cur = f \/ InStk(f) \* Fiber.running
|
|
68
|
+
|
|
69
|
+
\* f's evaluate starts now, nested in the running drive (or from the loop)
|
|
70
|
+
Push(f) == cur' = f /\ stk' = IF cur = "none" THEN stk ELSE Append(stk, cur)
|
|
71
|
+
\* the running drive returns to the drive it was nested in, or to the loop
|
|
72
|
+
EndDrive == IF stk = <<>> THEN cur' = "none" /\ stk' = stk
|
|
73
|
+
ELSE cur' = stk[Len(stk)] /\ stk' = SubSeq(stk, 1, Len(stk) - 1)
|
|
74
|
+
\* cur's drive ends and f's starts in its place (the caller has nothing left to run)
|
|
75
|
+
Replace(f) == cur' = f /\ UNCHANGED stk
|
|
76
|
+
|
|
77
|
+
\* the claim a resume, queued step or interrupt makes on the current Park, then evaluate
|
|
78
|
+
Claim(r, node) == [r EXCEPT !.pdone = TRUE, !.parked = FALSE, !.node = node,
|
|
79
|
+
!.wakes = IF r.parked THEN @ + 1 ELSE @]
|
|
80
|
+
|
|
81
|
+
Masked(f) == ~fb[f].intr \/ (f = "C" /\ fb[f].pc \in {5, 6})
|
|
82
|
+
\* Keep the explicit-mask interval independent of intr; also check inherited startup masks.
|
|
83
|
+
|
|
84
|
+
\* Fiber.interrupt_unsafe: deferred while running or masked, otherwise _interrupt_now at once
|
|
85
|
+
\* (take_interrupt, mark the parked Park done, evaluate the Failure). `now`: that drive starts.
|
|
86
|
+
\* A fiber whose queued start has not run has an empty stack and no children or observers
|
|
87
|
+
\* (only C is ever unstarted, and only P waits on it, after this call): its Failure goes
|
|
88
|
+
\* straight to _done and _publish, running no user code, so it publishes atomically here.
|
|
89
|
+
IntUnsafe(r, running) ==
|
|
90
|
+
IF r.exit # "none" THEN [rec |-> r, now |-> FALSE]
|
|
91
|
+
ELSE IF running \/ (~r.intr /\ Break # "no_mask_check")
|
|
92
|
+
THEN [rec |-> [r EXCEPT !.irq = TRUE, !.req = TRUE, !.dfr = TRUE], now |-> FALSE]
|
|
93
|
+
ELSE IF ~r.st
|
|
94
|
+
THEN [rec |-> [r EXCEPT !.irq = TRUE, !.req = TRUE, !.dfr = FALSE, !.exit = "int",
|
|
95
|
+
!.pubs = @ + 1], now |-> FALSE]
|
|
96
|
+
ELSE [rec |-> [Claim(r, "int") EXCEPT !.irq = TRUE, !.req = TRUE, !.dfr = FALSE],
|
|
97
|
+
now |-> TRUE]
|
|
98
|
+
|
|
99
|
+
\* end of evaluate: parked while an interrupt waited (it came in during register) -> a fresh
|
|
100
|
+
\* evaluate of the interrupt at the same nesting level; otherwise the drive returns
|
|
101
|
+
DriveTail(f, r) ==
|
|
102
|
+
IF r.dfr /\ r.intr /\ r.parked
|
|
103
|
+
THEN /\ fb' = [fb EXCEPT ![f] = [Claim(r, "int") EXCEPT !.dfr = FALSE]]
|
|
104
|
+
/\ UNCHANGED <<cur, stk>>
|
|
105
|
+
ELSE /\ fb' = [fb EXCEPT ![f] = r]
|
|
106
|
+
/\ EndDrive
|
|
107
|
+
|
|
108
|
+
\* Fiber.evaluate loop top: `if self._deferred and self.interruptible` -> Failure(take_interrupt())
|
|
109
|
+
LoopTop(f) ==
|
|
110
|
+
LET r == fb[f] IN
|
|
111
|
+
/\ cur = f /\ r.dfr /\ r.intr /\ Break # "no_loop_top"
|
|
112
|
+
/\ fb' = [fb EXCEPT ![f] = [r EXCEPT !.node = "int", !.dfr = FALSE]]
|
|
113
|
+
/\ UNCHANGED <<cur, stk, started, obs, sent, selfUsed>>
|
|
114
|
+
|
|
115
|
+
Ready(f) == cur = f /\ (~(fb[f].dfr /\ fb[f].intr) \/ Break = "no_loop_top")
|
|
116
|
+
|
|
117
|
+
\* Fiber._done, then _publish (single call site). o = obs after any cancel ran.
|
|
118
|
+
Done(f, e, o) ==
|
|
119
|
+
LET r == fb[f]
|
|
120
|
+
e2 == IF r.ending = "none" THEN e ELSE IF e = "int" THEN "int" ELSE r.ending
|
|
121
|
+
liveC == f = "P" /\ started /\ fb["C"].exit = "none" /\ Break # "no_wait"
|
|
122
|
+
p == fb["P"]
|
|
123
|
+
ic == IntUnsafe(fb["C"], Running("C"))
|
|
124
|
+
pub == [r EXCEPT !.exit = e2, !.pubs = @ + 1, !.node = "none"]
|
|
125
|
+
\* C's _publish calls P's _await_all observer: one_done -> resume(UNIT) -> P.evaluate.
|
|
126
|
+
\* C's drive has nothing left once it publishes, so P's drive replaces it; Python still
|
|
127
|
+
\* has C.running set here (upstream has already cleared it), but every entry to C now
|
|
128
|
+
\* returns at the `_exit` check, so reentry is harmless. White-box observers can see
|
|
129
|
+
\* the running flag difference; that observation is outside this protocol model.
|
|
130
|
+
notify == f = "C" /\ o /\ p.pid = WAIT /\ Break # "no_notify" /\ (~p.pdone \/ Break = "no_park_done")
|
|
131
|
+
\* the pre-fix _done published P from C's observer, outside P's run loop
|
|
132
|
+
oldPub == f = "C" /\ Break = "old_done" /\ p.pc = WAIT /\ p.exit = "none"
|
|
133
|
+
IN
|
|
134
|
+
IF ~liveC THEN
|
|
135
|
+
/\ IF f = "P" THEN \* no_wait: interrupt C, don't wait
|
|
136
|
+
IF Break = "no_wait" /\ started
|
|
137
|
+
THEN /\ fb' = [fb EXCEPT !["P"] = pub, !["C"] = ic.rec]
|
|
138
|
+
/\ IF ic.now THEN Replace("C") ELSE EndDrive
|
|
139
|
+
ELSE /\ fb' = [fb EXCEPT !["P"] = pub]
|
|
140
|
+
/\ EndDrive
|
|
141
|
+
ELSE IF notify THEN
|
|
142
|
+
/\ fb' = [fb EXCEPT !["C"] = pub, !["P"] = Claim(p, "ok")]
|
|
143
|
+
/\ Replace("P")
|
|
144
|
+
ELSE
|
|
145
|
+
/\ fb' = [fb EXCEPT !["C"] = pub,
|
|
146
|
+
!["P"] = IF oldPub THEN [p EXCEPT !.exit = p.ending, !.pubs = @ + 1]
|
|
147
|
+
ELSE p]
|
|
148
|
+
/\ EndDrive
|
|
149
|
+
/\ obs' = IF f = "C" THEN FALSE ELSE o
|
|
150
|
+
/\ UNCHANGED <<started, sent, selfUsed>>
|
|
151
|
+
ELSE IF Break = "old_done" THEN
|
|
152
|
+
/\ fb' = [fb EXCEPT !["P"] = [r EXCEPT !.ending = e2, !.pc = WAIT, !.node = "none"],
|
|
153
|
+
!["C"] = ic.rec]
|
|
154
|
+
/\ obs' = TRUE
|
|
155
|
+
/\ IF ic.now THEN Replace("C") ELSE EndDrive
|
|
156
|
+
/\ UNCHANGED <<started, sent, selfUsed>>
|
|
157
|
+
ELSE \* remember the exit, interrupt C (it may run now, nested), then evaluate _await_all
|
|
158
|
+
/\ fb' = [fb EXCEPT !["P"] = [r EXCEPT !.ending = e2, !.pc = WAIT, !.node = "await"],
|
|
159
|
+
!["C"] = ic.rec]
|
|
160
|
+
/\ obs' = o
|
|
161
|
+
/\ IF ic.now THEN Push("C") ELSE UNCHANGED <<cur, stk>>
|
|
162
|
+
/\ UNCHANGED <<started, sent, selfUsed>>
|
|
163
|
+
|
|
164
|
+
\* core.py Async._eval: register (which may interrupt its own fiber), _park, end of drive
|
|
165
|
+
Park(f) ==
|
|
166
|
+
\E self \in (IF selfUsed THEN {FALSE} ELSE BOOLEAN) :
|
|
167
|
+
LET r == fb[f]
|
|
168
|
+
r1 == IF self THEN IntUnsafe(r, TRUE).rec ELSE r
|
|
169
|
+
r2 == [r1 EXCEPT !.ext = @ \cup {r.pc}, !.parked = TRUE, !.pid = r.pc, !.pdone = FALSE,
|
|
170
|
+
!.wakes = 0, !.pc = @ + 1, !.node = "none"]
|
|
171
|
+
IN /\ DriveTail(f, r2)
|
|
172
|
+
/\ selfUsed' = (selfUsed \/ self)
|
|
173
|
+
/\ UNCHANGED <<started, obs, sent>>
|
|
174
|
+
|
|
175
|
+
\* Fiber.yield_now: queue the step on the dispatcher, park on it, end of drive
|
|
176
|
+
Yield(f) ==
|
|
177
|
+
LET r == fb[f]
|
|
178
|
+
r2 == [r EXCEPT !.drv = Append(@, <<"y", r.pc>>), !.parked = TRUE, !.pid = r.pc,
|
|
179
|
+
!.pdone = FALSE, !.wakes = 0, !.pc = @ + 1, !.node = "none"]
|
|
180
|
+
IN /\ DriveTail(f, r2)
|
|
181
|
+
/\ UNCHANGED <<started, obs, sent, selfUsed>>
|
|
182
|
+
|
|
183
|
+
\* fiber._await_all: add observers on C, park (interruptible), end of drive. If C already
|
|
184
|
+
\* published (it ran to its end inside the interrupt above), add_observer calls back during
|
|
185
|
+
\* register: the resume is synchronous and nothing parks.
|
|
186
|
+
AwaitPark ==
|
|
187
|
+
LET r == fb["P"]
|
|
188
|
+
r2 == [r EXCEPT !.parked = TRUE, !.pid = WAIT, !.pdone = FALSE, !.wakes = 0, !.node = "none"]
|
|
189
|
+
IN IF fb["C"].exit # "none"
|
|
190
|
+
THEN /\ fb' = [fb EXCEPT !["P"] = [r EXCEPT !.node = "ok"]]
|
|
191
|
+
/\ UNCHANGED <<cur, stk, obs, started, sent, selfUsed>>
|
|
192
|
+
ELSE /\ DriveTail("P", r2)
|
|
193
|
+
/\ obs' = TRUE
|
|
194
|
+
/\ UNCHANGED <<started, sent, selfUsed>>
|
|
195
|
+
|
|
196
|
+
\* one node of Fiber.evaluate's loop (`cur = cur._eval(self)`)
|
|
197
|
+
Eval(f) ==
|
|
198
|
+
LET r == fb[f]
|
|
199
|
+
ins == Prog[f][r.pc]
|
|
200
|
+
IN
|
|
201
|
+
/\ Ready(f)
|
|
202
|
+
/\ r.node # "none"
|
|
203
|
+
/\ IF r.node = "int" THEN
|
|
204
|
+
\* the interrupt unwinds to the top; under _await_all, its _AsyncCancel removes the observer
|
|
205
|
+
Done(f, "int", IF f = "P" /\ r.pc = WAIT THEN FALSE ELSE obs)
|
|
206
|
+
ELSE IF r.node = "await" THEN AwaitPark
|
|
207
|
+
ELSE IF r.pc = WAIT \/ r.pc = End(f) THEN Done(f, "ok", obs)
|
|
208
|
+
ELSE IF ins = "park" THEN Park(f)
|
|
209
|
+
ELSE IF ins = "yield" THEN Yield(f)
|
|
210
|
+
ELSE IF ins = "fork" THEN
|
|
211
|
+
\E imm \in BOOLEAN, inherit \in BOOLEAN :
|
|
212
|
+
/\ started' = TRUE
|
|
213
|
+
/\ IF imm THEN \* _start(immediate=True): C's evaluate runs now, nested in P's
|
|
214
|
+
/\ fb' = [fb EXCEPT ![f] = [r EXCEPT !.pc = @ + 1, !.node = "ok"],
|
|
215
|
+
!["C"] = [@ EXCEPT !.node = "start", !.parked = FALSE, !.st = TRUE,
|
|
216
|
+
!.intr = IF inherit THEN r.intr ELSE TRUE]]
|
|
217
|
+
/\ Push("C")
|
|
218
|
+
/\ UNCHANGED <<obs, sent, selfUsed>>
|
|
219
|
+
ELSE \* _start: C's start is queued on P's dispatcher
|
|
220
|
+
/\ fb' = [fb EXCEPT ![f] = [r EXCEPT !.pc = @ + 1, !.node = "ok"],
|
|
221
|
+
!["C"] = [@ EXCEPT !.drv = Append(@, <<"start", 0>>),
|
|
222
|
+
!.intr = IF inherit THEN r.intr ELSE TRUE]]
|
|
223
|
+
/\ UNCHANGED <<cur, stk, obs, sent, selfUsed>>
|
|
224
|
+
ELSE IF ins = "mask" THEN
|
|
225
|
+
/\ fb' = [fb EXCEPT ![f] = [r EXCEPT !.pc = @ + 1, !.node = "ok", !.intr = FALSE]]
|
|
226
|
+
/\ UNCHANGED <<cur, stk, started, obs, sent, selfUsed>>
|
|
227
|
+
ELSE \* "enable" / "unmask": interruptible / SetInterruptible.on_any deliver via take_interrupt
|
|
228
|
+
/\ fb' = [fb EXCEPT ![f] = [r EXCEPT !.pc = @ + 1, !.intr = TRUE,
|
|
229
|
+
!.node = IF r.irq THEN "int" ELSE "ok",
|
|
230
|
+
!.dfr = IF r.irq THEN FALSE ELSE r.dfr]]
|
|
231
|
+
/\ UNCHANGED <<cur, stk, started, obs, sent, selfUsed>>
|
|
232
|
+
|
|
233
|
+
\* a dispatcher task runs (its batch from the loop, or a flush nested in any drive)
|
|
234
|
+
Drive(f) ==
|
|
235
|
+
LET r == fb[f]
|
|
236
|
+
t == Head(r.drv)
|
|
237
|
+
r1 == [r EXCEPT !.drv = Tail(@)]
|
|
238
|
+
live == IF t[1] = "start" THEN r.exit = "none"
|
|
239
|
+
ELSE (t[2] = r.pid /\ ~r.pdone) \/ (Break = "no_token_claim" /\ r.exit = "none")
|
|
240
|
+
IN /\ r.drv # <<>>
|
|
241
|
+
/\ IF ~live THEN fb' = [fb EXCEPT ![f] = r1] /\ UNCHANGED <<cur, stk>>
|
|
242
|
+
ELSE IF t[1] = "start" THEN
|
|
243
|
+
fb' = [fb EXCEPT ![f] = [r1 EXCEPT !.node = "start", !.parked = FALSE, !.st = TRUE]]
|
|
244
|
+
/\ Push(f)
|
|
245
|
+
ELSE fb' = [fb EXCEPT ![f] = Claim(r1, "ok")] /\ Push(f)
|
|
246
|
+
/\ UNCHANGED <<started, obs, sent, selfUsed>>
|
|
247
|
+
|
|
248
|
+
\* an async completion fires: Async resume checks `not park.done`, then evaluates at once
|
|
249
|
+
ExtResume(f) ==
|
|
250
|
+
\E id \in fb[f].ext :
|
|
251
|
+
LET r == fb[f]
|
|
252
|
+
r1 == [r EXCEPT !.ext = @ \ {id}]
|
|
253
|
+
hit == (id = r.pid /\ ~r.pdone) \/ (Break = "no_park_done" /\ r.exit = "none")
|
|
254
|
+
IN /\ IF hit THEN fb' = [fb EXCEPT ![f] = Claim(r1, "ok")] /\ Push(f)
|
|
255
|
+
ELSE fb' = [fb EXCEPT ![f] = r1] /\ UNCHANGED <<cur, stk>>
|
|
256
|
+
/\ UNCHANGED <<started, obs, sent, selfUsed>>
|
|
257
|
+
|
|
258
|
+
\* someone calls P.interrupt_unsafe, from the loop or from inside any drive
|
|
259
|
+
Interrupt ==
|
|
260
|
+
LET x == IntUnsafe(fb["P"], Running("P")) IN
|
|
261
|
+
/\ ~sent /\ fb["P"].exit = "none"
|
|
262
|
+
/\ sent' = TRUE
|
|
263
|
+
/\ fb' = [fb EXCEPT !["P"] = x.rec]
|
|
264
|
+
/\ IF x.now THEN Push("P") ELSE UNCHANGED <<cur, stk>>
|
|
265
|
+
/\ UNCHANGED <<started, obs, selfUsed>>
|
|
266
|
+
|
|
267
|
+
Settled(f) == fb[f].drv = <<>> /\ fb[f].ext = {} /\ (fb[f].exit # "none" \/ (f = "C" /\ ~started))
|
|
268
|
+
Finished == cur = "none" /\ \A f \in Fibers : Settled(f)
|
|
269
|
+
Done_ == Finished /\ UNCHANGED vars
|
|
270
|
+
|
|
271
|
+
Next ==
|
|
272
|
+
\/ \E f \in Fibers : Drive(f) \/ LoopTop(f) \/ Eval(f) \/ ExtResume(f)
|
|
273
|
+
\/ Interrupt
|
|
274
|
+
\/ Done_
|
|
275
|
+
|
|
276
|
+
Spec == Init /\ [][Next]_vars /\ WF_vars(Next)
|
|
277
|
+
|
|
278
|
+
\* ---- invariants (docs/INVARIANTS.md) ----
|
|
279
|
+
LiveTasks(f) == {i \in 1..Len(fb[f].drv) :
|
|
280
|
+
IF fb[f].drv[i][1] = "start" THEN fb[f].exit = "none"
|
|
281
|
+
ELSE fb[f].drv[i][2] = fb[f].pid /\ ~fb[f].pdone}
|
|
282
|
+
Drives(f) == Cardinality({i \in 1..Len(stk) : stk[i] = f}) + (IF cur = f THEN 1 ELSE 0)
|
|
283
|
+
|
|
284
|
+
K1_ExitOnce == \A f \in Fibers : fb[f].pubs <= 1
|
|
285
|
+
K2_ResumeOnce == \A f \in Fibers : fb[f].wakes <= 1
|
|
286
|
+
\* one evaluate per fiber at a time, nested or not, and none queued while it runs or waits
|
|
287
|
+
K3_OneRunner == \A f \in Fibers : Drives(f) + Cardinality(LiveTasks(f)) <= 1
|
|
288
|
+
K6_MasksHold == \A f \in Fibers : (cur = f /\ fb[f].node = "int") => ~Masked(f)
|
|
289
|
+
K7_InterruptsLand == \A f \in Fibers : (fb[f].exit # "none" /\ fb[f].req) => fb[f].exit = "int"
|
|
290
|
+
K8_NoOrphans == (fb["P"].exit # "none" /\ started) => fb["C"].exit # "none"
|
|
291
|
+
|
|
292
|
+
\* progress: every fiber that started publishes
|
|
293
|
+
AllPublish == <>Finished
|
|
294
|
+
=============================================================================
|