Path Dictionary#

The OVX path dictionary is the shared interning layer that maps strings — attribute names and prim paths — to stable, trivially comparable handles used across OV libraries. Interning a string returns an ovx_token_t; a prim path returns an ovx_primpath_t; a set of paths becomes an immutable ovx_primpath_list_t that you pass to ovstage queries.

For handle-compatible sharing, obtain ovstage’s own dictionary rather than creating a separate one, so handles minted by your application and by ovstage compare directly:

  • C — ovstage_get_path_dictionary.

  • Python — ovstage.PathDictionary(stage) borrows the instance-owned dictionary.

Handle Types#

Handle

Interns

Notes

ovx_token_t

A string (e.g. an attribute name).

Same string always interns to the same token; compare tokens by value.

ovx_primpath_t

A single prim path.

Same path always interns to the same handle.

ovx_primpath_list_t

An ordered set of prim paths.

Immutable after creation; equal list handles imply the same paths in the same order.

The OVX_INVALID_* sentinels are all 0 and are never returned on success. Because identical inputs intern to identical handles, consumers use O(1) handle equality instead of string comparison at every boundary.

Interning and Resolving#

Intern a string to a token, then resolve the token back to its string:

# Intern a string -> a stable integer token, and resolve it back.
attr = paths.intern_token("temperature")
print("attribute token", attr, "=", paths.token_to_string(attr))

// The path dictionary is owned by the instance (no app-side create/destroy):
// obtain it, intern strings -> stable tokens, and resolve tokens back.
path_dictionary_instance_t* dict = ovstage_get_path_dictionary(stage);
if (!dict)
{
    std::fprintf(stderr, "no path dictionary for instance\n");
    return EXIT_FAILURE;
}

ovx_string_t attrName = literal_to_ovx_string("temperature");
ovx_token_t attr = OVX_INVALID_TOKEN;
ovx_api_result_t ovxResult = path_dictionary_create_tokens_from_strings(dict, &attrName, 1, &attr);
checkOvx(dict, ovxResult, "intern-token");

ovx_string_t resolved{};
ovxResult = path_dictionary_get_strings_from_tokens(dict, &attr, 1, &resolved);
checkOvx(dict, ovxResult, "resolve-token");

Building a Path List and Opening a Query#

An interned prim-path list is the input to Queries. Build one from strings and open a query over those prims:

# Build an interned prim-path list and open a query over those prims.
# The query is a context manager: block exit releases its handle, and
# Stage teardown requires all handles released first -- the try/finally
# releases the path list even when an error interrupts the flow.
prim_paths = paths.create_path_list_from_strings(["/World/A", "/World/B", "/World/C"])
try:
    with stage.query_from_path_list(prim_paths) as query:

// Build an immutable prim-path list from strings and open a query over it.
const ovx_string_t paths[] = { literal_to_ovx_string("/World/A"), literal_to_ovx_string("/World/B"),
                               literal_to_ovx_string("/World/C") };
ovx_primpath_list_t pathList = OVX_INVALID_PRIMPATH_LIST;
ovxResult = path_dictionary_create_path_list_from_strings(dict, paths, 3, &pathList);
checkOvx(dict, ovxResult, "create-path-list");

ovstage_query_handle_t query = OVSTAGE_INVALID_QUERY_HANDLE;
status = ovstage_query_from_path_list(stage, pathList, &query);
check(stage, status, "query_from_path_list");

Attribute Arguments: String or Token#

APIs that take an attribute accept either an already-interned token (the hot path — no lookup) or a plain string (interned at call time). In C this is the ovx_string_or_token_t dual-mode argument; in Python you can pass an int token or a str:

# Attribute arguments accept an interned token (int) or a plain str:
# a token skips the per-call dictionary lookup, a str is interned for
# you at call time.
stage.write_attribute(
    query, "temperature", ordinal=2, tensors=np.array([4.0, 5.0, 6.0], np.float32),
    is_array=False,
).wait()
stage.advance_write_floor(ordinal=2).wait()

// Attributes pass as ovx_string_or_token_t. We already hold an interned
// token, so set it (token != 0) and leave the string empty to skip a lookup.
ovx_string_or_token_t attrArg{ attr, {} };

Ownership and Lifetime#

  • The dictionary is owned by its producing subsystem. When you borrow ovstage’s dictionary, do not free its handle; ovstage owns it.

  • Tokens and paths are dictionary-lifetime. They are interned and are never freed individually.

  • Dictionary string pointers are borrowed. In C, an ovx_string_t returned by the dictionary points into dictionary-owned storage; copy it if it must outlive the dictionary (refer to String Handling).

  • Path lists are explicitly refcounted. create_path_list_from_* returns a list owned by the caller; pair each create with exactly one release. A path list handed back inside a read result is a borrow — do not release it.

Errors#

Every C path-dictionary call returns ovx_api_result_t { status, error }; on OVX_API_ERROR the error string must be released with path_dictionary_release_error. In Python, path-dictionary failures raise ovstage.OvxError. Refer to Error Handling and Diagnostics.

Where to Go Next#