Status Queries

Status Queries

When to Use

Use this skill when the user asks how to monitor long-running operations, show loading progress, inspect OperationStatus counters, use Operation.query_status(), or call ovrtx_query_op_status()/ovrtx_release_op_status().

Inputs

Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.

• Target API surface: Python, C/C++, or both.
• Operation whose progress should be queried: Python Operation or C operation index.
• Status fields the caller needs, such as progress, counters, labels, pending/running state, or log output.
• Poll interval, timeout behavior, and whether the final result still needs wait()/fetch().
• Repository source snippets referenced below. Treat these snippets as the API source of truth.

Prerequisites

• Use an ovrtx checkout that contains the referenced examples and docs tests.
• Read the relevant > **Source:** snippet before writing or explaining API usage.
• Use async-operations for the broader wait/fetch lifecycle; this skill covers progress snapshots while the operation is pending.

Instructions

1. Identify the async operation whose progress should be displayed or logged.
2. Poll status only while the operation is pending; treat a completed wait result as the authority for success or failure.
3. In Python, use Operation.query_status() for progress fields and keep the final wait()/fetch() lifecycle intact.
4. In C, use ovrtx_query_op_status() with the operation index and release the returned status object after reading it.
5. When changing code, run the status-query example for the operation type whenever practical.

Output Format

• For explanations, cite the relevant API names, source snippets, and caveats.
• For code changes, summarize the files changed, snippets affected, and validation run.

Scripts

This skill has no scripts.

Limitations

• The referenced snippets remain the source of truth; update or add tested snippets before documenting new API usage.

Overview

Status queries take a point-in-time snapshot of an async operation. Use them for long-running work such as USD loading, shader/material preparation, stage queries, attribute writes, or render steps when an application needs progress feedback instead of only blocking on completion.

Status queries complement waits:

1. Enqueue an operation and keep its operation object or op_index.
2. Query status before or during polling.
3. Wait until the operation completes.
4. Fetch any second-phase results if the operation has them.

Progress is operation-dependent. progress < 0.0 means indeterminate, and a counter total of 0 means the total is not currently known.

Python

Python async methods return Operation objects. Call Operation.query_status() while the operation is still active. After Operation.wait() completes, the operation releases its wait-phase context and query_status() is no longer available for that Operation.

Format an OperationStatus

Source: examples/python/status-queries/main.py snippet format-operation-status

Poll with status

Source: examples/python/status-queries/main.py snippet wait-operation-with-status

Load USD with status

USD population runs on the attached ovstage. Population operations expose no OperationStatus counters; poll them with a bounded wait(timeout=...) loop (nanoseconds, None return means still pending) and publish the ordinal once the load completes. Renderer operations (step, shader warm-up) keep the full status-counter API shown below.

Source: examples/python/status-queries/main.py snippet load-usd-with-status

Shader-cache warm-up with status

Source: examples/python/status-queries/main.py snippet compile-shader-cache-with-status

Step with status

Source: examples/python/status-queries/main.py snippet step-with-status

C

C enqueue calls return ovrtx_enqueue_result_t. Check .status first, then use .op_index with ovrtx_query_op_status() and ovrtx_wait_op().

Every successful ovrtx_query_op_status() call must be paired with ovrtx_release_op_status(). Strings and counters inside ovrtx_op_status_t are invalid after release, so copy anything that must outlive the query.

Format an ovrtx_op_status_t

Source: examples/c/status-queries/main.cpp snippet format-operation-status-c

Poll with status

Source: examples/c/status-queries/main.cpp snippet wait-operation-with-status-c

Shader-cache warm-up with status

Source: examples/c/status-queries/main.cpp snippet compile-shader-cache-with-status-c

Step with status

Source: examples/c/status-queries/main.cpp snippet step-with-status-c

Key Types / Functions

Troubleshooting

• Query status before Operation.wait() completes in Python. Once wait() returns a final result, query_status() raises because the operation context has been released.
• In C, call ovrtx_release_op_status() once for each successful ovrtx_query_op_status() call.
• Status query snapshots are not completion barriers. Continue to call wait() / ovrtx_wait_op() before using results from the operation.
• ovrtx_wait_op() waits for all queued operations up to and including the requested op_id, so status for one operation may reflect progress while earlier operations are also draining.
• Counters are operation-dependent. Do not hard-code a fixed set of counter names unless the application owns the operation type and runtime version.

References

• Use the > **Source:** directives in this skill to locate tested snippets before reusing API patterns.
• Keep related skills, docs, and snippets synchronized when changing the workflow.