SimulationDrivenWare.hpp

Go to the documentation of this file.

/*

  This file is part of OpenFLUID software
  Copyright(c) 2007, INRA - Montpellier SupAgro


 == GNU General Public License Usage ==

  OpenFLUID is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

  OpenFLUID is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with OpenFLUID. If not, see <http://www.gnu.org/licenses/>.


 == Other Usage ==

  Other Usage means a use of OpenFLUID that is inconsistent with the GPL
  license, and requires a written agreement between You and INRA.
  Licensees for Other Usage of OpenFLUID may use this file in accordance
  with the terms contained in the written agreement between You and INRA.
  
*/


/**
  @file SimulationDrivenWare.hpp

  @author Jean-Christophe FABRE <jean-christophe.fabre@inra.fr>
 */


#ifndef __OPENFLUID_WARE_SIMULATIONDRIVENWARE_HPP__
#define __OPENFLUID_WARE_SIMULATIONDRIVENWARE_HPP__


#include <openfluid/dllexport.hpp>
#include <openfluid/ware/PluggableWare.hpp>
#include <openfluid/base/SimulationLogger.hpp>
#include <openfluid/ware/WareException.hpp>
#include <openfluid/base/SimulationStatus.hpp>
#include <openfluid/base/FrameworkException.hpp>


/**
  @internal
*/
#define REQUIRE_SIMULATION_STAGE(stage,msg) \
  if (OPENFLUID_GetCurrentStage() != (stage)) \
  { \
    openfluid::base::ExceptionContext Context = computeFrameworkContext(OPENFLUID_CODE_LOCATION); \
    throw openfluid::base::FrameworkException(Context,msg); \
  }

/**
  @internal
*/
#define REQUIRE_SIMULATION_STAGE_GE(stage,msg) \
  if (OPENFLUID_GetCurrentStage() < (stage)) \
  { \
    openfluid::base::ExceptionContext Context = computeFrameworkContext(OPENFLUID_CODE_LOCATION); \
    throw openfluid::base::FrameworkException(Context,msg); \
  }

/**
  @internal
*/
#define REQUIRE_SIMULATION_STAGE_LE(stage,msg) \
  if (OPENFLUID_GetCurrentStage() > (stage)) \
  { \
    openfluid::base::ExceptionContext Context = computeFrameworkContext(OPENFLUID_CODE_LOCATION); \
    throw openfluid::base::FrameworkException(Context,msg); \
  }


// =====================================================================
// =====================================================================


/**
  @internal
*/
#define _STREAMTOSTRING(_stream) ((static_cast<std::ostringstream&>(std::ostringstream().flush() << _stream)).str())


// Log macros for warnings

/**
  Adds a warning message to simulation log file

  Exemple:
  @snippet help.snippets.infos-debug/InfosDebugSim.cpp macro_logwarning

  @cond OpenFLUID:completion
  {
    "contexts" : ["SIMULATOR", "OBSERVER"],
    "menupath" : ["Compute code", "Messages"],
    "title" : "Log warning message",
    "text" : "OPENFLUID_LogWarning(%%SEL_START%%\"message\"%%SEL_END%%)"
  }
  @endcond
*/
#define OPENFLUID_LogWarning(_stream) \
  appendToLog(openfluid::tools::FileLogger::LOG_WARNING,_STREAMTOSTRING(_stream))

/**
  Displays a warning message to stdout (on screen by default)

  Exemple:
  @snippet help.snippets.infos-debug/InfosDebugSim.cpp macro_displaywarning

  @cond OpenFLUID:completion
  {
    "contexts" : ["SIMULATOR", "OBSERVER"],
    "menupath" : ["Compute code", "Messages"],
    "title" : "Display warning message",
    "text" : "OPENFLUID_DisplayWarning(%%SEL_START%%\"message\"%%SEL_END%%)"
  }
  @endcond
*/
#define OPENFLUID_DisplayWarning(_stream) \
  displayToConsole(openfluid::tools::FileLogger::LOG_WARNING,_STREAMTOSTRING(_stream))

/**
  Adds a warning message to simulation log file and displays it to stdout (on screen by default)

  Exemple:
  @snippet help.snippets.infos-debug/InfosDebugSim.cpp macro_logdisplaywarning

  @cond OpenFLUID:completion
  {
    "contexts" : ["SIMULATOR", "OBSERVER"],
    "menupath" : ["Compute code", "Messages"],
    "title" : "Log and warning debug message",
    "text" : "OPENFLUID_LogAndDisplayWarning(%%SEL_START%%\"message\"%%SEL_END%%)"
  }
  @endcond
*/
#define OPENFLUID_LogAndDisplayWarning(_stream) \
  OPENFLUID_LogWarning(_stream); \
  OPENFLUID_DisplayWarning(_stream)


