SMTK  @SMTK_VERSION@
Simulation Modeling Tool Kit
Operation.h
1 //=========================================================================
2 // Copyright (c) Kitware, Inc.
3 // All rights reserved.
4 // See LICENSE.txt for details.
5 //
6 // This software is distributed WITHOUT ANY WARRANTY; without even
7 // the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
8 // PURPOSE. See the above copyright notice for more information.
9 //=========================================================================
10 #ifndef smtk_operation_Operation_h
11 #define smtk_operation_Operation_h
12 
13 #include "smtk/CoreExports.h"
14 #include "smtk/PublicPointerDefs.h"
15 #include "smtk/SharedFromThis.h"
16 
17 #include <string>
18 #include <typeindex>
19 #include <utility>
20 
21 namespace smtk
22 {
23 namespace attribute
24 {
25 class Attribute;
26 class Resource;
27 } // namespace attribute
28 namespace io
29 {
30 class Logger;
31 }
32 namespace operation
33 {
34 class ImportPythonOperation;
35 class Manager;
36 
47 class SMTKCORE_EXPORT Operation : smtkEnableSharedPtr(Operation)
48 {
49 public:
51 
52  // A hash value uniquely representing the operation.
53  typedef std::size_t Index;
54 
55  // An attribute describing the operation's input.
56  typedef std::shared_ptr<smtk::attribute::Attribute> Parameters;
57 
58  // An attribute containing the operation's result.
59  typedef std::shared_ptr<smtk::attribute::Attribute> Result;
60 
61  // An attribute resource containing the operation's execution definition
62  // result definition.
63  typedef std::shared_ptr<smtk::attribute::Resource> Specification;
64 
65  typedef std::shared_ptr<smtk::attribute::Definition> Definition;
66 
67  // These values are taken on by the "outcome" item of every Operation Result.
68  enum class Outcome
69  {
70  UNABLE_TO_OPERATE,
71  CANCELED,
72  FAILED,
73  SUCCEEDED,
74  UNKNOWN = -1
75  };
76 
77  friend Manager;
78  friend ImportPythonOperation;
79 
80  virtual ~Operation();
81 
82  // Index is a compile-time intrinsic of the derived operation; as such, it
83  // cannot be set. It is virtual so that derived operations can assign their
84  // own index (as is necessary for python operations that would otherwise all
85  // resolve to the same index).
86  virtual Index index() const { return std::type_index(typeid(*this)).hash_code(); }
87 
110  virtual bool configure(
112  const smtk::attribute::ItemPtr& changedItem = smtk::attribute::ItemPtr());
113 
117  virtual bool ableToOperate();
118 
121  Result operate();
122 
126  virtual smtk::io::Logger& log() const;
127 
132  Specification specification();
133 
137  Parameters parameters();
138  Parameters parameters() const;
139 
142  Result createResult(Outcome);
143 
145  ManagerPtr manager() const { return m_manager.lock(); }
146 
148  bool restoreTrace(const std::string& trace);
149 
151  void setManagers(const std::shared_ptr<smtk::common::Managers>& m) { m_managers = m; }
152  std::shared_ptr<smtk::common::Managers> managers() const { return m_managers; }
153 
155  virtual bool threadSafe() const { return true; }
156 
158  smtk::resource::ManagerPtr resourceManager();
159 
160 protected:
161  Operation();
162 
163  // Perform the actual operation and construct the result.
164  virtual Result operateInternal() = 0;
165 
166  // Apply post-processing to the result object. This method should not modify
167  // the modeling kernel but may change string/float/int properties stored on
168  // entities.
169  virtual void postProcessResult(Result&) {}
170 
171  // Mark resources as dirty or clean according to their use in the operation.
172  // By default, all resources used as inputs with Write LockTypes and all
173  // resources referenced in the result are marked dirty.
174  virtual void markModifiedResources(Result&);
175 
176  // Remove resources from the resource manager.
177  virtual bool unmanageResources(Result&);
178 
179  // Append an output summary string to the output result. Derived classes can
180  // reimplement this method to send custom summary strings to the logger.
181  virtual void generateSummary(Result&);
182 
183  // Construct the operation's base specification. This is done by reading
184  // an attribute .sbt file.
185  Specification createBaseSpecification() const;
186 
187  int m_debugLevel{ 0 };
188  std::weak_ptr<Manager> m_manager;
189  std::shared_ptr<smtk::common::Managers> m_managers;
190 
191  // Operations need the ability to execute Operations without going through
192  // all of the checks and locks associated with the public operate() method.
193  // We therefore use a variant of the PassKey pattern to grant Operation
194  // and all of its children access to another operator's operateInternal()
195  // method. It is up to the writer of the outer Operation to ensure that
196  // Resources are accessed with appropriate lock types and that Operations
197  // called in this manner have valid inputs.
198  struct Key
199  {
200  explicit Key() = default;
201  Key(std::initializer_list<int>) {}
202  };
203 
204 public:
205  Result operate(Key) { return operateInternal(); }
206 
207 private:
208  // Construct the operation's specification. This is typically done by reading
209  // an attribute .sbt file, but can be done by first constructing a base
210  // specification and then augmenting the specification to include the derived
211  // operation's input and output attributes.
212  virtual Specification createSpecification() = 0;
213 
214  Specification m_specification;
215  Parameters m_parameters;
216  Definition m_resultDefinition;
217  std::vector<std::weak_ptr<smtk::attribute::Attribute>> m_results;
218 };
219 } // namespace operation
220 } // namespace smtk
221 
222 #endif // smtk_operation_Operation_h
smtk
The main namespace for the Simulation Modeling Tool Kit (SMTK).
Definition: doc.h:33
PublicPointerDefs.h
smtk::operation::Manager
An operation Manager is responsible for creating new operations and filtering operations based on inp...
Definition: Manager.h:42
smtk::operation::Operation::Outcome
Outcome
Definition: Operation.h:68
smtk::operation::ImportPythonOperation
A class for adding python operations to the current session.
Definition: ImportPythonOperation.h:27
smtk::io::Logger
Log messages for later presentation to a user or a file.
Definition: Logger.h:95
smtkEnableSharedPtr
#define smtkEnableSharedPtr(...)
An abbreviation for enabling shared pointers.
Definition: SharedFromThis.h:154
smtk::operation::ManagerPtr
smtk::shared_ptr< smtk::operation::Manager > ManagerPtr
Definition: PublicPointerDefs.h:348
smtk::operation::Operation
Operation is a base class for all SMTK operations.
Definition: Operation.h:47
smtk::attribute::AttributePtr
smtk::shared_ptr< smtk::attribute::Attribute > AttributePtr
Definition: PublicPointerDefs.h:456
smtk::operation::Operation::Key
Definition: Operation.h:198
smtk::plugin::Manager
smtk::common::Singleton< detail::Manager > Manager
The Manager is a singleton interface for registering available plugins to manager instances.
Definition: Manager.h:92
smtk::operation::Operation::setManagers
void setManagers(const std::shared_ptr< smtk::common::Managers > &m)
Operations may be passed application state in the form of a Managers type-container.
Definition: Operation.h:151
smtk::operation::Operation::manager
ManagerPtr manager() const
Operations that are managed have a non-null pointer to their manager.
Definition: Operation.h:145
smtk::attribute::ItemPtr
smtk::shared_ptr< smtk::attribute::Item > ItemPtr
Definition: PublicPointerDefs.h:467
SharedFromThis.h
Macros for dealing with shared-pointer classes.
smtkTypeMacroBase
#define smtkTypeMacroBase(...)
Add typedefs to a class for identifcation.
Definition: SharedFromThis.h:55
smtk::resource::ManagerPtr
smtk::shared_ptr< smtk::resource::Manager > ManagerPtr
Definition: PublicPointerDefs.h:281
smtk::operation::Operation::threadSafe
virtual bool threadSafe() const
Is this type of operation safe to launch in a thread?
Definition: Operation.h:155