Struct DropTracker

pub struct DropTracker<K> { /* private fields */ }

Creates DropItems and tracks their state.

DropItems can be created using track or try_track and their state can be later checked using state.

DropItems are identified by keys. A key can be of any type that implement the Hash and Eq traits, which include, for example: u32, char, str, …

See the module documentation for details.

Implementations

impl<K> DropTracker<K>

pub fn new() -> Self

Creates a new empty DropTracker.

Examples

use drop_tracker::DropTracker;

let tracker = DropTracker::<u32>::new();
assert_eq!(tracker.tracked().count(), 0);

pub fn tracked( &self, ) -> impl Clone + Iterator<Item = &K> + ExactSizeIterator + FusedIterator

Returns an iterator over the keys tracked by this DropTracker.

The order of keys returned by this iterator is non deterministic.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();
let item_a = tracker.track("a");
let item_b = tracker.track("b");
let item_c = tracker.track("c");

let mut keys = tracker.tracked()
                      .collect::<Vec<&&str>>();
keys.sort();
assert_eq!(keys, [&"a", &"b", &"c"]);

pub fn alive(&self) -> impl Clone + Iterator<Item = &K> + FusedIterator

Returns an iterator over the keys tracked by this DropTracker that are alive.

The order of keys returned by this iterator is non deterministic.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();
let item_a = tracker.track("a");
let item_b = tracker.track("b");
let item_c = tracker.track("c");

drop(item_c);

let mut alive_keys = tracker.alive()
                            .collect::<Vec<&&str>>();
alive_keys.sort();
assert_eq!(alive_keys, [&"a", &"b"]);

drop(item_a);
drop(item_b);

assert_eq!(tracker.alive().count(), 0);

pub fn dropped(&self) -> impl Clone + Iterator<Item = &K> + FusedIterator

Returns an iterator over the keys tracked by this DropTracker that have been dropped.

The order of keys returned by this iterator is non deterministic.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();
let item_a = tracker.track("a");
let item_b = tracker.track("b");
let item_c = tracker.track("c");

assert_eq!(tracker.dropped().count(), 0);

drop(item_a);
drop(item_b);

let mut alive_keys = tracker.dropped()
                            .collect::<Vec<&&str>>();
alive_keys.sort();
assert_eq!(alive_keys, [&"a", &"b"]);

pub fn forget_all(&mut self)

Forgets all the items tracked by this DropTracker.

The DropItems previously returned by the tracker will still work normally, but it will no longer be possible to query their status after forgetting them.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();
assert_eq!(tracker.tracked().count(), 0);

let item_a = tracker.track("a");
let item_b = tracker.track("b");
let item_c = tracker.track("c");
assert_eq!(tracker.tracked().count(), 3);

tracker.forget_all();
assert_eq!(tracker.tracked().count(), 0);

pub fn forget_dropped(&mut self)

Forgets all the items tracked by this DropTracker that have been dropped.

The DropItems previously returned by the tracker will still work normally, but it will no longer be possible to query their status after forgetting them.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();
assert_eq!(tracker.tracked().count(), 0);

let item_a = tracker.track("a");
let item_b = tracker.track("b");
let item_c = tracker.track("c");
assert_eq!(tracker.tracked().count(), 3);

// After dropping an item, the item is still tracked
drop(item_a);
drop(item_b);
assert_eq!(tracker.tracked().count(), 3);

// Use `forget_dropped` to lose track of items that have been dropped
tracker.forget_dropped();
assert_eq!(tracker.tracked().count(), 1);

let mut keys = tracker.tracked()
                      .collect::<Vec<&&str>>();
keys.sort();
assert_eq!(keys, [&"c"]);

impl<K: Hash + Eq> DropTracker<K>

pub fn track(&mut self, key: K) -> DropItem<K>

where K: Clone,

Creates a new DropItem identified by the given key.

The value held by the DropItem is a clone of the key. Use DropTracker::track_with_value if you wish to specify a custom value.

Panics

Panics if the key is already used by another tracked item.

Call forget, forget_dropped or forget_all if you wish to reuse a key from an item you no longer need to track.

See try_track for a variant of this method that does not panic.

Examples

use drop_tracker::DropTracker;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let item = tracker.track("abc");
assert_eq!(tracker.state("abc"), State::Alive);

drop(item);
assert_eq!(tracker.state("abc"), State::Dropped);

Using the same key twice causes a panic:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track("abc");
let item2 = tracker.track("abc"); // panics!

Use forget to reuse the same key:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track("abc");
let _ = tracker.forget("abc");
let item2 = tracker.track("abc"); // works

pub fn try_track(&mut self, key: K) -> Result<DropItem<K>, CollisionError>

where K: Clone,

Creates a new DropItem identified by the given key, or Err if the key is already in use.

