From 9dc7f47c1b10c638e3a991a6aaed554ab7c45fc7 Mon Sep 17 00:00:00 2001
From: John Bell <bell.john.andrew@gmail.com>
Date: Mon, 8 Nov 2021 21:10:11 +0000
Subject: [PATCH] Adding Manual Reclaim Stratedy (#1)

* Adding manual reclaim strategy and exposing public reclaim method on domain.

* Applying rust format

* Fix typo in documentation of reclaim method
---
 Cargo.toml                     |  2 +-
 README.md                      |  2 +-
 src/domain/mod.rs              | 20 ++++++++++++++++++++
 src/domain/reclaim_strategy.rs |  6 ++++++
 4 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 1c8463f..befac2e 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "atom_box"
-version = "0.1.2"
+version = "0.1.3"
 edition = "2018"
 authors = ["John Bell <bell.john.andrew@gmail.com>"]
 
diff --git a/README.md b/README.md
index 166bdeb..4485a51 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # Atom Box
 
 Atom Box provides an atomic box implementation where the box owns the contained value and its underlying allocation.
-It is therefore, responsible for deallocating the memory when it is no longer being access by any threads.
+It is therefore, responsible for deallocating the memory when it is no longer being accessed by any threads.
 
 Under the covers Atom Box is 'a safe implementation of hazard pointers in rust.'
 
diff --git a/src/domain/mod.rs b/src/domain/mod.rs
index e513961..d696aec 100644
--- a/src/domain/mod.rs
+++ b/src/domain/mod.rs
@@ -161,6 +161,26 @@ On nightly this will panic if the domain id is equal to the shared domain's id (
         )
     }
 
+    /// Reclaim all unprotected retired items.
+    ///
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use atom_box::{AtomBox, domain::{Domain, ReclaimStrategy}};
+    ///
+    /// const CUSTOM_DOMAIN_ID: usize = 42;
+    /// static CUSTOM_DOMAIN: Domain<CUSTOM_DOMAIN_ID> = Domain::new(ReclaimStrategy::Manual);
+    ///
+    /// let atom_box = AtomBox::new_with_domain("Hello World", &CUSTOM_DOMAIN);
+    /// atom_box.swap("Goodbye World");
+    ///
+    /// CUSTOM_DOMAIN.reclaim();
+    /// ```
+    pub fn reclaim(&self) -> usize {
+        self.bulk_reclaim()
+    }
+
     fn bulk_reclaim(&self) -> usize {
         let retired_list = self
             .retired
diff --git a/src/domain/reclaim_strategy.rs b/src/domain/reclaim_strategy.rs
index fa90555..b4b66c8 100644
--- a/src/domain/reclaim_strategy.rs
+++ b/src/domain/reclaim_strategy.rs
@@ -11,6 +11,7 @@ const DEFAULT_HAZARD_POINTER_MULTIPLIER: isize = 2;
 /// A `default` const constructor function is defined for this enum. It cannot implement `Default`
 /// since we would like the `default` constructor to be a const function.
 #[derive(Debug)]
+#[non_exhaustive]
 pub enum ReclaimStrategy {
     /// Every time an item is retired the domain will try to reclaim any items which are not
     /// currently being protected by a hazard pointer.
@@ -19,6 +20,10 @@ pub enum ReclaimStrategy {
     /// Items will be reclaimed both periodically, and when the number of retired items exceeds
     /// certain thresholds.
     TimedCapped(TimedCappedSettings),
+
+    /// Memory reclaimation will only happen when the `reclaim` method on [`crate::domain::Domain`]
+    /// is called.
+    Manual,
 }
 
 impl ReclaimStrategy {
@@ -28,6 +33,7 @@ impl ReclaimStrategy {
             Self::TimedCapped(settings) => {
                 settings.should_reclaim(hazard_pointer_count, retired_count)
             }
+            Self::Manual => false,
         }
     }