Operation.h

//=========================================================================
//  Copyright (c) Kitware, Inc.
//  All rights reserved.
//  See LICENSE.txt for details.
//
//  This software is distributed WITHOUT ANY WARRANTY; without even
//  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
//  PURPOSE.  See the above copyright notice for more information.
//=========================================================================
#ifndef smtk_operation_Operation_h
#define smtk_operation_Operation_h
 
#include "smtk/resource/Lock.h"
 
#include "smtk/PublicPointerDefs.h"
#include "smtk/SharedFromThis.h"
#include "smtk/common/Deprecation.h"
 
#include <functional>
#include <map>
#include <string>
#include <typeindex>
#include <utility>
 
namespace smtk
{
namespace attribute
{
class Attribute;
class Resource;
} // namespace attribute
namespace io
{
class Logger;
}
namespace operation
{
class Helper;
 
class ImportPythonOperation;
class Manager;
class Operation;
 
using Handler = std::function<void(Operation&, const std::shared_ptr<smtk::attribute::Attribute>&)>;
 
using ResourceAccessMap = std::map<
  std::weak_ptr<smtk::resource::Resource>,
  smtk::resource::LockType,
  std::owner_less<std::weak_ptr<smtk::resource::Resource>>>;
 
class SMTKCORE_EXPORT Operation : smtkEnableSharedPtr(Operation)
{
  friend class Helper;
 
public:
  smtkTypeMacroBase(smtk::operation::Operation);
 
  // A hash value uniquely representing the operation.
  typedef std::size_t Index;
 
  // An attribute describing the operation's input.
  typedef std::shared_ptr<smtk::attribute::Attribute> Parameters;
 
  // An attribute containing the operation's result.
  typedef std::shared_ptr<smtk::attribute::Attribute> Result;
 
  // An attribute resource containing the operation's execution definition
  // result definition.
  typedef std::shared_ptr<smtk::attribute::Resource> Specification;
 
  typedef std::shared_ptr<smtk::attribute::Definition> Definition;
 
  // These values are taken on by the "outcome" item of every Operation Result.
  enum class Outcome
  {
    UNABLE_TO_OPERATE, 
    CANCELED,          
    FAILED,            
    SUCCEEDED,         
    UNKNOWN = -1       
  };
 
  friend Manager;
  friend ImportPythonOperation;
 
  virtual ~Operation();
 
  // Index is a compile-time intrinsic of the derived operation; as such, it
  // cannot be set. It is virtual so that derived operations can assign their
  // own index (as is necessary for python operations that would otherwise all
  // resolve to the same index).
  virtual Index index() const { return std::type_index(typeid(*this)).hash_code(); }
 
  virtual bool configure(
    const smtk::attribute::AttributePtr& changedAttribute = smtk::attribute::AttributePtr(),
    const smtk::attribute::ItemPtr& changedItem = smtk::attribute::ItemPtr());
 
  virtual bool ableToOperate();
 
  Result operate();
 
  Outcome safeOperate();
  Outcome safeOperate(Handler handler);
 
  virtual bool releaseResult(Result& result);
 
  virtual smtk::io::Logger& log() const;
 
  Specification specification();
 
  Parameters parameters();
  Parameters parameters() const;
 
  Result createResult(Outcome);
 
  ManagerPtr manager() const { return m_manager.lock(); }
 
  bool restoreTrace(const std::string& trace);
 
  void setManagers(const std::shared_ptr<smtk::common::Managers>& m) { m_managers = m; }
  std::shared_ptr<smtk::common::Managers> managers() const { return m_managers; }
 
  virtual bool threadSafe() const { return true; }
 
  smtk::resource::ManagerPtr resourceManager();
 
  enum LockOption
  {
    LockAll,         
    ParentLocksOnly, 
    SkipLocks        
  };
 
  enum ObserverOption
  {
    InvokeObservers, 
    SkipObservers    
  };
 
  enum ParametersOption
  {
    Validate,      
    SkipValidation 
  };
 
protected:
  Operation();
 
  virtual ResourceAccessMap identifyLocksRequired();
 
  const ResourceAccessMap& lockedResources() const { return this->m_lockedResources; }
 
  virtual Result operateInternal() = 0;
 
  // Apply post-processing to the result object. This method should not modify
  // the modeling kernel but may change string/float/int properties stored on
  // entities.
  virtual void postProcessResult(Result&) {}
 
  // Mark resources as dirty or clean according to their use in the operation.
  // By default, all resources used as inputs with Write LockTypes and all
  // resources referenced in the result are marked dirty.
  virtual void markModifiedResources(Result&);
 
  // Remove resources from the resource manager.
  virtual bool unmanageResources(Result&);
 
  // Append an output summary string to the output result. Derived classes can
  // reimplement this method to send custom summary strings to the logger.
  virtual void generateSummary(Result&);
 
  // Construct the operation's base specification. This is done by reading
  // an attribute .sbt file.
  Specification createBaseSpecification() const;
 
  int m_debugLevel{ 0 };
  std::weak_ptr<Manager> m_manager;
  std::shared_ptr<smtk::common::Managers> m_managers;
 
  struct BaseKey
  {
    BaseKey() = default;
    BaseKey(
      const Operation* parent,
      ObserverOption observerOption,
      LockOption lockOption,
      ParametersOption paramsOption)
      : m_parent(parent)
      , m_lockOption(lockOption)
      , m_observerOption(observerOption)
      , m_paramsOption(paramsOption)
    {
    }
 
    const Operation* m_parent{ nullptr };
    LockOption m_lockOption{ LockOption::SkipLocks };
    ObserverOption m_observerOption{ ObserverOption::SkipObservers };
    ParametersOption m_paramsOption{ ParametersOption::SkipValidation };
  };
 
  struct SMTK_DEPRECATED_IN_24_11(
    "Use this->childKey(ObserverOption::SkipObservers, LockOption::SkipLocks, "
    "ParametersOption::SkipValidation) instead.") Key : BaseKey
  {
    Key() = default;
  };
 
  BaseKey childKey(
    ObserverOption observerOption = ObserverOption::SkipObservers,
    LockOption lockOption = LockOption::LockAll,
    ParametersOption paramsOption = ParametersOption::Validate) const;
 
public:
  Result operate(const BaseKey& key);
 
private:
  // Construct the operation's specification. This is typically done by reading
  // an attribute .sbt file, but can be done by first constructing a base
  // specification and then augmenting the specification to include the derived
  // operation's input and output attributes.
  virtual Specification createSpecification() = 0;
 
  void unlockResources(const ResourceAccessMap& resources);
 
  Specification m_specification;
  Parameters m_parameters;
  Definition m_resultDefinition;
  std::vector<std::weak_ptr<smtk::attribute::Attribute>> m_results;
  ResourceAccessMap m_lockedResources;
};
 
SMTKCORE_EXPORT Operation::Outcome outcome(const Operation::Result& result);
SMTKCORE_EXPORT bool setOutcome(const Operation::Result& result, Operation::Outcome outcome);
 
} // namespace operation
} // namespace smtk
 
#endif // smtk_operation_Operation_h