feat: add ffi::Expected<T> for exception-free error handling #399

guan404ming · 2026-01-11T15:38:35Z

Why

Enable exception-free C++ API similar to Rust's Result or C++23's std::expected, as requested in #234.

How

Add Expected<T> class holding either success value T or Error
Add Function::CallExpected<T>() for exception-free function calls
Add is_expected type trait and Expected handling in unpack_call
Support registering functions that return Expected<T>"

gemini-code-assist · 2026-01-11T15:38:52Z

Summary of Changes

Hello @guan404ming, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the error handling capabilities within the FFI layer by introducing a new Expected type. This type provides a robust, exception-free mechanism for FFI functions to communicate either a successful result or a detailed error, aligning with modern C++ practices and similar patterns in other languages. The changes ensure that FFI calls can explicitly manage potential failures without relying on exceptions for control flow, leading to more predictable and maintainable code.

Highlights

Introduced ffi::Expected: A new type for exception-free error handling, similar to Rust's Result or C++23's std::expected, allowing functions to return either a success value T or an Error.
Added Function::CallExpected(): A new method for FFI function calls that returns an Expected, converting any caught exceptions into Error objects within the Expected type.
Enhanced FFI Type System: Integrated Expected into the FFI type traits (is_expected and RetSupported) and the unpack_call mechanism, enabling seamless handling of functions returning Expected.
Support for Registering Expected-Returning Functions: Functions that return Expected can now be registered with the FFI system, allowing them to be called from other languages or contexts while preserving the explicit error handling.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces ffi::Expected<T> for exception-free error handling, a valuable addition for creating more robust FFI functions. The implementation is comprehensive, covering the Expected<T> class, integration with tvm::ffi::Function via CallExpected, and support for packed functions returning Expected<T>. The tests are thorough and cover many important use cases.

The overall approach of using tvm::ffi::Any for storage within Expected<T> is a clever way to leverage the existing FFI infrastructure. I have a few suggestions to simplify the TypeTraits specialization and to add move semantics for value/error accessors, which would improve code clarity and performance. Overall, this is a well-executed feature.

gemini-code-assist · 2026-01-11T15:41:47Z

include/tvm/ffi/expected.h

+  TVM_FFI_INLINE T value() const {
+    if (is_err()) {
+      TVM_FFI_THROW(RuntimeError) << "Bad expected access: contains error";
+    }
+    return data_.cast<T>();
+  }


The value() method is const-qualified, which means it always returns a copy of the contained value. This can be inefficient when the Expected object is an rvalue (e.g., a temporary returned from a function). Consider adding an rvalue-qualified overload to allow moving the value out. This would improve performance in scenarios like std::move(expected).value().

You can change the existing method to be const&-qualified and add a &&-qualified overload:

TVM_FFI_INLINE T value() const& { if (is_err()) { TVM_FFI_THROW(RuntimeError) << "Bad expected access: contains error"; } return data_.cast<T>(); } TVM_FFI_INLINE T value() && { if (is_err()) { TVM_FFI_THROW(RuntimeError) << "Bad expected access: contains error"; } return std::move(data_).cast<T>(); }

gemini-code-assist · 2026-01-11T15:41:47Z

include/tvm/ffi/expected.h

+  TVM_FFI_INLINE Error error() const {
+    TVM_FFI_ICHECK(is_err()) << "Expected does not contain an error";
+    return data_.cast<Error>();
+  }


Similar to value(), the error() method is const-qualified and always returns a copy. You can add an rvalue-qualified overload to allow moving the Error object out, which is more efficient.

TVM_FFI_INLINE Error error() const& { TVM_FFI_ICHECK(is_err()) << "Expected does not contain an error"; return data_.cast<Error>(); } TVM_FFI_INLINE Error error() && { TVM_FFI_ICHECK(is_err()) << "Expected does not contain an error"; return std::move(data_).cast<Error>(); }

gemini-code-assist · 2026-01-11T15:41:47Z

include/tvm/ffi/expected.h

+  TVM_FFI_INLINE static void CopyToAnyView(const Expected<T>& src, TVMFFIAny* result) {
+    // Extract value from src.data_ and copy it properly
+    const TVMFFIAny* src_any = reinterpret_cast<const TVMFFIAny*>(&src.data_);
+
+    if (TypeTraits<T>::CheckAnyStrict(src_any)) {
+      // It contains T, copy it out and move to result
+      T value = TypeTraits<T>::CopyFromAnyViewAfterCheck(src_any);
+      TypeTraits<T>::MoveToAny(std::move(value), result);
+    } else {
+      // It contains Error, copy it out and move to result
+      Error err = TypeTraits<Error>::CopyFromAnyViewAfterCheck(src_any);
+      TypeTraits<Error>::MoveToAny(std::move(err), result);
+    }
+  }


The implementation of CopyToAnyView is correct but can be simplified. Instead of checking the type and manually performing a copy-then-move for each case, you can leverage the Any type's copy constructor to handle the logic. This makes the code more concise and less error-prone, as it relies on the already-tested Any copy semantics.

