Struct AnimationStore 

pub struct AnimationStore {
    anims: RefCell<Vec<Box<dyn CoreItemAnimation>>>,
}

A store of animations

It has interior mutability, because when pushing an animation into it, we need to return a reference to the animation, which is bound to the store’s lifetime.

To allow the mutation, we use a RefCell<Vec<Box<dyn AnyAnimation>>> in its inner.

Safety Contract

The following invariants must be maintained:

• No mutation after push: Once an animation is pushed into the store, it should never be mutated or removed. The only allowed mutation is pushing new animations into the store.

• No Vec reallocation issues: The returned references from push_eval_dynamic point directly to the heap-allocated AnimationCell<T> data inside the Box<dyn AnyAnimation>. Even if the Vec reallocates (which moves the Boxes), the heap data itself doesn’t move, so the pointers remain valid. This is safe because Box owns heap-allocated data, and the data doesn’t move when the Box is moved within the Vec.

Fields

anims: RefCell<Vec<Box<dyn CoreItemAnimation>>>

Implementations

impl AnimationStore

pub fn new() -> Self

Create a new store.

pub fn push_animation<T: AnyExtractCoreItem>( &self, anim: AnimationCell<T>, ) -> &AnimationCell<T>

Push an AnimationCell<T> into the store and return a reference to it.

The returned reference is bound to &self’s lifetime, which means it will be invalidated when the store is dropped. Since we use RefCell for interior mutability, we can modify the internal Vec while holding a shared reference &self.

Safety

This function uses unsafe code to return a reference that outlives the RefCell borrow. The safety relies on the following guarantees:

1. Pointer validity: The raw pointer ptr points to the heap-allocated AnimationCell<T> that is now owned by the Vec<Box<dyn AnyAnimation>> inside self.anims.

2. Memory layout: When we coerce Box<AnimationCell<T>> to Box<dyn AnyAnimation>, only the vtable pointer changes. The data pointer (pointing to the actual AnimationCell<T> on the heap) remains the same, so ptr is still valid.

3. Vec reallocation safety: Even if the Vec reallocates (which moves the Boxes), the heap-allocated AnimationCell<T> data inside each Box does not move. The pointer ptr points directly to this heap data, not to the Box itself, so it remains valid regardless of Vec reallocations. This is a key property of Box: moving the Box doesn’t move the data it points to on the heap.

4. Lifetime binding: The returned reference &AnimationCell<T> has a lifetime that is inferred from &self, ensuring it cannot outlive the store. This is enforced by Rust’s borrow checker.

5. No mutation after push: Once pushed, the animation is never mutated or removed, so the pointer remains valid for the lifetime of the store.

Trait Implementations

impl Default for AnimationStore

fn default() -> AnimationStore

Returns the “default value” for a type.