Application Flow
When to Use
Use this skill when the user asks how to structure an ovstage program end-to-end, what the
main steps are, how the pieces (instance, path dictionary, query, write/ordinal/write-floor,
read, release) fit together, or which focused skill owns each step.
Inputs
Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.
- Lifecycle stage in question: instance creation, prim/attribute identity, write, seal
(advance write floor), query/read, or release.
- Whether the program ingests existing USD (the population API,
ovstage_population.h)
or writes attributes directly (the path shown here).
- Whether it's a one-shot write→read or a running producer/consumer loop (CPU running ahead
of execution — see
cpu-ahead-gpu-async).
- The shipped headers and the referenced example snippets are the authoritative contract.
Prerequisites
- Use an ovstage checkout that contains the
include/ headers and the referenced example/snippets.
- Read the relevant
> **Source:** snippet before writing or explaining API usage.
- Understand the async submit/observe model (
cpu-ahead-gpu-async): state-mutating and
data-producing calls are enqueues; nothing is done until you wait_op / fetch_*.
- Remember this build is latest-snapshot only for payloads. Exact change membership is
retained across a bounded set of completed write-floor epochs; query
ovstage_get_oldest_preserved_ordinal before consuming an older range.
Instructions
- Create the instance (
ovstage_create_instance) and obtain its instance-owned path
dictionary (ovstage_get_path_dictionary).
- Establish identity: intern the attribute name →
ovx_token_t, build a prim-path list,
and open a query over it (ovstage_query_from_path_list).
- Write attribute values at an
ordinal (ovstage_write_attribute); observe the
enqueue with ovstage_wait_op.
- Seal: advance the write floor to that ordinal (
ovstage_advance_write_floor) so data
at/below it is immutable and readable.
- Read:
ovstage_read_attributes over an ordinal range → ovstage_fetch_read_next →
consume group.data tensors.
- Release in reverse: the read group, the read handle, the path-list reference, then
destroy the instance.
- Layer in the focused skills as concerns arise: tensor data (
dlpack-tensor-exchange),
submit/observe & concurrency (cpu-ahead-gpu-async), error reporting (error-handling),
string/token identity (string-handling, path-dictionary).
Once a committed snapshot must be persisted as USD, route to exporting-to-usd;
it owns selection, destination lifetime, save ownership, and export-specific waits.
Output Format
- For explanations, return an ordered lifecycle with the relevant follow-on skills.
- For code changes, summarize the lifecycle files touched, snippets affected, and validation run.
Scripts
This skill has no scripts.
Limitations
- The referenced snippets remain the source of truth; this skill composes the minimal
example's snippets in lifecycle order rather than introducing new code.
- Ordinal surface, latest-only payloads: ordinals, write floors, ordinal ranges, and
ovstage_get_oldest_preserved_ordinal describe ordering, sealing, and retained
change/deletion membership — that surface is part of the API contract. In the current
build, payload reads are latest-snapshot only and do not provide historical payload
versions. At or above the reported inclusive retention frontier, a range selects exact
changed/deleted membership. It returns current payload/delete state only when the selected
key has no retained successor after the range end; otherwise it returns
OVSTAGE_ERROR_OUT_OF_RANGE. Below that frontier, membership may be coalesced or discarded.
Do not treat an ordinal range as a historical-payload event log.
- USD population not covered here. Ingesting existing USD uses the population API
(
ovstage_population.h); this skill documents the direct write/read lifecycle.
- ⚠️ Draft — API in flux. Treat exact symbols/ordering as provisional against the headers.
Overview
ovstage is a data stage, not a renderer. A program creates an instance, identifies
prims/attributes through the (instance-owned) path dictionary, writes attribute columns at
ordinals, seals them by advancing the write floor, and reads them back — all on the
asynchronous submit/observe model. (ovrtx's renderer lifecycle — Camera / RenderProduct /
step() / render output — does not apply.)
Two cross-cutting rules shape every stage:
- Async enqueue / observe. Enqueue is synchronous and cheap and returns an
op_index; the
CPU can run ahead. Same-ordinal ops execute in submission order; different-ordinal ops are
independent. Block or poll with ovstage_wait_op. (→ cpu-ahead-gpu-async)
- Ordinals + write floor. Writes carry an
ordinal. Advancing the write floor seals
everything at/below it; reads target sealed data at/below the floor, while queries resolve
against the latest committed state.
Lifecycle
1. Create instance → project-setup-c
2. Get path dictionary → path-dictionary
3. Identify prims + attributes → path-dictionary, string-handling
(intern token, build path list, open query)
4. Write attribute(s) at an ordinal → dlpack-tensor-exchange (data) + cpu-ahead-gpu-async (submit/observe)
5. Advance the write floor (seal) → cpu-ahead-gpu-async
6. Read / fetch → dlpack-tensor-exchange
7. Release + destroy instance → error-handling (status checks throughout)
Optional: ingest existing USD via the population API (ovstage_population.h) instead of, or
before, direct writes.
C — end-to-end
The minimal example walks the whole lifecycle. After ovstage_create_instance (see
project-setup-c), compose these snippets in order — get the path dictionary + intern a
token, build a path list + open a query, form the attribute argument, then write → seal →
read:
Source: examples/c/minimal/main.cpp snippet intern-and-resolve
Followed by: examples/c/minimal/main.cpp snippet path-list-query
Followed by: examples/c/minimal/main.cpp snippet string-or-token-arg
Followed by: examples/c/minimal/main.cpp snippet minimal-write-read
Every state-mutating / data-producing call is an async enqueue; drive each to completion and
check synchronous calls along the way:
Source: examples/c/minimal/main.cpp snippet enqueue-wait-error
And for synchronous calls: examples/c/minimal/main.cpp snippet check-sync-error
The public C test asserts this whole round-trip (write → seal → read → verify the
values) against the produced package, not just prints it:
Source: tests/c/test_minimal.cpp snippet write-read-roundtrip-c
The essential ordering is: ovstage_create_instance → ovstage_get_path_dictionary →
intern token / path_dictionary_create_path_list_from_strings → ovstage_query_from_path_list
→ ovstage_write_attribute (ordinal) → ovstage_advance_write_floor (seal) →
ovstage_read_attributes → ovstage_fetch_read_next → release (ovstage_release_group →
ovstage_release_read → path_dictionary_release_path_list_reference) →
ovstage_destroy_instance.
Key Stages / Functions
| Stage |
Function(s) |
Detail skill |
| Create / destroy instance |
ovstage_create_instance / ovstage_destroy_instance |
project-setup-c |
| Path dictionary (identity) |
ovstage_get_path_dictionary, path_dictionary_create_tokens_from_strings, path_dictionary_create_path_list_from_strings |
path-dictionary, string-handling |
| Query target prims |
ovstage_query_from_path_list |
path-dictionary |
| Write (ordinal-keyed) |
ovstage_write_attribute (+ ovstage_write_data_t) |
dlpack-tensor-exchange, cpu-ahead-gpu-async |
| Seal |
ovstage_advance_write_floor |
cpu-ahead-gpu-async |
| Read |
ovstage_read_attributes → ovstage_fetch_read_next → ovstage_release_group |
dlpack-tensor-exchange |
| Observe / errors |
ovstage_wait_op, ovstage_get_error_string, ovstage_get_last_op_error |
cpu-ahead-gpu-async, error-handling |
Troubleshooting
- Read fails with
OVSTAGE_ERROR_WRITE_FLOOR_VIOLATION after a write — the selected state is
not sealed; call ovstage_advance_write_floor to/above its ordinal. Also remember that enqueue
success means accepted, not executed (wait/fetch first). See cpu-ahead-gpu-async.
- Fixed range fails with
OVSTAGE_ERROR_OUT_OF_RANGE — a selected (attribute, path) has a
retained successor after the range end, so latest-only storage cannot represent that window.
Widen/rebase the range, repoll from a newer cursor, or explicitly request latest state.
Advancing the floor alone does not resolve it.
- Write rejected (
OVSTAGE_ERROR_WRITE_FLOOR_VIOLATION) — you wrote at an ordinal at or
below the current write floor. Write above the floor, then advance the floor afterward.
- Expecting historical payloads from an ordinal range — unsupported in this
latest-snapshot build. Ranges at or above the reported retention frontier provide exact
changed-prim membership; representable ranges carry current payload/delete state, while a
retained same-key successor after the range end produces
OUT_OF_RANGE.
- Leaks / teardown crashes — release in reverse: the read group, the read handle, the
path-list reference, then destroy the instance (the path dictionary is instance-owned —
never free it yourself).
- Can't stringify an error before the instance exists —
ovstage_get_error_string is
vtable-dispatched and takes the instance; print the numeric code in the create window. Per-op
errors come from ovstage_wait_op + ovstage_get_last_op_error (see error-handling).
Python
The Python bindings expose the same lifecycle — Stage + PathDictionary context
managers, async ops returning handles with .wait(), write → advance write floor → read. See
project-setup-python for the package surface. The verified example walks it end to end:
Source: examples/python/minimal/main.py snippet setup
Followed by: examples/python/minimal/main.py snippet intern-and-resolve
Followed by: examples/python/minimal/main.py snippet path-list-query
Followed by: examples/python/minimal/main.py snippet minimal-write-read
The public Python test asserts the same round-trip against the produced package:
Source: tests/python/test_minimal.py snippet write-read-roundtrip
References
- Use the
> **Source:** directives in this skill to locate tested snippets before reusing API patterns.
project-setup-c — instance creation and build/link setup.
path-dictionary / string-handling — prim/attribute identity (tokens, path lists, queries).
cpu-ahead-gpu-async — the async submit/observe model and ordinal/write-floor semantics.
dlpack-tensor-exchange — attribute data as DLPack tensors (write/read/map).
error-handling — status checks and per-op error reporting throughout the lifecycle.
- Keep related skills, docs, and snippets synchronized when changing the workflow.
1---2name: application-flow-33description: "End-to-end ovstage application lifecycle: create an instance, identify prims/attributes via the path dictionary, write attribute columns at an ordinal, advance the write floor to seal them, query/read, and release. Use when user asks how to structure an ovstage program, what the main steps are, or how the pieces fit together."4license: LicenseRef-NvidiaProprietary5---67# Application Flow89## When to Use1011Use this skill when the user asks how to structure an ovstage program end-to-end, what the12main steps are, how the pieces (instance, path dictionary, query, write/ordinal/write-floor,13read, release) fit together, or which focused skill owns each step.1415## Inputs1617Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.1819- Lifecycle stage in question: instance creation, prim/attribute identity, write, seal20 (advance write floor), query/read, or release.21- Whether the program ingests existing **USD** (the population API, `ovstage_population.h`)22 or **writes attributes directly** (the path shown here).23- Whether it's a one-shot write→read or a running producer/consumer loop (CPU running ahead24 of execution — see `cpu-ahead-gpu-async`).25- The shipped headers and the referenced example snippets are the authoritative contract.2627## Prerequisites2829- Use an ovstage checkout that contains the `include/` headers and the referenced example/snippets.30- Read the relevant `> **Source:**` snippet before writing or explaining API usage.31- Understand the async **submit/observe** model (`cpu-ahead-gpu-async`): state-mutating and32 data-producing calls are enqueues; nothing is done until you `wait_op` / `fetch_*`.33- Remember this build is **latest-snapshot only for payloads**. Exact change membership is34 retained across a bounded set of completed write-floor epochs; query35 `ovstage_get_oldest_preserved_ordinal` before consuming an older range.3637## Instructions38391. **Create the instance** (`ovstage_create_instance`) and obtain its instance-owned path40 dictionary (`ovstage_get_path_dictionary`).412. **Establish identity:** intern the attribute name → `ovx_token_t`, build a prim-path list,42 and open a query over it (`ovstage_query_from_path_list`).433. **Write** attribute values at an `ordinal` (`ovstage_write_attribute`); observe the44 enqueue with `ovstage_wait_op`.454. **Seal:** advance the write floor to that ordinal (`ovstage_advance_write_floor`) so data46 at/below it is immutable and readable.475. **Read:** `ovstage_read_attributes` over an ordinal range → `ovstage_fetch_read_next` →48 consume `group.data` tensors.496. **Release in reverse:** the read group, the read handle, the path-list reference, then50 destroy the instance.517. **Layer in the focused skills** as concerns arise: tensor data (`dlpack-tensor-exchange`),52 submit/observe & concurrency (`cpu-ahead-gpu-async`), error reporting (`error-handling`),53 string/token identity (`string-handling`, `path-dictionary`).54 Once a committed snapshot must be persisted as USD, route to `exporting-to-usd`;55 it owns selection, destination lifetime, save ownership, and export-specific waits.5657## Output Format5859- For explanations, return an ordered lifecycle with the relevant follow-on skills.60- For code changes, summarize the lifecycle files touched, snippets affected, and validation run.6162## Scripts6364This skill has no scripts.6566## Limitations6768- The referenced snippets remain the source of truth; this skill composes the minimal69 example's snippets in lifecycle order rather than introducing new code.70- **Ordinal surface, latest-only payloads:** ordinals, write floors, ordinal ranges, and71 `ovstage_get_oldest_preserved_ordinal` describe ordering, sealing, and retained72 change/deletion membership — that surface is part of the API contract. **In the current73 build**, payload reads are latest-snapshot only and do not provide historical payload74 versions. At or above the reported inclusive retention frontier, a range selects exact75 changed/deleted membership. It returns current payload/delete state only when the selected76 key has no retained successor after the range end; otherwise it returns77 `OVSTAGE_ERROR_OUT_OF_RANGE`. Below that frontier, membership may be coalesced or discarded.78 Do not treat an ordinal range as a historical-payload event log.79- **USD population not covered here.** Ingesting existing USD uses the population API80 (`ovstage_population.h`); this skill documents the direct write/read lifecycle.81- **⚠️ Draft — API in flux.** Treat exact symbols/ordering as provisional against the headers.8283## Overview8485ovstage is a **data stage, not a renderer**. A program creates an instance, identifies86prims/attributes through the (instance-owned) path dictionary, writes attribute columns at87**ordinals**, **seals** them by advancing the write floor, and reads them back — all on the88asynchronous submit/observe model. (ovrtx's renderer lifecycle — Camera / RenderProduct /89`step()` / render output — does not apply.)9091Two cross-cutting rules shape every stage:9293- **Async enqueue / observe.** Enqueue is synchronous and cheap and returns an `op_index`; the94 CPU can run ahead. Same-ordinal ops execute in submission order; different-ordinal ops are95 independent. Block or poll with `ovstage_wait_op`. (→ `cpu-ahead-gpu-async`)96- **Ordinals + write floor.** Writes carry an `ordinal`. Advancing the **write floor** seals97 everything at/below it; reads target sealed data at/below the floor, while queries resolve98 against the latest committed state.99100## Lifecycle101102```1031. Create instance → project-setup-c1042. Get path dictionary → path-dictionary1053. Identify prims + attributes → path-dictionary, string-handling106 (intern token, build path list, open query)1074. Write attribute(s) at an ordinal → dlpack-tensor-exchange (data) + cpu-ahead-gpu-async (submit/observe)1085. Advance the write floor (seal) → cpu-ahead-gpu-async1096. Read / fetch → dlpack-tensor-exchange1107. Release + destroy instance → error-handling (status checks throughout)111```112113Optional: ingest existing USD via the population API (`ovstage_population.h`) instead of, or114before, direct writes.115116## C — end-to-end117118The minimal example walks the whole lifecycle. After `ovstage_create_instance` (see119`project-setup-c`), compose these snippets in order — get the path dictionary + intern a120token, build a path list + open a query, form the attribute argument, then write → seal →121read:122123> **Source:** `examples/c/minimal/main.cpp` snippet `intern-and-resolve`124>125> Followed by: `examples/c/minimal/main.cpp` snippet `path-list-query`126>127> Followed by: `examples/c/minimal/main.cpp` snippet `string-or-token-arg`128>129> Followed by: `examples/c/minimal/main.cpp` snippet `minimal-write-read`130131Every state-mutating / data-producing call is an async enqueue; drive each to completion and132check synchronous calls along the way:133134> **Source:** `examples/c/minimal/main.cpp` snippet `enqueue-wait-error`135>136> And for synchronous calls: `examples/c/minimal/main.cpp` snippet `check-sync-error`137138The public C test asserts this whole round-trip (write → seal → read → verify the139values) against the produced package, not just prints it:140141> **Source:** `tests/c/test_minimal.cpp` snippet `write-read-roundtrip-c`142143The essential ordering is: `ovstage_create_instance` → `ovstage_get_path_dictionary` →144intern token / `path_dictionary_create_path_list_from_strings` → `ovstage_query_from_path_list`145→ `ovstage_write_attribute` *(ordinal)* → `ovstage_advance_write_floor` *(seal)* →146`ovstage_read_attributes` → `ovstage_fetch_read_next` → release (`ovstage_release_group` →147`ovstage_release_read` → `path_dictionary_release_path_list_reference`) →148`ovstage_destroy_instance`.149150## Key Stages / Functions151152| Stage | Function(s) | Detail skill |153|-------|-------------|--------------|154| Create / destroy instance | `ovstage_create_instance` / `ovstage_destroy_instance` | `project-setup-c` |155| Path dictionary (identity) | `ovstage_get_path_dictionary`, `path_dictionary_create_tokens_from_strings`, `path_dictionary_create_path_list_from_strings` | `path-dictionary`, `string-handling` |156| Query target prims | `ovstage_query_from_path_list` | `path-dictionary` |157| Write (ordinal-keyed) | `ovstage_write_attribute` (+ `ovstage_write_data_t`) | `dlpack-tensor-exchange`, `cpu-ahead-gpu-async` |158| Seal | `ovstage_advance_write_floor` | `cpu-ahead-gpu-async` |159| Read | `ovstage_read_attributes` → `ovstage_fetch_read_next` → `ovstage_release_group` | `dlpack-tensor-exchange` |160| Observe / errors | `ovstage_wait_op`, `ovstage_get_error_string`, `ovstage_get_last_op_error` | `cpu-ahead-gpu-async`, `error-handling` |161162## Troubleshooting163164- **Read fails with `OVSTAGE_ERROR_WRITE_FLOOR_VIOLATION` after a write** — the selected state is165 not sealed; call `ovstage_advance_write_floor` to/above its ordinal. Also remember that enqueue166 success means *accepted*, not *executed* (wait/fetch first). See `cpu-ahead-gpu-async`.167- **Fixed range fails with `OVSTAGE_ERROR_OUT_OF_RANGE`** — a selected `(attribute, path)` has a168 retained successor after the range end, so latest-only storage cannot represent that window.169 Widen/rebase the range, repoll from a newer cursor, or explicitly request latest state.170 Advancing the floor alone does not resolve it.171- **Write rejected (`OVSTAGE_ERROR_WRITE_FLOOR_VIOLATION`)** — you wrote at an ordinal at or172 below the current write floor. Write above the floor, then advance the floor afterward.173- **Expecting historical payloads from an ordinal range** — unsupported in this174 latest-snapshot build. Ranges at or above the reported retention frontier provide exact175 changed-prim membership; representable ranges carry current payload/delete state, while a176 retained same-key successor after the range end produces `OUT_OF_RANGE`.177- **Leaks / teardown crashes** — release in reverse: the read group, the read handle, the178 path-list reference, *then* destroy the instance (the path dictionary is instance-owned —179 never free it yourself).180- **Can't stringify an error before the instance exists** — `ovstage_get_error_string` is181 vtable-dispatched and takes the instance; print the numeric code in the create window. Per-op182 errors come from `ovstage_wait_op` + `ovstage_get_last_op_error` (see `error-handling`).183184## Python185186The Python bindings expose the same lifecycle — `Stage` + `PathDictionary` context187managers, async ops returning handles with `.wait()`, write → advance write floor → read. See188`project-setup-python` for the package surface. The verified example walks it end to end:189190> **Source:** `examples/python/minimal/main.py` snippet `setup`191>192> Followed by: `examples/python/minimal/main.py` snippet `intern-and-resolve`193>194> Followed by: `examples/python/minimal/main.py` snippet `path-list-query`195>196> Followed by: `examples/python/minimal/main.py` snippet `minimal-write-read`197198The public Python test asserts the same round-trip against the produced package:199200> **Source:** `tests/python/test_minimal.py` snippet `write-read-roundtrip`201202## References203204- Use the `> **Source:**` directives in this skill to locate tested snippets before reusing API patterns.205- `project-setup-c` — instance creation and build/link setup.206- `path-dictionary` / `string-handling` — prim/attribute identity (tokens, path lists, queries).207- `cpu-ahead-gpu-async` — the async submit/observe model and ordinal/write-floor semantics.208- `dlpack-tensor-exchange` — attribute data as DLPack tensors (write/read/map).209- `error-handling` — status checks and per-op error reporting throughout the lifecycle.210- Keep related skills, docs, and snippets synchronized when changing the workflow.