The value held by the DropItem is a clone of the key. Use DropTracker::try_track_with_value if you wish to specify a custom value.

See also track.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item = tracker.try_track("abc");
assert!(item.is_ok());

let item = tracker.try_track("abc");
assert!(item.is_err()); // key is already used

pub fn track_with_value<V>(&mut self, key: K, value: V) -> DropItem<V>

Creates a new DropItem identified by the given key and holding the given value.

Panics

Panics if the key is already used by another tracked item.

Call forget, forget_dropped or forget_all if you wish to reuse a key from an item you no longer need to track.

See try_track_with_value for a variant of this method that does not panic.

Examples

use drop_tracker::DropTracker;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let item = tracker.track_with_value("abc", vec![1, 2, 3]);
assert_eq!(tracker.state("abc"), State::Alive);

drop(item);
assert_eq!(tracker.state("abc"), State::Dropped);

Using the same key twice causes a panic:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track_with_value("abc", vec![1, 2, 3]);
let item2 = tracker.track_with_value("abc", vec![4, 5, 6]); // panics!

Use forget to reuse the same key:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track_with_value("abc", vec![1, 2, 3]);
let _ = tracker.forget("abc");
let item2 = tracker.track_with_value("abc", vec![4, 5, 6]); // works

pub fn try_track_with_value<V>( &mut self, key: K, value: V, ) -> Result<DropItem<V>, CollisionError>

Creates a new DropItem identified by the given key and holding the given value, or Err if the key is already in use.

See also track_with_value.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item = tracker.try_track_with_value("abc", vec![1, 2, 3]);
assert!(item.is_ok());

let item = tracker.try_track_with_value("abc", vec![4, 5, 6]);
assert!(item.is_err()); // key is already used

pub fn track_many<'a, Iter>( &'a mut self, keys: Iter, ) -> impl Iterator<Item = DropItem<K>> + 'a

where Iter: IntoIterator<Item = K> + 'a, K: Clone,

Creates multiple new DropItem structs, each identified by a key from the given iterable.

Calling track_many is equivalent to calling track multiple times.

Examples

use drop_tracker::DropTracker;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let mut items = tracker.track_many(["abc", "def", "ghi"]);

let abc = items.next().unwrap();
let def = items.next().unwrap();
let ghi = items.next().unwrap();
assert_eq!(items.next(), None);
drop(items);

assert_eq!(abc, "abc");
assert_eq!(def, "def");
assert_eq!(ghi, "ghi");

assert_eq!(tracker.state("abc"), State::Alive);
assert_eq!(tracker.state("def"), State::Alive);
assert_eq!(tracker.state("ghi"), State::Alive);

drop(def);

assert_eq!(tracker.state("abc"), State::Alive);
assert_eq!(tracker.state("def"), State::Dropped);
assert_eq!(tracker.state("ghi"), State::Alive);

impl<K: Hash + Eq> DropTracker<K>

pub fn state<Q>(&self, key: &Q) -> State

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Checks the state of a DropItem tracked by this DropTracker: alive or dropped.

Panics

Panics if the given key is not tracked.

See try_state for a variant of this method that does not panic.

Examples

use drop_tracker::DropTracker;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let item = tracker.track("abc");
assert_eq!(tracker.state("abc"), State::Alive);

drop(item);
assert_eq!(tracker.state("abc"), State::Dropped);

Querying a key that is not tracked causes a panic:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item = tracker.track("abc");
let state = tracker.state("def"); // panics!

pub fn try_state<Q>(&self, key: &Q) -> Result<State, NotTrackedError>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Checks the state of a DropItem tracked by this DropTracker: alive or dropped. Returns Err it the given key is not tracked.

See also state.

Examples

use drop_tracker::DropTracker;
use drop_tracker::NotTrackedError;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let item = tracker.track("abc");
assert_eq!(tracker.try_state("abc"), Ok(State::Alive));
assert_eq!(tracker.try_state("def"), Err(NotTrackedError));

drop(item);
assert_eq!(tracker.try_state("abc"), Ok(State::Dropped));
assert_eq!(tracker.try_state("def"), Err(NotTrackedError));

pub fn forget<Q>(&mut self, key: &Q) -> State

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Forgets an item tracked by this DropTracker, and returns its current state (alive or dropped).

The DropItems previously returned by the tracker will still work normally, but it will no longer be possible to query their status after forgetting them.

Panics

Panics if the given key is not tracked.

See try_forget for a variant of this method that does not panic.

Examples

use drop_tracker::DropTracker;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let item = tracker.track("a");
assert!(tracker.is_tracked("a"));

assert_eq!(tracker.forget("a"), State::Alive);
assert!(!tracker.is_tracked("a"));

Forgetting a key that is not tracked causes a panic:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item = tracker.track("abc");
let state = tracker.forget("def"); // panics!

