[−][src]Crate debug_tag
A library for creating debug-only tags to track and check where values are used.
Useful for asserting that two values stem from the same origin. For example, an operation on two
nodes may only be valid if the nodes are in the same graph. DebugTag
can be used to check for
this in tests and when debugging.
See the DebugTag
type for more details.
Motivation
When developing Rust, we often use indices to refer to other values instead of using pointers. Using indices allows us to "point" to a value without borrowing it and can basically be seen as bypassing the borrow checker in a restricted way.
One of the issues of using indicies, is that it is not connected at compile time to the container storing the value. An index used with an incorrect container might panic, or worse, return garbage values.
We need a way to "tag" values such that we can determine if an index is used with the correct container.
Example
use debug_tag::DebugTag; /// An example vec-like structure that allows pushing values and getting values by index. #[derive(Default)] struct Slab<T>{ items: Vec<T>, tag: DebugTag, } /// An index into a value on a slab. #[derive(Copy, Clone)] struct Index { index: usize, tag: DebugTag, } impl<T> Slab<T> { /// Pushes a new value onto the slab. fn push(&mut self, item: T) -> Index { let index = self.items.len(); self.items.push(item); Index { index, tag: self.tag } } /// Gets a value in this `Slab`. If the index is not from this slab, either panics or /// returns an arbitrary value. fn get(&self, index: Index) -> &T { assert_eq!(self.tag, index.tag, "Index must stem from this slab"); &self.items[index.index] } } let mut slab_a = Slab::default(); let ix = slab_a.push(42); assert_eq!(slab_a.get(ix), &42); let mut slab_b = Slab::default(); slab_b.push(1337); // Panics due to the tags being checked: // assert_eq!(slab_b.get(ix), &1337);
Without DebugTag
s, the last line above would just return 1337 - a "garbage value" since ix
stems from a different Slab
.
Structs
DebugTag | A value that guarentees that if two |