ixa/entity/
entity_store.rs

1/*!
2
3The `EntityStore` maintains all registered entities in the form of [`EntityRecord`]s,
4`EntityRecord`s track the count of the instances of the [`Entity`] (valid [`EntityId<Entity>`]
5values) and owns the [`PropertyStore<E>`], which manages the entity's properties.
6
7Although each Entity type may own its own data, client code cannot create or destructure
8`EntityId<Entity>` values directly. Instead, `EntityStore` centrally manages entity counts
9for all registered types so that only valid (existing) `EntityId<E>` values are ever created.
10
11
12*/
13
14use std::any::{Any, TypeId};
15use std::cell::OnceCell;
16use std::sync::atomic::{AtomicUsize, Ordering};
17use std::sync::{LazyLock, Mutex, OnceLock};
18
19use crate::entity::property_store::PropertyStore;
20use crate::entity::{Entity, EntityId, PopulationIterator};
21use crate::HashMap;
22
23/// Global entity index counter; keeps track of the index that will be assigned to the next entity that
24/// requests an index. Equivalently, holds a *count* of the number of entities currently registered.
25static NEXT_ENTITY_INDEX: Mutex<usize> = Mutex::new(0);
26
27/// For each entity we keep track of the properties associated with it. This maps
28/// `entity_type_id` to `(vec_of_all_property_type_ids, vec_of_required_property_type_ids)`.
29/// This data is actually written by the property ctors with a call to
30/// [`register_property_with_entity()`].
31#[allow(clippy::type_complexity)]
32static ENTITY_METADATA_BUILDER: LazyLock<Mutex<HashMap<TypeId, (Vec<TypeId>, Vec<TypeId>)>>> =
33    LazyLock::new(|| Mutex::new(HashMap::default()));
34
35/// The frozen entity->property registry, created exactly once on first read.
36///
37/// This is derived from `ENTITY_METADATA_BUILDER` by moving the builder `HashMap` out and
38/// converting the `Vec`s to boxed slices to prevent further mutation.
39#[allow(clippy::type_complexity)]
40static ENTITY_METADATA: OnceLock<HashMap<TypeId, (Box<[TypeId]>, Box<[TypeId]>)>> = OnceLock::new();
41
42/// Private helper to fetch or initialize the frozen metadata.
43#[allow(clippy::type_complexity)]
44fn entity_metadata() -> &'static HashMap<TypeId, (Box<[TypeId]>, Box<[TypeId]>)> {
45    ENTITY_METADATA.get_or_init(|| {
46        let mut builder = ENTITY_METADATA_BUILDER.lock().unwrap();
47        let builder = std::mem::take(&mut *builder);
48        builder
49            .into_iter()
50            .map(|(entity_type_id, (props, reqs))| {
51                (
52                    entity_type_id,
53                    (props.into_boxed_slice(), reqs.into_boxed_slice()),
54                )
55            })
56            .collect()
57    })
58}
59
60/// The public setter interface to `ENTITY_METADATA`.
61pub fn register_property_with_entity(
62    entity_type_id: TypeId,
63    property_type_id: TypeId,
64    required: bool,
65) {
66    let mut builder = ENTITY_METADATA_BUILDER.lock().unwrap();
67    if ENTITY_METADATA.get().is_some() {
68        panic!(
69            "`register_property_with_entity()` called after entity metadata was frozen; registration must occur during startup/ctors."
70        );
71    }
72
73    let (property_type_ids, required_property_type_ids) = builder
74        .entry(entity_type_id)
75        .or_insert_with(|| (Vec::new(), Vec::new()));
76    property_type_ids.push(property_type_id);
77    if required {
78        required_property_type_ids.push(property_type_id);
79    }
80}
81
82/// Returns the pre-computed, frozen metadata for an entity type.
83///
84/// This registry is built during startup by property ctors calling
85/// [`register_property_with_entity()`], then frozen exactly once on first read.
86#[must_use]
87pub fn get_entity_metadata_static(
88    entity_type_id: TypeId,
89) -> (&'static [TypeId], &'static [TypeId]) {
90    match entity_metadata().get(&entity_type_id) {
91        Some((props, reqs)) => (props.as_ref(), reqs.as_ref()),
92        None => (&[], &[]),
93    }
94}
95
96/// Adds a new entity to the registry. The job of this method is to create whatever
97/// "singleton" data/metadata is associated with the [`Entity`] if it doesn't already
98/// exist, which in this case is only the value of `Entity::id()`.
99///
100/// In our use case, this method is called in the `ctor` function of each `Entity`
101/// type and ultimately exists only so that we know how many `EntityRecord`s to
102/// construct in the constructor of `EntityStore`, so that we never have to mutate
103/// `EntityStore` itself when an `Entity` is accessed for the first time. (The
104/// `OnceCell`s handle the interior mutability required for initialization.)
105pub fn add_to_entity_registry<R: Entity>() {
106    let _ = R::id();
107}
108
109/// A convenience getter for `NEXT_ENTITY_INDEX`.
110pub fn get_registered_entity_count() -> usize {
111    *NEXT_ENTITY_INDEX.lock().unwrap()
112}
113
114/// Encapsulates the synchronization logic for initializing an entity's index.
115///
116/// Acquires a global lock on the next available item index, but only increments
117/// it if we successfully initialize the provided index. The `index` of a registered
118/// item is assigned at runtime but only once per type. It's possible for a single
119/// type to attempt to initialize its index multiple times from different threads,
120/// which is why all this synchronization is required. However, the overhead
121/// is negligible, as this initialization only happens once upon first access.
122///
123/// In fact, for our use case we know we are calling this function
124/// once for each type in each `Entity`'s `ctor` function, which
125/// should be the only time this method is ever called for the type.
126pub fn initialize_entity_index(plugin_index: &AtomicUsize) -> usize {
127    // Acquire a global lock.
128    let mut guard = NEXT_ENTITY_INDEX.lock().unwrap();
129    let candidate = *guard;
130
131    // Try to claim the candidate index. Here we guard against the potential race condition that
132    // another instance of this plugin in another thread just initialized the index prior to us
133    // obtaining the lock. If the index has been initialized beneath us, we do not update
134    // [`NEXT_ITEM_INDEX`], we just return the value `plugin_index` was initialized to.
135    // For a justification of the data ordering, see:
136    //     https://github.com/CDCgov/ixa/pull/477#discussion_r2244302872
137    match plugin_index.compare_exchange(usize::MAX, candidate, Ordering::AcqRel, Ordering::Acquire)
138    {
139        Ok(_) => {
140            // We won the race — increment the global next plugin index and return the new index
141            *guard += 1;
142            candidate
143        }
144        Err(existing) => {
145            // Another thread beat us — don’t increment the global next plugin index,
146            // just return existing
147            existing
148        }
149    }
150}
151
152/// We store our own instance data alongside the `Entity` instance itself.
153pub struct EntityRecord {
154    /// The total count of all entities of this type (i.e., the next index to assign).
155    pub(crate) entity_count: usize,
156    /// Whether `EntityCreatedEvent` has any subscribers for this entity type. This is a performance
157    /// optimization for `add_entity`.
158    pub(in crate::entity) entity_created_event_subscribed: bool,
159    /// Lazily initialized `Entity` instance.
160    pub(crate) entity: OnceCell<Box<dyn Any>>,
161    /// A type-erased `Box<PropertyStore<E>>`, lazily initialized.
162    pub(crate) property_store: OnceCell<Box<dyn Any>>,
163}
164
165impl EntityRecord {
166    pub(crate) fn new() -> Self {
167        Self {
168            entity_count: 0,
169            entity_created_event_subscribed: false,
170            entity: OnceCell::new(),
171            property_store: OnceCell::new(),
172        }
173    }
174}
175
176/// A wrapper around a vector of entities.
177pub struct EntityStore {
178    pub(in crate::entity) items: Vec<EntityRecord>,
179}
180
181impl Default for EntityStore {
182    fn default() -> Self {
183        EntityStore::new()
184    }
185}
186
187impl EntityStore {
188    /// Creates a new [`EntityStore`], allocating the exact number of slots as there are
189    /// registered [`Entity`]s.
190    ///
191    /// This method assumes all types implementing `Entity` have been implemented _correctly_.
192    /// This is one of the pitfalls of this pattern: there is no guarantee that types
193    /// implementing `Entity` followed the rules. We can have at least some confidence,
194    /// though, in their correctness by supplying a correct implementation via a macro.
195    #[must_use]
196    pub fn new() -> Self {
197        let num_items = get_registered_entity_count();
198        Self {
199            items: (0..num_items).map(|_| EntityRecord::new()).collect(),
200        }
201    }
202
203    /// Fetches an immutable reference to the entity `E` from the registry. This
204    /// implementation lazily instantiates the item if it has not yet been instantiated.
205    #[must_use]
206    pub fn get<E: Entity>(&self) -> &E {
207        let index = E::id();
208        self.items
209        .get(index)
210        .unwrap_or_else(|| panic!("No registered entity found with index = {index:?}. You must use the `define_entity!` macro to create an entity."))
211        .entity
212        .get_or_init(|| E::new_boxed())
213        .downcast_ref::<E>()
214        .expect("TypeID does not match registered entity type. You must use the `define_entity!` macro to create an entity.")
215    }
216
217    /// Fetches a mutable reference to the item `E` from the registry. This
218    /// implementation lazily instantiates the item if it has not yet been instantiated.
219    #[must_use]
220    pub fn get_mut<E: Entity>(&mut self) -> &mut E {
221        let index = E::id();
222
223        let record = self.items.get_mut(index).unwrap_or_else(|| {
224            panic!(
225                "No registered entity found with index = {index:?}. \
226             You must use the `define_entity!` macro to create an entity."
227            )
228        });
229
230        // Initialize if needed
231        if record.entity.get().is_none() {
232            record.entity.set(E::new_boxed()).unwrap();
233        }
234
235        // The cell was already initialized or was initialized immediately above.
236        record.entity.get_mut().unwrap().downcast_mut::<E>().expect(
237            "TypeID does not match registered entity type. \
238             You must use the `define_entity!` macro to create an entity.",
239        )
240    }
241
242    /// Creates a new `EntityId` for the given `Entity` type `E`.
243    /// Increments the entity counter and returns the next valid ID together with whether
244    /// `EntityCreatedEvent<E>` has subscribers.
245    pub(crate) fn new_entity_id<E: Entity>(&mut self) -> (EntityId<E>, bool) {
246        let index = E::id();
247        let record = &mut self.items[index];
248        let id = record.entity_count;
249        record.entity_count += 1;
250        (EntityId::new(id), record.entity_created_event_subscribed)
251    }
252
253    /// Returns a total count of all created entities of type `E`.
254    #[must_use]
255    pub fn get_entity_count<E: Entity>(&self) -> usize {
256        let index = E::id();
257        let record = &self.items[index];
258        record.entity_count
259    }
260
261    /// Returns a total count of all created entities of type `E`.
262    #[must_use]
263    pub fn get_entity_count_by_id(&self, id: usize) -> usize {
264        let record = &self.items[id];
265        record.entity_count
266    }
267
268    /// Returns an iterator over all valid `EntityId<E>`s
269    #[must_use]
270    pub fn get_entity_iterator<E: Entity>(&self) -> PopulationIterator<E> {
271        let count = self.get_entity_count::<E>();
272        PopulationIterator::new(count)
273    }
274
275    #[must_use]
276    #[inline]
277    pub fn get_property_store<E: Entity>(&self) -> &PropertyStore<E> {
278        let index = E::id();
279        let record = self.items
280                         .get(index)
281                         .unwrap_or_else(|| panic!("No registered entity found with index = {index:?}. You must use the `define_entity!` macro to create an entity."));
282        let property_store = record
283            .property_store
284            .get_or_init(|| Box::new(PropertyStore::<E>::new()));
285        property_store.downcast_ref::<PropertyStore<E>>()
286                      .expect("TypeID does not match registered item type. You must use the `define_registered_item!` macro to create a registered item.")
287    }
288
289    pub fn get_property_store_mut<E: Entity>(&mut self) -> &mut PropertyStore<E> {
290        let index = E::id();
291        let record = self.items
292                         .get_mut(index)
293                         .unwrap_or_else(|| panic!("No registered entity found with index = {index:?}. You must use the `define_entity!` macro to create an entity."));
294        let _ = record
295            .property_store
296            .get_or_init(|| Box::new(PropertyStore::<E>::new()));
297        // `get_or_init` guarantees that the cell now contains a property store.
298        let property_store = record.property_store.get_mut().unwrap();
299        property_store.downcast_mut::<PropertyStore<E>>()
300                      .expect("TypeID does not match registered item type. You must use the `define_registered_item!` macro to create a registered item.")
301    }
302}
303
304#[cfg(test)]
305mod tests {
306    use std::any::Any;
307    use std::sync::atomic::{AtomicUsize, Ordering};
308    use std::sync::{Arc, Barrier};
309    use std::thread;
310
311    use crate::entity::entity_store::{
312        add_to_entity_registry, get_registered_entity_count, initialize_entity_index, EntityStore,
313    };
314    use crate::entity::Entity;
315    use crate::{impl_entity, with, Context, ContextEntitiesExt, HashMap};
316    // Test item types
317    #[derive(Debug, Clone, PartialEq)]
318    pub struct TestItem1 {
319        value: usize,
320    }
321    impl Default for TestItem1 {
322        fn default() -> Self {
323            Self { value: 42 }
324        }
325    }
326
327    #[derive(Debug, Clone, PartialEq)]
328    pub struct TestItem2 {
329        name: String,
330    }
331    impl Default for TestItem2 {
332        fn default() -> Self {
333            TestItem2 {
334                name: "test".to_string(),
335            }
336        }
337    }
338
339    #[derive(Debug, Clone, PartialEq)]
340    pub struct TestItem3 {
341        data: Vec<u8>,
342    }
343    impl Default for TestItem3 {
344        fn default() -> Self {
345            TestItem3 {
346                data: vec![1, 2, 3],
347            }
348        }
349    }
350
351    // Implement RegisteredItem manually for testing without macro
352    impl_entity!(TestItem1);
353    impl_entity!(TestItem2);
354    impl_entity!(TestItem3);
355
356    // Test the internal synchronization mechanisms of `initialize_entity_index()`.
357    //
358    // It is convenient to only have a single test that mutates `NEXT_ENTITY_INDEX`,
359    // because we can assume no other thread is incrementing it and can therefore
360    // test the value of `NEXT_ENTITY_INDEX` at the beginning and then at the end of
361    // the test.
362    //
363    // Note that this doesn't really interfere with other tests involving `EntityStore`,
364    // because at worst `EntityStore` will just allocate addition slots for
365    // nonexistent items, which will never be requested with a `get()` call.
366    #[test]
367    fn test_initialize_item_index_concurrent() {
368        // Test 1: Try to initialize a single index from multiple threads simultaneously.
369        let initial_registered_items_count = get_registered_entity_count();
370
371        const NUM_THREADS: usize = 100;
372        let index = Arc::new(AtomicUsize::new(usize::MAX));
373        let barrier = Arc::new(Barrier::new(NUM_THREADS));
374
375        let handles: Vec<_> = (0..NUM_THREADS)
376            .map(|_| {
377                let index_clone = Arc::clone(&index);
378                let barrier_clone = Arc::clone(&barrier);
379
380                thread::spawn(move || {
381                    // Wait for all threads to be ready
382                    barrier_clone.wait();
383                    // All threads try to initialize at once
384                    initialize_entity_index(&index_clone)
385                })
386            })
387            .collect();
388
389        let results: Vec<usize> = handles.into_iter().map(|h| h.join().unwrap()).collect();
390
391        let first = results[0];
392
393        // The index should be initialized
394        assert_ne!(first, usize::MAX);
395        // All threads should get the same index
396        assert!(results.iter().all(|&r| r == first));
397        // And that index should be what was originally the next available index
398        assert_eq!(first, initial_registered_items_count);
399
400        // Test 2: Try to initialize multiple indices from multiple threads simultaneously.
401        //
402        // Creates 5 different entities (each with their own atomic). Initializes
403        // each from a separate thread. Verifies they receive sequential,
404        // unique indices. Confirms the global counter matches the entity count.
405
406        // W
407        let initial_registered_items_count = get_registered_entity_count();
408
409        // Create multiple different entities (each with their own atomic)
410        const NUM_ENTITIES: usize = 5;
411        let entities: Vec<_> = (0..NUM_ENTITIES)
412            .map(|_| Arc::new(AtomicUsize::new(usize::MAX)))
413            .collect();
414
415        let mut handles = vec![];
416
417        // Initialize each entity from a different thread
418        for entity in entities.iter() {
419            let entity_clone = Arc::clone(entity);
420            let handle = thread::spawn(move || initialize_entity_index(&entity_clone));
421            handles.push(handle);
422        }
423
424        // Collect results
425        let mut results = vec![];
426        for handle in handles {
427            results.push(handle.join().unwrap());
428        }
429
430        // Each entity should get a unique, sequential index starting with `initial_registered_items_count`.
431        results.sort();
432        for (i, &result) in results.iter().enumerate() {
433            assert_eq!(
434                result,
435                i + initial_registered_items_count,
436                "Entity should have index {}, got {}",
437                i,
438                result
439            );
440        }
441
442        // Test 3: Try to initialize multiple entities from multiple threads multiple times.
443
444        // We account for the fact that some entities have been initialized
445        // in their `ctors`, so the indices we create don't start with 0.
446        let initial_registered_items_count = get_registered_entity_count();
447
448        // Create 3 entities
449        let entity1 = Arc::new(AtomicUsize::new(usize::MAX));
450        let entity2 = Arc::new(AtomicUsize::new(usize::MAX));
451        let entity3 = Arc::new(AtomicUsize::new(usize::MAX));
452
453        let mut handles = vec![];
454
455        // Multiple threads racing on each of entity1, entity2, entity3
456        for _ in 0..5 {
457            let e1 = Arc::clone(&entity1);
458            handles.push(thread::spawn(move || initialize_entity_index(&e1)));
459
460            let e2 = Arc::clone(&entity2);
461            handles.push(thread::spawn(move || initialize_entity_index(&e2)));
462
463            let e3 = Arc::clone(&entity3);
464            handles.push(thread::spawn(move || initialize_entity_index(&e3)));
465        }
466
467        // Collect all results
468        let results: Vec<_> = handles.into_iter().map(|h| h.join().unwrap()).collect();
469
470        // Count occurrences of each index
471        let mut counts = HashMap::default();
472        for &result in &results {
473            *counts.entry(result).or_insert(0) += 1;
474        }
475
476        // Should have exactly 3 unique indices
477        assert_eq!(counts.len(), 3, "Should have 3 unique indices");
478
479        // Each index should appear exactly 5 times (one entity, 5 threads)
480        for (&idx, &count) in &counts {
481            assert_eq!(
482                count, 5,
483                "Index {} should appear 5 times, appeared {} times",
484                idx, count
485            );
486        }
487
488        // Global counter should be 3
489        assert_eq!(
490            get_registered_entity_count() - initial_registered_items_count,
491            3
492        );
493
494        // Each entity should have one of the indices
495        let indices: Vec<_> = vec![
496            entity1.load(Ordering::Acquire),
497            entity2.load(Ordering::Acquire),
498            entity3.load(Ordering::Acquire),
499        ];
500
501        let mut sorted_indices = indices.clone();
502        sorted_indices.sort_unstable();
503        // As before, we account for the fact that some entities have been
504        // initialized in their `ctors`, so the indices we created don't start at 0.
505        let expected_indices = vec![
506            initial_registered_items_count,
507            1 + initial_registered_items_count,
508            2 + initial_registered_items_count,
509        ];
510        assert_eq!(sorted_indices, expected_indices);
511    }
512
513    // Registering items is idempotent
514    #[test]
515    fn test_add_to_registry_idempotent() {
516        let index1 = TestItem1::id();
517        let index2 = TestItem2::id();
518        let index3 = TestItem3::id();
519
520        // All should be initialized (uninitialized indices are `usize::MAX`)
521        assert_ne!(index1, usize::MAX);
522        assert_ne!(index2, usize::MAX);
523        assert_ne!(index3, usize::MAX);
524
525        // Each should have a unique index
526        assert_ne!(index1, index2);
527        assert_ne!(index2, index3);
528        assert_ne!(index1, index3);
529
530        // Adding the same type multiple times should return the same index.
531        add_to_entity_registry::<TestItem1>();
532        add_to_entity_registry::<TestItem1>();
533        add_to_entity_registry::<TestItem1>();
534
535        let index_from_registry_1 = TestItem1::id();
536        let index_from_registry_2 = TestItem2::id();
537        let index_from_registry_3 = TestItem3::id();
538
539        assert_eq!(index1, index_from_registry_1);
540        assert_eq!(index2, index_from_registry_2);
541        assert_eq!(index3, index_from_registry_3);
542    }
543
544    // Getting items lazily initializes `Entity` instances
545    #[test]
546    fn test_registered_items_get() {
547        // Test mutable `EntityStore::get_mut`
548        {
549            let mut items = EntityStore::new();
550
551            let item1 = items.get_mut::<TestItem1>();
552            assert_eq!(item1.value, 42);
553            assert_eq!(TestItem1::name(), "TestItem1");
554
555            let item2 = items.get_mut::<TestItem2>();
556            assert_eq!(item2.name, "test");
557
558            let item3 = items.get_mut::<TestItem3>();
559            assert_eq!(item3.data, vec![1, 2, 3]);
560        }
561
562        // Test immutable `EntityStore::get`
563        {
564            let items = EntityStore::new();
565
566            let item1 = items.get::<TestItem1>();
567            assert_eq!(item1.value, 42);
568            assert_eq!(TestItem1::name(), "TestItem1");
569
570            let item2 = items.get::<TestItem2>();
571            assert_eq!(item2.name, "test");
572
573            let item3 = items.get::<TestItem3>();
574            assert_eq!(item3.data, vec![1, 2, 3]);
575        }
576    }
577
578    // Initialization happens once
579    #[test]
580    fn test_registered_items_get_cached() {
581        // Test immutable `EntityStore::get`
582        {
583            let items = EntityStore::new();
584
585            // Get the item twice
586            let item1_ref1 = items.get::<TestItem1>();
587            let item1_ref2 = items.get::<TestItem1>();
588
589            // Both should point to the same instance
590            assert!(std::ptr::eq(item1_ref1, item1_ref2));
591        }
592
593        // Test mutable `EntityStore::get_mut`
594        {
595            let mut items = EntityStore::new();
596
597            // Get the item twice. We can safely get multiple mutable pointers so long as we don't dereference them.
598            let item1_ptr1: *mut TestItem1 = items.get_mut::<TestItem1>();
599            let item1_ptr2: *mut TestItem1 = items.get_mut::<TestItem1>();
600
601            // Both should point to the same instance
602            assert!(std::ptr::eq(item1_ptr1, item1_ptr2));
603        }
604    }
605
606    #[test]
607    fn test_registered_items_get_mut() {
608        let mut items = EntityStore::new();
609
610        // Get mutable reference and modify
611        let item = items.get_mut::<TestItem1>();
612        assert_eq!(item.value, 42);
613        item.value = 100;
614
615        // Verify the change persisted
616        let item = items.get::<TestItem1>();
617        assert_eq!(item.value, 100);
618    }
619
620    #[test]
621    fn test_registered_items_multiple_items_mutated() {
622        let mut items = EntityStore::new();
623
624        // Read and mutate multiple items
625        let item1 = items.get_mut::<TestItem1>();
626        assert_eq!(item1.value, 42);
627        item1.value = 10;
628
629        let item2 = items.get_mut::<TestItem2>();
630        assert_eq!(item2.name, "test");
631        item2.name = "modified".to_string();
632
633        let item3 = items.get_mut::<TestItem3>();
634        assert_eq!(item3.data, vec![1, 2, 3]);
635        item3.data = vec![9, 8, 7];
636
637        // Verify all changes
638        assert_eq!(items.get::<TestItem1>().value, 10);
639        assert_eq!(items.get::<TestItem2>().name, "modified");
640        assert_eq!(items.get::<TestItem3>().data, vec![9, 8, 7]);
641    }
642
643    #[test]
644    #[should_panic(expected = "No registered entity found with index")]
645    fn test_registered_items_invalid_index() {
646        #[derive(Debug, Default)]
647        struct UnregisteredEntity;
648
649        // Intentionally implement `RegisteredItem` incorrectly.
650        impl Entity for UnregisteredEntity {
651            fn name() -> &'static str
652            where
653                Self: Sized,
654            {
655                "UnregisteredItem"
656            }
657
658            fn id() -> usize
659            where
660                Self: Sized,
661            {
662                87000 // An invalid index
663            }
664
665            fn as_any(&self) -> &dyn Any {
666                self
667            }
668            fn as_any_mut(&mut self) -> &mut dyn Any {
669                self
670            }
671        }
672
673        // Create items container with insufficient capacity
674        let items = EntityStore::new();
675
676        // This should panic because TestItem1's index doesn't exist
677        let _ = items.get::<UnregisteredEntity>();
678    }
679
680    #[test]
681    fn test_registered_item_trait_name() {
682        assert_eq!(TestItem1::name(), "TestItem1");
683        assert_eq!(TestItem2::name(), "TestItem2");
684        assert_eq!(TestItem3::name(), "TestItem3");
685    }
686
687    #[test]
688    fn test_registered_item_new_boxed() {
689        let boxed1 = TestItem1::new_boxed();
690        assert_eq!(boxed1.value, 42);
691
692        let boxed2 = TestItem2::new_boxed();
693        assert_eq!(boxed2.name, "test");
694
695        let boxed3 = TestItem3::new_boxed();
696        assert_eq!(boxed3.data, vec![1, 2, 3]);
697    }
698
699    #[test]
700    fn test_box_dyn_registered_item_type_alias() {
701        let item = TestItem1::new_boxed();
702        assert_eq!(
703            (item as Box<dyn Any>)
704                .downcast_ref::<TestItem1>()
705                .unwrap()
706                .value,
707            42
708        );
709    }
710
711    #[test]
712    fn test_entity_iterator() {
713        let mut context = Context::new();
714
715        // Add different numbers of entities for each type
716        // Note: add_entity returns Result<EntityId<E>, ...>, we unwrap for the test.
717        for _ in 0..5 {
718            context
719                .add_entity::<TestItem1, _>(with!(TestItem1))
720                .unwrap();
721        }
722        for _ in 0..3 {
723            context
724                .add_entity::<TestItem2, _>(with!(TestItem2))
725                .unwrap();
726        }
727        // TestItem3 remains at 0 for now
728
729        // 1. Verify counts
730        assert_eq!(context.get_entity_count::<TestItem1>(), 5);
731        assert_eq!(context.get_entity_count::<TestItem2>(), 3);
732        assert_eq!(context.get_entity_count::<TestItem3>(), 0);
733
734        // 2. Verify iterators
735        let iter1 = context.get_entity_iterator::<TestItem1>();
736        let results1: Vec<_> = iter1.collect();
737        assert_eq!(results1.len(), 5);
738        // Verify ID sequence (starts at 0)
739        for (i, id) in results1.into_iter().enumerate() {
740            assert_eq!(id.0, i);
741        }
742
743        let iter2 = context.get_entity_iterator::<TestItem2>();
744        assert_eq!(iter2.count(), 3);
745
746        let mut iter3 = context.get_entity_iterator::<TestItem3>();
747        assert!(iter3.next().is_none());
748
749        // 3. Verify iterator snapshot behavior
750        // Iterators created now should not see entities added later
751        let snapshot_iter = context.get_entity_iterator::<TestItem1>();
752
753        context
754            .add_entity::<TestItem1, _>(with!(TestItem1))
755            .unwrap();
756
757        assert_eq!(context.get_entity_count::<TestItem1>(), 6);
758        assert_eq!(snapshot_iter.count(), 5); // Still sees original population
759        assert_eq!(context.get_entity_iterator::<TestItem1>().count(), 6); // New iterator sees 6
760    }
761}
ixa/entity/entity_store.rs

ixa/entity/
entity_store.rs