pub fn try_forget<Q>(&mut self, key: &Q) -> Result<State, NotTrackedError>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Forgets an item tracked by this DropTracker, and returns its current state (alive or dropped), or Err if the item is not tracked.

The DropItems previously returned by the tracker will still work normally, but it will no longer be possible to query their status after forgetting them.

See also forget.

Examples

use drop_tracker::DropTracker;
use drop_tracker::NotTrackedError;
use drop_tracker::State;

let mut tracker = DropTracker::new();

let item = tracker.track("a");
assert!(tracker.is_tracked("a"));

assert_eq!(tracker.try_forget("a"), Ok(State::Alive));
assert_eq!(tracker.try_forget("b"), Err(NotTrackedError));

pub fn is_tracked<Q>(&self, key: &Q) -> bool

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Returns true if an item identified by the given key is tracked by this DropTracker, false otherwise.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();
assert!(!tracker.is_tracked("abc"));

let item = tracker.track("abc");
assert!(tracker.is_tracked("abc"));

pub fn all_alive<Q, Item, Iter>( &self, iter: Iter, ) -> Result<(), NotAllAliveError<Item>>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized, Item: Borrow<Q>, Iter: IntoIterator<Item = Item>,

Returns Ok if all the given keys point to items that are alive, Err otherwise.

An error may be returned in two cases: either a key is not tracked, or it has been dropped.

This method returns Ok if the sequence of keys passed is empty.

Examples

use drop_tracker::DropTracker;
use drop_tracker::NotAllAliveError;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);
let item3 = tracker.track(3);
let item4 = tracker.track(4);

drop(item3);
drop(item4);

assert_eq!(tracker.all_alive([1, 2]), Ok(()));

assert_eq!(tracker.all_alive([1, 2, 3, 4, 5, 6]),
           Err(NotAllAliveError {
               dropped: vec![3, 4],
               untracked: vec![5, 6],
           }));

Passing an empty set of keys returns Ok:

use drop_tracker::DropTracker;

let tracker = DropTracker::<()>::new();
assert_eq!(tracker.all_alive([(); 0]), Ok(()));

pub fn all_dropped<Q, Item, Iter>( &self, iter: Iter, ) -> Result<(), NotAllDroppedError<Item>>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized, Item: Borrow<Q>, Iter: IntoIterator<Item = Item>,

Returns Ok if all the given keys point to items that are dropped, Err otherwise.

An error may be returned in two cases: either a key is not tracked, or it is alive.

This method returns Ok if the sequence of keys passed is empty.

Examples

use drop_tracker::DropTracker;
use drop_tracker::NotAllDroppedError;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);
let item3 = tracker.track(3);
let item4 = tracker.track(4);

drop(item3);
drop(item4);

assert_eq!(tracker.all_dropped([3, 4]), Ok(()));

assert_eq!(tracker.all_dropped([1, 2, 3, 4, 5, 6]),
           Err(NotAllDroppedError {
               alive: vec![1, 2],
               untracked: vec![5, 6],
           }));

Passing an empty set of keys returns Ok:

use drop_tracker::DropTracker;

let tracker = DropTracker::<()>::new();
assert_eq!(tracker.all_dropped([(); 0]), Ok(()));

pub fn fully_alive(&self) -> Result<(), SomeDroppedError<'_, K>>

Returns Ok if all the keys tracked are alive, Err otherwise.

The error returned references an arbitrary keys that was found dropped.

If the tracker is empty, this method returns Ok.

Examples

use drop_tracker::DropTracker;
use drop_tracker::SomeDroppedError;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);
let item3 = tracker.track(3);

assert_eq!(tracker.fully_alive(), Ok(()));

drop(item1);

assert_eq!(tracker.fully_alive(), Err(SomeDroppedError { dropped: &1 }));

Calling fully_alive() on an empty tracker always returns Ok:

use drop_tracker::DropTracker;

let tracker = DropTracker::<()>::new();
assert_eq!(tracker.fully_alive(), Ok(()));

pub fn fully_dropped(&self) -> Result<(), SomeAliveError<'_, K>>

Returns Ok if all the keys tracked are dropped, Err otherwise.

The error returned references an arbitrary keys that was found alive.

If the tracker is empty, this method returns Ok.

Examples

use drop_tracker::DropTracker;
use drop_tracker::SomeAliveError;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);
let item3 = tracker.track(3);

drop(item1);
drop(item2);

assert_eq!(tracker.fully_dropped(), Err(SomeAliveError { alive: &3 }));

drop(item3);

assert_eq!(tracker.fully_dropped(), Ok(()));

Calling fully_dropped() on an empty tracker always returns Ok:

use drop_tracker::DropTracker;

let tracker = DropTracker::<()>::new();
assert_eq!(tracker.fully_dropped(), Ok(()));

