# Omniverse Client Library — Runtime behavior (usage)

How the library behaves at runtime when you call the public C or Python API. For API surface and parameters, see `references/c-api.md` and `references/python-api.md`. For knobs and auth, see `references/configuration.md`.

## URL routing

Every operation uses a URL. The **scheme** (and for OmniStorage, discovery registration) selects the backend:

| Scheme / pattern | Typical backend |
|---|---|
| `*` (OmniStorage) first | OmniStorage gRPC intercepts URLs it recognizes (discovery / env) before other handlers |
| `omniverse://` / `omni://` | Nucleus or OmniStorage, depending on registration |
| `http://` / `https://` | Generic HTTP, or S3/Azure when the hostname matches those providers |
| `file://` or bare paths | Local filesystem |

OmniStorage registers with a wildcard scheme and gets **first** routing priority when it recognizes a URL.

## Async model and threads

- Operations are **async at the core**: C APIs take a callback and `userData`; Python offers blocking, `async`, and callback variants.
- **Callbacks may not run on the thread that issued the request.** The library dispatches completion callbacks from an internal **tick** path so work is ordered consistently with shutdown and other I/O.
- **Python:** C callbacks are marshaled onto a **dedicated callback thread** that acquires the GIL before running your Python handler. Blocking Python calls release the GIL so other Python threads can run.
- Design UI and other thread-safe boundaries accordingly (e.g. marshal to your main/UI thread if required).

## HTTP / S3 / Azure: list and stat caching

HTTP-based providers may **cache** `list()` and `stat()` results client-side for performance.

- **C:** `omniClientClearListCache(url)` clears cached list/stat state for the matching provider.
- **Python:** `omni.client.clear_list_cache(url)` — same idea.

Use this when you need a fresh view after remote changes.

## Live collaboration (two mechanisms)

**Live sessions** — Create/list/join sessions on a layer URL; presence and messaging. Works across providers that support the session APIs.

**Live objects** (Nucleus-oriented) — Lower-level live object read/update with jitter handling. For Nucleus, **`live_process()` must be driven from the main thread** as required by your app model (see public docs and `references/python-api.md` / `references/c-api.md` for the exact functions).

Pick the API that matches your product (sessions vs. live objects); do not mix semantics blindly.

## Supported platforms

Windows x64, Linux x86_64, Linux aarch64 (as documented in the official client-library release notes and public docs).