// Log macros for infos

/**
  Adds an information message to simulation log file

  Exemple:
  @snippet help.snippets.infos-debug/InfosDebugSim.cpp macro_loginfo

  @cond OpenFLUID:completion
  {
    "contexts" : ["SIMULATOR", "OBSERVER"],
    "menupath" : ["Compute code", "Messages"],
    "title" : "Log information message",
    "text" : "OPENFLUID_LogInfo(%%SEL_START%%\"message\"%%SEL_END%%)"
  }
  @endcond
*/
#define OPENFLUID_LogInfo(_stream) \
  appendToLog(openfluid::tools::FileLogger::LOG_INFO,_STREAMTOSTRING(_stream))

/**
  Displays an information message to stdout (on screen by default)

  Exemple:
  @snippet help.snippets.infos-debug/InfosDebugSim.cpp macro_displayinfo

  @cond OpenFLUID:completion
  {
    "contexts" : ["SIMULATOR", "OBSERVER"],
    "menupath" : ["Compute code", "Messages"],
    "title" : "Display information message",
    "text" : "OPENFLUID_DisplayInfo(%%SEL_START%%\"message\"%%SEL_END%%)"
  }
  @endcond
*/
#define OPENFLUID_DisplayInfo(_stream) \
  displayToConsole(openfluid::tools::FileLogger::LOG_INFO,_STREAMTOSTRING(_stream))

/**
  Adds an information message to simulation log file and displays it to stdout (on screen by default)

  Exemple:
  @snippet help.snippets.infos-debug/InfosDebugSim.cpp macro_logdisplayinfo

  @cond OpenFLUID:completion
  {
    "contexts" : ["SIMULATOR", "OBSERVER"],
    "menupath" : ["Compute code", "Messages"],
    "title" : "Log and display information message",
    "text" : "OPENFLUID_LogAndDisplayInfo(%%SEL_START%%\"message\"%%SEL_END%%)"
  }
  @endcond
*/
#define OPENFLUID_LogAndDisplayInfo(_stream) \
  OPENFLUID_LogInfo(_stream); \
  OPENFLUID_DisplayInfo(_stream)


// Log macros for debug

/**
  @def OPENFLUID_LogDebug
  Adds a debug message to simulation log file

  Exemple:
  @snippet help.snippets.infos-debug/InfosDebugSim.cpp macro_logdebug

  @cond OpenFLUID:completion
  {
    "contexts" : ["SIMULATOR", "OBSERVER"],
    "menupath" : ["Compute code", "Messages"],
    "title" : "Log debug message",
    "text" : "OPENFLUID_LogDebug(%%SEL_START%%\"message\"%%SEL_END%%)"
  }
  @endcond
*/

/**
  @def OPENFLUID_DisplayDebug
  Displays a debug message to stdout (on screen by default)

  Exemple:
  @snippet help.snippets.infos-debug/InfosDebugSim.cpp macro_displaydebug

  @cond OpenFLUID:completion
  {
    "contexts" : ["SIMULATOR", "OBSERVER"],
    "menupath" : ["Compute code", "Messages"],
    "title" : "Display debug message",
    "text" : "OPENFLUID_DisplayDebug(%%SEL_START%%\"message\"%%SEL_END%%)"
  }
  @endcond
*/

/**
  @def OPENFLUID_LogAndDisplayDebug
  Adds a debug message to simulation log file and displays it to stdout (on screen by default)

  @snippet help.snippets.infos-debug/InfosDebugSim.cpp macro_logdisplaydebug

  @cond OpenFLUID:completion
  {
    "contexts" : ["SIMULATOR", "OBSERVER"],
    "menupath" : ["Compute code", "Messages"],
    "title" : "Log and display debug message",
    "text" : "OPENFLUID_LogAndDisplayDebug(%%SEL_START%%\"message\"%%SEL_END%%)"
  }
  @endcond
*/

#ifndef NDEBUG

#define OPENFLUID_LogDebug(_stream) \
  appendToLog(openfluid::tools::FileLogger::LOG_DEBUG,_STREAMTOSTRING(_stream))

