Initial implementation

Author: andreacorbellini

.gitignore

@@ -0,0 +1,2 @@
+/Cargo.lock
+/target

Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "drop-tracker"
+version = "0.1.0"
+edition = "2021"
+authors = ["Andrea Corbellini <[email protected]>"]
+license = "BSD-3-Clause"
+
+description = "Crate to check when a variable gets dropped. Useful for testing wrappers and containers that use unsafe memory management."
+repository = "https://github.com/andreacorbellini/rust-drop-tracker"
+
+keywords = ["testing", "drop"]
+categories = ["development-tools::testing", "rust-patterns"]
+
+[dependencies]

LICENSE.txt

@@ -0,0 +1,26 @@
+Copyright 2022 Andrea Corbellini
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,94 @@
+Rust crate to check if a variable got correctly [dropped]. This crate is mostly useful in unit
+tests for code involving [`ManuallyDrop`], [`MaybeUninit`], unsafe memory management,
+custom containers, and more.
+
+More specifically, this crate allows you to test if a variable is alive or has been dropped, and
+also detects when a variable gets dropped twice. These features can be used to detect bugs in your
+custom wrappers or containers that make use of unsafe memory management and cannot be checked at
+compile time by the Rust compiler.
+
+[dropped]: https://doc.rust-lang.org/reference/destructors.html
+[`ManuallyDrop`]: std::mem::ManuallyDrop
+[`MaybeUninit`]: std::mem::MaybeUninit
+
+# Concepts
+
+The main struct of this crate is `DropTracker`. Once you initialize a tracker, you call
+`DropTracker::track` on it to get a `DropItem`. Each drop item is identified by a key;
+the key can be used at any time to check the state of the item and see if it's alive or
+if it has been dropped.
+
+# Examples
+
+This is how you would test that a container like [`Vec`] drops all its items when the container
+is dropped:
+
+```
+use drop_tracker::DropTracker;
+
+let mut tracker = DropTracker::new();
+
+// Create a new vector and add a bunch of elements to it. The elements in this case are
+// identified by integer key (1, 2, 3), but any hashable type would work.
+//
+// Labels are only used to identify the elements within the tracker, and are not passed
+// around. In this example, the integers 1, 2 and 3 are not placed into the vector, but are
+// kept into the DropTracker.
+let v = vec![tracker.track(1),
+             tracker.track(2),
+             tracker.track(3)];
+
+// Assert that all elements in the vector are alive
+tracker.all_alive(1..=3)
+       .expect("expected all elements to be alive");
+
+// Once the vector is dropped, all items should be dropped with it
+drop(v);
+tracker.all_dropped(1..=3)
+       .expect("expected all elements to be dropped");
+```
+
+This is how you would test a struct that involves [`MaybeUninit`]:
+
+```
+# #![allow(dead_code)]
+use std::mem::MaybeUninit;
+
+struct MyOption<T> {
+    set: bool,
+    data: MaybeUninit<T>,
+}
+
+impl<T> MyOption<T> {
+    fn none() -> Self {
+        Self { set: false, data: MaybeUninit::uninit() }
+    }
+
+    fn some(x: T) -> Self {
+        Self { set: true, data: MaybeUninit::new(x) }
+    }
+}
+
+// BUG: MyOption<T> does not implement Drop!
+// BUG: The instance inside `data` may be initialized but not be properly destructed!
+
+// BUG: The following code will silently leak memory:
+let opt = MyOption::some(String::from("hello"));
+drop(opt); // the String does not get deallocated
+
+// DropTracker is able to catch this sort of bugs:
+use drop_tracker::DropTracker;
+
+let mut tracker = DropTracker::new();
+let opt = MyOption::some(tracker.track("item"));
+
+tracker.state(&"item")
+       .alive()
+       .expect("item is expected to be alive"); // works
+
+drop(opt);
+
+tracker.state(&"item")
+       .dropped()
+       .expect("item is expected to be dropped"); // panics, meaning that the bug was detected
+```