Document bevy_ecs::storage

crates/bevy_ecs/src/storage/blob_vec.rs

@@ -35,13 +35,21 @@ impl std::fmt::Debug for BlobVec {
 }
 
 impl BlobVec {
+    /// Creates a new [`BlobVec`] with the specified `capacity`.
+    ///
+    /// `drop` is an optional function pointer that is meant to be invoked when any element in the [`BlobVec`]
+    /// should be dropped. For all Rust-based types, this should match 1:1 with the implementation of [`Drop`]
+    /// if present, and should be `None` if `T: !Drop`. For non-Rust based types, this should match any cleanup
+    /// processes typically associated with the stored
+    ///
     /// # Safety
     ///
     /// `drop` should be safe to call with an [`OwningPtr`] pointing to any item that's been pushed into this [`BlobVec`].
     ///
     /// If `drop` is `None`, the items will be leaked. This should generally be set as None based on [`needs_drop`].
     ///
     /// [`needs_drop`]: core::mem::needs_drop
+    /// [`Drop`]: core::mem::Drop
     pub unsafe fn new(
         item_layout: Layout,
         drop: Option<unsafe fn(OwningPtr<'_>)>,
@@ -70,26 +78,37 @@ impl BlobVec {
         }
     }
 
+    /// Gets the number of elements currently stored in the [`BlobVec`].
     #[inline]
     pub fn len(&self) -> usize {
         self.len
     }
 
+    /// Checks if the [`BlobVec`] is currently empty.
     #[inline]
     pub fn is_empty(&self) -> bool {
         self.len == 0
     }
 
+    /// Gets the maximum possible number of elements the [`BlobVec`] can store without
+    /// reallocating its underlying buffer.
     #[inline]
     pub fn capacity(&self) -> usize {
         self.capacity
     }
 
+    /// Fetches the [`Layout`] of the underlying type stored within the [`BlobVec`].
     #[inline]
     pub fn layout(&self) -> Layout {
         self.item_layout
     }
 
+    /// Reserves the minimum capacity for at least `additional` more elements to be inserted in the given `BlobVec`.
+    /// After calling `reserve_exact`, capacity will be greater than or equal to `self.len() + additional`. Does nothing if
+    /// the capacity is already sufficient.
+    ///
+    /// Note that the allocator may give the collection more space than it requests. Therefore, capacity can not be relied upon
+    /// to be precisely minimal.
     pub fn reserve_exact(&mut self, additional: usize) {
         let available_space = self.capacity - self.len;
         if available_space < additional && self.item_layout.size() > 0 {
@@ -134,6 +153,8 @@ impl BlobVec {
         self.capacity = new_capacity;
     }
 
+    /// Initializes the value at `index` to `value`. This function does not do any bounds checking.
+    ///
     /// # Safety
     /// - index must be in bounds
     /// - the memory in the [`BlobVec`] starting at index `index`, of a size matching this [`BlobVec`]'s
@@ -145,6 +166,8 @@ impl BlobVec {
         std::ptr::copy_nonoverlapping::<u8>(value.as_ptr(), ptr.as_ptr(), self.item_layout.size());
     }
 
+    /// Replaces the value at `index` with `value`. This function does not do any bounds checking.
+    ///
     /// # Safety
     /// - index must be in-bounds
     /// - the memory in the [`BlobVec`] starting at index `index`, of a size matching this
@@ -201,7 +224,7 @@ impl BlobVec {
         std::ptr::copy_nonoverlapping::<u8>(source, destination.as_ptr(), self.item_layout.size());
     }
 
-    /// Pushes a value to the [`BlobVec`].
+    /// Appends a value to the back of the [`BlobVec`].
     ///
     /// # Safety
     /// `value` must be valid to add to this [`BlobVec`]
@@ -213,6 +236,8 @@ impl BlobVec {
         self.initialize_unchecked(index, value);
     }
 
+    /// Forces the length of the vector to `len`.
+    ///
     /// # Safety
     /// `len` must be <= `capacity`. if length is decreased, "out of bounds" items must be dropped.
     /// Newly added items must be immediately populated with valid values and length must be
@@ -255,6 +280,7 @@ impl BlobVec {
 
     /// Removes the value at `index` and copies the value stored into `ptr`.
     /// Does not do any bounds checking on `index`.
+    /// The removed element is replaced by the last element of the `BlobVec`.
     ///
     /// # Safety
     /// It is the caller's responsibility to ensure that `index` is < `self.len()`
@@ -274,6 +300,10 @@ impl BlobVec {
         self.len -= 1;
     }
 
+    /// Removes the value at `index` and drops it.
+    /// Does not do any bounds checking on `index`.
+    /// The removed element is replaced by the last element of the `BlobVec`.
+    ///
     /// # Safety
     /// It is the caller's responsibility to ensure that `index` is < self.len()
     #[inline]
@@ -286,6 +316,9 @@ impl BlobVec {
         }
     }
 
+    /// Fetches a read-only reference to the value at `index`.
+    /// Does not do any bounds checking on `index`.
+    ///
     /// # Safety
     /// It is the caller's responsibility to ensure that `index` is < self.len()
     #[inline]
@@ -300,6 +333,9 @@ impl BlobVec {
         self.get_ptr().byte_add(index * size)
     }
 
+    /// Fetches a mutable reference to the value at `index`.
+    /// Does not do any bounds checking on `index`.
+    ///
     /// # Safety
     /// It is the caller's responsibility to ensure that `index` is < self.len()
     #[inline]
@@ -337,6 +373,7 @@ impl BlobVec {
         std::slice::from_raw_parts(self.data.as_ptr() as *const UnsafeCell<T>, self.len)
     }
 
+    /// Clears the [`BlobVec`] by removing and dropping all of its elements.
     pub fn clear(&mut self) {
         let len = self.len;
         // We set len to 0 _before_ dropping elements for unwind safety. This ensures we don't

crates/bevy_ecs/src/storage/mod.rs

@@ -1,4 +1,24 @@
 //! Storage layouts for ECS data.
+//!
+//! This module contains the low-level backing data stores for ECS. These all offer minimal and often
+//! unsafe APIs, exposed primarily for debugging and monitoring purposes.
+//!
+//! # Fetching Storages
+//! Each of the primary backing data stores can be fetched via [`Storages`], which can be fetched from a
+//! [`World`] via [`World::storages`]. It exposes a top level container for each class of storage within
+//! ECS:
+//!
+//!  - [`Tables`] - columnar contiguous blocks of memory, optimized for fast iteration.
+//!  - [`SparseSets`] - sparse `HashMap`-like mappings from entities to components, optimized for random
+//!    lookup and regular insertion/removal of components.
+//!  - [`Resources`] - singleton storage for the resources in the world
+//!
+//! # Safety
+//! To avoid trivially unsound use of the APIs in this module, it is explicitly impossible to get a mutable
+//! reference to [`Storages`] from [`World`], and none of the types publicly expose a mutable interface.
+//!
+//! [`World`]: crate::world::World
+//! [`World::storages`]: crate::world::World::storages
 
 mod blob_vec;
 mod resource;
@@ -12,8 +32,12 @@ pub use table::*;
 /// The raw data stores of a [World](crate::world::World)
 #[derive(Default)]
 pub struct Storages {
+    /// Backing storage for [`SparseSet`] components.
     pub sparse_sets: SparseSets,
+    /// Backing storage for [`Table`] components.
     pub tables: Tables,
+    /// Backing storage for resources.
     pub resources: Resources<true>,
+    /// Backing storage for `!Send` resources.
     pub non_send_resources: Resources<false>,
 }

crates/bevy_ecs/src/storage/resource.rs

@@ -42,6 +42,10 @@ impl<const SEND: bool> ResourceData<SEND> {
     /// The only row in the underlying column.
     const ROW: TableRow = TableRow::new(0);
 
+    /// Validates the access to `!Send` resources is only done on the thread they were created from.
+    ///
+    /// # Panics
+    /// If `SEND` is false, this will panic if called from a different thread than the one it was inserted from.
     #[inline]
     fn validate_access(&self) {
         if SEND {
@@ -70,7 +74,7 @@ impl<const SEND: bool> ResourceData<SEND> {
         self.id
     }
 
-    /// Gets a read-only pointer to the underlying resource, if available.
+    /// Gets a read-only pointer to the underlying resource, if present.
     ///
     /// # Panics
     /// If `SEND` is false, this will panic if a value is present and is not accessed from the
@@ -83,12 +87,14 @@ impl<const SEND: bool> ResourceData<SEND> {
         })
     }
 
-    /// Gets a read-only reference to the change ticks of the underlying resource, if available.
+    /// Gets a read-only reference to the change ticks of the underlying resource, if present.
     #[inline]
     pub fn get_ticks(&self) -> Option<ComponentTicks> {
         self.column.get_ticks(Self::ROW)
     }
 
+    /// Gets a read-only reference and the change detection ticks for the resource, if present.
+    ///
     /// # Panics
     /// If `SEND` is false, this will panic if a value is present and is not accessed from the
     /// original thread it was inserted in.
@@ -100,6 +106,11 @@ impl<const SEND: bool> ResourceData<SEND> {
         })
     }
 
+    /// Gets a mutable reference for the resource, if present.
+    ///
+    /// # Panics
+    /// If `SEND` is false, this will panic if a value is present and is not accessed from the
+    /// original thread it was inserted in.
     pub(crate) fn get_mut(
         &mut self,
         last_change_tick: u32,