Skip to content

Add process handles to the broker - #1886

Draft
Weidong Cui (wdcui) wants to merge 8 commits into
uliteboxfrom
wdcui/ulitebox/process-handles
Draft

Weidong Cui (wdcui) wants to merge 8 commits into
uliteboxfrom
wdcui/ulitebox/process-handles

Conversation

@wdcui

Copy link
Copy Markdown
Member

This PR adds a guest-neutral process handle to the broker. A handle refers to one process, even after its ID is reused, without keeping that ID or the process's registration alive. It becomes readable once the process's exit is visible to its parent, and reports hang-up once that exit is collected or discarded. A handle can be duplicated and inherited, used as a signal target (refusing processes the caller's PID namespace can't see), and used to select a child whose exit to collect. Core and wire tests cover each readiness point.

@wdcui
Weidong Cui (wdcui) force-pushed the wdcui/ulitebox/process-handles branch 2 times, most recently from a49e5ee to f2e1e9d Compare November 15, 2026 00:04
Weidong Cui (wdcui) and others added 5 commits November 15, 2026 15:13
A process handle is a new broker object that refers to one process
rather than to its ID. It holds the process weakly, so it keeps neither
the process, its IDs, nor its registration alive, and it never reaches
a later process that reuses the ID. It becomes readable once the
process's exit is observable and closed once the process is released
or gone, can be duplicated, and serves as a signal target and as a
child selector for exit collection, so guest shims can build process
descriptors such as Linux pidfds on it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f5406de6-bab4-4f3b-b232-ae238032c2c2
Expose broker process handles to guest shims: `ProcessHandle` owns a
handle opened by process ID or inherited from the parent, reports its
readiness through `IOPollable`, sends signals to and collects the exit
of its process, and can be inherited and watched by readiness queues.
`ProcessError::OutsideNamespace` reports a target the caller's PID
namespace doesn't see, which Linux guests see as `EINVAL`.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f5406de6-bab4-4f3b-b232-ae238032c2c2
Every use of a process handle needs the wait right, so opening one without it
now fails with PolicyDenied, as opening signals does, instead of returning a
handle whose later uses fail.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c844968b-a8b8-4865-8057-057d31657925
Add litebox-level SignalTarget and ChildSelector enums without handle
variants, so only the typed ProcessHandle wrapper can name a handle.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c844968b-a8b8-4865-8057-057d31657925
Publish release readiness from cleanup rather than only from drop, and
fail handle signals with PeerClosed once the handle reads closed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c844968b-a8b8-4865-8057-057d31657925
@wdcui
Weidong Cui (wdcui) force-pushed the wdcui/ulitebox/process-handles branch from f2e1e9d to 89d6c15 Compare November 15, 2026 23:14
Weidong Cui (wdcui) and others added 3 commits November 15, 2026 17:14
The name ProcessHandle clashed with the platform's ProcessHandle trait.
Broker-side names keep "handle", where it means a broker object reference.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c844968b-a8b8-4865-8057-057d31657925
Drive ProcessRef through the in-process broker: a parent following its
child through exit and collection, another process watching and
signalling without collecting, and dropping releasing the broker
reference. The test broker can now connect a second root process
without the test terminal, which only one session can hold.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c844968b-a8b8-4865-8057-057d31657925
Drop the litebox-level SignalTarget and ChildSelector enums. The
generic LiteBox API now takes the broker's enums directly.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c844968b-a8b8-4865-8057-057d31657925
@github-actions

Copy link
Copy Markdown

🤖 SemverChecks 🤖 ⚠️ Potential breaking API changes detected ⚠️

Click for details
--- failure enum_variant_added: enum variant added on exhaustive enum ---

Description:
A publicly-visible enum without #[non_exhaustive] has a new variant.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#enum-variant-new
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.51.0/src/lints/enum_variant_added.ron

Failed in:
  variant ReadinessTarget:ProcessRef in /home/runner/work/litebox/litebox/litebox/src/event/readiness_queue.rs:82
  variant InheritableFd:ProcessRef in /home/runner/work/litebox/litebox/litebox/src/process.rs:416
  variant ProcessError:OutsideNamespace in /home/runner/work/litebox/litebox/litebox/src/process.rs:79

--- failure enum_variant_added: enum variant added on exhaustive enum ---

Description:
A publicly-visible enum without #[non_exhaustive] has a new variant.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#enum-variant-new
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.51.0/src/lints/enum_variant_added.ron

Failed in:
  variant ProcessResponse:OpenProcessHandle in /home/runner/work/litebox/litebox/litebox_broker_protocol/src/message.rs:804
  variant SignalTarget:ProcessHandle in /home/runner/work/litebox/litebox/litebox_broker_protocol/src/signal.rs:42
  variant ChildSelector:ProcessHandle in /home/runner/work/litebox/litebox/litebox_broker_protocol/src/process.rs:361
  variant ProcessRequest:OpenProcessHandle in /home/runner/work/litebox/litebox/litebox_broker_protocol/src/message.rs:503

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant