#tracker #track #change

macro tracker-macros

Macros for the tracker crate

10 releases

0.2.1 Mar 20, 2023
0.2.0 Nov 30, 2022
0.1.7 Sep 27, 2022
0.1.6 Nov 13, 2021
0.1.0 Jul 27, 2021

#1519 in Data structures

Download history 584/week @ 2023-11-25 550/week @ 2023-12-02 537/week @ 2023-12-09 700/week @ 2023-12-16 550/week @ 2023-12-23 305/week @ 2023-12-30 532/week @ 2024-01-06 418/week @ 2024-01-13 522/week @ 2024-01-20 564/week @ 2024-01-27 469/week @ 2024-02-03 589/week @ 2024-02-10 610/week @ 2024-02-17 637/week @ 2024-02-24 601/week @ 2024-03-02 476/week @ 2024-03-09

2,377 downloads per month
Used in 18 crates (via tracker)

Apache-2.0 OR MIT

14KB
225 lines

Tracker - track changes to structs efficiently

Rust Tracker on crates.io Tracker on docs.rs

Tracker is a small crate that allows you to track changes to struct fields.

It implements the following methods for your struct fields:

  • get_#field_name()
    Get a immutable reference to your field

  • get_mut_#field_name()
    Get a mutable reference to your field. Assumes the field will be modified and marks it as changed.

  • set_#field_name(value)
    Get a mutable reference to your field. Marks the field as changed only if the new value isn't equal with the previous value.

  • update_#field_name(fn)
    Update your mutable field with a function or closure. Assumes the field will be modified and marks it as changed.

To check for changes you can call var_name.changed(StructName::field_name()) and it will return a bool.

To reset all previous changes you can call var_name.reset().

How it works

Let's have a look at a small example.

#[tracker::track]
struct Test {
    x: u8,
    y: u64,
}

fn main() {
    let mut t = Test {
        x: 0,
        y: 0,
        // the macro generates a new variable called
        // "tracker" that stores the changes
        tracker: 0,
    };

    t.set_x(42);
    // let's check whether the change was detected
    assert!(t.changed(Test::x()));

    // reset t so we don't track old changes
    t.reset();

    t.set_x(42);
    // same value so no change
    assert!(!t.changed(Test::x()));
}

What happens behind the scenes when you call set_x() is that a bitflag is set in the tracker field of your struct:

                                        y   x
tracker: u8 = | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
set_x(42)  -> | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 |
reset()    -> | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |

As you can see this works pretty efficient. The macro expansion looks like this:

impl Test {
    pub fn get_x(&self) -> &u8 {
        &self.x
    }
    pub fn get_mut_x(&mut self) -> &mut u8 {
        self.tracker |= Self::x();
        &mut self.x
    }
    pub fn update_x<F: Fn(&mut u8)>(&mut self, f: F) {
        self.tracker |= Self::x();
        f(&mut self.x);
    }
    pub const fn x() -> u8 {
        1 << 0usize
    }
    pub fn set_x(&mut self, value: u8) {
        if self.x != value {
        self.tracker |= Self::x();
        }
        self.x = value;
    }
}

Further attributes

#[tracker::track]
struct Test {
    #[tracker::do_not_track]
    a: u8,
    #[do_not_track]
    b: u8,
    #[tracker::no_eq]
    c: u8,
    #[no_eq]
    d: u8,
}

You can mark fields as

  • do_not_track if you don't want tracker to implement anything for this field
  • no_eq if the type of the field doesn't implement PartialEq or tracker should not check for equality when calling set_#field_name(value) so that even overwriting with the same value marks the field as changed.

Dependencies

~310–760KB
~18K SLoC