Skip to main content

ixa/macros/
entity_impl.rs

1//! Macros to correctly define and implement the `Entity` trait.
2
3/// Defines a zero-sized struct with the right derived traits and implements the `Entity` trait. If you already
4/// have a type defined (struct, enum, etc.), you can use the `impl_entity!` macro instead.
5#[macro_export]
6macro_rules! define_entity {
7    ($entity_name:ident) => {
8        #[allow(unused)]
9        #[derive(Default, Debug, PartialEq, Eq, Clone, Copy)]
10        pub struct $entity_name;
11
12        impl $entity_name {
13            #[allow(unused)]
14            pub fn new() -> Self {
15                <Self as std::default::Default>::default()
16            }
17        }
18
19        $crate::impl_entity!($entity_name);
20    };
21}
22
23/// Implements the `Entity` trait for the given existing type and defines a type alias
24/// of the form `MyEntityId = EntityId<MyEntity>`. For simple zero-sized types, use the
25/// `define_entity!` macro instead, which will define the struct and derive all the super traits.
26///
27/// This macro ensures the correct implementation of the `Entity` trait. The tricky bit is the implementation of
28/// `Entity::index`, which requires synchronization in multithreaded runtimes. This is an instance of
29/// _correctness via macro_.
30#[macro_export]
31macro_rules! impl_entity {
32    ($entity_name:ident) => {
33        // Alias of the form `MyEntityId = EntityId<MyEntity>`
34        $crate::paste::paste! {
35            #[allow(unused)]
36            pub type [<$entity_name Id>] = $crate::entity::EntityId<$entity_name>;
37        }
38
39        impl $crate::entity::Entity for $entity_name {
40            #[inline]
41            fn id() -> usize {
42                // This static must be initialized with a compile-time constant expression.
43                // We use `usize::MAX` as a sentinel to mean "uninitialized". This
44                // static variable is shared among all instances of this concrete item type.
45                static INDEX: std::sync::atomic::AtomicUsize =
46                    std::sync::atomic::AtomicUsize::new(usize::MAX);
47
48                // Fast path: already initialized.
49                let index = INDEX.load(std::sync::atomic::Ordering::Relaxed);
50                if index != usize::MAX {
51                    return index;
52                }
53
54                // Slow path: install the complete registration before publishing the ID.
55                $crate::entity::schema_registry::ensure_entity_registered::<Self>(&INDEX)
56            }
57
58            fn all_query_identity() -> usize {
59                static IDENTITY: std::sync::OnceLock<usize> = std::sync::OnceLock::new();
60
61                *IDENTITY.get_or_init(|| {
62                    $crate::entity::multi_property::intern_query_identity_raw::<Self>(&[])
63                })
64            }
65        }
66
67        // Using `ctor` to initialize entities at program start-up means we know how many entities
68        // there are at the time any `EntityStore` is created, which means we never have
69        // to mutate `EntityStore` to initialize an `Entity` that hasn't yet been accessed.
70        // (The mutation happens inside of a `OnceCell`, which we can already have ready
71        // when we construct `EntityStore`.) In other words, we could do away with `ctor`
72        // if we were willing to have a mechanism for interior mutability for `EntityStore`.
73        $crate::paste::paste! {
74            $crate::ctor::declarative::ctor!{
75                #[ctor(unsafe)]
76                fn [<_register_entity_$entity_name:snake>]() {
77                    $crate::entity::schema_registry::add_to_entity_registry::<$entity_name>();
78                }
79            }
80        }
81    };
82}