gwr_track/

entity.rs

// Copyright (c) 2023 Graphcore Ltd. All rights reserved.

//! A simulation entity.
//!
//! All parts of a model should contain an entity in order to maintain a
//! hierarchy of simulation entities. They contain a name and a unique ID
//! for tracing.

use std::fmt;
use std::rc::Rc;

use crate::tracker::aka::{Aka, get_alternative_names};
use crate::{Id, Tracker, create_id, destroy, trace};

/// A capacity value and its units.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Capacity {
    /// Capacity value.
    pub value: usize,

    /// Capacity units, for example "objects" or "bytes".
    pub units: String,
}

impl Capacity {
    /// Construct a new [`Capacity`].
    #[must_use]
    pub fn new(value: usize, units: impl Into<String>) -> Self {
        Self {
            value,
            units: units.into(),
        }
    }
}

/// A simulation entity
///
/// An entity is a part of a hierarchical simulation in which it must have a
/// parent. The simulation top-level should be created using `toplevel("name")`.
///
/// The entity is used when logging so that its unique ID can be emitted and
/// it can determine which messages are emitted to both the binary and textual
/// outputs.
pub struct Entity {
    /// Name of this entity.
    pub name: String,

    /// Optional parent entity (only the top-level should be None).
    pub parent: Option<Rc<Entity>>,

    /// Unique simulation identifier used for bin/log messages.
    pub id: Id,

    /// [`Tracker`] used to handle trace/log events.
    pub tracker: Tracker,

    /// Most verbose log level enabled for this entity by any tracker.
    enabled_level: log::Level,
}

static JOIN: &str = "::";

impl Entity {
    /// Create a new entity.
    #[must_use]
    pub fn new(parent: &Rc<Entity>, name: &str) -> Self {
        Self::new_with_renames(parent, name, None)
    }

    /// Create a new entity with a potential list of alternative names
    #[must_use]
    pub fn new_with_renames(parent: &Rc<Entity>, name: &str, aka: Option<&Aka>) -> Self {
        let alternative_names = get_alternative_names(aka, name);
        let mut full_name = parent.full_name();
        full_name.push_str(JOIN);
        full_name.push_str(name);

        let tracker = parent.tracker.clone();
        let id = create_id!(parent);
        let enabled_level = tracker.add_entity(id, &full_name, alternative_names);

        let entity = Self {
            name: String::from(name),
            parent: Some(parent.clone()),
            id,
            tracker,
            enabled_level,
        };
        entity.track_create(parent.id, &full_name);

        if let Some(alternative_names) = alternative_names {
            for name in alternative_names {
                trace!(entity ; "aka {name}");
            }
        }

        entity
    }

    /// Returns the full hierarchical name of this entity
    #[must_use]
    pub fn full_name(&self) -> String {
        match &self.parent {
            Some(parent) => {
                let mut name = parent.full_name();
                name.push_str(JOIN);
                name.push_str(self.name.as_str());
                name
            }
            None => self.name.clone(),
        }
    }

    /// Return whether trace-level events for this entity will be emitted.
    #[must_use]
    pub fn trace_enabled(&self) -> bool {
        self.enabled_for(log::Level::Trace)
    }

    /// Return whether events at the given level will be emitted for this
    /// entity.
    #[must_use]
    pub fn enabled_for(&self, level: log::Level) -> bool {
        level <= self.enabled_level
    }

    /// Emit the capacity represented by this simulation entity.
    pub fn track_capacity(&self, value: usize, units: impl Into<String>) {
        self.tracker.capacity(self.id, Capacity::new(value, units));
    }

    /// Emit an enter event for an object.
    pub fn track_enter(&self, entered: Id) {
        self.tracker.enter(self.id, entered);
    }

    /// Emit an exit event for an object.
    pub fn track_exit(&self, exited: Id) {
        self.tracker.exit(self.id, exited);
    }

    fn track_create(&self, created_by: Id, full_name: &str) {
        self.tracker.create_entity(created_by, self.id, full_name);
    }
}

impl Drop for Entity {
    fn drop(&mut self) {
        destroy!(self);
    }
}

impl fmt::Debug for Entity {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Entity")
            .field("name", &self.name)
            .field("parent", &self.parent)
            .field("id", &self.id)
            .finish()
    }
}

impl fmt::Display for Entity {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if let Some(parent) = &self.parent {
            parent.fmt(f).unwrap();
            write!(f, "{}{}", JOIN, self.name)
        } else {
            write!(f, "{}", self.name)
        }
    }
}

/// Create the top-level entity. This should be the only entity without a
/// parent.
pub fn toplevel(tracker: &Tracker, name: &str) -> Rc<Entity> {
    let id = tracker.unique_id();
    let enabled_level = tracker.add_entity(id, name, None);
    let top = Rc::new(Entity {
        parent: None,
        name: String::from(name),
        id,
        tracker: tracker.clone(),
        enabled_level,
    });
    top.track_create(crate::NO_ID, name);
    top
}

