Skip to content

Document v2 runner architecture - #20

Draft
tkilias wants to merge 13 commits into
documentation/design_v2_protocolfrom
documentation/v2_runner_design
Draft

tkilias wants to merge 13 commits into
documentation/design_v2_protocolfrom
documentation/v2_runner_design

Conversation

@tkilias

@tkilias tkilias commented Aug 19, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • add documentation-only v2 runner architecture
  • define the private C++ implementation, stable C ABI, and header-only C++ facade
  • document socket acceptance, reusable worker-pool dispatch, context creation, ownership, shutdown, and ABI rules
  • add Mermaid source diagrams with rendered SVGs for layering, components, lifecycle, descriptor ownership, and the ABI boundary

Validation

  • all runner Markdown links resolve
  • all Mermaid source/render pairs exist
  • Mermaid diagrams render successfully
  • git diff --check passes

@tkilias
tkilias force-pushed the documentation/v2_runner_design branch from c70ff7d to c6290ed Compare September 1, 2026 16:22
@tkilias
tkilias changed the base branch from main to documentation/design_v2_protocol September 1, 2026 16:23
Comment thread doc/design/v2/runner/README.md Outdated
Comment thread doc/design/v2/runner/context_implementation.md
Comment thread doc/design/v2/runner/context_implementation.md Outdated
Comment thread doc/design/v2/runner/context_implementation.md
Comment thread doc/design/v2/runner/context_implementation.md Outdated
Comment thread doc/design/v2/runner/context_implementation.md
Comment thread doc/design/v2/runner/context_implementation.md Outdated
Comment thread doc/design/v2/runner/context_implementation.md Outdated
Comment thread doc/design/v2/runner/context_implementation.md Outdated
Comment thread doc/design/v2/runner/context_interface.md Outdated
Comment thread doc/design/v2/runner/context_interface.md Outdated
Comment thread doc/design/v2/runner/context_implementation.md Outdated
Comment thread doc/design/v2/runner/context_implementation.md Outdated
- a call receive never returns control-stream or other-call traffic;
- a control receive never returns call traffic.

One consumer is expected for each call and for the control stream. Concurrent receives from different calls are

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is meant be "Concurrent receives from different calls" - there should be only one producer per context, or?

### Worker-side data flow control

The worker-side `Call::send()` path owns the outbound credit state for each call and data direction. A record-batch
send is allowed to block on the inbound queue because the worker must process `Next` messages before it can send more

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens if there never is a "Next" message - will it block forever?

@tkilias tkilias Sep 22, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this actual show another problem we cant stop to wait because, the split happens on the worker side, that we can add a block timeout we need to move the split into background thread. this has another consequence we need another mechanism to indicate send permission to the worker. the bg threads budget to the worker thread as long the worker thread still has budget it is allowed to send the current batch. the bg thread takes care splitting it using real remaining.

This branch has not been deployed

No deployments
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.

2 participants