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}