#define OPENFLUID_DisplayDebug(_stream) \
  displayToConsole(openfluid::tools::FileLogger::LOG_DEBUG,_STREAMTOSTRING(_stream))

#define OPENFLUID_LogAndDisplayDebug(_stream) \
  OPENFLUID_LogDebug(_stream); \
  OPENFLUID_DisplayDebug(_stream)

#else

#define OPENFLUID_LogDebug(_stream)

#define OPENFLUID_DisplayDebug(_stream)

#define OPENFLUID_LogAndDisplayDebug(_stream)

#endif


// =====================================================================
// =====================================================================


namespace openfluid { namespace ware {


class OPENFLUID_API SimulationDrivenWare : public PluggableWare
{
  private:

    const openfluid::base::SimulationStatus* mp_SimStatus;

    openfluid::base::SimulationLogger* mp_SimLogger;

    openfluid::core::TimeIndex_t m_PreviousTimeIndex;


  protected:


    virtual bool isLinked() const
    { 
      return (PluggableWare::isLinked() &&  mp_SimLogger != nullptr && mp_SimStatus != nullptr); 
    }

    void appendToLog(openfluid::tools::FileLogger::LogType LType, const std::string& Msg) const;

    void displayToConsole(openfluid::tools::FileLogger::LogType LType, const std::string& Msg) const;


    openfluid::base::ExceptionContext computeWareContext(const std::string& CodeLoc = "") const;

    openfluid::base::ExceptionContext computeFrameworkContext(const std::string& CodeLoc = "") const;


    /**
      Returns the real beginning date of the simulated period
      @return the date

      @cond OpenFLUID:completion
      {
        "contexts" : ["SIMULATOR", "OBSERVER"],
        "menupath" : ["Compute code", "Time"],
        "title" : "Get begin date of simulation",
        "text" : "OPENFLUID_GetBeginDate()"
      }
      @endcond
    */
    openfluid::core::DateTime OPENFLUID_GetBeginDate() const;

    /**
      Returns the real ending date of the simulated period
      @return the date

      @cond OpenFLUID:completion
      {
        "contexts" : ["SIMULATOR", "OBSERVER"],
        "menupath" : ["Compute code", "Time"],
        "title" : "Get end date of simulation",
        "text" : "OPENFLUID_GetEndDate()"
      }
      @endcond
    */
    openfluid::core::DateTime OPENFLUID_GetEndDate() const;

    /**
      Returns the current real date corresponding to the current time index
      @return the date
    
      @cond OpenFLUID:completion
      {
        "contexts" : ["SIMULATOR", "OBSERVER"],
        "menupath" : ["Compute code", "Time"],
        "title" : "Get begin current date of simulation",
        "text" : "OPENFLUID_GetCurrentDate()"
      }
      @endcond
    */
    openfluid::core::DateTime OPENFLUID_GetCurrentDate() const;

    /**
      Returns the simulation duration in seconds
      @return the duration in seconds

      @cond OpenFLUID:completion
      {
        "contexts" : ["SIMULATOR", "OBSERVER"],
        "menupath" : ["Compute code", "Time"],
        "title" : "Get total simulation duration",
        "text" : "OPENFLUID_GetSimulationDuration()"
      }
      @endcond
    */
    openfluid::core::Duration_t OPENFLUID_GetSimulationDuration() const;

    /**
      Returns the default DeltaT used by the scheduler
      @return the deltaT in seconds

      @cond OpenFLUID:completion
      {
        "contexts" : ["SIMULATOR", "OBSERVER"],
        "menupath" : ["Compute code", "Time"],
        "title" : "Get default deltaT",
        "text" : "OPENFLUID_GetDefaultDeltaT()"
      }
      @endcond
    */
    openfluid::core::Duration_t OPENFLUID_GetDefaultDeltaT() const;

    /**
      Returns the current time index of the simulation, in seconds since the simulation started.
      When the simulation starts, the time index is equal to zero.
      @return the current time index in seconds

      @cond OpenFLUID:completion
      {
        "contexts" : ["SIMULATOR", "OBSERVER"],
        "menupath" : ["Compute code", "Time"],
        "title" : "Get current time index",
        "text" : "OPENFLUID_GetCurrentTimeIndex()"
      }
      @endcond
    */
    openfluid::core::TimeIndex_t OPENFLUID_GetCurrentTimeIndex() const;

