Rename Tracker to Constraint

Author: laurmaedje

macros/src/lib.rs

@@ -17,15 +17,6 @@ use quote::quote;
 use syn::{parse_quote, Error, Result};
 
 /// Memoize a pure function.
-///
-/// ```
-/// #[memoize]
-/// fn describe(image: Tracked<Image>) -> String {
-///     let w = image.width();
-///     let h = image.height();
-///     format!("The image is {w}x{h} pixels.")
-/// }
-/// ```
 #[proc_macro_attribute]
 pub fn memoize(_: TokenStream, stream: TokenStream) -> TokenStream {
     let func = syn::parse_macro_input!(stream as syn::ItemFn);
@@ -35,28 +26,6 @@ pub fn memoize(_: TokenStream, stream: TokenStream) -> TokenStream {
 }
 
 /// Make a type trackable.
-///
-/// ```
-/// /// A decoded raster image.
-/// pub struct Image {
-///     width: u32,
-///     height: u32,
-///     pixels: Vec<u8>,
-/// }
-///
-/// #[track]
-/// impl Image {
-///     fn width(&self) -> u32 {
-///         self.width
-///     }
-///
-///     fn height(&self) -> u32 {
-///         self.height
-///     }
-/// }
-/// ```
-///
-/// [`Track`]: ../comemo/trait.Track.html
 #[proc_macro_attribute]
 pub fn track(_: TokenStream, stream: TokenStream) -> TokenStream {
     let block = syn::parse_macro_input!(stream as syn::ItemImpl);

macros/src/memoize.rs

@@ -28,9 +28,8 @@ pub fn expand(func: &syn::ItemFn) -> Result<proc_macro2::TokenStream> {
     }
 
     let arg = args[0];
-    /*
     let ty = types[0];
-    let track = match ty {
+    let _inner = match ty {
         syn::Type::Path(path) => {
             let segs = &path.path.segments;
             if segs.len() != 1 {
@@ -50,7 +49,6 @@ pub fn expand(func: &syn::ItemFn) -> Result<proc_macro2::TokenStream> {
         }
         _ => bail!(ty, "expected type of the form `Tracked<_>`"),
     };
-    */
 
     let mut outer = func.clone();
     outer.block = parse_quote! { {

macros/src/track.rs

@@ -16,7 +16,7 @@ pub fn expand(block: &syn::ItemImpl) -> Result<proc_macro2::TokenStream> {
             syn::ReturnType::Default => unreachable!(),
             syn::ReturnType::Type(_, ty) => ty.as_ref(),
         };
-        quote! { #name: ::comemo::internal::AccessTracker<#ty>, }
+        quote! { #name: ::comemo::internal::HashConstraint<#ty>, }
     });
 
     let tracked_methods = methods.iter().map(|method| {
@@ -26,10 +26,10 @@ pub fn expand(block: &syn::ItemImpl) -> Result<proc_macro2::TokenStream> {
             method.vis = parse_quote! { pub(super) };
         }
         method.block = parse_quote! { {
-            let (inner, tracker) = ::comemo::internal::to_parts(self.0);
+            let (inner, constraint) = ::comemo::internal::to_parts(self.0);
             let output = inner.#name();
-            if let Some(tracker) = &tracker {
-                tracker.#name.track(&output);
+            if let Some(constraint) = &constraint {
+                constraint.#name.set(&output);
             }
             output
         } };
@@ -39,7 +39,7 @@ pub fn expand(block: &syn::ItemImpl) -> Result<proc_macro2::TokenStream> {
     let tracked_valids = methods.iter().map(|method| {
         let name = &method.sig.ident;
         quote! {
-            tracker.#name.valid(&self.#name())
+            constraint.#name.valid(&self.#name())
         }
     });
 
@@ -48,10 +48,10 @@ pub fn expand(block: &syn::ItemImpl) -> Result<proc_macro2::TokenStream> {
 
         impl ::comemo::Track for #ty {}
         impl ::comemo::internal::Trackable for #ty {
-            type Tracker = Tracker;
+            type Constraint = Constraint;
             type Surface = SurfaceFamily;
 
-            fn valid(&self, tracker: &Self::Tracker) -> bool {
+            fn valid(&self, constraint: &Self::Constraint) -> bool {
                 #(#tracked_valids)&&*
             }
 
@@ -77,7 +77,7 @@ pub fn expand(block: &syn::ItemImpl) -> Result<proc_macro2::TokenStream> {
         }
 
         #[derive(Default)]
-        pub struct Tracker {
+        pub struct Constraint {
             #(#tracked_fields)*
         }
     };

src/cache.rs

@@ -16,8 +16,8 @@ pub struct Cache {
 }
 
 /// An entry in the cache.
-struct Entry<Tracker, R> {
-    tracker: Tracker,
+struct Entry<C, R> {
+    constraint: C,
     output: R,
 }
 
@@ -30,18 +30,18 @@ impl Cache {
         R: Debug + Clone + 'static,
     {
         let mut hit = true;
-        let output = self.lookup(tracked).unwrap_or_else(|| {
-            let tracker = T::Tracker::default();
+        let output = self.lookup::<T, R>(tracked).unwrap_or_else(|| {
+            let constraint = T::Constraint::default();
             let (inner, _) = to_parts(tracked);
-            let tracked = from_parts(inner, Some(&tracker));
+            let tracked = from_parts(inner, Some(&constraint));
             let output = f(tracked);
-            self.insert::<T, R>(tracker, output.clone());
+            self.insert::<T, R>(constraint, output.clone());
             hit = false;
             output
         });
 
-        let label = if hit { "[hit]: " } else { "[miss]:" };
-        eprintln!("{name} {label} {output:?}");
+        let label = if hit { "[hit]" } else { "[miss]" };
+        eprintln!("{name:<9} {label:<7} {output:?}");
 
         output
     }
@@ -56,18 +56,18 @@ impl Cache {
         self.map
             .borrow()
             .iter()
-            .filter_map(|boxed| boxed.downcast_ref::<Entry<T::Tracker, R>>())
-            .find(|entry| Trackable::valid(inner, &entry.tracker))
+            .filter_map(|boxed| boxed.downcast_ref::<Entry<T::Constraint, R>>())
+            .find(|entry| Trackable::valid(inner, &entry.constraint))
             .map(|entry| entry.output.clone())
     }
 
     /// Insert an entry into the cache.
-    fn insert<T, R>(&self, tracker: T::Tracker, output: R)
+    fn insert<T, R>(&self, constraint: T::Constraint, output: R)
     where
         T: Track,
         R: 'static,
     {
-        let entry = Entry { tracker, output };
+        let entry = Entry { constraint, output };
         self.map.borrow_mut().push(Box::new(entry));
     }
 }

src/hash.rs

@@ -1,7 +1,9 @@
+use std::cell::Cell;
 use std::hash::Hash;
+use std::marker::PhantomData;
+use std::num::NonZeroU128;
 
 use siphasher::sip128::{Hasher128, SipHasher};
-use std::num::NonZeroU128;
 
 /// Produce a non zero 128-bit hash of a value.
 pub fn siphash<T: Hash>(value: &T) -> NonZeroU128 {
@@ -13,3 +15,22 @@ pub fn siphash<T: Hash>(value: &T) -> NonZeroU128 {
         .try_into()
         .unwrap_or(NonZeroU128::new(u128::MAX).unwrap())
 }
+
+/// Defines a constraint for a value through its hash.
+#[derive(Default)]
+pub struct HashConstraint<T: Hash> {
+    cell: Cell<Option<NonZeroU128>>,
+    marker: PhantomData<T>,
+}
+
+impl<T: Hash> HashConstraint<T> {
+    /// Set the constraint for the value.
+    pub fn set(&self, value: &T) {
+        self.cell.set(Some(siphash(value)));
+    }
+
+    /// Whether the value fulfills the constraint.
+    pub fn valid(&self, value: &T) -> bool {
+        self.cell.get().map_or(true, |v| v == siphash(value))
+    }
+}

src/lib.rs

@@ -11,5 +11,6 @@ pub use comemo_macros::{memoize, track};
 #[doc(hidden)]
 pub mod internal {
     pub use crate::cache::CACHE;
-    pub use crate::track::{from_parts, to_parts, AccessTracker, Family, Trackable};
+    pub use crate::hash::HashConstraint;
+    pub use crate::track::{to_parts, Family, Trackable};
 }

src/main.rs

@@ -42,16 +42,17 @@ fn describe(image: Tracked<Image>) -> &'static str {
 }
 
 const _: () = {
-    mod inner {
+    mod private {
         use super::*;
 
         impl ::comemo::Track for Image {}
         impl ::comemo::internal::Trackable for Image {
-            type Tracker = Tracker;
+            type Constraint = Constraint;
             type Surface = SurfaceFamily;
 
-            fn valid(&self, tracker: &Self::Tracker) -> bool {
-                tracker.width.valid(&self.width()) && tracker.height.valid(&self.height())
+            fn valid(&self, constraint: &Self::Constraint) -> bool {
+                constraint.width.valid(&self.width())
+                    && constraint.height.valid(&self.height())
             }
 
             fn surface<'a, 'r>(tracked: &'r Tracked<'a, Image>) -> &'r Surface<'a>
@@ -73,28 +74,28 @@ const _: () = {
 
         impl<'a> Surface<'a> {
             pub(super) fn width(&self) -> u32 {
-                let (inner, tracker) = ::comemo::internal::to_parts(self.0);
+                let (inner, constraint) = ::comemo::internal::to_parts(self.0);
                 let output = inner.width();
-                if let Some(tracker) = &tracker {
-                    tracker.width.track(&output);
+                if let Some(constraint) = &constraint {
+                    constraint.width.set(&output);
                 }
                 output
             }
 
             pub(super) fn height(&self) -> u32 {
-                let (inner, tracker) = ::comemo::internal::to_parts(self.0);
+                let (inner, constraint) = ::comemo::internal::to_parts(self.0);
                 let output = inner.height();
-                if let Some(tracker) = &tracker {
-                    tracker.height.track(&output);
+                if let Some(constraint) = &constraint {
+                    constraint.height.set(&output);
                 }
                 output
             }
         }
 
         #[derive(Default)]
-        pub struct Tracker {
-            width: ::comemo::internal::AccessTracker<u32>,
-            height: ::comemo::internal::AccessTracker<u32>,
+        pub struct Constraint {
+            width: ::comemo::internal::HashConstraint<u32>,
+            height: ::comemo::internal::HashConstraint<u32>,
         }
     }
 };

src/track.rs

@@ -1,36 +1,22 @@
-use std::cell::Cell;
-use std::hash::Hash;
-use std::marker::PhantomData;
-use std::num::NonZeroU128;
 use std::ops::Deref;
 
-use crate::hash::siphash;
-
 /// Tracks accesses to a value.
 ///
-/// Encapsulates a reference to a value and tracks all accesses to it.
-/// The only methods accessible on `Tracked<T>` are those defined in an impl
-/// block for `T` annotated with [`#[track]`](track).
-///
-/// ```
-/// use comemo::Track;
-///
-/// let image = Image::random(20, 40);
-/// let sentence = describe(image.track());
-/// println!("{sentence}");
-/// ```
+/// Encapsulates a reference to a value and tracks all accesses to it. The only
+/// methods accessible on `Tracked<T>` are those defined in an implementation
+/// block for `T` annotated with [`#[track]`](macro@crate::track).
 pub struct Tracked<'a, T>
 where
     T: Track + ?Sized,
 {
     /// A reference to the tracked value.
     inner: &'a T,
-    /// A tracker which stores constraints for T. It is filled by the tracked
-    /// methods on T's generated surface type.
+    /// A constraint that is generated for T by the tracked methods on T's
+    /// surface type.
     ///
-    /// Starts out as `None` and is set to a stack-stored tracker in the
+    /// Starts out as `None` and is set to a stack-stored constraint in the
     /// preamble of memoized functions.
-    tracker: Option<&'a T::Tracker>,
+    constraint: Option<&'a T::Constraint>,
 }
 
 // The type `Tracked<T>` automatically dereferences to T's generated surface
@@ -59,42 +45,45 @@ where
 }
 
 /// Destructure a `Tracked<_>` into its parts.
-pub fn to_parts<T>(tracked: Tracked<T>) -> (&T, Option<&T::Tracker>)
+pub fn to_parts<T>(tracked: Tracked<T>) -> (&T, Option<&T::Constraint>)
 where
     T: Track,
 {
-    (tracked.inner, tracked.tracker)
+    (tracked.inner, tracked.constraint)
 }
 
 /// Create a `Tracked<_>` from its parts.
-pub fn from_parts<'a, T>(inner: &'a T, tracker: Option<&'a T::Tracker>) -> Tracked<'a, T>
+pub fn from_parts<'a, T>(
+    inner: &'a T,
+    constraint: Option<&'a T::Constraint>,
+) -> Tracked<'a, T>
 where
     T: Track,
 {
-    Tracked { inner, tracker }
+    Tracked { inner, constraint }
 }
 
 /// A trackable type.
 ///
 /// This is implemented by types that have an implementation block annoted with
-/// [`#[track]`](track).
+/// [`#[track]`](macro@crate::track).
 pub trait Track: Trackable {
     /// Start tracking a value.
     fn track(&self) -> Tracked<Self> {
-        Tracked { inner: self, tracker: None }
+        Tracked { inner: self, constraint: None }
     }
 }
 
 /// Non-exposed parts of the `Track` trait.
 pub trait Trackable {
-    /// Keeps track of accesses to the value.
-    type Tracker: Default + 'static;
+    /// Describes an instance of type.
+    type Constraint: Default + 'static;
 
     /// The tracked API surface of this type.
     type Surface: for<'a> Family<'a>;
 
-    /// Whether an instance fulfills the given tracker's constraints.
-    fn valid(&self, tracker: &Self::Tracker) -> bool;
+    /// Whether an instance fulfills the given constraint.
+    fn valid(&self, constraint: &Self::Constraint) -> bool;
 
     /// Cast a reference from `Tracked` to this type's surface.
     fn surface<'a, 'r>(
@@ -109,17 +98,3 @@ pub trait Family<'a> {
     /// The surface with lifetime.
     type Out;
 }
-
-/// Tracks accesses to a value.
-#[derive(Default)]
-pub struct AccessTracker<T: Hash>(Cell<Option<NonZeroU128>>, PhantomData<T>);
-
-impl<T: Hash> AccessTracker<T> {
-    pub fn track(&self, value: &T) {
-        self.0.set(Some(siphash(value)));
-    }
-
-    pub fn valid(&self, value: &T) -> bool {
-        self.0.get().map_or(true, |v| v == siphash(value))
-    }
-}