pub fn assert_alive<Q>(&self, key: &Q)

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Checks that all the given key points to an item that is alive, panics otherwise.

assert_alive(...) is a shortcut for state(...).alive().unwrap(). See state() for more details.

Panics

If the key is not tracked, or if it has been dropped.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item2 = tracker.track(1);
let item2 = tracker.track(2);

drop(item2);

tracker.assert_alive(&1); // succeeds
tracker.assert_alive(&2); // panics (item was dropped)
tracker.assert_alive(&3); // panics (key is not tracked)

pub fn assert_dropped<Q>(&self, key: &Q)

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Checks that all the given key points to an item that is dropped, panics otherwise.

assert_dropped(...) is a shortcut for state(...).dropped().unwrap(). See state() for more details.

Panics

If the key is not tracked, or if it is alive.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);

drop(item1);

tracker.assert_dropped(&1); // succeeds
tracker.assert_dropped(&2); // panics (item is alive)
tracker.assert_dropped(&3); // panics (key is not tracked)

pub fn assert_all_alive<Q, Item, Iter>(&self, iter: Iter)

where K: Borrow<Q>, Q: Hash + Eq + ?Sized, Item: Borrow<Q> + Debug, Iter: IntoIterator<Item = Item>,

Checks that all the given keys point to items that are alive, panics otherwise.

assert_all_alive(...) is a shortcut for all_alive(...).unwrap(). See all_alive() for more details.

Panics

If a key is not tracked, or if it has been dropped.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);
let item3 = tracker.track(3);
let item4 = tracker.track(4);

drop(item3);
drop(item4);

tracker.assert_all_alive([1, 2]); // succeeds
tracker.assert_all_alive([3, 4]); // panics (items were dropped)
tracker.assert_all_alive([5, 6]); // panics (keys are not tracked)

Passing an empty set of keys succeeds:

use drop_tracker::DropTracker;

let tracker = DropTracker::<()>::new();
tracker.assert_all_alive([(); 0]);

pub fn assert_all_dropped<Q, Item, Iter>(&self, iter: Iter)

where K: Borrow<Q>, Q: Hash + Eq + ?Sized, Item: Borrow<Q> + Debug, Iter: IntoIterator<Item = Item>,

Checks that all the given keys point to items that are dropped, panics otherwise.

assert_all_dropped(...) is a shortcut for all_dropped(...).unwrap(). See all_dropped() for more details.

Panics

If a key is not tracked, or if it is alive.

Examples

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);
let item3 = tracker.track(3);
let item4 = tracker.track(4);

drop(item1);
drop(item2);

tracker.assert_all_dropped([1, 2]); // succeeds
tracker.assert_all_dropped([3, 4]); // panics (items are alive)
tracker.assert_all_dropped([5, 6]); // panics (keys are not tracked)

Passing an empty set of keys succeeds:

use drop_tracker::DropTracker;

let tracker = DropTracker::<()>::new();
tracker.assert_all_dropped([(); 0]);

pub fn assert_fully_alive(&self)

where K: Debug,

Checks that all the keys tracked are alive, panics otherwise.

assert_fully_alive() is a shortcut for fully_alive().unwrap(). See fully_alive() for more details.

Panics

If one or more items were found to have been dropped.

Examples

Calling assert_fully_alive() when all items are alive succeeds:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);

tracker.assert_fully_alive(); // succeeds

Calling assert_fully_alive() when one or more items are dropped causes a panic:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);

drop(item1);

tracker.assert_fully_alive(); // panics

Calling assert_fully_alive() when the tracker is empty succeeds:

use drop_tracker::DropTracker;

let tracker = DropTracker::<()>::new();
tracker.assert_fully_alive(); // succeeds

pub fn assert_fully_dropped(&self)

where K: Debug,

Checks that all the keys tracked are dropped, panics otherwise.

assert_fully_dropped() is a shortcut for fully_dropped().unwrap(). See fully_dropped() for more details.

Panics

If one or more items were found alive.

Examples

Calling assert_fully_dropped() when items are alive causes a panic:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);

tracker.assert_fully_dropped(); // panics

Calling assert_fully_dropped() when all items are dropped succeeds:

use drop_tracker::DropTracker;

let mut tracker = DropTracker::new();

let item1 = tracker.track(1);
let item2 = tracker.track(2);

drop(item1);
drop(item2);

tracker.assert_fully_dropped(); // succeeds

Calling assert_fully_dropped() when the tracker is empty succeeds:

use drop_tracker::DropTracker;

let tracker = DropTracker::<()>::new();
tracker.assert_fully_dropped(); // succeeds

Trait Implementations

impl<K: Debug> Debug for DropTracker<K>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<K: Default> Default for DropTracker<K>

fn default() -> DropTracker<K>

Returns the “default value” for a type.