/// A monitor entity that is only allowed to emit value events.
pub struct EntityMonitor {
    /// The wrapped tracked entity.
    pub entity: Rc<Entity>,

    /// Unique simulation identifier used for bin/log messages.
    pub id: Id,

    /// Name of this monitor.
    pub name: String,
}

impl EntityMonitor {
    /// Create a new monitor entity.
    #[must_use]
    pub fn new(parent: &Rc<Entity>, name: &str) -> Self {
        let mut full_name = parent.full_name();
        full_name.push_str(JOIN);
        full_name.push_str(name);

        let id = create_id!(parent);
        parent.tracker.add_entity(id, &full_name, None);

        let monitor = Self {
            entity: parent.clone(),
            id,
            name: String::from(name),
        };

        monitor.track_create(parent.id, &full_name);

        monitor
    }

    fn track_create(&self, created_by: Id, full_name: &str) {
        self.entity
            .tracker
            .create_monitor(created_by, self.id, full_name);
    }

    /// Emit a value event for this monitor.
    pub fn track_value(&self, value: f64) {
        self.entity.tracker.value(self.entity.id, value);
    }
}

/// A child trace lane used to represent named activity intervals.
pub struct EntityLane {
    /// Parent entity that owns this lane.
    pub entity: Rc<Entity>,

    /// Unique simulation identifier used for trace events.
    pub id: Id,

    /// Name of this lane.
    pub name: String,

    active: bool,
    active_activity: Option<Id>,
    active_group: Option<Id>,
}

impl EntityLane {
    /// Create a new lane under `parent`.
    #[must_use]
    pub fn new(parent: &Rc<Entity>, name: &str) -> Self {
        let mut full_name = parent.full_name();
        full_name.push_str(JOIN);
        full_name.push_str(name);

        let id = create_id!(parent);
        let lane = Self {
            entity: parent.clone(),
            id,
            name: String::from(name),
            active: false,
            active_activity: None,
            active_group: None,
        };

        lane.track_create(parent.id, &full_name);

        lane
    }

    fn track_create(&self, created_by: Id, full_name: &str) {
        self.entity
            .tracker
            .create_lane(created_by, self.id, full_name);
    }

    /// Begin the named activity on this lane.
    pub fn begin(&mut self, name: &str) {
        let activity_id = create_id!(self.entity);
        self.entity
            .tracker
            .begin_activity(activity_id, self.id, name);
        self.active_activity = Some(activity_id);
        self.active = true;
    }

    /// Begin the named activity as part of a group.
    pub fn begin_in_group(&mut self, name: &str, group: &EntityGroup) {
        let activity_id = create_id!(self.entity);
        self.entity.tracker.add_to_group(activity_id, group.id);
        self.active_activity = Some(activity_id);
        self.active_group = Some(group.id);
        self.entity
            .tracker
            .begin_activity(activity_id, self.id, name);
        self.active = true;
    }

    /// End the current activity on this lane.
    pub fn end(&mut self) {
        if self.active {
            let activity_id = self
                .active_activity
                .take()
                .expect("active lane should have an activity ID");
            self.entity.tracker.end_activity(activity_id);
            if let Some(group_id) = self.active_group.take() {
                self.entity.tracker.remove_from_group(activity_id, group_id);
            }
            self.active = false;
        }
    }
}

impl Drop for EntityLane {
    fn drop(&mut self) {
        self.end();
        self.entity.tracker.destroy(self.entity.id, self.id);
    }
}

/// A trace group used to associate related activities.
pub struct EntityGroup {
    /// Parent entity that owns this group.
    pub entity: Rc<Entity>,

    /// Unique simulation identifier used for trace events.
    pub id: Id,

    /// Name of this group.
    pub name: String,
}

impl EntityGroup {
    /// Create a new group under `parent`.
    #[must_use]
    pub fn new(parent: &Rc<Entity>, name: &str) -> Self {
        let mut full_name = parent.full_name();
        full_name.push_str(JOIN);
        full_name.push_str(name);

        let id = create_id!(parent);
        let group = Self {
            entity: parent.clone(),
            id,
            name: String::from(name),
        };

        group
            .entity
            .tracker
            .create_group(parent.id, group.id, &full_name);

        group
    }
}

impl Drop for EntityGroup {
    fn drop(&mut self) {
        self.entity.tracker.destroy(self.entity.id, self.id);
    }
}

/// The `GetEntity` trait is used to provide access to an objects [Entity]
pub trait GetEntity {
    /// Return the [Entity]
    fn entity(&self) -> &Rc<Entity>;
}

impl GetEntity for EntityMonitor {
    fn entity(&self) -> &Rc<Entity> {
        &self.entity
    }
}