Trait trackable::Trackable

pub trait Trackable {
    type Event: From<Location>;
    fn enable_tracking(self) -> Self
    where
        Self: Sized;
    fn disable_tracking(self) -> Self
    where
        Self: Sized;
    fn history(&self) -> Option<&History<Self::Event>>;
    fn history_mut(&mut self) -> Option<&mut History<Self::Event>>;

    fn track<F>(&mut self, f: F)
    where
        F: FnOnce() -> Self::Event,
    { ... }
    fn in_tracking(&self) -> bool { ... }
}

This trait allows to track an instance of an implementation type.

A trackable instance has the following properties:

1. Tracking history:
   • It manages own backtrace-like (but more general) history for tracking.
   • You can add entries to the history by calling tracking macros (e.g., track!)
2. Tracking mode:
   • You can enable (resp. disable) tracking by calling enable_tracking (resp. disable_tracking) method of this trait.
   • If some instances of a type are not needed to be trackable (e.g., non critical errors), it may be useful to disable tracking of those for reducing runtime overhead.

See TrackableError as a typical implementaion of this trait.

Examples

Defines a trackable type.

#[macro_use]
extern crate trackable;

use trackable::{Trackable, History, Location};

#[derive(Default)]
struct TrackableObject {
    history: Option<History<Location>>,
}
impl Trackable for TrackableObject {
    type Event = Location;
    fn enable_tracking(mut self) -> Self where Self: Sized {
        if self.history.is_none() {
            self.history = Some(History::new());
        }
        self
    }
    fn disable_tracking(mut self) -> Self where Self: Sized {
        self.history = None;
        self
    }
    fn history(&self) -> Option<&History<Self::Event>> {
        self.history.as_ref()
    }
    fn history_mut(&mut self) -> Option<&mut History<Self::Event>> {
        self.history.as_mut()
    }
}

fn main() {
    let o = TrackableObject::default();
    let o = track!(o);  // Ignored

    let o = o.enable_tracking();
    let o = track!(o);
    let o = track!(o, "Hello");
    let o = track!(o, "Hello {}", "World!");

    assert_eq!(format!("\n{}", o.history().unwrap()).replace('\\', "/"), r#"
HISTORY:
  [0] at src/lib.rs:35
  [1] at src/lib.rs:36 -- Hello
  [2] at src/lib.rs:37 -- Hello World!
"#);
}

Associated Types

type Event: From<Location>

Event type which a history of an instance of this type can have.

Required Methods

fn enable_tracking(self) -> Self where
    Self: Sized, 

Enables tracking of this instance.

fn disable_tracking(self) -> Self where
    Self: Sized, 

Disables tracking of this intance.

fn history(&self) -> Option<&History<Self::Event>>

Returns the reference of the tracking history of this instance.

fn history_mut(&mut self) -> Option<&mut History<Self::Event>>

Returns the mutable reference of the tracking history of this instance.

Provided Methods

fn track<F>(&mut self, f: F) where
    F: FnOnce() -> Self::Event, 

Add an event into the tail of the history of this instance.

Typically, this is called via track! macro.

fn in_tracking(&self) -> bool

Returns true if tracking of this instance is enabled, otherwise false.

Implementations on Foreign Types

impl<T: Trackable> Trackable for Option<T>

type Event = T::Event

fn enable_tracking(self) -> Self where
    Self: Sized, 

fn disable_tracking(self) -> Self where
    Self: Sized, 

fn history(&self) -> Option<&History<Self::Event>>

fn history_mut(&mut self) -> Option<&mut History<Self::Event>>

fn track<F>(&mut self, f: F) where
    F: FnOnce() -> Self::Event, 

fn in_tracking(&self) -> bool

impl<T, E: Trackable> Trackable for Result<T, E>

type Event = E::Event

fn enable_tracking(self) -> Self where
    Self: Sized, 

fn disable_tracking(self) -> Self where
    Self: Sized, 

fn history(&self) -> Option<&History<Self::Event>>

fn history_mut(&mut self) -> Option<&mut History<Self::Event>>

fn track<F>(&mut self, f: F) where
    F: FnOnce() -> Self::Event, 

fn in_tracking(&self) -> bool

Implementors

• impl Trackable for Failure type Event = Event;
• impl<K> Trackable for TrackableError<K> type Event = Event;