Skip to content

Commit 67b7220

Browse files
GordonSmithCopilot
GordonSmith
and
Copilot
authored
fix: Complete resource handle lifecycle (#12)
* fix: Complete resource handle lifecycle Signed-off-by: Gordon Smith <GordonJSmith@gmail.com> * Update include/cmcpp/context.hpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update include/cmcpp/context.hpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Signed-off-by: Gordon Smith <GordonJSmith@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent af57bb6 commit 67b7220

File tree

5 files changed

+471
-50
lines changed

5 files changed

+471
-50
lines changed

‎docs/issue-backlog.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# GitHub Issue Backlog
2+
3+
Draft issues ready to be copy-pasted into GitHub. Each entry lists a suggested title, labels, background, concrete scope, and acceptance criteria aligned with the canonical ABI reference implementation.
4+
5+
---
6+
7+
## Issue: Implement canonical async runtime scaffolding
8+
- **Labels:** `enhancement`, `async`
9+
10+
### Background
11+
The canonical ABI reference (`design/mvp/canonical-abi/definitions.py`) includes a `Store`, `Thread`, and scheduling loop that enable cooperative async execution via `tick()`. The current C++ headers lack any runtime to drive asynchronous component calls.
12+
13+
### Scope
14+
- Add `Store`, `Thread`, `Task`, and related scheduling types to `cmcpp` mirroring the canonical semantics.
15+
- Implement queueing of pending threads and `tick()` to resume ready work.
16+
- Expose hooks for component functions to register `on_start`/`on_resolve` callbacks and support cancellation tokens on the returned `Call` object.
17+
- Provide doctest (or equivalent) coverage that simulates async invocation and verifies correct scheduling behavior.
18+
19+
### Acceptance Criteria
20+
1. New runtime types are available in the public API and documented.
21+
2. Asynchronous component calls can progress via repeated `tick()` calls without blocking the host thread.
22+
3. Unit tests demonstrate thread scheduling, `on_start` argument delivery, and cooperative cancellation.
23+
4. Documentation explains how hosts drive async work.
24+
25+
---
26+
27+
## Issue: Complete resource handle lifecycle
28+
- **Labels:** `enhancement`, `abi`
29+
30+
### Background
31+
`ResourceHandle`, `ResourceType`, and `ComponentInstance.resources` are currently empty shells. The canonical implementation tracks ownership, borrow counts, destructors, and exposes `canon resource.{new,drop,rep}`.
32+
33+
### Scope
34+
- Flesh out `ResourceHandle` with `own`, `borrow_scope`, and `num_lends` semantics.
35+
- Implement `ResourceType` destructor registration, including async callback support.
36+
- Add `canon resource.new`, `canon resource.drop`, and `canon resource.rep` helper functions that update component tables and trap on misuse.
37+
- Write tests covering own/borrow flows, lend counting, and destructor invocation.
38+
39+
### Acceptance Criteria
40+
1. Resource creation traps if the table would overflow or if ownership rules are violated.
41+
2. Dropping resources invokes registered destructors exactly once and respects async/sync constraints.
42+
3. Borrowed handles track lend counts and trap on invalid drops or reps.
43+
4. Tests mirror canonical success and trap cases.
44+
45+
---
46+
47+
## Issue: Add waitable, stream, and future infrastructure
48+
- **Labels:** `enhancement`, `async`
49+
50+
### Background
51+
Canonical ABI defines waitables, waitable-sets, buffers, streams, and futures plus their cancellation behaviors. Our headers only contain empty structs.
52+
53+
### Scope
54+
- Model waitable and waitable-set state, including registration with the component store.
55+
- Implement buffer management for {stream,future} types, covering readable/writable halves.
56+
- Provide APIs for `canon waitable-set.{new,wait,poll,drop}`, `canon waitable.join`, and `canon {stream,future}.{new,read,write,cancel,drop}`.
57+
- Add tests verifying read/write ordering, cancellation pathways, and polling semantics.
58+
59+
### Acceptance Criteria
60+
1. Streams and futures can be created, awaited, and canceled via the new APIs.
61+
2. Waitable sets correctly block/unblock pending tasks and surface readiness in tests.
62+
3. Cancellation propagates to queued operations per canonical rules.
63+
4. Documentation describes how hosts integrate these constructs.
64+
65+
---
66+
67+
## Issue: Implement backpressure and task lifecycle management
68+
- **Labels:** `enhancement`, `async`
69+
70+
### Background
71+
`ComponentInstance` holds flags for `may_leave`, `backpressure`, and call-state tracking but they are unused. Canonical ABI specifies `canon task.{return,cancel}`, `canon yield`, and backpressure counters governing concurrent entry.
72+
73+
### Scope
74+
- Track outstanding synchronous/async calls and enforce `may_leave` invariants when entering/leaving component code.
75+
- Implement `canon task.return` and `canon task.cancel` helpers wired to pending task queues.
76+
- Support `canon yield` to hand control back to the embedder.
77+
- Ensure backpressure counters gate `Store.invoke` while tasks are paused or pending.
78+
79+
### Acceptance Criteria
80+
1. Re-entrant sync calls are rejected per canonical rules (tests cover both allowed and disallowed cases).
81+
2. Tasks marked for cancellation resolve promptly with `on_resolve(None)`.
82+
3. `canon yield` transitions tasks to pending and requires a subsequent `tick()` to resume.
83+
4. Backpressure metrics are exposed for debugging and verified in tests.
84+
85+
---
86+
87+
## Issue: Support context locals and error-context APIs
88+
- **Labels:** `enhancement`, `abi`
89+
90+
### Background
91+
`LiftLowerContext` currently omits instance references and borrow scopes, and `ContextLocalStorage`/`ErrorContext` types are unused. The canonical ABI exposes `canon context.{get,set}` and `canon error-context.{new,debug-message,drop}`.
92+
93+
### Scope
94+
- Extend `LiftLowerContext` to hold the active `ComponentInstance` and scoped borrow variant.
95+
- Implement context-local storage getters/setters with bounds validation.
96+
- Provide error-context creation, debug-message formatting via the host converter, and drop semantics that respect async callbacks.
97+
- Add tests ensuring invalid indices and double drops trap.
98+
99+
### Acceptance Criteria
100+
1. Borrowed resources capture their scope and trap when accessed outside it.
101+
2. Context locals persist across lift/lower calls and reset appropriately between tasks.
102+
3. Error-context debug messages surface through the host trap mechanism.
103+
4. Test coverage includes both success and failure paths for each API.
104+
105+
---
106+
107+
## Issue: Finish function flattening utilities
108+
- **Labels:** `enhancement`, `abi`
109+
110+
### Background
111+
`include/cmcpp/func.hpp` contains commented-out flattening helpers. Canonical ABI requires flattening functions to honor `MAX_FLAT_PARAMS/RESULTS` and spill to heap memory via the provided `realloc`.
112+
113+
### Scope
114+
- Implement `cmcpp::func::flatten`, `pack_flags_into_int`, and the associated load/store helpers.
115+
- Respect max-flat thresholds and ensure out-params allocate via `LiftLowerContext::opts.realloc`.
116+
- Add regression tests covering large tuples, records, and flag types that exceed the flat limit.
117+
- Compare flattened signatures against outputs from the canonical Python definitions for validation.
118+
119+
### Acceptance Criteria
120+
1. Flattened core signatures match canonical expectations for representative WIT signatures.
121+
2. Heap-based lowering is invoked automatically when flat limits are exceeded.
122+
3. Flags marshal correctly between bitsets and flat integers.
123+
4. Tests demonstrate both flat and heap pathways.
124+
125+
---
126+
127+
## Issue: Wire canonical options and callbacks through lift/lower
128+
- **Labels:** `enhancement`, `abi`
129+
130+
### Background
131+
`CanonicalOptions` exposes `post_return`, `callback`, and `sync` but they are currently unused. Canonical ABI requires these flags to control async vs sync paths and post-return cleanup.
132+
133+
### Scope
134+
- Invoke `post_return` after successful lowerings when provided.
135+
- Enforce `sync` by trapping when async behavior would occur while `sync == true`.
136+
- Invoke `callback` when async continuations schedule additional work.
137+
- Ensure option fields propagate through `InstanceContext::createLiftLowerContext` and task lifecycles.
138+
139+
### Acceptance Criteria
140+
1. `post_return` is called exactly once per lowering when configured (verified via tests).
141+
2. Async lowering attempts while `sync == true` trap with a descriptive error.
142+
3. Registered callbacks fire for asynchronous continuations and can trigger host-side scheduling.
143+
4. Documentation clarifies option usage and interaction with new runtime pieces.
144+
145+
---
146+
147+
## Issue: Expand docs and tests for canonical runtime features
148+
- **Labels:** `documentation`, `testing`
149+
150+
### Background
151+
New runtime pieces require supporting documentation and tests. Currently, README lacks guidance and test coverage mirrors only existing functionality.
152+
153+
### Scope
154+
- Update `README.md` (or add a new guide) summarizing the async runtime, resource management, and waitable APIs.
155+
- Add doctest/ICU-backed unit tests covering the new behavior to `test/main.cpp` (or adjacent files).
156+
- Optionally add a Python cross-check using `ref/component-model/design/mvp/canonical-abi/run_tests.py` for parity.
157+
158+
### Acceptance Criteria
159+
1. Documentation explains how to configure `InstanceContext`, allocate options, and drive async flows.
160+
2. New tests pass in CI and cover at least one example for each newly implemented feature.
161+
3. The backlog of canonical ABI features is reflected as "Done" within this issue once merged.

‎include/cmcpp.hpp‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
#ifndef CMCPP_HPP
22
#define CMCPP_HPP
33

4+
#include <cmcpp/context.hpp>
45
#include <cmcpp/integer.hpp>
56
#include <cmcpp/float.hpp>
67
#include <cmcpp/string.hpp>

0 commit comments

Comments
 (0)