Tasks.h

/******************************************************************************
* Copyright (c) ATTX LLC 2024. All Rights Reserved.
*
* This software and associated documentation (the "Software") are the 
* proprietary and confidential information of ATTX, LLC. The Software is 
* furnished under a license agreement between ATTX and the user organization 
* and may be used or copied only in accordance with the terms of the agreement.
* Refer to 'license/attx_license.adoc' for standard license terms.
*
* EXPORT CONTROL NOTICE: THIS SOFTWARE MAY INCLUDE CONTENT CONTROLLED UNDER THE
* INTERNATIONAL TRAFFIC IN ARMS REGULATIONS (ITAR) OR THE EXPORT ADMINISTRATION 
* REGULATIONS (EAR99). No part of the Software may be used, reproduced, or 
* transmitted in any form or by any means, for any purpose, without the express 
* written permission of ATTX, LLC.
******************************************************************************/
/*
Tasks header file - Includes definitions for task, model, monitor, event, construct
 
Author: Alex Reynolds
*/
#ifndef ARCHITECTURE_TASKS_H
#define ARCHITECTURE_TASKS_H
 
#include "architecture/EventLogger.h"
#include "architecture/Time.h"
#include "data_management/GraphTreeObject.h"
#include "data_management/DataIO.hpp"
#include "core/clockwerkerrors.h"
#include "core/macros.h"
 
namespace clockwerk {
 
    /// Classes the Task object will rely on
    class Executive;
 
    /// @brief  This is the base implementation of the task class
    /// 
    /// This class defines the base task from which other tasks
    /// are inherited. Tasks are simple events which execute
    /// every step, or as scheduled, with their step function.
    /// 
    /// The task class has two key step functions called by the
    /// Scheduler class -- startup, which should be called once
    /// on step start, and the step function, which is called every
    /// time the event may step. These functions should not be
    /// implemented in derived classes. Instead, derived events 
    /// should implement the start and execute functions,
    /// which are designed for that purpose. The eventStartup
    /// is called from within startup, and should implement event-
    /// specific setup functionality. The execute function will
    /// be called every step step, and should 
    /// contain all event-specific code.
    /// 
    /// The task class has parameters, inputs, and outputs which correspond to
    /// the following definitions: 
    ///
    ///  PARAMETERS:     Configuration flags which should be carefully controlled
    ///                  and only modified at few, select events (i.e. not every
    ///                  timestep)
    ///  INPUTS:         Input parameters to the model which may, but do not have
    ///                  to, change often. These will often be connected to the
    ///                  outputs of other models.
    ///  OUTPUTS:        Output parameters from the model which are the result
    ///                  of an internal calculation in the model.
    /// 
    /// This class should not be used on its own, and must be
    /// derived in a child class.
    class Task : public GraphTreeObject {
    public:
        /// @brief  Default constructor for the task object for simplicity.
        ///         Note: Masks some functionality and should not be used for
        ///         production deployment.
        Task();
 
        /// @brief Task-based constructor for the task. Auto-assigns executive
        /// @param pnt The task to assign as parent of this task
        /// @param nme Name of the task
        Task(Task &pnt, const std::string &m_name="Unnamed");
 
        /// @brief Executive-based constructor for the task
        /// @param executive The executive to set
        /// @param m_name The name for the task
        Task(Executive &executive, const std::string &m_name="Unnamed");
 
        /// @brief Task-based constructor for the task. Auto-assigns executive
        /// @param pnt The task to assign as parent of this task
        /// @param nme Name of the task
        /// @param slot The slot to which the task should be scheduled. 
        ///                      Negative indicates it should not be scheduled.
        Task(Task &pnt, int slot, const std::string &m_name="Unnamed");
 
        /// @brief Executive-based constructor for the task
        /// @param executive The executive to set
        /// @param m_name The name for the task
        /// @param slot The slot to which the task should be scheduled. 
        ///                      Negative indicates it should not be scheduled.
        Task(Executive &executive, int slot, const std::string &m_name="Unnamed");
 
        /// @brief Desrtuctor. Doesn't really do anything
        virtual ~Task() {};
 
        /// @brief   Function to perform startup activities (step once at start after creation).
        ///          Should not be modified in derived task.
        /// @return  Error code corresponding to success/failure
        /// @note    This is the master task function, which calls start internally
        ///          and performs other tasks before and after
        int startup();
 
