Document bevy_ecs::storage

crates/bevy_ecs/src/archetype.rs

@@ -648,6 +648,9 @@ impl Archetypes {
  self.archetypes.get(id.index())
  }
 
+ /// # Panics
+ ///
+ /// Panics if `a` and `b` are equal.
  #[inline]
  pub(crate) fn get_2_mut(
  &mut self,

crates/bevy_ecs/src/storage/blob_vec.rs

@@ -10,7 +10,9 @@ use bevy_utils::OnDrop;
 
 /// A flat, type-erased data storage type
 ///
-/// Used to densely store homogeneous ECS data.
+/// Used to densely store homogeneous ECS data. A blob is usually just an arbitrary block of contiguous memory without any identity, and
+/// could be used to represent any arbitrary data (i.e. string, arrays, etc). This type is an extendable and reallcatable blob, which makes
+/// it a blobby Vec, a `BlobVec`.
 pub(super) struct BlobVec {
  item_layout: Layout,
  capacity: usize,
@@ -35,13 +37,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 element.
+ ///
  /// # 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::ops::Drop
  pub unsafe fn new(
  item_layout: Layout,
  drop: Option<unsafe fn(OwningPtr<'_>)>,
@@ -70,26 +80,36 @@ impl BlobVec {
  }
  }
 
+ /// Returns the number of elements in the vector.
  #[inline]
  pub fn len(&self) -> usize {
  self.len
  }
 
+ /// Returns `true` if the vector contains no elements.
  #[inline]
  pub fn is_empty(&self) -> bool {
  self.len == 0
  }
 
+ /// Returns the total number of elements the vector can hold without reallocating.
  #[inline]
  pub fn capacity(&self) -> usize {
  self.capacity
  }
 
+ /// Returns the [`Layout`] of the element type stored in the vector.
  #[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 +154,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 +167,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,10 +225,10 @@ impl BlobVec {
  std::ptr::copy_nonoverlapping::<u8>(source, destination.as_ptr(), self.item_layout.size());
  }
 
- /// Pushes a value to the [`BlobVec`].
+ /// Appends an element to the back of the vector.
  ///
  /// # Safety
- /// `value` must be valid to add to this [`BlobVec`]
+ /// The `value` must match the [`layout`](`BlobVec::layout`) of the elements in the [`BlobVec`].
  #[inline]
  pub unsafe fn push(&mut self, value: OwningPtr<'_>) {
  self.reserve_exact(1);
@@ -213,6 +237,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 +281,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 +301,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,8 +317,10 @@ impl BlobVec {
  }
  }
 
+ /// Returns a reference to the element at `index`, without doing bounds checking.
+ ///
  /// # Safety
- /// It is the caller's responsibility to ensure that `index` is < self.len()
+ /// It is the caller's responsibility to ensure that `index < self.len()`.
  #[inline]
  pub unsafe fn get_unchecked(&self, index: usize) -> Ptr<'_> {
  debug_assert!(index < self.len());
@@ -300,8 +333,10 @@ impl BlobVec {
  self.get_ptr().byte_add(index * size)
  }
 
+ /// Returns a mutable reference to the element at `index`, without doing bounds checking.
+ ///
  /// # Safety
- /// It is the caller's responsibility to ensure that `index` is < self.len()
+ /// It is the caller's responsibility to ensure that `index < self.len()`.
  #[inline]
  pub unsafe fn get_unchecked_mut(&mut self, index: usize) -> PtrMut<'_> {
  debug_assert!(index < self.len());
@@ -337,6 +372,9 @@ impl BlobVec {
  std::slice::from_raw_parts(self.data.as_ptr() as *const UnsafeCell<T>, self.len)
  }
 
+ /// Clears the vector, removing (and dropping) all values.
+ ///
+ /// Note that this method has no effect on the allocated capacity of the vector.
  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 implements the low-level collections that store data in a [`World`]. These all offer minimal and often
+//! unsafe APIs, and have been made `pub` primarily for debugging and monitoring purposes.
+//!
+//! # Fetching Storages
+//! Each of the below 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.
+ /// Returns a reference to the resource, if it exists.
  ///
  /// # 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.
+ /// Returns a reference to the resource's change ticks, if it exists.
  #[inline]
  pub fn get_ticks(&self) -> Option<ComponentTicks> {
  self.column.get_ticks(Self::ROW)
  }
 
+ /// Returns references to the resource and its change ticks, if it exists.
+ ///
  /// # 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> {
  })
  }
 
+ /// Returns a mutable reference to the resource, if it exists.
+ ///
+ /// # 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,