bevy_reflect/
utility.rs

1//! Helpers for working with Bevy reflection.
2
3use crate::TypeInfo;
4use bevy_utils::{FixedState, NoOpHash, TypeIdMap};
5use core::{
6    any::{Any, TypeId},
7    hash::BuildHasher,
8};
9use std::sync::{OnceLock, PoisonError, RwLock};
10
11/// A type that can be stored in a ([`Non`])[`GenericTypeCell`].
12///
13/// [`Non`]: NonGenericTypeCell
14pub trait TypedProperty: sealed::Sealed {
15    type Stored: 'static;
16}
17
18/// Used to store a [`String`] in a [`GenericTypePathCell`] as part of a [`TypePath`] implementation.
19///
20/// [`TypePath`]: crate::TypePath
21pub struct TypePathComponent;
22
23mod sealed {
24    use super::{TypeInfo, TypePathComponent, TypedProperty};
25
26    pub trait Sealed {}
27
28    impl Sealed for TypeInfo {}
29    impl Sealed for TypePathComponent {}
30
31    impl TypedProperty for TypeInfo {
32        type Stored = Self;
33    }
34
35    impl TypedProperty for TypePathComponent {
36        type Stored = String;
37    }
38}
39
40/// A container for [`TypeInfo`] over non-generic types, allowing instances to be stored statically.
41///
42/// This is specifically meant for use with _non_-generic types. If your type _is_ generic,
43/// then use [`GenericTypeCell`] instead. Otherwise, it will not take into account all
44/// monomorphizations of your type.
45///
46/// Non-generic [`TypePath`]s should be trivially generated with string literals and [`concat!`].
47///
48/// ## Example
49///
50/// ```
51/// # use std::any::Any;
52/// # use bevy_reflect::{DynamicTypePath, NamedField, PartialReflect, Reflect, ReflectMut, ReflectOwned, ReflectRef, StructInfo, Typed, TypeInfo, TypePath, ApplyError};
53/// use bevy_reflect::utility::NonGenericTypeInfoCell;
54///
55/// struct Foo {
56///     bar: i32
57/// }
58///
59/// impl Typed for Foo {
60///     fn type_info() -> &'static TypeInfo {
61///         static CELL: NonGenericTypeInfoCell = NonGenericTypeInfoCell::new();
62///         CELL.get_or_set(|| {
63///             let fields = [NamedField::new::<i32>("bar")];
64///             let info = StructInfo::new::<Self>(&fields);
65///             TypeInfo::Struct(info)
66///         })
67///     }
68/// }
69/// # impl TypePath for Foo {
70/// #     fn type_path() -> &'static str { todo!() }
71/// #     fn short_type_path() -> &'static str { todo!() }
72/// # }
73/// # impl PartialReflect for Foo {
74/// #     fn get_represented_type_info(&self) -> Option<&'static TypeInfo> { todo!() }
75/// #     fn into_partial_reflect(self: Box<Self>) -> Box<dyn PartialReflect> { todo!() }
76/// #     fn as_partial_reflect(&self) -> &dyn PartialReflect { todo!() }
77/// #     fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect { todo!() }
78/// #     fn try_into_reflect(self: Box<Self>) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>> { todo!() }
79/// #     fn try_as_reflect(&self) -> Option<&dyn Reflect> { todo!() }
80/// #     fn try_as_reflect_mut(&mut self) -> Option<&mut dyn Reflect> { todo!() }
81/// #     fn try_apply(&mut self, value: &dyn PartialReflect) -> Result<(), ApplyError> { todo!() }
82/// #     fn reflect_ref(&self) -> ReflectRef { todo!() }
83/// #     fn reflect_mut(&mut self) -> ReflectMut { todo!() }
84/// #     fn reflect_owned(self: Box<Self>) -> ReflectOwned { todo!() }
85/// #     fn clone_value(&self) -> Box<dyn PartialReflect> { todo!() }
86/// # }
87/// # impl Reflect for Foo {
88/// #     fn into_any(self: Box<Self>) -> Box<dyn Any> { todo!() }
89/// #     fn as_any(&self) -> &dyn Any { todo!() }
90/// #     fn as_any_mut(&mut self) -> &mut dyn Any { todo!() }
91/// #     fn into_reflect(self: Box<Self>) -> Box<dyn Reflect> { todo!() }
92/// #     fn as_reflect(&self) -> &dyn Reflect { todo!() }
93/// #     fn as_reflect_mut(&mut self) -> &mut dyn Reflect { todo!() }
94/// #     fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>> { todo!() }
95/// # }
96/// ```
97///
98/// [`TypePath`]: crate::TypePath
99pub struct NonGenericTypeCell<T: TypedProperty>(OnceLock<T::Stored>);
100
101/// See [`NonGenericTypeCell`].
102pub type NonGenericTypeInfoCell = NonGenericTypeCell<TypeInfo>;
103
104impl<T: TypedProperty> NonGenericTypeCell<T> {
105    /// Initialize a [`NonGenericTypeCell`] for non-generic types.
106    pub const fn new() -> Self {
107        Self(OnceLock::new())
108    }
109
110    /// Returns a reference to the [`TypedProperty`] stored in the cell.
111    ///
112    /// If there is no entry found, a new one will be generated from the given function.
113    pub fn get_or_set<F>(&self, f: F) -> &T::Stored
114    where
115        F: FnOnce() -> T::Stored,
116    {
117        self.0.get_or_init(f)
118    }
119}
120
121impl<T: TypedProperty> Default for NonGenericTypeCell<T> {
122    fn default() -> Self {
123        Self::new()
124    }
125}
126
127/// A container for [`TypedProperty`] over generic types, allowing instances to be stored statically.
128///
129/// This is specifically meant for use with generic types. If your type isn't generic,
130/// then use [`NonGenericTypeCell`] instead as it should be much more performant.
131///
132/// `#[derive(TypePath)]` and [`impl_type_path`] should always be used over [`GenericTypePathCell`]
133/// where possible.
134///
135/// ## Examples
136///
137/// Implementing [`TypeInfo`] with generics.
138///
139/// ```
140/// # use std::any::Any;
141/// # use bevy_reflect::{DynamicTypePath, PartialReflect, Reflect, ReflectMut, ReflectOwned, ReflectRef, TupleStructInfo, Typed, TypeInfo, TypePath, UnnamedField, ApplyError, Generics, TypeParamInfo};
142/// use bevy_reflect::utility::GenericTypeInfoCell;
143///
144/// struct Foo<T>(T);
145///
146/// impl<T: Reflect + Typed + TypePath> Typed for Foo<T> {
147///     fn type_info() -> &'static TypeInfo {
148///         static CELL: GenericTypeInfoCell = GenericTypeInfoCell::new();
149///         CELL.get_or_insert::<Self, _>(|| {
150///             let fields = [UnnamedField::new::<T>(0)];
151///             let info = TupleStructInfo::new::<Self>(&fields)
152///                 .with_generics(Generics::from_iter([TypeParamInfo::new::<T>("T")]));
153///             TypeInfo::TupleStruct(info)
154///         })
155///     }
156/// }
157/// # impl<T: TypePath> TypePath for Foo<T> {
158/// #     fn type_path() -> &'static str { todo!() }
159/// #     fn short_type_path() -> &'static str { todo!() }
160/// # }
161/// # impl<T: PartialReflect + TypePath> PartialReflect for Foo<T> {
162/// #     fn get_represented_type_info(&self) -> Option<&'static TypeInfo> { todo!() }
163/// #     fn into_partial_reflect(self: Box<Self>) -> Box<dyn PartialReflect> { todo!() }
164/// #     fn as_partial_reflect(&self) -> &dyn PartialReflect { todo!() }
165/// #     fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect { todo!() }
166/// #     fn try_into_reflect(self: Box<Self>) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>> { todo!() }
167/// #     fn try_as_reflect(&self) -> Option<&dyn Reflect> { todo!() }
168/// #     fn try_as_reflect_mut(&mut self) -> Option<&mut dyn Reflect> { todo!() }
169/// #     fn try_apply(&mut self, value: &dyn PartialReflect) -> Result<(), ApplyError> { todo!() }
170/// #     fn reflect_ref(&self) -> ReflectRef { todo!() }
171/// #     fn reflect_mut(&mut self) -> ReflectMut { todo!() }
172/// #     fn reflect_owned(self: Box<Self>) -> ReflectOwned { todo!() }
173/// #     fn clone_value(&self) -> Box<dyn PartialReflect> { todo!() }
174/// # }
175/// # impl<T: Reflect + Typed + TypePath> Reflect for Foo<T> {
176/// #     fn into_any(self: Box<Self>) -> Box<dyn Any> { todo!() }
177/// #     fn as_any(&self) -> &dyn Any { todo!() }
178/// #     fn as_any_mut(&mut self) -> &mut dyn Any { todo!() }
179/// #     fn into_reflect(self: Box<Self>) -> Box<dyn Reflect> { todo!() }
180/// #     fn as_reflect(&self) -> &dyn Reflect { todo!() }
181/// #     fn as_reflect_mut(&mut self) -> &mut dyn Reflect { todo!() }
182/// #     fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>> { todo!() }
183/// # }
184/// ```
185///
186///  Implementing [`TypePath`] with generics.
187///
188/// ```
189/// # use std::any::Any;
190/// # use bevy_reflect::TypePath;
191/// use bevy_reflect::utility::GenericTypePathCell;
192///
193/// struct Foo<T>(T);
194///
195/// impl<T: TypePath> TypePath for Foo<T> {
196///     fn type_path() -> &'static str {
197///         static CELL: GenericTypePathCell = GenericTypePathCell::new();
198///         CELL.get_or_insert::<Self, _>(|| format!("my_crate::foo::Foo<{}>", T::type_path()))
199///     }
200///     
201///     fn short_type_path() -> &'static str {
202///         static CELL: GenericTypePathCell = GenericTypePathCell::new();
203///         CELL.get_or_insert::<Self, _>(|| format!("Foo<{}>", T::short_type_path()))
204///     }
205///
206///     fn type_ident() -> Option<&'static str> {
207///         Some("Foo")
208///     }
209///
210///     fn module_path() -> Option<&'static str> {
211///         Some("my_crate::foo")
212///     }
213///
214///     fn crate_name() -> Option<&'static str> {
215///         Some("my_crate")
216///     }
217/// }
218/// ```
219/// [`impl_type_path`]: crate::impl_type_path
220/// [`TypePath`]: crate::TypePath
221pub struct GenericTypeCell<T: TypedProperty>(RwLock<TypeIdMap<&'static T::Stored>>);
222
223/// See [`GenericTypeCell`].
224pub type GenericTypeInfoCell = GenericTypeCell<TypeInfo>;
225/// See [`GenericTypeCell`].
226pub type GenericTypePathCell = GenericTypeCell<TypePathComponent>;
227
228impl<T: TypedProperty> GenericTypeCell<T> {
229    /// Initialize a [`GenericTypeCell`] for generic types.
230    pub const fn new() -> Self {
231        Self(RwLock::new(TypeIdMap::with_hasher(NoOpHash)))
232    }
233
234    /// Returns a reference to the [`TypedProperty`] stored in the cell.
235    ///
236    /// This method will then return the correct [`TypedProperty`] reference for the given type `T`.
237    /// If there is no entry found, a new one will be generated from the given function.
238    pub fn get_or_insert<G, F>(&self, f: F) -> &T::Stored
239    where
240        G: Any + ?Sized,
241        F: FnOnce() -> T::Stored,
242    {
243        self.get_or_insert_by_type_id(TypeId::of::<G>(), f)
244    }
245
246    /// Returns a reference to the [`TypedProperty`] stored in the cell, if any.
247    ///
248    /// This method will then return the correct [`TypedProperty`] reference for the given type `T`.
249    fn get_by_type_id(&self, type_id: TypeId) -> Option<&T::Stored> {
250        self.0
251            .read()
252            .unwrap_or_else(PoisonError::into_inner)
253            .get(&type_id)
254            .copied()
255    }
256
257    /// Returns a reference to the [`TypedProperty`] stored in the cell.
258    ///
259    /// This method will then return the correct [`TypedProperty`] reference for the given type `T`.
260    /// If there is no entry found, a new one will be generated from the given function.
261    fn get_or_insert_by_type_id<F>(&self, type_id: TypeId, f: F) -> &T::Stored
262    where
263        F: FnOnce() -> T::Stored,
264    {
265        match self.get_by_type_id(type_id) {
266            Some(info) => info,
267            None => self.insert_by_type_id(type_id, f()),
268        }
269    }
270
271    fn insert_by_type_id(&self, type_id: TypeId, value: T::Stored) -> &T::Stored {
272        self.0
273            .write()
274            .unwrap_or_else(PoisonError::into_inner)
275            .entry(type_id)
276            .insert({
277                // We leak here in order to obtain a `&'static` reference.
278                // Otherwise, we won't be able to return a reference due to the `RwLock`.
279                // This should be okay, though, since we expect it to remain statically
280                // available over the course of the application.
281                Box::leak(Box::new(value))
282            })
283            .get()
284    }
285}
286
287impl<T: TypedProperty> Default for GenericTypeCell<T> {
288    fn default() -> Self {
289        Self::new()
290    }
291}
292
293/// Deterministic fixed state hasher to be used by implementors of [`Reflect::reflect_hash`].
294///
295/// Hashes should be deterministic across processes so hashes can be used as
296/// checksums for saved scenes, rollback snapshots etc. This function returns
297/// such a hasher.
298///
299/// [`Reflect::reflect_hash`]: crate::Reflect
300#[inline]
301pub fn reflect_hasher() -> bevy_utils::AHasher {
302    FixedState.build_hasher()
303}
bevy_reflect/utility.rs

bevy_reflect/
utility.rs
