[seo-rii]

Stacked on adobe#46 ("let callers set ONNX Runtime session threads", by another contributor). Its commit is mirrored here as upstream/pr-46-session-threads, so review only db4470a. This extends adobe#46's SessionOptions instead of adding a parallel options type, and does not duplicate the thread API.

Problem

The crate always runs on ONNX Runtime's CPU provider. There was no way to request a GPU, to choose what happens when the GPU can't be used, or to find out which provider actually ran.

Change

• SessionOptions gains two fields; it is still Copy/Eq, and defaults are unchanged:
  • execution_provider: ExecutionProvider, default Cpu;
  • fallback: ProviderFallback, default Error.
• ExecutionProvider { Cpu, Cuda { device_id } } is #[non_exhaustive] and implements Display.
  • The CUDA path needs the new opt-in cargo feature cuda = ["ort/cuda"].
  • Without the feature, requesting Cuda fails when the model loads, with a message that names the feature.
• ProviderFallback { Error, Cpu } chooses between failing and falling back to the CPU when the provider can't be registered.
• Diagnostics: Trustmark::encoder_provider() / decoder_provider() return ProviderInfo { requested, registered, fallback_reason }.
• New error: Error::ExecutionProvider { provider, source }.
  • If building the session with the provider fails, the model is retried on the CPU before the provider is blamed. A missing model file therefore still reports Error::Ort.
• Documented limit: registered means the provider was registered. It does not prove every node runs on it; ORT only logs node placement. The README explains how to see it with ORT_LOG=verbose and a tracing subscriber.
• The session mutexes and the default behaviour are unchanged.
• CoreML and DirectML are not added because they can't be tested here; non_exhaustive leaves room for them.

GPU verification (NVIDIA A100 80GB, driver 580.105.08)

• Setup: CUDA 12.9 and cuDNN 9.27 runtime libraries came from the nvidia-*-cu12 wheels via LD_LIBRARY_PATH. The binaries were built with --features cuda (ORT 1.22, CUDA 12 build).
• Tests: 31/31 pass with --include-ignored.
• ORT verbose log, for both models: "Successfully registered CUDAExecutionProvider" and "All nodes placed on [CUDAExecutionProvider]" (52 encoder nodes, 125 decoder nodes); MemcpyTransformer modified 0 nodes.
• nvidia-smi: the bench process held 778 MiB in 45 of 48 samples.
• Bad device id: rejected when the provider is registered ("Invalid device ID: 9").

Timings (median of 20 warm runs, Q/BCH_5, same host; CPU with 8 intra-op threads):

Image	Step	CUDA	CPU
ghost 512×512	encode	26.7 ms	88.2 ms
ghost 512×512	decode	5.0 ms	47.5 ms
ripley 4032×2268	encode	877.5 ms	932.3 ms
ripley 4032×2268	decode	36.9 ms	74.3 ms

• Loading took 442 ms on CUDA and 290 ms on CPU.
• The first CUDA encode took 1106 ms, from CUDA start-up and cuDNN's algorithm search.
• Encoding large images is dominated by image processing on the CPU; a separate PR targets that.

Deployment note (added to the README): a standalone binary does not find libonnxruntime_providers_shared.so next to itself. It must be on LD_LIBRARY_PATH; cargo run and cargo test set this up automatically.

Local checks

• cargo fmt --check passes.
• clippy with -D warnings passes, both with default features and with --all-features.
• cargo test --workspace: 29 lib tests plus 2 doctests pass.
• --features cuda on a machine without a GPU: 28 pass and the 3 GPU tests are ignored. The fallback test hit a real registration failure (missing libcublasLt.so.12) and fell back as expected.
• cargo doc and cargo publish --dry-run --locked (default features) pass, and so does the MSRV 1.88 check, also with --features cuda --lib.

Compatibility

• The new Error variant breaks exhaustive matches downstream, because Error is not #[non_exhaustive]. The next release should therefore be 0.5.0.
• CI's clippy step uses --all-features, so it will now also download the ~170 MB CUDA build of ORT.
• Only Linux x86-64 was tested.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.