SMTK  @SMTK_VERSION@
Simulation Modeling Tool Kit
Classes | Public Types | Public Member Functions | Public Attributes | Protected Types | Protected Member Functions | Protected Attributes | Friends | List of all members
smtk::operation::Operation Class Referenceabstract

Operation is a base class for all SMTK operations. More...

#include <Operation.h>

Inheritance diagram for smtk::operation::Operation:
[legend]
Collaboration diagram for smtk::operation::Operation:
[legend]

Classes

struct  Key
 

Public Types

enum  Outcome {
  Outcome::UNABLE_TO_OPERATE, Outcome::CANCELED, Outcome::FAILED, Outcome::SUCCEEDED,
  Outcome::UNKNOWN = -1
}
 
typedef std::size_t Index
 
typedef std::shared_ptr< smtk::attribute::AttributeParameters
 
typedef std::shared_ptr< smtk::attribute::AttributeResult
 
typedef std::shared_ptr< smtk::attribute::ResourceSpecification
 
typedef std::shared_ptr< smtk::attribute::DefinitionDefinition
 

Public Member Functions

 smtkTypeMacroBase (smtk::operation::Operation)
 
virtual Index index () const
 
virtual bool configure (const smtk::attribute::AttributePtr &changedAttribute=smtk::attribute::AttributePtr(), const smtk::attribute::ItemPtr &changedItem=smtk::attribute::ItemPtr())
 Update the operation's specification and operations to be consistent. More...
 
virtual bool ableToOperate ()
 Check if the operation's attribute resource is valid. More...
 
Result operate ()
 Execute the operation, log its outcome and return its results. More...
 
Outcome safeOperate ()
 Execute the operation in an asynchronous environment. More...
 
Outcome safeOperate (Handler handler)
 
virtual bool releaseResult (Result &result)
 Release the operation result returned by operate(). More...
 
virtual smtk::io::Loggerlog () const
 Retrieve the operation's logger. More...
 
Specification specification ()
 This accessor facilitates the lazy construction of the specification, allowing for derived implementations of its creation. More...
 
Parameters parameters ()
 Access the operation's input parameters, constructing them if necessary. More...
 
Parameters parameters () const
 
Result createResult (Outcome)
 Create an attribute representing this operation's result type. More...
 
ManagerPtr manager () const
 Operations that are managed have a non-null pointer to their manager.
 
bool restoreTrace (const std::string &trace)
 restore operation parameters from the trace of a previously run operation.
 
void setManagers (const std::shared_ptr< smtk::common::Managers > &m)
 Operations may be passed application state in the form of a Managers type-container.
 
std::shared_ptr< smtk::common::Managersmanagers () const
 
virtual bool threadSafe () const
 Is this type of operation safe to launch in a thread?
 
smtk::resource::ManagerPtr resourceManager ()
 retrieve the resource manager, if available.
 
Result operate (const BaseKey &key)
 

Public Attributes

friend Manager
 
friend ImportPythonOperation
 

Protected Types

enum  LockOption { LockAll, ParentLocksOnly, SkipLocks }
 
enum  ObserverOption { InvokeObservers, SkipObservers }
 
enum  ParametersOption { Validate, SkipValidation }
 

Protected Member Functions

virtual ResourceAccessMap identifyLocksRequired ()
 Identify resources to lock, and whether to lock them for reading or writing. More...
 
const ResourceAccessMaplockedResources () const
 Returns the set of resources that are currently locked by this operation.
 
virtual Result operateInternal ()=0
 Perform the actual operation and construct the result.
 
virtual void postProcessResult (Result &)
 
virtual void markModifiedResources (Result &)
 
virtual bool unmanageResources (Result &)
 
virtual void generateSummary (Result &)
 
Specification createBaseSpecification () const
 
BaseKey childKey (ObserverOption observerOption=ObserverOption::SkipObservers, LockOption lockOption=LockOption::LockAll, ParametersOption paramsOption=ParametersOption::Validate) const
 

Protected Attributes

int m_debugLevel { 0 }
 
std::weak_ptr< Managerm_manager
 
std::shared_ptr< smtk::common::Managersm_managers
 

Friends

class Helper
 

Detailed Description

Operation is a base class for all SMTK operations.

