doeff-vm

The Rust virtual machine that runs doeff programs.

This README is for Python developers who use doeff and want to know what doeff-vm does. After reading it you can tell whether you need to import it directly, install it, and use its low-level program nodes.

What it does

doeff-vm is a Python extension module written in Rust (PyO3). It executes doeff programs:

• it keeps the stack of installed handlers,
• it sends each performed effect to the innermost handler that accepts it,
• it resumes the program through one-shot continuations (a continuation k can be resumed at most once).

The scheduler behind doeff's concurrency effects (Spawn, Gather, …) also runs on it.

Most users never import doeff_vm directly. doeff.run(...) drives this VM, and pip install doeff installs it for you.

How one effect is handled:

run(program)
   │
   ▼
doeff-vm steps through the program
   │  the program performs an effect
   ▼
innermost handler in scope ──Resume(k, value)──► the program continues with `value`
   │  Pass(effect, k)
   ▼
next handler outward … ──(no handler left)──► UnhandledEffect is raised

Installation

pip install doeff        # recommended: installs doeff-vm together with the Python API
pip install doeff-vm     # the VM alone

Requires Python 3.11 or newer. If pip finds no prebuilt wheel for your platform, it builds from the source distribution, which needs a Rust toolchain (cargo).

Minimal example

@do functions and handler installers build a tree of program nodes, and the VM evaluates that tree. You can also build the tree by hand with the node classes that doeff_vm exports:

from dataclasses import dataclass

import doeff_vm
from doeff import do, run


@dataclass(frozen=True)
class Double(doeff_vm.EffectBase):
    n: int


@do
def double_handler(effect, k):
    if isinstance(effect, Double):
        return (yield doeff_vm.Resume(k, effect.n * 2))
    yield doeff_vm.Pass(effect, k)  # not ours: hand it to the next handler outward


# The tree that `@do` code and handler installers normally build for you.
program = doeff_vm.WithHandler(double_handler, doeff_vm.Perform(Double(21)))
print(run(program))  # 42

What it exports

Type stubs ship with the package (py.typed).

How it fits with the other doeff packages

doeff is published as five core packages. pip install doeff installs the first three; the extra hy (pip install "doeff[hy]") adds doeff-hy and doeff-hy-pytest.

Arrows point from a package to a package it depends on (the dotted one only with the extra hy):

doeff ──► doeff-vm
  │
  └─────► doeff-core-effects ┄┄► doeff-hy ──► doeff-hy-pytest

doeff-hy also depends on doeff and doeff-core-effects, so the five packages are released together with matching versions.

The VM core is the Rust crate doeff-vm-core. It is compiled into this extension and is not published separately.

Developing

Build and test from a clone of the repository:

git clone https://github.com/proboscis/doeff
cd doeff
make sync                         # builds the extension into the uv environment
uv run pytest packages/doeff-vm/tests

make sync rebuilds the extension whenever the Rust sources change. Do not run maturin develop directly; the build goes through tools/doeff_cargo_backend.py. Dispatch micro-benchmarks live in packages/doeff-vm-core/benches/ (see the root README).

License

MIT. See LICENSE.