microsoft / microsoft/bocpy

User-defined, struct-backed types that travel between workers by reference

Open
#33 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

design
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.