        /// @brief   Function to step the task. This will be called every step
        /// @return  Error code corresponding to success/failure
        /// @note    Inherited in derived monitor/event for special cases but
        ///          should not be implemented directly in inherited classes
        virtual int step();
 
        /// @brief Function to activate the task
        /// @return Error code corresponding to success/failure
        /// @note    This is an inherited function that should be overwritten in inherited
        ///          task class, if implemented. If it is not implemented in the inherited
        ///          class, step() function will do nothing
        virtual int activate() {active(true); _error = step(); return _error;}
 
        /// @brief Function to deactivate the task
        /// @return Error code corresponding to success/failure
        /// @note    This is an inherited function that should be overwritten in inherited
        ///          task class, if implemented. If it is not implemented in the inherited
        ///          class, step() function will do nothing
        virtual int deactivate() {active(false); return NO_ERROR;}
 
        /// @brief Function to command this task to record timing information
        void recordTiming() {_record_timing = true;}
 
        /// @brief Function to set the local model log level
        /// @param new_level The new level to set logging to
        void logLevel(log_level_e new_level) {_local_log_level = new_level;}
 
        /// @brief The active flag for the task -- set to true by default
        DataIO<bool> active = DataIO<bool>(this, "active", true);
 
        /// @brief The schedule slot this task will step in -- set to 0 by default
        DataIO<int> schedule_slot = DataIO<int>(this, "schedule_slot", 0);
 
        /// @brief Time of entry (per wallClockTimer) of the last step of this task
        DataIO<Time> entry_time = DataIO<Time>(this, "entry_time", Time());
 
        /// @brief Time of exit (per wallClockTimer) of the last step of this task
        DataIO<Time> exit_time = DataIO<Time>(this, "exit_time", Time());
    protected:
        /// @brief   Function to perform task startup activities (step once after creation)
        /// @return  Error code corresponding to success/failure
        /// @note    This is an inherited function that should be overwritten in inherited
        ///          task class, if implemented. If it is not implemented in the inherited
        ///          class, it will do nothing.
        virtual int start() {return NO_ERROR;}
 
        /// @brief   Function to execute the task. All math and calculations should be here.
        /// @return  Error code corresponding to success/failure
        /// @note    This is an inherited function that should be overwritten in inherited
        ///          task class, if implemented. If it is not implemented in the inherited
        ///          class, it will do nothing.
        virtual int execute() {return NO_ERROR;}
 
        ///  ----------------------------------------------------------
        ///  General utility functions for models
        ///  ----------------------------------------------------------
        ///  @brief   Overloaded function to check range on a parameter
        ///  @param   min     The minimum acceptable value
        ///  @param   max     The maximum acceptable value
        ///  @param   signal  The signal to be evaluated
        ///  @return  Error code corresponding to value validity
        int rangeCheck(double min, double max, DataIO<double> signal);
        int rangeCheck(float min, float max, DataIO<float> signal);
        int rangeCheck(int min, int max, DataIO<int> signal);
 
        /// Our local log level -- allows a higher log level locally than the overall system
        log_level_e _local_log_level = NONE;
 
        /// Simple variable to track error in task
        int _error = NO_ERROR;
 
        /// Variable to enable or disable timing
        bool _record_timing = false;
 
        /// Pointer to the executive object
        Executive *exc = nullptr;
    };
 
    ///  @brief  Base class implementation of the monitor
    ///
    ///  This file implements the base monitor class. A monitor is
    ///  a simplified model that checks one or multiple conditions
    ///  and sets a flag when triggered. It is designed to be 
    ///  implemented in a child class which sets the monitor flag.
    ///
    ///  Child classes should simply implement the "checkConditions"
    ///  virtual class, which sets the trigger flag.
    ///
    ///  By default, the monitor comes with two flags which the child
    ///  implementation should set:
    ///
    ///  trigger -   This is the flag indicating when the monitor's conditions
    ///              are met. It will indicate true when conditions are met 
    ///              (either once or thereafter depending on persistence flag)
    ///  persistence -   This flag indicates whether the monitor should persist
    ///                  upon trigger or not. If set to true, once monitor conditions
    ///                  are met the monitor will cease stepning and remain true
    ///                  thereafter. If false, the monitor may set the trigger on/
    ///                  off at its own discretion.
    ///
    ///  Note that monitors are analogous to interrupts -- they should do
    ///  nothing besides check conditions and set their own flag. Any 
    ///  resulting actions should be taken by a triggered event.
    class Monitor : public Task {
    public:
        /// @brief  Default constructor for the task object for simplicity.
        ///         Note: Masks some functionality and should not be used for
        ///         production deployment.
        Monitor() : Task() {};
 
