#track #tracker #change

tracker

A macro to track changes to your structs

2 releases

0.1.1 Aug 11, 2021
0.1.0 Jul 27, 2021

#272 in Data structures

Download history 139/week @ 2021-10-03 131/week @ 2021-10-10 57/week @ 2021-10-17 89/week @ 2021-10-24 61/week @ 2021-10-31 84/week @ 2021-11-07 69/week @ 2021-11-14 218/week @ 2021-11-21 152/week @ 2021-11-28 122/week @ 2021-12-05 80/week @ 2021-12-12 146/week @ 2021-12-19 87/week @ 2021-12-26 120/week @ 2022-01-02 90/week @ 2022-01-09 115/week @ 2022-01-16

420 downloads per month
Used in 9 crates (2 directly)

LGPL-3.0-or-later

10KB
84 lines

Tracker - track changes to structs efficiently

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

~285–700KB
~17K SLoC