SMTK operations are essentially functors that operate on SMTK resources and resource components. Their input parameters and output results are described by an SMTK attribute resource that is constructed in derived operation classes via the method createSpecification(). There should be exactly one attribute definition that derives from "operation" and one definition that derives from "result". The creation, destruction and manipulation of SMTK resources and components occurs in the method operateInternal(). Operations are designed to work in conjunction with an smtk::operation::Manager, but can also be used as standalone functors.

Member Enumeration Documentation

◆ Outcome

Enumerator
UNABLE_TO_OPERATE 

The operation is misconfigured.

CANCELED 

An observer requested the operation be canceled. And it was.

FAILED 

The operation attempted to execute but encountered a problem.

SUCCEEDED 

The operation succeeded.

UNKNOWN 

The operation has not been run or the outcome is uninitialized.

Member Function Documentation

◆ ableToOperate()

bool smtk::operation::Operation::ableToOperate ( )
virtual

◆ configure()

bool smtk::operation::Operation::configure ( const smtk::attribute::AttributePtr changedAttribute = smtk::attribute::AttributePtr(),
const smtk::attribute::ItemPtr changedItem = smtk::attribute::ItemPtr() 
)
virtual

Update the operation's specification and operations to be consistent.

This does nothing by default but subclasses may override this method to update default values (say, based on the current set of associations). This method should be called by user interfaces when the associations (and potentially other attributes/items in the specification) are modified.

By default, the attribute and item passed are null. If values are passed, the attribute or item must belong to the resource for the operation itself, and should indicate changes made by the user. When an attribute is created or removed at the user's behest it is passed. When an item's value(s) are directly edited by a user, then a pointer to it is passed. Only one value (the item or the attribute) should be non-null for a given invocation of configure(). Both may be null (for instance, when an operation is being asked to initialize its parameters based on the global application state rather than a particular user input).

This method should return true if any changes were made to the operation's specification and false otherwise.

Reimplemented in smtk::session::oscillator::EditSource.

◆ createResult()

Operation::Result smtk::operation::Operation::createResult ( Outcome  outcome)

Create an attribute representing this operation's result type.

The result attribute is distinguished by its derivation from the "result" attribute.

◆ identifyLocksRequired()

ResourceAccessMap smtk::operation::Operation::identifyLocksRequired ( )
protectedvirtual

Identify resources to lock, and whether to lock them for reading or writing.

The default implementation simply calls extractResourceAndLockTypes() on the operation's parameters.

◆ log()

smtk::io::Logger & smtk::operation::Operation::log ( ) const
virtual

Retrieve the operation's logger.

By default, we use the singleton logger. Derived classes can reimplement this method if an alternative logging system is needed.

◆ operate()

Operation::Result smtk::operation::Operation::operate ( )

Execute the operation, log its outcome and return its results.

This method calls operateInternal() and handles additional bookkeeping.

◆ parameters()

Operation::Parameters smtk::operation::Operation::parameters ( )

Access the operation's input parameters, constructing them if necessary.

The parameters attribute is distinguished by its derivation from the "operation" attribute.

◆ releaseResult()

bool smtk::operation::Operation::releaseResult ( Result &  result)
virtual

Release the operation result returned by operate().

Note that if you do not release the result, it will eventually be released when the operation itself is destroyed.

This removes the Result (an smtk::attribute::Attribute) from the operation's resource; anyone holding the shared pointer to the result will keep the attribute in memory but will experience inconsistent behavior since its items are removed as part of releasing it from control by the attribute::Resource.

◆ safeOperate()

Operation::Outcome smtk::operation::Operation::safeOperate ( )

Execute the operation in an asynchronous environment.

This method does not return until the operation is complete, but because it does not return a result, only observers can process the operation. This prevents simultaneous, unguarded access to results as observers are invoked before resource locks are released.

If you pass a handler to safeOperate, it will be invoked after other observers have run but before resource locks have been released (thus preventing deadlocks or unguarded access to the result).

Unlike Operation::operate(), this method removes its Result from the specification before returning.

This method will eventually replace Operation::operate().

◆ specification()

Operation::Specification smtk::operation::Operation::specification ( )

This accessor facilitates the lazy construction of the specification, allowing for derived implementations of its creation.

More sophisticated operations may contain additional attributes as input parameters; they can be accessed through the specification.


The documentation for this class was generated from the following files: