c++_api/inc/opals/IControlObject.hpp

#ifndef OPALS_CONTROL_OBJECT_HPP_INCLUDED
#define OPALS_CONTROL_OBJECT_HPP_INCLUDED

#pragma once

#include "opals/fwd.hpp"
#include "opals/String.hpp"
#include "opals/Vector.hpp"
#include "opals/LogLevel.hpp"

namespace opals {

  /**
  \class  IControlObject
  \brief  Interface for retrieving status and progress information from a module run
  \author jo
  \date   06.09.2012

  \internal
  An object that is derived from that interface can be applied to an opals module allows
  retrieving status and progress information while executing the run function. Status information
  is set synchronous by the modules. Attention: complex code within that the member functions (especially \see setSteps) 
  will slow down the processing performance. If the object is also accessed from a second thread, its the objects 
  responsibility to secure thread safety.
  
  A control object can be passed (by reference) to a OPALS module either while creating a new instance or using the 
  opals::IModuleBase::set_controlObject. It's the programmers responsibility to secure proper lifetime of the control
  object (or use opals::IModuleBase::unset_controlObject to remove the internal link). 

  To interrupt processing throw the opals::Exceptions::UserInterrupt within the overloaded member function (mainly relevant in setSteps).
  */

  class OPALS_API IControlObject {
  public:
    virtual ~IControlObject() {}

    /// sets the descriptions of the stages (implicitly sets the number of stages. it will be set within the module's run function)
    virtual void setStages(const Vector<String> &stageDescriptions) = 0;

    /// \brief sets the current stage (zero based index)
    /// In rare situations no step information will be available for a certain stage. Usually those stages are processed quite quickly  
    virtual void setCurrStage(unsigned currentStage) = 0;

    /// \brief sets the number of steps for the current stage (will be called after the stage was set)
    /// This function is always called before the first corresponding setCurrStep call.
    virtual void setSteps(long long stepCount) = 0;

    /// \brief sets the current step
    /// It is internally secured that for the last setCurrStep call currStep >= stepCount for the corresponding stage. 
    virtual void setCurrStep(long long currStep) = 0;

    /// retrieve log message
    virtual void log(LogLevel::Type level, unsigned threadId, const char* message) = 0;
  };

}

#endif //OPALS_CONTROL_OBJECT_HPP_INCLUDED