        /// @brief Task-based constructor for the task. Auto-assigns executive
        /// @param pnt The task to assign as parent of this task
        /// @param nme Name of the task
        /// @param schedule_slot The slot to which the task should be scheduled. 
        ///                      Negative indicates it should not be scheduled.    
        Monitor(Task &pnt, int schedule_slot=0, const std::string &m_name="Unnamed")
            : Task(pnt, schedule_slot, m_name) {};
 
        /// @brief Executive-based constructor for the task
        /// @param executive The executive to set
        /// @param m_name The name for the task
        /// @param schedule_slot The slot to which the task should be scheduled. 
        ///                      Negative indicates it should not be scheduled.
        Monitor(Executive &executive, int schedule_slot=0, const std::string &m_name="Unnamed")
            : Task(executive, schedule_slot, m_name) {};
 
        /// @brief Desrtuctor. Doesn't really do anything
        virtual ~Monitor() {};
 
        /// @brief   Function to step the monitor. This will be called every step
        /// @return  Error code corresponding to success/failure
        int step();
 
        ///  @brief   Function to reset the monitor's trigger to false
        void reset() {trigger(false);}
 
        ///  Our trigger -- this is the flag set and unset by the monitor as
        ///  its ultimate output, and should be used downstream by events, etc.
        DataIO<bool> trigger = DataIO<bool>(this, "trigger", false);
 
        ///  Our latch flag -- If true, the monitor will continue to return
        ///  triggered even after conditions change. 
        DataIO<bool> latch = DataIO<bool>(this, "latch", false);
    };
 
    /**
     * @brief   Base event class
     * 
     * The event class is a special class implementation designed
     * to step only when triggered by an external flag, typically
     * tied to the Monitor class. 
     * 
     * The event class has two key step functions called by the
     * Scheduler class -- startup, which should be called once
     * on step start, and the step function, which is called every
     * time the event may step. These functions should not be
     * implemented in derived classes. Instead, derived events 
     * should implement the eventStartup and execute functions,
     * which are designed for that purpose. The eventStartup
     * is called from within startup, and should implement event-
     * specific setup functionality. The execute function will
     * be called only when the event is triggered, and should 
     * contain all event-specific code.
     * 
     * Events are triggered according to the trigger() signal
     * included in this class definition. It should be mapped 
     * to a boolean indicator of trigger, which should almost
     * definitely/always be the trigger on a monitor.
    */
    class Event : public Task {
    public:
        /// @brief  Default constructor for the task object for simplicity.
        ///         Note: Masks some functionality and should not be used for
        ///         production deployment.
        Event() : Task() {};
 
        /// @brief Task-based constructor for the task. Auto-assigns executive
        /// @param pnt The task to assign as parent of this task
        /// @param nme Name of the task
        /// @param schedule_slot The slot to which the task should be scheduled. 
        ///                      Negative indicates it should not be scheduled.    
        Event(Task &pnt, int schedule_slot=0, const std::string &m_name="Unnamed")
            : Task(pnt, schedule_slot, m_name) {};
 
        /// @brief Executive-based constructor for the task
        /// @param executive The executive to set
        /// @param m_name The name for the task
        /// @param schedule_slot The slot to which the task should be scheduled. 
        ///                      Negative indicates it should not be scheduled.
        Event(Executive &executive, int schedule_slot=0, const std::string &m_name="Unnamed")
            : Task(executive, schedule_slot, m_name) {};
 
        /// @brief Desrtuctor. Doesn't really do anything
        virtual ~Event() {};
 
        /// @brief   Function to step the Event. This will be called every step,
        ///          but only call execute when triggered
        /// @return  Error code corresponding to success/failure
        int step();
 
        /// Our trigger -- this is the flag indicating to the event that it
        /// should step.
        DataIO<bool> trigger = DataIO<bool>(this, "trigger", false);
    };
 
}
 
#endif