User-defined, struct-backed types that travel between workers by reference
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 184
- Forks
- 9
- PR merge metrics
- No merged PRs in 30d
Description
Problem
bocpy lets you put data in a Cown and hand it to behaviors running on
worker sub-interpreters. Today that data crosses the interpreter boundary by
being pickled and copied — which is fine for ordinary Python objects, but
leaves a gap for users who want a small, fixed-shape record (a particle, a
pixel, a quote, a sensor reading) to move between workers cheaply and by
reference, the way Matrix already does.
Right now, getting that requires writing a C extension against the public ABI.
That is a high bar for a Python programmer who simply wants a typed struct
with a handful of numeric fields. We have a proto-Region pattern that makes
native types safe to share across interpreters, but no on-ramp to it that
stays entirely in Python.
User need
A Python programmer should be able to define their own type — a normal
class, with their own methods and their own place in their own class
hierarchy — give it a struct-shaped data core, and have instances of it move
between workers without a copy and without writing any C. Crucially, bocpy
should not dictate how they structure or package that type.
The access-safety guarantees that make this sound (only one interpreter may
touch the data at a time; a stale handle left behind after a handoff cannot
read or corrupt the data) must hold automatically, without the user having to
reason about interpreters or ownership.
What a solution should be able to do
- Let a user describe a fixed record of struct-packable fields (ints, floats,
fixed-width bytes) using only the standard library, no C. - Ship one such record between workers by reference when possible, falling
back to a copy only when a copy is genuinely unavoidable. - Enforce single-owner access discipline at the boundary, so reads/writes from
the wrong interpreter fail loudly rather than silently racing. - Impose no base class on the user. They opt in by exposing a small hook
on their own type, and they keep full control of their methods and class
layout. - Make ordinary editor intellisense "just work" for the user's fields, on both
the producing and consuming side, without bocpy-specific ceremony. - Leave it entirely to the user whether (and how) to reattach their own
methods to data received in a worker — bocpy moves the data, the user owns
the business logic.
Explicitly out of scope (for a first cut)
- Variable-length, resizable, or nested records.
- Arbitrary Python object fields or embedded cowns.
- Zero-copy live views (buffer protocol) into the shared data.
- The full region model (nesting, freeze, merge, borrow tracking).
Notes
A design exploration and a runnable Python-only prototype already exist and
validate the core concept — a small shippable data core, a one-method
extraction protocol, and automatic single-owner enforcement — including the
cross-interpreter handoff and the stale-handle failure mode. This issue tracks
turning that concept into a real feature; the detailed design will be linked
separately.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the existing design exploration and runnable Python-only prototype, then compare its data-core and extraction protocol with the current Matrix and proto-Region patterns. The implementation should support user-defined fixed records, cross-worker reference handoff, stale-handle failures, and copy fallback while preserving user-owned classes and methods.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 28/100