    /**
      Returns the time index of the simulation when the plugged ware was previously run
      @return the time index in seconds

      @cond OpenFLUID:completion
      {
        "contexts" : ["SIMULATOR", "OBSERVER"],
        "menupath" : ["Compute code", "Time"],
        "title" : "Get time index of the previous ware run",
        "text" : "OPENFLUID_GetPreviousRunTimeIndex()"
      }
      @endcond
    */
    openfluid::core::TimeIndex_t OPENFLUID_GetPreviousRunTimeIndex() const;

    /**
      Returns the current stage of the simulation
      @return the stage

      @cond OpenFLUID:completion
      {
        "contexts" : ["SIMULATOR", "OBSERVER"],
        "menupath" : ["Compute code", "Time"],
        "title" : "Get current simulation stage",
        "text" : "OPENFLUID_GetCurrentStage()"
      }
      @endcond
    */
    openfluid::base::SimulationStatus::SimulationStage OPENFLUID_GetCurrentStage() const;

    /**
      Returns the current stage of the simulation as a string
      @return the stage name

      @cond OpenFLUID:completion
      {
        "contexts" : ["SIMULATOR", "OBSERVER"],
        "menupath" : ["Compute code", "Time"],
        "title" : "Get current simulation stage as a string",
        "text" : "OPENFLUID_GetCurrentStageAsString()"
      }
      @endcond
    */
    std::string OPENFLUID_GetCurrentStageAsString() const;

    /**
      Returns the scheduling constraint applied to the simulation (may be NONE)
      @return the constraint type

      @cond OpenFLUID:completion
      {
        "contexts" : ["SIMULATOR", "OBSERVER"],
        "menupath" : ["Compute code", "Time"],
        "title" : "Get scheduling constraint mode",
        "text" : "OPENFLUID_GetSchedulingConstraint()"
      }
      @endcond
    */
    openfluid::base::SimulationStatus::SchedulingConstraint OPENFLUID_GetSchedulingConstraint() const;


    /**
      Raises a time-marked warning message to the kernel. This does not stops the simulation
      @param[in] Msg the content of the message
    */
    virtual void OPENFLUID_RaiseWarning(const std::string& Msg);

    /**
       Raises a time-marked warning message to the kernel. This does not stops the simulation
       @param[in] Source the source of the message
       @param[in] Msg the content of the message
       @deprecated Since version 2.1.0.
       Use openfluid::ware::SimulationDrivenWare::OPENFLUID_RaiseWarning(const std::string&)
       or #OPENFLUID_LogWarning instead
     */
    [[deprecated]] virtual void OPENFLUID_RaiseWarning(const std::string& Source, const std::string& Msg);

    /**
      Raises an error message to the kernel. This stops the simulation the next time the kernel has the control
      @param[in] Msg the content of the message

      @cond OpenFLUID:completion
      {
        "contexts" : ["SIMULATOR", "OBSERVER"],
        "menupath" : ["Compute code", "Messages"],
        "title" : "Raise fatal error",
        "text" : "OPENFLUID_RaiseError(%%SEL_START%%\"message\"%%SEL_END%%)"
      }
      @endcond
    */
    virtual void OPENFLUID_RaiseError(const std::string& Msg);

    /**
      Raises an error message to the kernel. This stops the simulation the next time the kernel has the control
      @param[in] Source the source of the message
      @param[in] Msg the content of the message
      @deprecated Since version 2.1.0.
      Use openfluid::ware::SimulationDrivenWare::OPENFLUID_RaiseError(const std::string&) instead
    */
    [[deprecated]] virtual void OPENFLUID_RaiseError(const std::string& Source, const std::string& Msg);

    SimulationDrivenWare(WareType WType) : PluggableWare(WType),
        mp_SimStatus(nullptr), mp_SimLogger(nullptr), m_PreviousTimeIndex(0) 
    { }


  public:

    virtual ~SimulationDrivenWare()
    { }

    void linkToSimulation(const openfluid::base::SimulationStatus* SimStatus);

    void linkToSimulationLogger(openfluid::base::SimulationLogger* SimLogger)
    { 
      mp_SimLogger = SimLogger; 
    }

    void initializeWare(const WareID_t& ID);

    void finalizeWare();

    void setPreviousTimeIndex(const openfluid::core::TimeIndex_t& TimeIndex)
    { 
      m_PreviousTimeIndex = TimeIndex;
    }

};


} } // openfluid::ware


#endif /* __OPENFLUID_WARE_SIMULATIONDRIVENWARE_HPP__ */