Trait trackable::Trackable [] [src]

pub trait Trackable {
    type Event: From<Location>;
    fn assign_tracking_number(&mut self);
    fn tracking_number(&self) -> Option<TrackingNumber>;
    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 following three 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.
  3. Tracking number:
    • It is possible to assign a randomly generated tracking number to a Trackable instance by calling assign_tracking_number method.

See TrackableError as a typical implementaion of this trait.

Examples

Defines a trackable type.

#[macro_use]
extern crate trackable;

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

#[derive(Default)]
struct TrackableObject {
    history: Option<History<Location>>,
    tracking_number: Option<TrackingNumber>,
}
impl Trackable for TrackableObject {
    type Event = Location;
    fn assign_tracking_number(&mut self) {
        if self.tracking_number.is_none() {
            self.tracking_number = Some(TrackingNumber::generate());
        }
    }
    fn tracking_number(&self) -> Option<TrackingNumber> {
        self.tracking_number
    }
    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()), r#"
HISTORY:
  [0] at <anon>:44
  [1] at <anon>:45 -- Hello
  [2] at <anon>:46 -- Hello World!
"#);
}

Associated Types

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

Required Methods

Assigns a randomly generated tracking number to this instance.

Note that implementations must simply ignore the second and subsequent calls of this method.

Returns the tracking number of this instance if it has been assigned.

Enables tracking of this instance.

Disables tracking of this intance.

Returns the reference of the tracking history of this instance.

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

Provided Methods

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

Typically, this is called via track! macro.

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

Implementors