T0b1/wasmtime
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clean up the documentation for the entity module.

Browse Source
This commit is contained in:
Jakob Stoklund Olesen
2017-08-18 17:14:31 -07:00
parent 9cb0529be4
commit a9238eda7a
5 changed files with 113 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
lib/cretonne/src/entity/sparse.rs
View File

@@ -6,34 +6,6 @@
//!
//! > Briggs, Torczon, *An efficient representation for sparse sets*,
//! ACM Letters on Programming Languages and Systems, Volume 2, Issue 1-4, March-Dec. 1993.
//!
//! A `SparseMap<K, V>` map provides:
//!
//! - Memory usage equivalent to `EntityMap<K, u32>` + `Vec<V>`, so much smaller than
//! `EntityMap<K, V>` for sparse mappings of larger `V` types.
//! - Constant time lookup, slightly slower than `EntityMap`.
//! - A very fast, constant time `clear()` operation.
//! - Fast insert and erase operations.
//! - Stable iteration that is as fast as a `Vec<V>`.
//!
//! # Compared to `EntityMap`
//!
//! When should we use a `SparseMap` instead of a secondary `EntityMap`? First of all, `SparseMap`
//! does not provide the functionality of a primary `EntityMap` which can allocate and assign
//! entity references to objects as they are pushed onto the map. It is only the secondary
//! entity maps that can be replaced with a `SparseMap`.
//!
//! - A secondary entity map requires its values to implement `Default`, and it is a bit loose
//! about creating new mappings to the default value. It doesn't distinguish clearly between an
//! unmapped key and one that maps to the default value. `SparseMap` does not require `Default`
//! values, and it tracks accurately if a key has been mapped or not.
//! - Iterating over the contents of an `EntityMap` is linear in the size of the *key space*, while
//! iterating over a `SparseMap` is linear in the number of elements in the mapping. This is an
//! advantage precisely when the mapping is sparse.
//! - `SparseMap::clear()` is constant time and super-fast. `EntityMap::clear()` is linear in the
//! size of the key space. (Or, rather the required `resize()` call following the `clear()` is).
//! - `SparseMap` requires the values to implement `SparseMapValue<K>` which means that they must
//! contain their own key.
use entity::{EntityRef, EntityMap};
use std::mem;
@@ -51,6 +23,33 @@ pub trait SparseMapValue<K> {
}
/// A sparse mapping of entity references.
///
/// A `SparseMap<K, V>` map provides:
///
/// - Memory usage equivalent to `EntityMap<K, u32>` + `Vec<V>`, so much smaller than
/// `EntityMap<K, V>` for sparse mappings of larger `V` types.
/// - Constant time lookup, slightly slower than `EntityMap`.
/// - A very fast, constant time `clear()` operation.
/// - Fast insert and erase operations.
/// - Stable iteration that is as fast as a `Vec<V>`.
///
/// # Compared to `EntityMap`
///
/// When should we use a `SparseMap` instead of a secondary `EntityMap`? First of all, `SparseMap`
/// does not provide the functionality of a `PrimaryMap` which can allocate and assign entity
/// references to objects as they are pushed onto the map. It is only the secondary entity maps
/// that can be replaced with a `SparseMap`.
///
/// - A secondary entity map assigns a default mapping to all keys. It doesn't distinguish between
/// an unmapped key and one that maps to the default value. `SparseMap` does not require
/// `Default` values, and it tracks accurately if a key has been mapped or not.
/// - Iterating over the contents of an `EntityMap` is linear in the size of the *key space*, while
/// iterating over a `SparseMap` is linear in the number of elements in the mapping. This is an
/// advantage precisely when the mapping is sparse.
/// - `SparseMap::clear()` is constant time and super-fast. `EntityMap::clear()` is linear in the
/// size of the key space. (Or, rather the required `resize()` call following the `clear()` is).
/// - `SparseMap` requires the values to implement `SparseMapValue<K>` which means that they must
/// contain their own key.
pub struct SparseMap<K, V>
where K: EntityRef,
V: SparseMapValue<K>