[Feature Request] Introduce `ffi::Expected<>`

[junrushao]

Goal Enable an exception-free C++ API by introducing an ffi::Expected<T> type (mirroring std::expected / Rust Result) and wiring it through ffi::Function invocation and registration.

Problem Current ffi::Function calls always return Any; failures rely on exceptions. Consumers needing hard real-time or exception-free environments lack a native way to detect errors without exceptions, and we can’t guanratee callbacks are all exception-free.

Proposal

• Add ffi::Expected<T> where T is any type TVM-FFI supports but not tvm::ffi::Error; Err is always ffi::Error.
• Extend ffi::Function invocation helpers so users can request wrappers of type (Args...) -> ffi::Expected<T>; calls that produce an ffi::Error fill the error branch instead of throwing.
• Allow registering functions that implement (Args...) -> ffi::Expected<T>; the dispatcher should convert returned Expected objects into the existing error propagation path so current exception-based APIs keep working.
• Document usage patterns, including examples of calling and registering Expected functions, and guidance on when to "use exception" vs. Expected flows.

[tqchen]

Some notes:

• ffi::Expected<T> can be effectively implemented like ffi::Variant
  • We forbid T to be ffi::Error
• We can add ffi::Function::CallExpected (naming of CallExpected can be debated), it simply redirect to the TVMFFISafeCall

func : ffi::Function = ...;
ffi::Expected<Any> res = func.CallExpected(a0, a1, a2);

• Add ffi::Function::FromTypedExpected (similar to FromTyped, naming can be debated) that takes (Args...) -> ffi::Expected<T> and convery into ffi function

At high-level, a ffi::Function can be called with normal mode(throws exception) or expected mode(always go through safe call and converts into Expected). The currenr runtime mechanism should enable such interop quite nicely

[junrushao]

CC @DarkSharpness if you are interested

[Ubospica]

Good topic! FYI, we had an implementation for expected (named Result) in xgrammar: https://github.com/mlc-ai/xgrammar/blob/main/cpp/support/utils.h#L251. Below are several of its design choices, which could be helpful for the design here:

• It forces moving its content in or out of the result object, to eliminate the overhead of copying content
• Provides a ResultOk and ResultErr util functions that don't require explicitly specifying template parameters
• Allows constructing object / error object with their constructor parameters within ResultOk and ResultErr

The implementation is also attributed to @DarkSharpness. Just wanna paste it here for reference.

Also can we allow ffi::Expected<T, E> where E is a subclass of Error? This would be helpful for downstream applications that customizes the error class (e.g. Error id).

[prabalpatkar558412-collab]

Hi @junrushao,
I’ve gone through the discussion and the design around adding ffi::Expected, and I’m really interested in taking this on. I’m comfortable with the C++ FFI pieces and can handle the Expected type, the CallExpected path, the typed-expected registration flow, and the docs/examples.

If no one is actively working on it, I’d be happy to pick it up.
Could you assign the issue to me?

Thanks!