feat(rust): add ordered match_any dispatch

Author: tlopex

docs/reference/rust/index.rst

@@ -37,4 +37,4 @@ The Rust API is organized into three crates:
    * - 📦 `tvm-ffi-sys <generated/tvm_ffi_sys/index.html>`_
      - Low-level unsafe bindings to the C API.
    * - 📦 `tvm-ffi-macros <generated/tvm_ffi_macros/index.html>`_
-     - Procedural macros for deriving Object and ObjectRef traits.
+     - Procedural macros for deriving Object and ObjectRef traits and for ordered matching of erased values.

rust/README.md

@@ -19,6 +19,7 @@
 
 (Experimental) Rust support for the `tvm-ffi` ABI.
 Currently, the rust support is in an experimental stage.
+The workspace requires Rust 1.85 or newer.
 This workspace contains three crates:
 
 - `tvm-ffi`: Safe, ergonomic Rust bindings over the ABI.
@@ -70,3 +71,60 @@ cargo run --example load_library --features example
 ```
 
 Check out the [load_library.rs](tvm-ffi/examples/load_library.rs) for details.
+
+## Ordered Type Matching
+
+`match_any!` matches an erased value against `AnyPattern` implementations in
+source order.  A matcher is evaluated before its guard, a false guard continues
+with the next arm, and a final `_` fallback is required.  The current phase-1
+implementation deliberately uses ordered conditional dispatch; it does not
+build an index table or apply an index-space heuristic.
+
+```rust
+use tvm_ffi::{match_any, Any, AnyPattern, AnyView};
+
+struct Integer;
+
+impl AnyPattern for Integer {
+    type Bound<'a> = i64;
+
+    fn try_match<'a>(value: AnyView<'a>) -> Option<Self::Bound<'a>> {
+        value.try_as::<i64>()
+    }
+}
+
+let value = Any::from(42_i64);
+let result = match_any! {
+    value {
+        Integer(integer) if integer > 0 => integer,
+        _ => 0,
+    }
+};
+assert_eq!(result, 42);
+```
+
+## Object Layout Contracts
+
+Types using `#[derive(Object)]` must use `#[repr(C)]` and place their registered
+base object in the first field.  The declared type key and type index must
+identify a registered TVM-FFI object whose direct parent is that base type.  The
+derive validates these properties when its type index is first used and rejects
+conflicting Rust layout claims for the same runtime index.
+
+Because registry metadata cannot prove every foreign field offset and Rust
+validity invariant, deriving also requires a separate
+`unsafe impl ObjectLayout for MyObject`.  That explicit implementation asserts
+that the complete Rust field ABI matches every foreign allocation registered
+under the type key; it must be reviewed like any other unsafe FFI declaration.
+
+Registration and type lookup use the process-wide TVM-FFI type table.  Type
+registration must finish before concurrent lookup begins, unless the caller
+provides external synchronization.  Manual `unsafe impl ObjectCore`
+implementations remain responsible for the same header, prefix-layout,
+registration, and foreign-ABI compatibility requirements.
+
+Rust-owned `ObjectArc` allocations do not currently support foreign weak
+owners.  Releasing the final strong owner through Rust or C++ while a foreign
+weak owner remains aborts the process rather than permitting access to an
+already-dropped embedded reference-count header.  Cloning an `ObjectArc` also
+aborts before the ABI's 32-bit strong-count field can overflow.

rust/tvm-ffi-macros/Cargo.toml

@@ -21,6 +21,7 @@ description = "Procedural macro crate for tvm-ffi"
 
 version = "0.1.0-alpha.0"
 edition = "2021"
+rust-version = "1.85"
 license = "Apache-2.0"
 
 
@@ -32,3 +33,4 @@ proc-macro2 = "^1.0"
 quote = "^1.0"
 syn = { version = "1.0.48", features = ["full", "parsing", "extra-traits"] }
 proc-macro-error = "^1.0"
+proc-macro-crate = "=3.1.0"

rust/tvm-ffi-macros/src/lib.rs

@@ -20,10 +20,30 @@
 use proc_macro::TokenStream;
 use proc_macro_error::proc_macro_error;
 
+mod match_any;
 mod object_macros;
 mod utils;
 
+/// Match an erased TVM-FFI value against ordered typed patterns.
+///
+/// A pattern is a type that implements `tvm_ffi::AnyPattern`.  Patterns are
+/// attempted in source order, and a false guard continues with the next arm.
+/// A final `_` fallback arm is required.  Shared-reference and `AnyView`
+/// lifetimes are preserved in borrowed bindings.  A mutable-reference
+/// scrutinee is only shared-reborrowed for the invocation, so a binding cannot
+/// use that mutable reference's longer lifetime after the macro returns.
 #[proc_macro_error]
+#[proc_macro]
+pub fn match_any(input: TokenStream) -> TokenStream {
+    match_any::expand(input)
+}
+
+#[proc_macro_error]
+/// Derive the checked `ObjectCore` boilerplate for a registered object struct.
+///
+/// The generated implementation is conditional on a separate manual
+/// `unsafe impl tvm_ffi::ObjectLayout for MyObject`, which is the caller's
+/// explicit assertion that the complete Rust fields match the foreign ABI.
 #[proc_macro_derive(Object, attributes(type_key, type_index))]
 pub fn derive_object(input: TokenStream) -> TokenStream {
     TokenStream::from(object_macros::derive_object(input))