Skip to main content

tvm_ffi/
match_any_internal.rs

1/*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements.  See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership.  The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License.  You may obtain a copy of the License at
9 *
10 *   http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied.  See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19
20//! Runtime support for the `match_any!` and `#[dispatch]` expansions. Only
21//! macro output names these items.
22
23use std::any::TypeId;
24use std::marker::PhantomData;
25
26use tvm_ffi_sys::TVMFFITypeIndex as TypeIndex;
27
28use crate::{AnyCompatible, AnyView};
29
30/// Per-call-site arm number assigned by `match_any!`.
31#[doc(hidden)]
32pub type ArmId = u32;
33
34impl<'a, T> From<&'a crate::MutationView<'_, T>> for AnyView<'a> {
35    #[inline(always)]
36    fn from(value: &'a crate::MutationView<'_, T>) -> Self {
37        value.as_any_view()
38    }
39}
40
41/// Holds the matched value. The expansion calls `prepare()`; inherent impls for
42/// `AnyView`, `&T` and `MutationView` take priority over the [`PrepareSource`]
43/// fallback, which selects the source by type at compile time.
44#[doc(hidden)]
45pub struct SourceProbe<T>(Option<T>);
46impl<T> SourceProbe<T> {
47    #[inline(always)]
48    pub fn new(value: T) -> Self {
49        Self(Some(value))
50    }
51}
52
53/// A source read through an `AnyView`.
54#[doc(hidden)]
55pub struct ViewSource<'a>(AnyView<'a>);
56/// A source read through a mutation view, kept so a `MutationView<T>` arm can
57/// narrow it.
58#[doc(hidden)]
59pub struct MutationSource<'a>(crate::MutationView<'a>);
60
61/// Fallback `prepare()` for an owned value: it stays in the probe for the whole
62/// match and is viewed in place, without a move or refcount change.
63#[doc(hidden)]
64pub trait PrepareSource {
65    fn prepare(&mut self) -> ViewSource<'_>;
66}
67impl<T> PrepareSource for SourceProbe<T>
68where
69    for<'a> AnyView<'a>: From<&'a T>,
70{
71    #[inline(always)]
72    fn prepare(&mut self) -> ViewSource<'_> {
73        ViewSource(self.0.as_ref().unwrap().into())
74    }
75}
76impl<'a> SourceProbe<AnyView<'a>> {
77    #[inline(always)]
78    pub fn prepare(&mut self) -> ViewSource<'a> {
79        ViewSource(self.0.take().unwrap())
80    }
81}
82impl<'a, T: ?Sized> SourceProbe<&'a T> {
83    #[inline(always)]
84    pub fn prepare<'out>(&mut self) -> ViewSource<'out>
85    where
86        AnyView<'out>: From<&'a T>,
87    {
88        ViewSource(self.0.take().unwrap().into())
89    }
90}
91impl<'a, T> SourceProbe<crate::MutationView<'a, T>> {
92    #[inline(always)]
93    pub fn prepare(&mut self) -> MutationSource<'a> {
94        MutationSource(self.0.take().unwrap().into_untyped())
95    }
96}
97
98/// Read access arms use on a source: the view, or its cell for in-place borrows.
99#[doc(hidden)]
100pub trait SourceView {
101    fn view(&self) -> AnyView<'_>;
102    /// The source's own cell, which a reference pattern borrows in place.
103    fn cell(&self) -> &crate::tvm_ffi_sys::TVMFFIAny;
104}
105impl SourceView for ViewSource<'_> {
106    #[inline(always)]
107    fn view(&self) -> AnyView<'_> {
108        self.0
109    }
110    #[inline(always)]
111    fn cell(&self) -> &crate::tvm_ffi_sys::TVMFFIAny {
112        self.0.as_raw_ffi_any()
113    }
114}
115impl SourceView for MutationSource<'_> {
116    #[inline(always)]
117    fn view(&self) -> AnyView<'_> {
118        self.0.as_any_view()
119    }
120    #[inline(always)]
121    fn cell(&self) -> &crate::tvm_ffi_sys::TVMFFIAny {
122        self.0.cell()
123    }
124}
125
126/// A value arm `Type(name)`: if the source strictly holds a `Self`, return it
127/// owned. Never consumes the source, so a rejected guard falls through.
128#[doc(hidden)]
129pub trait ValuePattern<S>: Sized {
130    /// `None` leaves the source untouched for the next arm. A typed mutation
131    /// view aliases the source, which the expansion never uses after an arm
132    /// accepts.
133    fn try_match(source: S) -> Option<Self>;
134}
135impl<'b, T: crate::type_traits::ContainerElement, S: SourceView> ValuePattern<&'b mut S> for T {
136    #[inline(always)]
137    fn try_match(source: &'b mut S) -> Option<Self> {
138        let view = source.view();
139        let data = view.as_raw_ffi_any();
140        unsafe {
141            (T::container_check_any_strict(data) && T::container_match_constraints(data))
142                .then(|| T::container_copy_from_any_view_after_check(data))
143        }
144    }
145}
146impl<'a, 'b, 'out> ValuePattern<&'b mut ViewSource<'a>> for AnyView<'out>
147where
148    'a: 'out,
149{
150    #[inline(always)]
151    fn try_match(source: &'b mut ViewSource<'a>) -> Option<Self> {
152        Some(source.0)
153    }
154}
155impl<'a, 'b> ValuePattern<&'b mut MutationSource<'a>> for AnyView<'b> {
156    #[inline(always)]
157    fn try_match(source: &'b mut MutationSource<'a>) -> Option<Self> {
158        Some(source.view())
159    }
160}
161impl<'a, 'b, T: crate::type_traits::ContainerElement> ValuePattern<&'b mut MutationSource<'a>>
162    for crate::MutationView<'a, T>
163{
164    #[inline(always)]
165    fn try_match(source: &'b mut MutationSource<'a>) -> Option<Self> {
166        // SAFETY: the macro-private source is never used after an arm accepts
167        // this view, so the alias stays the only live handle.
168        unsafe { source.0.alias() }.downcast::<T>().ok()
169    }
170}
171
172/// Autoref probe for a reference arm: `(&&&probe).try_match_ref(..)` selects the
173/// borrowing impl when `T: DowncastRefFromAny`, else the owned fallback.
174#[doc(hidden)]
175pub struct RefPatternProbe<T>(PhantomData<fn() -> T>);
176impl<T> RefPatternProbe<T> {
177    #[doc(hidden)]
178    pub const fn new() -> Self {
179        Self(PhantomData)
180    }
181}
182
183/// A reference arm `Type(ref name)`: return a holder that borrows as `&T`, in
184/// place when possible (no refcount change), else an owned `T` from
185/// [`ValuePattern`].
186#[doc(hidden)]
187pub trait RefPattern<'b, S, T> {
188    type Holder: std::borrow::Borrow<T>;
189    /// `None` leaves the source untouched for the next arm.
190    fn try_match_ref(&self, source: &'b mut S) -> Option<Self::Holder>;
191}
192impl<'b, T: crate::type_traits::DowncastRefFromAny + 'static, S: SourceView> RefPattern<'b, S, T>
193    for &&RefPatternProbe<T>
194{
195    type Holder = &'b T;
196    #[inline(always)]
197    fn try_match_ref(&self, source: &'b mut S) -> Option<Self::Holder> {
198        // Borrow the source's own cell, which lives for 'b: a reference type
199        // such as `&Add` points into the cell, an object type into the heap.
200        let node = unsafe { T::downcast_ref_from_any(source.cell()) }? as *const T;
201        // SAFETY: the checked value is borrowed from source for 'b, and the arm
202        // does not modify a list or dict holding it (the `match_any!`
203        // contract). No owning conversion or view transfer can occur while this
204        // borrow lives.
205        Some(unsafe { &*node })
206    }
207}
208impl<'b, S: 'b, T: ValuePattern<&'b mut S>> RefPattern<'b, S, T> for &RefPatternProbe<T> {
209    type Holder = T;
210    #[inline(always)]
211    fn try_match_ref(&self, source: &'b mut S) -> Option<T> {
212        T::try_match(source)
213    }
214}
215
216// ----------------------------------------------------------------------------
217// Jump table: arms that are all exact final types, no guards, 20+ arms
218// ----------------------------------------------------------------------------
219
220/// Type index → arm table for arms that are all exact final types. Built and
221/// validated once per call site; each match is one lookup.
222#[doc(hidden)]
223pub struct JumpTable {
224    type_list_id: TypeId,
225    base: i32,
226    arm_ids: Box<[ArmId]>,
227}
228
229const NO_ARM_ID: ArmId = ArmId::MAX;
230
231impl JumpTable {
232    #[doc(hidden)]
233    #[cold]
234    #[inline(never)]
235    pub fn build(type_list_id: TypeId, type_indices: &[i32]) -> Self {
236        assert!(
237            !type_indices.is_empty(),
238            "match_any! jump table requires at least one arm"
239        );
240        assert!(
241            type_indices
242                .iter()
243                .all(|&type_index| type_index >= TypeIndex::kTVMFFIStaticObjectBegin as i32),
244            "match_any! jump table arm has a non-object type index"
245        );
246        let min_type_index = *type_indices.iter().min().unwrap();
247        let max_type_index = *type_indices.iter().max().unwrap();
248        let span = usize::try_from(i64::from(max_type_index) - i64::from(min_type_index) + 1)
249            .expect("match_any! jump table has an invalid type-index span");
250        assert!(
251            type_indices.len() <= NO_ARM_ID as usize,
252            "match_any! jump table has too many arms"
253        );
254        let mut arm_ids = vec![NO_ARM_ID; span];
255        for (arm_id, &type_index) in type_indices.iter().enumerate() {
256            let offset = (type_index - min_type_index) as usize;
257            let slot = &mut arm_ids[offset];
258            // Keep the first source arm for duplicate runtime indices.
259            if *slot == NO_ARM_ID {
260                *slot = arm_id as ArmId;
261            }
262        }
263
264        Self {
265            type_list_id,
266            base: min_type_index,
267            arm_ids: arm_ids.into_boxed_slice(),
268        }
269    }
270
271    #[doc(hidden)]
272    #[inline(always)]
273    #[allow(clippy::result_unit_err)]
274    pub fn lookup(&self, type_list_id: TypeId, type_index: i32) -> Result<Option<ArmId>, ()> {
275        if self.type_list_id != type_list_id {
276            return Err(());
277        }
278        let offset = type_index.wrapping_sub(self.base) as usize;
279        let arm_id = self.arm_ids.get(offset).copied().unwrap_or(NO_ARM_ID);
280        Ok((arm_id != NO_ARM_ID).then_some(arm_id))
281    }
282}
283
284/// Compile-time list of the arms' exact types, used to build the jump table.
285/// Its key uses the final object types, so arm types need not be `'static`.
286#[doc(hidden)]
287pub trait JumpTableTypes {
288    #[doc(hidden)]
289    type Key: 'static;
290
291    #[doc(hidden)]
292    const ALL_EXACT_FINAL: bool;
293
294    /// Validate that the final payload identity describes this exact matcher.
295    #[doc(hidden)]
296    fn matches_key() -> bool;
297
298    #[doc(hidden)]
299    fn fill_type_indices(out: &mut [i32]);
300}
301
302impl JumpTableTypes for () {
303    type Key = ();
304    const ALL_EXACT_FINAL: bool = true;
305
306    #[inline(always)]
307    fn matches_key() -> bool {
308        true
309    }
310
311    #[inline(always)]
312    fn fill_type_indices(out: &mut [i32]) {
313        debug_assert!(out.is_empty());
314    }
315}
316
317impl<Head, Tail> JumpTableTypes for (Head, Tail)
318where
319    Head: AnyCompatible + crate::object::ObjectRefCore,
320    Tail: JumpTableTypes,
321{
322    type Key = (
323        <Head as crate::object::ObjectRefCore>::ContainerType,
324        Tail::Key,
325    );
326    const ALL_EXACT_FINAL: bool = Head::MATCH_ANY_EXACT
327        && <Head::ContainerType as crate::object::ObjectCore>::TYPE_FINAL
328        && Tail::ALL_EXACT_FINAL;
329
330    #[inline(always)]
331    fn matches_key() -> bool {
332        Head::match_any_exact_type_index()
333            == <Head::ContainerType as crate::object::ObjectCore>::type_index()
334            && Tail::matches_key()
335    }
336
337    #[inline(always)]
338    fn fill_type_indices(out: &mut [i32]) {
339        let (head, tail) = out
340            .split_first_mut()
341            .expect("match_any! pattern metadata length mismatch");
342        *head = Head::match_any_exact_type_index();
343        Tail::fill_type_indices(tail);
344    }
345}
346
347/// A typed mutation view arm routes as its value type.
348impl<'a, Head, Tail> JumpTableTypes for (crate::MutationView<'a, Head>, Tail)
349where
350    Head: AnyCompatible + crate::object::ObjectRefCore,
351    Tail: JumpTableTypes,
352{
353    type Key = <(Head, Tail) as JumpTableTypes>::Key;
354    const ALL_EXACT_FINAL: bool = <(Head, Tail) as JumpTableTypes>::ALL_EXACT_FINAL;
355    fn matches_key() -> bool {
356        <(Head, Tail) as JumpTableTypes>::matches_key()
357    }
358    fn fill_type_indices(out: &mut [i32]) {
359        <(Head, Tail) as JumpTableTypes>::fill_type_indices(out);
360    }
361}
362
363/// A reference arm's entry in a [`JumpTableTypes`] list.
364#[doc(hidden)]
365pub struct RefJumpTableType<T>(PhantomData<fn() -> T>);
366
367impl<Head: crate::object::ObjectCore, Tail: JumpTableTypes> JumpTableTypes
368    for (RefJumpTableType<Head>, Tail)
369{
370    type Key = (Head, Tail::Key);
371    const ALL_EXACT_FINAL: bool = Head::TYPE_FINAL && Tail::ALL_EXACT_FINAL;
372
373    #[inline(always)]
374    fn matches_key() -> bool {
375        Tail::matches_key()
376    }
377
378    #[inline(always)]
379    fn fill_type_indices(out: &mut [i32]) {
380        let (head, tail) = out
381            .split_first_mut()
382            .expect("match_any! pattern metadata length mismatch");
383        *head = Head::type_index();
384        Tail::fill_type_indices(tail);
385    }
386}
387
388/// Autoref probe that decides at compile time whether every arm qualifies for
389/// the jump table; if not, the expansion tries arms in order.
390#[doc(hidden)]
391pub struct JumpTableProbe<T>(PhantomData<fn() -> T>);
392
393impl<T> JumpTableProbe<T> {
394    #[doc(hidden)]
395    pub fn prepend<Head>(self, _: PhantomData<Head>) -> JumpTableProbe<(Head, T)> {
396        JumpTableProbe::new()
397    }
398
399    #[doc(hidden)]
400    pub const fn new() -> Self {
401        Self(PhantomData)
402    }
403}
404
405/// The probe's jump-table inputs: the type list id, the key check and the arms'
406/// type indices.
407#[doc(hidden)]
408pub trait JumpTableMetadata {
409    #[doc(hidden)]
410    fn type_list_id(&self) -> Option<TypeId> {
411        None
412    }
413
414    #[doc(hidden)]
415    fn matches_key(&self) -> bool {
416        false
417    }
418
419    #[doc(hidden)]
420    fn fill_type_indices(&self, _out: &mut [i32]) {}
421}
422
423impl<T> JumpTableMetadata for &JumpTableProbe<T> {}
424
425impl<T: JumpTableTypes> JumpTableMetadata for JumpTableProbe<T> {
426    #[inline(always)]
427    fn type_list_id(&self) -> Option<TypeId> {
428        T::ALL_EXACT_FINAL.then(TypeId::of::<T::Key>)
429    }
430
431    #[inline(always)]
432    fn matches_key(&self) -> bool {
433        T::matches_key()
434    }
435
436    #[inline(always)]
437    fn fill_type_indices(&self, out: &mut [i32]) {
438        T::fill_type_indices(out);
439    }
440}
441
442/// A reference arm's entry in the jump table's type list, selected by the same
443/// autoref probe as [`RefPattern`].
444#[doc(hidden)]
445pub trait RefJumpTableEntry {
446    type Entry;
447    fn table_entry(&self) -> PhantomData<Self::Entry> {
448        PhantomData
449    }
450}
451impl<T: crate::object::ObjectCore> RefJumpTableEntry for &&RefPatternProbe<T> {
452    type Entry = RefJumpTableType<T>;
453}
454impl<T> RefJumpTableEntry for &RefPatternProbe<T> {
455    type Entry = T;
456}