TVM_FFI_INLINE static void CopyToAnyView(const Expected<T>& src, TVMFFIAny* result) { // An Expected<T> is represented by its underlying value (T or Error) // at the FFI boundary. We can simply copy the contained Any. Any copied_any = src.data_; *result = details::AnyUnsafe::MoveAnyToTVMFFIAny(std::move(copied_any)); }

gemini-code-assist · 2026-01-11T15:41:47Z

include/tvm/ffi/expected.h

+  TVM_FFI_INLINE static void MoveToAny(Expected<T> src, TVMFFIAny* result) {
+    // Extract value from src.data_ and move it properly
+    TVMFFIAny* src_any = reinterpret_cast<TVMFFIAny*>(&src.data_);
+
+    if (TypeTraits<T>::CheckAnyStrict(src_any)) {
+      // It contains T, move it out and move to result
+      T value = TypeTraits<T>::MoveFromAnyAfterCheck(src_any);
+      TypeTraits<T>::MoveToAny(std::move(value), result);
+    } else {
+      // It contains Error, move it out and move to result
+      Error err = TypeTraits<Error>::MoveFromAnyAfterCheck(src_any);
+      TypeTraits<Error>::MoveToAny(std::move(err), result);
+    }
+  }


Similar to CopyToAnyView, the MoveToAny implementation can be greatly simplified. Since src is passed by value (effectively a move), you can move the underlying Any object directly. This is more readable and directly expresses the intent of moving the contained value.

TVM_FFI_INLINE static void MoveToAny(Expected<T> src, TVMFFIAny* result) { // An Expected<T> is represented by its underlying value (T or Error) // at the FFI boundary. We can simply move the contained Any. *result = details::AnyUnsafe::MoveAnyToTVMFFIAny(std::move(src.data_)); }

tqchen · 2026-01-12T14:15:11Z

Thanks a lot for the contribution, this would benefit from careful reviews, @junrushao @DarkSharpness @Ubospica can you help

Kathryn-cat · 2026-01-14T16:24:22Z

@guan404ming Thanks for the contribution! I will take a closer look sometime this week to provide a round of review.

Kathryn-cat · 2026-01-20T07:58:09Z

include/tvm/ffi/expected.h

+   */
+  TVM_FFI_INLINE T value() const {
+    if (is_err()) {
+      TVM_FFI_THROW(RuntimeError) << "Bad expected access: contains error";


If value() failed, it appears that it throws an error here but doesn't preserve the original error. Is it possible to retain the original error information?

Done. Changed value() to throw the contained error directly instead of a generic RuntimeError:

if (is_err()) { throw data_.cast<Error>(); }

Kathryn-cat · 2026-01-20T08:20:17Z

include/tvm/ffi/expected.h

+    if (is_err()) {
+      TVM_FFI_THROW(RuntimeError) << "Bad expected access: contains error";
+    }
+    return data_.cast<T>();


For large data, we can use move instead of copy, so I agree with Gemini that we can add an overload function here:

TVM_FFI_INLINE T value() && { if (is_err()) { throw error(); } return std::move(data_).cast<T>(); }

Agree as well. I've added both const& and && qualified overloads for value():

Kathryn-cat · 2026-01-20T08:29:25Z

include/tvm/ffi/expected.h

+   * \brief Check if the Expected contains an error.
+   * \return True if contains error, false if contains success value.
+   */
+  TVM_FFI_INLINE bool is_err() const { return data_.as<Error>().has_value(); }


It is likely that ObjectRef as a base class of Error can have both is_ok()=True and is_err()=True, since CheckAnyStrict relies on inheritance checking, not type matching. I would suggest returning !is_ok() here.

Also it would be helpful to enhance the test cases on this.

Changed is_err() to return !is_ok() and also fixed is_ok() to check for Error first.

Kathryn-cat · 2026-01-20T08:41:38Z

include/tvm/ffi/expected.h

+  /*!
+   * \brief Access the error value.
+   * \return The error value.
+   * \note Behavior is undefined if the Expected contains a success value.


Let's instead of saying "behavior is undefined", say it throws a RuntimeError on bad access.

Perhaps change the function body into

if (!is_err()) { TVM_FFI_THROW(RuntimeError) << "Bad expected access: contains value, not error"; }

to mimic value() impl.

Sure, I've updated the docstring and changed from TVM_FFI_ICHECK to TVM_FFI_THROW(RuntimeError)

guan404ming changed the title ~~feat: Add ffi::Expected<T> for exception-free error handling~~ feat: add ffi::Expected<T> for exception-free error handling Jan 11, 2026

gemini-code-assist bot reviewed Jan 11, 2026

View reviewed changes

guan404ming force-pushed the feat/expected-type branch from 2f70b38 to f1a4dc9 Compare January 11, 2026 15:46

guan404ming marked this pull request as ready for review January 12, 2026 02:56

tqchen assigned Kathryn-cat Jan 14, 2026

Kathryn-cat suggested changes Jan 20, 2026

View reviewed changes

feat: Add ffi::Expected<T> for exception-free error handling

b510df6

guan404ming force-pushed the feat/expected-type branch from f1a4dc9 to 486f68e Compare January 20, 2026 11:20

guan404ming requested a review from Kathryn-cat January 20, 2026 11:21

refactor: apply review comments

ad48e1b

guan404ming force-pushed the feat/expected-type branch from 486f68e to ad48e1b Compare January 20, 2026 11:27

feat: add ffi::Expected<T> for exception-free error handling #399

Are you sure you want to change the base?

feat: add ffi::Expected<T> for exception-free error handling #399

Conversation

guan404ming commented Jan 11, 2026

Why

How

Uh oh!

gemini-code-assist bot commented Jan 11, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jan 11, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 11, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 11, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 11, 2026

Choose a reason for hiding this comment

Uh oh!

tqchen commented Jan 12, 2026

Uh oh!

Kathryn-cat commented Jan 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants