All workspace operations must derive from this class. More...

#include <Workspace/DataExecution/Operations/operation.h>

Inheritance diagram for Operation:

Classes
struct	IOBaseAccessor

struct	IOBaseAccessor< Input, IsConst >

struct	IOBaseAccessor< Output, IsConst >

class	IOBaseIteratorRange
	begin/end range for Input/Output iterators. Needed because Operations supply a range of both inputs and outputs. More...

Public Types
enum	ConfigStatus { GoodConfig = 0x00 , UnknownConfig = 0x01 , InvalidConfig = 0x02 }

using	difference_type = ptrdiff_t

enum	GraphicsSize { Default = 100 , Small = 65 }
	Options for the graphical size of an operation, able to be changed by derived classes. Values are percentages. More...

enum	IndexCountingOption { SkipNone = 0x0 , SkipInvisible = 0x1 , SkipDependencies = 0x2 }

using	size_type = size_t

Public Member Functions
	~Operation () override

bool	addInput (Input &input, bool modifiedInPlace=false)

bool	addOutput (Output &output)

template<typename T >
bool	assignInput (const QString &inputName, const T &value)

bool	canSerialize () const override

bool	connectProgressEvents (QProgressBar *progressBar)

virtual Presentation::CustomOperationProperties *	createCustomPropertiesHandler ()

virtual void	ensureHasData ()

bool	getBroadcastUpdateEvents () const

QColor	getColor () const

virtual QString	getDefaultIconPath () const

QString	getDefaultUiPath () const

QString	getDeprecationMessage () const

const QString &	getDescription () const

SerializedItem	getExtras ()

const OperationFactory &	getFactory () const

Operation *	getFromPath (const QString &path, Workspace &relativeTo, QStringList &errors) const override

virtual GraphicsSize	getGraphicsSize () const

virtual QString	getHelpPage () const

QString	getIconPath () const

const QUuid &	getId () const

QString	getIdPath (bool scoped=true) const override

QString	getIdPath (const Workspace &relativeTo) const

difference_type	getIndex (const Input &input, IndexCountingOptions options=SkipNone) const

difference_type	getIndex (const Output &output, IndexCountingOptions options=SkipNone) const

void	getIndexPair (InputScalar &input, difference_type &mainIndex, difference_type &arrayIndex)

Input *	getInput (const QString &name)

const Input *	getInput (const QString &name) const

Input *	getInput (size_type index)

const Input *	getInput (size_type index) const

InputArray *	getInputArray (const QString &name)

const InputArray *	getInputArray (const QString &name) const

IOBaseIteratorRange< Input, false >	getInputs ()

IOBaseIteratorRange< Input, true >	getInputs () const

InputScalar *	getInputScalar (const QString &name)

const InputScalar *	getInputScalar (const QString &name) const

template<typename T >
T &	getInputValue (const QString &inputName)

template<typename T >
const T &	getInputValue (const QString &inputName) const

const QString &	getLabel () const

QString	getLabelRelativeToRoot () const

Output *	getOutput (const QString &name)

const Output *	getOutput (const QString &name) const

Output *	getOutput (size_type index)

const Output *	getOutput (size_type index) const

IOBaseIteratorRange< Output, false >	getOutputs ()

IOBaseIteratorRange< Output, true >	getOutputs () const

template<typename T >
T &	getOutputValue (const QString &outputName)

template<typename T >
const T &	getOutputValue (const QString &outputName) const

bool	getProfilingEnabled () const

int	getProgress () const

int	getProgressContribution () const

bool	getProgressResetByNotUpToDate () const

virtual SchedulerFeatures	getRequiredSchedulerFeatures () const

InputScalar *	getScalarInput (size_type mainIndex, difference_type arrayIndex)

QString	getShortLabel () const

QString	getTagName () const

bool	getTerminateExecution () const

QString	getUiPath () const

bool	getUpToDate () const override

virtual bool	hasRequiredSchedulerFeatures () const

void	idPathChanged () override

virtual bool	inputRebuilt (InputScalar &input)

virtual bool	isAsynchronous () const

virtual bool	isAtomicUpdate () const

bool	isConnectedToAsynchronous () const override

bool	isDeprecated () const

bool	isEditable () const

bool	isIdPathCachingEnabled () const

virtual bool	isPolymorphicType () const

virtual bool	isRunningAsynchronously () const

virtual bool	isThreadSafe () const

template<typename T >
bool	isType () const

bool	isType (const OperationFactory &type) const

bool	isUpdating () const

virtual bool	isUserConfigurable ()

bool	isUsingDefaultColor () const

bool	isUsingDefaultIconPath () const

bool	isUsingDefaultUiPath () const

bool	isWaitingForAsynchronousUpdate () const override

bool	isWorkspaceType () const

bool	load (const SerializedItem &item) override

void	markUpToDateWhereSafe ()

bool	matchesType (const Operation &otherOperation) const

size_type	numInputs (IndexCountingOptions=SkipNone) const

size_type	numOutputs (IndexCountingOptions=SkipNone) const

bool	removeInput (const QString &name)

bool	removeInput (Input &input)

bool	removeOutput (const QString &name)

bool	removeOutput (Output &output)

virtual void	resetExecutionDependencies ()

bool	save (SerializedItem &item) const override

virtual bool	saveWithData (SerializedItem &item) const

virtual void	setAtomicUpdate (bool atomic)

void	setBroadcastUpdateEvents (bool enable)

void	setColor (const QColor &c)

void	setDescription (const QString &description)

void	setEditable (bool b)

void	setIconPath (const QString &path)

void	setId (const QUuid &id)

virtual void	setIdPathCachingEnabled (bool b)

virtual void	setInputNotUpToDate (InputScalar &input)

virtual void	setIsAsynchronous (bool asynchronous)

virtual void	setIsRunningAsynchronously (bool asynchronous)

void	setLabel (const QString &label)

virtual void	setOutputNotUpToDate (Output &output)

void	setProfilingEnabled (bool enable)

virtual void	setProgress (int percent)

void	setProgressContribution (int percent)

void	setProgressResetByNotUpToDate (bool b)

virtual void	setRequiredSchedulerFeatures (const SchedulerFeatures &)

void	setTerminateExecution (bool b)

void	setUiPath (const QString &path)

void	setUpToDate (bool b) override

bool	update (Updater *updater=nullptr) override

Public Member Functions inherited from WorkspaceElement
	~WorkspaceElement () override

const Workspace *	getWorkspace () const override

Workspace *	getWorkspace () override

virtual void	workspaceChanged (Workspace *oldWorkspace)

Public Member Functions inherited from Updatable
	~Updatable () override

virtual bool	comesFromExternal () const

QString	getEnclosingScope () const

virtual Updatable *	getFromPath (const QString &path, Workspace &relativeTo, QStringList &errors) const =0

const QString &	getGlobalName () const

virtual QString	getIdPath (bool scoped=true) const =0

virtual Workspace *	getRootWorkspace ()

virtual const Workspace *	getRootWorkspace () const

QString	getScopedGlobalName () const

virtual bool	getUpToDate () const =0

virtual const Workspace *	getWorkspace () const =0

virtual Workspace *	getWorkspace ()=0

virtual void	idPathChanged ()

virtual bool	isConnectedToAsynchronous () const =0

virtual bool	isWaitingForAsynchronousUpdate () const =0

void	setGlobalName (const QString &name)

virtual void	setUpToDate (bool b)=0

virtual bool	update (Updater *updater=nullptr)=0

Public Member Functions inherited from Observable
virtual	~Observable ()

void	attachObserver (Observer &observer)

void	destroy ()

void	detachObserver (Observer &observer)

void	notifyEvent (const ObservableEvent &event)

Public Member Functions inherited from Serialize
virtual	~Serialize ()=default

virtual bool	canSerialize () const =0

virtual bool	load (const SerializedItem &item)=0

virtual bool	save (SerializedItem &item) const =0

Public Member Functions inherited from TextLogger
	TextLogger ()

	TextLogger (const DataExecution::IOBase &io)

	TextLogger (const DataExecution::Operation &operation)

	TextLogger (const TextLogger &logger)

	TextLogger (TextLogger &&logger)

virtual	~TextLogger ()

void	logLine (const Application::LogManager::MessageCategory &category, const QString &msg) const

void	logLine (const QString &msg) const

void	logText (const Application::LogManager::MessageCategory &category, const QString &msg) const

void	logText (const QString &msg) const

TextLogger &	operator= (TextLogger)

Protected Member Functions
	Operation (const OperationFactory &factory, const QString &label)

bool	bringArrayOfInputsUpToDate (Input *&array, size_type arraySize)

bool	bringArrayOfInputsUpToDate (std::vector< Input * > &array)

virtual bool	bringInputsUpToDate ()

bool	bringInputUpToDate (Input &input)

virtual void	cancelExecution (bool b)

virtual bool	execute ()=0

virtual bool	finishInputsOutputsAfterLoad (const SerializedItem &item)

Updater *	getCurrentUpdater ()

virtual const Input *	getRenamedInput (const QString &name) const

virtual const Output *	getRenamedOutput (const QString &name) const

virtual bool	inputsAreUpToDate () const

virtual bool	makeOutputsValid ()

virtual void	markOutputsUpToDate ()

void	pauseUpdate ()

virtual bool	postSave (SerializedItem &item) const

virtual bool	prepareInputsOutputsForLoad (const SerializedItem &item)

void	saveExtras (SerializedItem &item) const

virtual bool	shouldPutInExtras (const QString &tagName) const

Protected Member Functions inherited from WorkspaceElement
	WorkspaceElement ()

Protected Member Functions inherited from Updatable
	Updatable ()

	Updatable (const Updatable &up)

void	notifyUpdated ()

Updatable &	operator= (const Updatable &up)

Protected Member Functions inherited from Observable
	Observable ()

	Observable (const Observable &)

Additional Inherited Members
Static Public Member Functions inherited from Updatable
static InputScalar *	findInputScalarGlobalName (const QString &scopedGlobalName, Workspace &relativeTo)

static IOBase *	findIOBaseGlobalName (const QString &scopedGlobalName, Workspace &relativeTo)

static Operation *	findOperationGlobalName (const QString &scopedGlobalName, Workspace &relativeTo)

Detailed Description

Subclasses must, at a minimum, override the execute() function. They will usually set up their inputs and outputs in their constructor and not add or remove any more thereafter.

For many operations, this is all that is needed. The serialization of the operation and all its inputs is fully automated, and handling the up-to-date status dependencies between inputs and outputs is also implemented by the Operation class. Therefore, subclasses should just be able to concentrate on implementing the specific functionality it provides.

Over time, it is possible that subclass implementors may wish to rename an input or an output. This can be done in a backwards compatible way by implementing the getRenamedInput() and getRenamedOutput() functions.

Warning: Once an Operation is added to a workspace, it should never be removed from it except when the Operation is being deleted. It is not allowable to "re-parent" an Operation into a different Workspace or to make it an orphan once it has been placed in a Workspace. This is required in order to make handling of inputs, outputs and execution threads work efficiently and robustly when things like widgets are associated with any of these.

Member Typedef Documentation

◆ difference_type

using difference_type = ptrdiff_t

◆ size_type

using size_type = size_t

Member Enumeration Documentation

◆ ConfigStatus

enum ConfigStatus

Enumerator
GoodConfig
UnknownConfig
InvalidConfig

◆ GraphicsSize

enum GraphicsSize

Enumerator
Default
Small

◆ IndexCountingOption

enum IndexCountingOption

Enumerator
SkipNone
SkipInvisible
SkipDependencies

Constructor & Destructor Documentation

◆ ~Operation()

~Operation ( )

override

Clean up private implementation.

◆ Operation()

Operation	(	const OperationFactory &	factory,
		const QString &	label
	)

protected

Parameters

factory	The operation factory responsible for creating and destroying operations of this type.
label	The label for this operation. Labels can be changed with the setLabel function, but operations should always be created with a default label.

Operations should generally add all their inputs and outputs in their constructors. Implementers of Operation subclasses should think of inputs and outputs as static properties of an operation. Only special kinds of operations would generally add or remove inputs or outputs dynamically (such as a workspace operation).

The label of an operation is only informational. There is no requirement that a label be unique, nor is it used for anything other than user information. A typical use of an operation's label is to display it in the GUI view of a workspace.

Member Function Documentation

◆ addInput()

bool addInput	(	Input &	input,
		bool	modifiedInPlace = `false`
	)

Parameters

input The input to add to the operation.

modifiedInPlace If the operation will modify the data held by this input, then modifiedInPlace must be set to true. This allows the operation to ensure that when the operation is marked as no longer up to date, the input is also marked not up to date. This ensures that the data on the input is provided by its source again. For most inputs, modifiedInPlace will be false. Only if the input can be modified directly should this parameter be set to true or else unnecessary workspace updates will be triggered and potentially slow down performance.

Returns: True if the input could be added. It will only return false if an input with the same name already exists (more accurately, the name with spaces converted to underscores).

Note that the Operation does not take ownership of input, since the caller will almost certainly want to retain its own reference to the input object so it can retrieve the input's value when needed. It will, however, associate input with this operation by calling its setOperation function.

Clients would not normally need to call this function directly. The constructors for InputScalar and InputArray already do this for you.

◆ addOutput()

bool addOutput ( Output & output )

Parameters

output The output to add to the operation.

Returns: True if the output could be added. It will only return false if an output with the same name already exists (more accurately, the name with spaces converted to underscores).

Note that the Operation does not take ownership of output, since the caller will almost certainly want to retain its own reference to the output object so it can set or retrieve the output's value when needed. It will, however, associate output with this operation by calling its setOperation function.

◆ assignInput()

bool assignInput	(	const QString &	inputName,
		const T &	value
	)

inline

Parameters

inputName	The name of the scalar input to assign to.
value	The value to assign to the specified input. The underlying type of value must support the assignment operator or else the code will not compile.

This is a convenience function. It allows callers to set the value of an operation's input as long as the input's underlying type has an assignment operator. Checks are performed to ensure that the type of the value supplied matches the underlying type of the input. If the input's data object does not have any data at the time of the call, it will have data created by this function. Thus, it does not matter if the input does not yet have data when using this function.

Returns: True if the assignment was successful. If the function returns false, then either the operation has no input by the name given in inputName, or the data type of the value supplied does not match the underlying type of the input.

Note: This function should really only be used if you can guarantee that your own code is compiled with the exact same compiler and compiler flags as the plugin library that supplies the data type of value. It is primarily aimed at use within test code.

See also: InputScalar::assign()

◆ bringArrayOfInputsUpToDate() [1/2]

bool bringArrayOfInputsUpToDate	(	Input *&	array,
		size_type	arraySize
	)

protected

Parameters

array	An array of (pointers to) inputs to bring up to date.
arraySize	The number of items in the array

This function is responsible for bringing all inputs in the specified array up to date. All subclasses which override bringInputsUpToDate() should call this function when they want to update more than one input, since this function may handle automatic multi-threading in a future implementation. For the best performance, as many of the required inputs as possible should be included in a single array rather than making repeated calls to it with smaller arrays.

Note: There is no guarantee as to the order in which the inputs will be brought up to date. Clients should not rely on them being updated in the order in which they occur in the specified array. If order is important, split the array up across multiple calls to this function (eg you can just make calls for different ranges within the same array).

Returns: True if all inputs in the specified array were able to be brought up to date.

See also: bringInputsUpToDate(), bringInputUpToDate()

◆ bringArrayOfInputsUpToDate() [2/2]

bool bringArrayOfInputsUpToDate ( std::vector< Input * > & array )

inlineprotected

◆ bringInputsUpToDate()

bool bringInputsUpToDate ( )

protectedvirtual

This function is responsible for first bringing the dependency input up to date, then determining all the inputs required to update the operation's outputs and bring those inputs up to date as well.

The default implementation assumes all inputs need to be brought up to date, but some operations may only require some of the inputs to be up to date in order to calculate the outputs. Indeed, some of the inputs may need to be up to date, their values checked and then some combination of the rest brought up to date. An example where this could be useful is where an operation should behave differently for different iterations of a loop.

Subclasses which choose to override this function should call the other overloaded version of this function as necessary to actually bring the inputs it needs up to date, since it will handle multi-threading in a future implementation. It must update the dependency input first on its own before anything else.

Returns: True if required inputs were able to be brought up to date.

See also: update(), execute(), bringInputUpToDate(), bringArrayOfInputsUpToDate()

◆ bringInputUpToDate()

bool bringInputUpToDate ( Input & input )

protected

Parameters

input A single input to bring up to date.

Subclasses can call this function if they only need to update a single input but they are better off calling bringArrayOfInputsUpToDate() if more than one input needs updating. Note, however, that bringInputUpToDate() must be called directly or indirectly when an input is updated as part of a call to update(). This is so that update() can ensure that previously updated inputs don't become not up to date while other inputs are being brought up to date. This situation is most commonly observed when widgets are interacting with a workspace while it is running and some input updates are time consuming.

Returns: True if the input was successfully brought up to date.

See also: bringArrayOfInputsUpToDate()

◆ cancelExecution()

void cancelExecution ( bool b )

protectedvirtual

Parameters

b If true, then execution should be cancelled. If false, the function should reset any internal data from a previous reset. A false parameter must be passed to this function at some point after a cancelled execution so that subclasses have a chance to reset any internal data used to implement the last cancellation.

It is not compulsory for operations to support a specific cancel event. They can choose to do nothing in this function (which is the default implementation) or they can override this function to take some action to enact the cancellation during execution. If the function does nothing, then the operation will finish any currently running call to update(), but any subsequent calls to update() will fail. This is controlled by the workspace execution system and need not be implemented in subclasses.

If the cancellation might take some time to happen, then something should be done to indicate to the currently running update() and cancelExecution() should then return immediately without waiting for the cancellation to finish. In other words, cancelExecution() should "schedule" the cancellation rather than block waiting for it to happen.

Subclass implementors should note that the call to cancelExecution() is very likely to come from a different thread, so special care needs to be taken to avoid race conditions. It should also be noted that this function may be called when an operation is not actually executing, in which case it should do nothing.

See also: setTerminateExecution()

Reimplemented in AnimateDataSeriesChange, IgesReaderOperation, NastranReaderOperation, StlReaderOperation, ScheduleWorkflow, and Workspace.

◆ canSerialize()

bool canSerialize ( ) const

overridevirtual

Returns: True if this object can be serialized.

For objects that can be serialized, the save and load functions will be used to do the serialization. If this function returns false, both load() and save() must also return false.

Implements Serialize.

◆ connectProgressEvents()

bool connectProgressEvents ( QProgressBar * progressBar )

◆ createCustomPropertiesHandler()

Presentation::CustomOperationProperties * createCustomPropertiesHandler ( )

virtual

Returns: An object that can be used to add custom properties to a dialog and to create undoable commands to apply changes to those custom properties. If the operation has no custom properties, a null pointer will be returned Since most operations won't have custom properties, the default implementation simply returns a null pointer.

Reimplemented in CreateChart, CreateChartObjectDictionary, RunMatLabScript, RunPythonScript, SceneItemLibraryBuilder, ShaderLibraryBuilder, CreateObjectDictionary, DecomposeObjectDictionary, FilePathBuilder, ModifyGroup, ModifyObjectDictionary, PolymorphicDataOperation, RunQtScript, FormatString, TreeSelectionBuilder, Workspace, and CustomInputsOutputsOperation.

◆ ensureHasData()

void ensureHasData ( )

virtual

This function is for convenience only. Its purpose is to ensure that all the inputs to the operation have valid data objects. This can be useful, for example, just before saving the workspace to which the operation belongs, since it would ensure that values are saved for each input. If there is no valid data object, no value is saved for an input. Subclasses are permitted to override this function if they need to do specialised processing, but this would not normally be necessary. If they do, they must obey the post condition.

Postcondition: All operation inputs that are not connected to something will have valid data objects. If they have internal Operation objects (eg such as for Workspace objects), those operation's inputs should also have valid data objects. This pattern is recursive, such that all Operations nested to any level must have valid data objects at the completion of this call.

Reimplemented in Workspace.

◆ execute()

virtual bool execute ( )

protectedpure virtual

Subclasses need to implement this function to do the actual processing of the operation. Clients should not call this function directly, but should instead call the update() function, since it ensures all inputs are updated first and all outputs have setUpToDate called on each one.

Precondition: When called, this function can assume that all of its required inputs have already been brought up to date.

Postcondition: When this function exits, all of the operation's outputs need to have had their values set. It is not required that setUpToDate be called for each output, since this is done by the update() function after execute() returns.

Returns: True if the operation was able to execute successfully.

◆ finishInputsOutputsAfterLoad()

bool finishInputsOutputsAfterLoad ( const SerializedItem & item )

protectedvirtual

Parameters

item	The serialized item that will be loaded.

This function is called just before load() returns (if no errors were encountered during loading). The default implementation simply returns true to indicate that loading completed successfully. Subclasses may override this function to perform any required tasks that must be done after all other loading tasks have completed. Typical uses usually revolve around tasks that rename inputs or outputs, such as setting the data name of data sources or requesters.

Most subclasses will not need to override this function.

Returns: True if the function was successful, false otherwise.

◆ getBroadcastUpdateEvents()

bool getBroadcastUpdateEvents ( ) const

◆ getColor()

QColor getColor ( ) const

Returns: The color to use as the background for this operation when a background color is needed, typically by the workflow editor.

See also: setColor()

◆ getCurrentUpdater()

Updater * getCurrentUpdater ( )

protected

Returns: The current execution thread, or a null pointer if no execution thread is currently updating the operation. Note that the operation could still be updating even if this function returns a null pointer, since clients can call update() from anywhere, not just within an execution thread.

◆ getDefaultIconPath()

QString getDefaultIconPath ( ) const

virtual

Returns: The default icon path for this type of operation. Whenever a new operation is created, it will be given this icon path as a default. Clients can still override the icon used for an operation if they so wish by calling setIconPath().

It is not required that getDefaultIconPath() always returns the same value. In fact, it can be a useful way of showing visual differences based on some property of the operation. For example, the Workspace class overrides this function and provides two different icons; one for regular workspaces and different icon for when the workspace comes from an external source.

See also: setIconPath(), getIconPath(), isUsingDefaultIconPath()

Reimplemented in OpenCLJuliaSet, QueryOpenCLDevices, MqttSubscribeLoop, CreateColorStateShader, SshGetFile, SshLogin, SshSendCommand, SshSendFile, ConditionalLoop, FileLoop, ForLoop, ObjectArrayLoop, TranslateObjectDictionary, Workspace, ZeroMQReplyLoop, and ZeroMQSubscribeLoop.

◆ getDefaultUiPath()

QString getDefaultUiPath ( ) const

◆ getDeprecationMessage()

QString getDeprecationMessage ( ) const

Returns: A QString containing a message explaining the deprecation reason, or advice on what to do if this deprecated operation is used.

◆ getDescription()

const QString & getDescription ( ) const

Returns: A description for human users of what this Operation does (for tooltips etc)

◆ getExtras()

SerializedItem getExtras ( )

Returns: The extra state information associated with the operation. All information should be in children of the returned SerializedItem object.

Typically, the extra state information would include things like the operation's position and size in a workspace window when used in a graphical environment. How this information is used is up to the subclass and/or clients.

Even though the return value is by value, not by reference, any changes made to the return value directly affect the data held within the operation. This is because SerializedItem acts as a handle to the real data (somewhat like a pointer) rather than holding the data itself.

See also: saveExtras()

◆ getFactory()

const OperationFactory & getFactory ( ) const

Returns: The operation factory associated with this operation.

◆ getFromPath()

Operation * getFromPath	(	const QString &	path,
		Workspace &	relativeTo,
		QStringList &	errors
	)		const

overridevirtual

Parameters

path	The global path for which an updatable object should be found.
relativeTo	The workspace where the search for path should begin. If path is relative, then it will be treated as relative to relativeTo.
errors	Upon exit, this will hold any errors encountered when trying to find an updatable object that matches path.

Returns: A pointer to the updatable object that matches path, or a null pointer if no such object could be found.

Implements Updatable.

◆ getGraphicsSize()

Operation::GraphicsSize getGraphicsSize ( ) const

virtual

Returns the size of the operation as it is meant to be drawn on the canvas.

Reimplemented in Incrementer, and Logical< T, Op, Multi >.

◆ getHelpPage()

QString getHelpPage ( ) const

virtual

Returns: The file name of the help page for this operation. The file name should be unique within this plugin's help documentation and would normally correspond to the name given to a \page in doxygen-generated documentation sets. For example, the operation's help page is often defined like so:

\page helpmyoperation MyOperation

In this case, getHelpPage() should return the string "helpmyoperation".

Note: Due to issues with how doxygen handles lower/uppercase keywords, you should use only lowercase names for your \page's. Otherwise you may find that cross-references to these pages do not work.

Reimplemented in VtkReaderOperation, CacheData, ComposeGroup, CountedLoop, DecomposeGroup, GetEnvironment, ModifyGroup, ObjectArrayBuilder, PlaceHolder, RunQtScript, UpdateBarrier, WorkspaceInput, and WorkspaceOutput.

◆ getIconPath()

QString getIconPath ( ) const

Returns: The path for the icon to be used for this operation where such an icon is required. Initially, this path is set to the result of getDefaultIconPath() and it will remain at that value until it is explicitly changed by calling setIconPath().

See also: setIconPath(), getDefaultIconPath(), isUsingDefaultIconPath()

◆ getId()

const QUuid & getId ( ) const

Returns: The universally unique id of the operation.

◆ getIdPath() [1/2]

QString getIdPath ( bool scoped = true ) const

overridevirtual

Parameters

scoped If true then return full scope of the item. If false, only return identifier local to its workflow.

Returns: The string that represents the global path to this object using the numeric ID notation. Note that the global name can always be obtained from getGlobalName() so this function is only needed when the ID path is required, typically because the caller cannot handle situations where a global name could potentially be used more than once across the whole workspace hierarchy (in which case the path/global name would not be sufficient to uniquely identify the object). If this string is passed as the first parameter to getFromPath(), we should get this object back again unless it is an empty string. An empty string would normally indicate that this type of updatable object does not have path global support.

Implements Updatable.

◆ getIdPath() [2/2]

QString getIdPath ( const Workspace & relativeTo ) const

◆ getIndex() [1/2]

Operation::difference_type getIndex	(	const Input &	input,
		IndexCountingOptions	options = `SkipNone`
	)		const

Parameters

input	The input to find.
options	Index counting options

Returns: The index of the specified input within the operation, or -1 if input is not one of this operation's inputs.

◆ getIndex() [2/2]

Operation::difference_type getIndex	(	const Output &	output,
		IndexCountingOptions	options = `SkipNone`
	)		const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ getIndexPair()

void getIndexPair	(	InputScalar &	input,
		difference_type &	mainIndex,
		difference_type &	arrayIndex
	)

Parameters

input	The input whose indices are required
mainIndex	Upon exit, this will hold the main index of the input. If input is a regular input, the main index is the result of getIndex(input). If instead input is an element of an array input, the main index is the index of the array input, not of input.
arrayIndex	Upon exit, if input is an element of an array input, arrayIndex will hold the index of input within that array input. If arrayIndex is negative upon exit, this indicates that input is not an element of an array input.

See also: getScalarInput(int,int)

◆ getInput() [1/4]

Input * getInput ( const QString & name )

Parameters

name	The name of the input to retrieve.

Returns: The input which matches name, or a null pointer if name could not be found.

This version is safer than the indexed version, but it is slower since it checks for the existence of name. Most clients will, however, generally use the named version unless iterating over the whole list of inputs.

If name is not found in the list of the operation's inputs, then this function calls getRenamedInput(). This allows subclass implementors to rename inputs and still maintain backwards compatibility. Note, however, that this also means that the input returned from getInput() could have a name different to the one passed as its parameter.

◆ getInput() [2/4]

const Input * getInput ( const QString & name ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ getInput() [3/4]

Input * getInput ( size_type index )

Parameters

index The index of the input to retrieve.

Returns: A modifiable reference to the specified input object.

This function would generally only be used by connection objects to update an input. Most clients should call the const version of this function, which will return a non-modifiable reference to the input. Except for connections, no object should try to modify an input.

Warning: No attempt is made to check if the specified index is valid. The caller should check the number of available inputs with numInputs to ensure index is valid.

◆ getInput() [4/4]

const Input * getInput ( size_type index ) const

Parameters

index The index of the input to retrieve.

Returns: A non-modifiable reference to the specified input object.

Warning: No attempt is made to check if the specified index is valid. The caller should check the number of available inputs with numInputs to ensure index is valid.

◆ getInputArray() [1/2]

InputArray * getInputArray ( const QString & name )

Parameters

name	The name of the array input to retrieve.

Returns: The array input which matches name, or a null pointer if name could not be found or was not an array input.

This function is essentially just a wrapper around getInput to make type safety easier to handle.

◆ getInputArray() [2/2]

const InputArray * getInputArray ( const QString & name ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ getInputs() [1/2]

Operation::IOBaseIteratorRange< Input, false > getInputs ( )

◆ getInputs() [2/2]

Operation::IOBaseIteratorRange< Input, true > getInputs ( ) const

◆ getInputScalar() [1/2]

InputScalar * getInputScalar ( const QString & name )

Parameters

name	The name of the scalar input to retrieve.

Returns: The scalar input which matches name, or a null pointer if name could not be found or was not a scalar input.

This function is essentially just a wrapper around getInput to make type safety easier to handle.

◆ getInputScalar() [2/2]

const InputScalar * getInputScalar ( const QString & name ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ getInputValue() [1/2]

T & getInputValue ( const QString & inputName )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

inputName The name of the scalar input from which we are retrieving a value.

This is a convenience function. It allows callers to retrieve the raw data value assigned to a named input. Checks are performed to ensure that the type requested matches the type of the input. If no data exists on the input at the time this function is invoked, it will create the data.

Returns: A pointer to the value associated with the named scalar input. If the input does not exist, or the types do not match, zero will be returned.

◆ getInputValue() [2/2]

const T & getInputValue ( const QString & inputName ) const

inline

Parameters

inputName The name of the scalar input from which we are retrieving a value.

This is a convenience function. It allows callers to retrieve the raw data value assigned to a named input. Checks are performed to ensure that the type requested matches the type of the input. If no data exists on the input at the time this function is invoked, it will create the data.

Returns: A pointer to the value associated with the named scalar input. If the input does not exist, or the types do not match, zero will be returned.

◆ getLabel()

const QString & getLabel ( ) const

Returns: The label currently assigned to this operation. Note that this may contain HTML markup.

See also: getShortLabel()

◆ getLabelRelativeToRoot()

QString getLabelRelativeToRoot ( ) const

Returns: A concatenated label that includes all ancestors

◆ getOutput() [1/4]

Output * getOutput ( const QString & name )

Parameters

name	The name of the output to retrieve.

Returns: The output which matches name, or a null pointer if name could not be found.

This version is safer than the indexed version, but it is slower since it checks for the existence of name. Most clients will, however, generally use the named version unless iterating over the whole list of outputs.

If name is not found in the list of the operation's outputs, then this function calls getRenamedOutput(). This allows subclass implementors to rename outputs and still maintain backwards compatibility. Note, however, that this also means that the output returned from getOutput() could have a name different to the one passed as its parameter.

◆ getOutput() [2/4]

const Output * getOutput ( const QString & name ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ getOutput() [3/4]

Output * getOutput ( size_type index )

Parameters

index The index of the output to retrieve.

Returns: A modifiable reference to the specified output object.

Warning: No attempt is made to check if the specified index is valid. The caller should check the number of available inputs with numInputs to ensure index is valid.

◆ getOutput() [4/4]

const Output * getOutput ( size_type index ) const

Parameters

index The index of the output to retrieve.

Returns: A non-modifiable reference to the specified output object.

Warning: No attempt is made to check if the specified index is valid. The caller should check the number of available inputs with numInputs to ensure index is valid.

◆ getOutputs() [1/2]

Operation::IOBaseIteratorRange< Output, false > getOutputs ( )

◆ getOutputs() [2/2]

Operation::IOBaseIteratorRange< Output, true > getOutputs ( ) const

◆ getOutputValue() [1/2]

T & getOutputValue ( const QString & outputName )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

outputName The name of the output from which we are retrieving a value.

This is a convenience function. It allows callers to retrieve the raw data value assigned to a named output. Checks are performed to ensure that the type requested matches the type of the output. If no data exists on the output at the time this function is invoked, zero will be returned.

Note: It is the responsibility of the caller to ensure that the operation is brought up-to-date prior to invoking this function.

Returns: A pointer to the value associated with the named scalar output. If the output does not exist, or the types do not match, zero will be returned.

◆ getOutputValue() [2/2]

const T & getOutputValue ( const QString & outputName ) const

inline

Parameters

outputName The name of the output from which we are retrieving a value.

This is a convenience function. It allows callers to retrieve the raw data value assigned to a named output. Checks are performed to ensure that the type requested matches the type of the output. If no data exists on the output at the time this function is invoked, zero will be returned.

Note: It is the responsibility of the caller to ensure that the operation is brought up-to-date prior to invoking this function.

Returns: A pointer to the value associated with the named scalar output. If the output does not exist, or the types do not match, zero will be returned.

◆ getProfilingEnabled()

bool getProfilingEnabled ( ) const

◆ getProgress()

int getProgress ( ) const

Returns: The current progress as a percentage. The value will normally be in the range [0,100], although a negative value may be encountered if the operation subclass does not set the progress when it executes. A negative progress is called an indeterminate state and some clients will treat this in a special way, such as a different kind of progress bar in a GUI.

◆ getProgressContribution()

int getProgressContribution ( ) const

Returns: The percentage contribution this operation makes to its containing workspace.

See also: setProgressContribution(), getProgress()

◆ getProgressResetByNotUpToDate()

bool getProgressResetByNotUpToDate ( ) const

Returns: The percentage contribution this operation makes to its containing workspace.

See also: setProgressResetByNotUpToDate()

◆ getRenamedInput()

const Input * getRenamedInput ( const QString & name ) const

protectedvirtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Reimplemented in CreateImageTileSet, Hdf5MeshModelWriter, Hdf5SceneWriter, FindStateRange, PlyReader, BoundingBoxOfModels, ScheduleWorkflow, WaitWorkflow, SplitAndLodPointCloudOp, ModifyObjectDictionary, ObjectDictionaryInfo, and WhileLoop.

◆ getRenamedOutput()

const Output * getRenamedOutput ( const QString & name ) const

protectedvirtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Reimplemented in ElementStateMapperBuilder, SelectableMeshReader, HasFeature, ModifyObjectDictionary, and WhileLoop.

◆ getRequiredSchedulerFeatures()

SchedulerFeatures getRequiredSchedulerFeatures ( ) const

virtual

Returns: The features required in order to run this operation.

Reimplemented in Workspace.

◆ getScalarInput()

InputScalar * getScalarInput	(	size_type	mainIndex,
		difference_type	arrayIndex
	)

Parameters

mainIndex	The main index of the input to retrieve. If the input at this index is a scalar input, then arrayIndex must be negative (this is only checked by an assertion, so in non-debug builds this won't be checked). If the input at mainIndex is an array input, then arrayIndex must have a non-negative value.
arrayIndex	If mainIndex refers to an array input, then arrayIndex specifies the index within the input array of the scalar input to be retrieved. Otherwise, the value of arrayIndex can be arbitrary.

Returns: The scalar input specified by the pair of indices, or a null pointer if the indices do not specify a valid scalar input. Note that a null pointer can only be returned in non-debug builds, since debug builds will trigger an assertion if a null pointer would otherwise be returned.

See also: getIndexPair()

◆ getShortLabel()

QString getShortLabel ( ) const

◆ getTagName()

QString getTagName ( ) const

Returns: The tag name to use for this object when it is serialized.

◆ getTerminateExecution()

bool getTerminateExecution ( ) const

Returns: True if the operation has been asked to terminate execution.

See setTerminateExecution() for details regarding when such a request might be active and how clients should use execution termination functions.

◆ getUiPath()

QString getUiPath ( ) const

◆ getUpToDate()

bool getUpToDate ( ) const

overridevirtual

Returns: True if this operation is up to date.

Implements Updatable.

◆ hasRequiredSchedulerFeatures()

bool hasRequiredSchedulerFeatures ( ) const

virtual

Returns true if the operation has required scheduler features.

◆ idPathChanged()

void idPathChanged ( )

overridevirtual

Sub-classes should override this if they want to control notifications in response to ancestry changes.

Reimplemented from Updatable.

Reimplemented in Workspace.

◆ inputRebuilt()

bool inputRebuilt ( InputScalar & input )

virtual

Parameters

input The input for which the connection was rebuilt.

Normally, an operation doesn't need to do anything when a connection is rebuilt. The input's underlying data object may have changed, but operations generally don't cache it and only retrieve it inside its execute() function. If, however, the input is also being passed directly through as an output for the operation, as would be common for an operation which modifies its input directly and passes the modified version on as an output, the operation needs to make sure the ouput is marked as no longer up to date and is therefore itself no longer up to date.

Returns: True if the operation can successfully respond to the input being rebuilt. The default implementation unconditionally returns true and performs no other action.

◆ inputsAreUpToDate()

bool inputsAreUpToDate ( ) const

protectedvirtual

Reimplemented in ScheduleWorkflow, and RunOperationsInParallel.

◆ isAsynchronous()

bool isAsynchronous ( ) const

virtual

Returns: True if this Operation executes asynchronously.

See also: setIsAsynchronous()

Reimplemented in Workspace.

◆ isAtomicUpdate()

bool isAtomicUpdate ( ) const

virtual

Returns: True if this Operation behaves as a single atomic operation from an execution point of view.

When an atomic operation has one of it's inputs or one of its outputs that are using 'in place data' marked out of date, then all outputs are marked out of date. When this happens the operation needs to be executed to guarantee each output is back up to date.

For a normal operation with a single execute function or a nested workspace providing some sort of atomic functionality this makes sense.

However it is possible for a Workspace operation to be acting as a logical grouping of other operations. In this case a nested workspace may contain independent execution paths that don't affect each other meaning some inputs and in-place outputs may have nothing to do with some outputs.

A non-atomic workspace does not get updated as a whole. Instead the updater traverses into the workspace for the given output it's trying to update and brings only that output up to date. This means when an input is marked out of date only outputs actually connected to that input need to be marked out of date.

Reimplemented in Workspace.

◆ isConnectedToAsynchronous()

bool isConnectedToAsynchronous ( ) const

overridevirtual

Returns: True if this Operation is connected to an asynchronous operation.

Implements Updatable.

Reimplemented in Workspace.

◆ isDeprecated()

bool isDeprecated ( ) const

Returns: True if the operation is deprecated (i.e. earmarked for removal), or false otherwise.

◆ isEditable()

bool isEditable ( ) const

Returns: true if the operation is editable (i.e. can be modified), false otherwise.

◆ isIdPathCachingEnabled()

bool isIdPathCachingEnabled ( ) const

Returns: True if id path caching is enabled, false otherwise.

◆ isPolymorphicType()

bool isPolymorphicType ( ) const

virtual

Returns: True if this operation is a type of polymorphic operation, i.e. a class derived from PolymorphicOperation.

Reimplemented in PolymorphicDataOperation.

◆ isRunningAsynchronously()

bool isRunningAsynchronously ( ) const

virtual

Returns: True if this Operation is executing asynchronously.

See also: setIsRunningAsynchronously()

Reimplemented in Workspace.

◆ isThreadSafe()

bool isThreadSafe ( ) const

virtual

Returns true if the operation is thread safe.

◆ isType() [1/2]

bool isType ( ) const

inline

Returns: True if the operation's type matches the specified type. False otherwise. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Template function for testing the type of the Operation. Shorthand for:

&operation.getFactory() == &OperationFactoryTraits<T>::getInstance()

◆ isType() [2/2]

bool isType ( const OperationFactory & type ) const

inline

Returns: True if the operation's type matches the specified type. False otherwise. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Utility function for testing the type of the operation. Shorthand for:

&operation.getFactory() == &type

◆ isUpdating()

bool isUpdating ( ) const

Returns: Is this operation in the process of being brought up to date.

◆ isUserConfigurable()

bool isUserConfigurable ( )

virtual

Returns: Is this operation user configurable. Examples would include: 1) a polymorphic operation 2) an operation where the number of inputs and/or outputs be: changed (such as CreateChart) or hidden (such as RunMatLabScript).

Reimplemented in RunMatLabScript, RunPythonScript, CreateObjectDictionary, DecomposeObjectDictionary, FilePathBuilder, PolymorphicDataOperation, RunQtScript, and TreeSelectionBuilder.

◆ isUsingDefaultColor()

bool isUsingDefaultColor ( ) const

Returns: True if the current color is set to the default.

Client code should call this function rather than testing against what it believes is the default color. The default color might change in the future and using isUsingDefaultColor() will ensure the client code is robust to such a change.

◆ isUsingDefaultIconPath()

bool isUsingDefaultIconPath ( ) const

Returns: True if the operation is set to use the default icon path. Note that explicitly setting the icon path to the same as the path returned by getDefaultIconPath() will result in this function returning true (ie it effectively clears any custom path).

See also: setIconPath(), getIconPath(), getDefaultIconPath()

◆ isUsingDefaultUiPath()

bool isUsingDefaultUiPath ( ) const

◆ isWaitingForAsynchronousUpdate()

bool isWaitingForAsynchronousUpdate ( ) const

overridevirtual

Returns: True if the updatable object is waiting for an asynchronous update.

See also: update()

Implements Updatable.

Reimplemented in Workspace.

◆ isWorkspaceType()

bool isWorkspaceType ( ) const

Returns: True if this operation is a type of nested workflow operation, i.e. a class derived from Workspace.

◆ load()

bool load ( const SerializedItem & item )

overridevirtual

Parameters

item	Supplies the state to be loaded into this object.

This function will load the state of this object from item. For many object types, this is most easily implemented in terms of the object's input operator (>>).

It would be reasonable for subclass implementations to assume that the data provided in item is in the same form as would have been saved from a call to save.

Returns: If the state of the object could not be loaded, the function returns false. A return value of true implies that the object state was successfully loaded. If canSerialize() returns false, this function must do nothing except return false as well.

Implements Serialize.

Reimplemented in PostFileToDIDS, StoreProvenanceData, and Workspace.

◆ makeOutputsValid()

bool makeOutputsValid ( )

protectedvirtual

By default, before an operation executes, it updates its inputs and it also ensures that all of its outputs hold valid data objects. Therefore, by the time the execute() function is called, it can be assumed that all inputs are up to date and all outputs have valid data objects.

The makeOutputsValid() function normally takes care of ensuring that the outputs hold valid data objects. A subclass may choose to override this behaviour if it wants to delay the creation of the outputs until somewhere in its execute() function. There are two requirements on the subclass' implementation if it overrides makeOutputsValid():

If execute() returns true (indicating success), then all of the operation's outputs have data and can be assumed to be up to date.
The makeOutputsValid() function will not trigger any further updates under any circumstances. This means it cannot request up to date values of any of the operation's inputs, nor cause the operation itself to update itself (this would lead to infinite recursion).

Strictly speaking, this function is not actually necessary. It exists to make the creation of all operation outputs before execute() is called the default behaviour, since most operations want to do this. Putting that part of the update process in a separate function removes the burden on subclasses from having to do this for themselves, but since it is a virtual function the subclass can implement alternative behaviour. The most common reason for doing this is to delay the creation of the outputs until sometime in execute().

Returns: True if the function was successful. Note that success does not necessarily mean data objects are guaranteed to exist for all of the operation's outputs, since subclasses may have changed the behaviour to delay this until the execute() call. The key behaviour is that if this function fails to achieve what it needs to do, it should return false.

See also: Operation::update(), Operation::execute(), Operation::bringInputsUpToDate()

Reimplemented in MeshModelSource, MeshModelInstanceBuilder, DecomposeGroup, and ObjectArrayAccessor.

◆ markOutputsUpToDate()

void markOutputsUpToDate ( )

protectedvirtual

Reimplemented in TranslateObjectDictionary, and Workspace.

◆ markUpToDateWhereSafe()

void markUpToDateWhereSafe ( )

Mark as up to date every input which has data and is not connected to an output. Calling this function is most useful after an operation has been created or loaded. It allows things to access the data where those entities require an input to be up to date before access is allowed. Workspace widgets are a prime example of this (and indeed are the main motivation for this function's existence).

It is not safe to mark an operation's outputs as up to date except by executing the operation itself. This is because an operation is allowed to update its output in any way it sees fit, including a process with side effects. Thus, to preserve any assumptions made by the operation's author, we do not alter the up to date status of outputs in this function. We also do not alter the up to date status of the operation itself for the same reasons.

◆ matchesType()

bool matchesType ( const Operation & otherOperation ) const

inline

Returns: True if the operation's type matches the type of another operation. i False otherwise.

Utility function for testing whether the type of two operations matches. Shorthand for:

&operation.getFactory() == &otherOperation.getFactory()

◆ numInputs()

Operation::size_type numInputs ( IndexCountingOptions options = SkipNone ) const

Parameters

options Options for how the count is performed.

Returns: The number of inputs for this operation, including the dependency input (which is always at index zero).

◆ numOutputs()

Operation::size_type numOutputs ( IndexCountingOptions options = SkipNone ) const

Parameters

options Options for how the count is performed.

Returns: The number of outputs for this operation, including the dependency output (which is always at index zero).

◆ pauseUpdate()

void pauseUpdate ( )

protected

Called by the default implementation of update() for an Operation. If subclasses override update(), they must call pauseUpdate() at least once at a time when it is safe for their inputs and/or outputs to change. Long-running operations should call pauseUpdate() periodically to allow other threads to process their requests to modify or read data in the workspace's inputs or outputs.

It must be safe for the caller to continue after calling this function, even if the data in the Operation inputs changes arbitrarily. It is even possible for the input data to be no longer up to date, hence it may not be safe to even read the inputs when pauseUpdate() returns. The caller should locally cache anything it needs or else explicitly test the status of inputs it still wants to use. The caller can, however, rely on the connectivity of the workspace remaining the same, so none of its inputs will have any connections added or removed (but they might get rebuilt). Similarly, no input elements will be added to or removed from an input array held by the operation.

◆ postSave()

bool postSave ( SerializedItem & item ) const

protectedvirtual

Parameters

item	The item into which data should be saved.

This function is called as the last step in save() to allow subclasses to save any further information specific to them. It differs from the extras data in that the extras are meant for clients outside the inheritence heirachy and may change depending on what clients use the class. The postSave() function, on the other hand, is meant for subclasses to use to save data that is always needed and used internally by the subclass.

The default implementation saves no additional information and simply returns true to indicate success.

Returns: True if successful.

Reimplemented in RunPythonScript, CreateChart, SceneItemLibraryBuilder, ShaderLibraryBuilder, CustomInputsOutputsOperation, ModifyGroup, ModifyObjectDictionary, PostFileToDIDS, StoreProvenanceData, RunMatLabScript, PolymorphicDataOperation, RunQtScript, ReplaceString, and Workspace.

◆ prepareInputsOutputsForLoad()

bool prepareInputsOutputsForLoad ( const SerializedItem & item )

protectedvirtual

Parameters

item	The serialized item that will be loaded.

This function is called just before load() attempts to load the data for inputs and outputs from item. The default implementation simply returns true to indicate that loading can proceed. Subclasses may override this function to perform any required tasks that must be done before the inputs or outputs can be accessed. Typical uses usually revolve around tasks that create inputs and outputs, such as populating a nested workspace, setting the data type of a polymorphic data operation, etc.

Most subclasses will not need to override this function.

Returns: True if the function was successful and the data for the inputs and outputs can be loaded.

◆ removeInput() [1/2]

bool removeInput ( const QString & name )

Parameters

name	The name of the input to remove from the operation.

Returns: True if the input could be removed, or false if the specified name was not one of the operation's inputs.

This function does not delete the input, it only removes the association between the input and this operation. The input could even be subsequently added to a different operation if desired. The dependency input for an operation cannot be removed.

◆ removeInput() [2/2]

bool removeInput ( Input & input )

Parameters

input The input to remove from the operation.

Returns: True if the input could be removed, or false if the specified input was not one of the operation's inputs.

This function does not delete the input, it only removes the association between the input and this operation. The input could even be subsequently added to a different operation if desired. The dependency input for an operation cannot be removed.

◆ removeOutput() [1/2]

bool removeOutput ( const QString & name )

Parameters

name	The name of the output to remove from the operation.

Returns: True if the output could be removed, or false if the specified name was not one of the operation's outputs. It will also return false if the caller is trying to remove the dependency output.

This function does not delete the output, it only removes the association between the output and this operation. The output could even be subsequently added to a different operation if desired. The dependency output for an operation cannot be removed.

◆ removeOutput() [2/2]

bool removeOutput ( Output & output )

Parameters

output The output to remove from the operation.

Returns: True if the output could be removed, or false if the specified output was not one of the operation's outputs. It will also return false if the caller is trying to remove the dependency output.

This function does not delete the output, it only removes the association between the output and this operation. The output could even be subsequently added to a different operation if desired. The dependency output for an operation cannot be removed.

◆ resetExecutionDependencies()

void resetExecutionDependencies ( )

virtual

When a workspace is being updated continuously, it notifies interested clients each time. The usual arrangement is for an observer to call resetExecutionDependencies for each notification.

See also: ResetDependency

Reimplemented in Workspace.

◆ save()

bool save ( SerializedItem & item ) const

overridevirtual

Parameters

item	Where to save the state of this object.

This function will serialise the object by saving it to item. For most object types, this is most easily implemented in terms of the object's output operator (<<).

It is allowable for an object to only serialize part of itself. This would be useful if the data it represents has a set of defaults and only those values different to the defaults need to be serialized. Such an implementation then needs to be careful how it handles the complimentary load member function.

Returns: If an object could not be serialised or if the underlying object type does not support serialisation, this function should return false. A return value of true implies that the object was successfully saved to item. If canSerialize() returns false, this function must do nothing except return false as well.

Implements Serialize.

◆ saveExtras()

void saveExtras ( SerializedItem & item ) const

protected

Parameters

item	Where to save the extra state data of this operation.

This function is responsible for saving any extra state information associated with the operation that is not managed by Operation or its subclass. External clients of Operation can use this to add their own data to the operation and have it included when the operation is serialized, such as when saved to a workspace file. Clients can access these extras at any time using getExtras() and they may modify those extras to suit their own purposes. It is highly advisable that clients doing this should work with a child below the top level extras item where the name of that child is somehow related to what they are doing with the data. This will help minimize the chances of a name clash with other clients who might also be putting their own data into the extras information.

See also: getExtras()

◆ saveWithData()

bool saveWithData ( SerializedItem & item ) const

virtual

Reimplemented in Workspace.

◆ setAtomicUpdate()

void setAtomicUpdate ( bool atomic )

virtual

This method is overridden for Workspace operations.

See also: isAtomicUpdate()

Reimplemented in PlaceHolder, and Workspace.

◆ setBroadcastUpdateEvents()

void setBroadcastUpdateEvents ( bool enable )

◆ setColor()

void setColor ( const QColor & c )

Parameters

c	The color to use as the background for this operation when a background color is needed, typically by the workflow editor.

See also: getColor()

◆ setDescription()

void setDescription ( const QString & description )

Parameters

description A description for human users of what this Operation does (for tooltips etc)

◆ setEditable()

void setEditable ( bool b )

Parameters

b	Whether or not the properties of this operation should be editable.

◆ setIconPath()

void setIconPath ( const QString & path )

Parameters

path	The path for the icon to be used for this operation where such an icon is required (typically in the workflow editor window). The icon would normally be 48x48 pixels and must be one of the formats supported by Qt. If in doubt, use PNG.

Note that setting the icon path to the same as the result of getDefaultIconPath() effectively reverts the icon back to the default. If the result of getDefaultIconPath() later changes, the icon path used by this operation will change along with it. This is to support operations which change their default icon based on things like operation properties, the most notable of which is Workspace which has a different default icon when its external source URL is set.

See also: getIconPath(), getDefaultIconPath(), isUsingDefaultIconPath()

◆ setId()

void setId ( const QUuid & id )

Parameters

id	The universally unique id of the operation.

◆ setIdPathCachingEnabled()

void setIdPathCachingEnabled ( bool b )

virtual

Parameters

b	Whether or not to enable IdPath caching.

If enabled, the operation will cache its IdPath both in memory and in serialised form. If the operation is going to be executed in a distributed environment away from its in-memory parent workflow, a cached ID path is necessary, however, rather than imposing this memory / file size encumbrance on all operations, we make it an opt-in.

Reimplemented in Workspace.

◆ setInputNotUpToDate()

void setInputNotUpToDate ( InputScalar & input )

virtual

Parameters

input The input making the requested status change.

This function is provided so that operations can take special action when a particular input is marked as not up to date. The default implementation marks the whole operation as not up to date by calling setUpToDate(false), but subclasses (notably Workspace) may want to do something more interesting.

◆ setIsAsynchronous()

void setIsAsynchronous ( bool asynchronous )

virtual

This method is overridden for Workspace operations.

See also: isAsynchronous()

Reimplemented in Workspace.

◆ setIsRunningAsynchronously()

void setIsRunningAsynchronously ( bool asynchronous )

virtual

This method is overridden for Workspace operations.

See also: isRunningAsynchronously()

Reimplemented in Workspace.

◆ setLabel()

void setLabel ( const QString & label )

Parameters

label The label to assign to this operation.

An operation's label is mostly just for users to be able to identify them. They are not used for anything meaningful internally, so the user can pretty much relabel operations to anything they like.

◆ setOutputNotUpToDate()

void setOutputNotUpToDate ( Output & output )

virtual

Parameters

output The output making the requested status change.

This function is provided so that operations can take special action when a particular output is marked as not up to date. The default implementation marks the whole operation as not up to date by calling setUpToDate(false), but subclasses (notably Workspace) may want to do something more interesting.

Reimplemented in GetItemFromJson, GetItemFromObjectDictionary, TryInputs, and Workspace.

◆ setProfilingEnabled()

void setProfilingEnabled ( bool enable )

◆ setProgress()

void setProgress ( int percent )

virtual

Parameters

percent The progress of the operation expressed as a percentage.

If percent is different from the currently stored progress value, a ProgressEvent will be raised and all entities observing this operation for progress events will be notified in the current thread.

This function is public so that private implementation classes can forward progress notifications. Client code would not normally call this under other circumstances.

Not all operations support progress notifications. Even so, when an operation is about to execute, it will always have its progress set to zero and if/when it completes successfully it will have its progress set to 100. If execution fails for some reason, the up to date status handling will ensure that a progress of zero will be set.

See also: update()

◆ setProgressContribution()

void setProgressContribution ( int percent )

Parameters

percent The percentage of the containing workspace's progress that this operation represents. It must be in the range 0 to 100. If set to zero, it indicates that this operation does not meaningfully contribute to the parent's overall progress, in which case any progress notifications on this operation would not be forwarded to the parent.

Not all operations support progress notifications. In that case, the progress contribution should remain at the default value of zero.

The last thing this function does before returning is raise a ProgressContributionChangeEvent notification. The containing workspace would normally be the only thing responding to that event.

See also: setProgress(), getProgressContribution()

◆ setProgressResetByNotUpToDate()

void setProgressResetByNotUpToDate ( bool b )

Parameters

b	If true (the default), calls to setUpToDate() should also reset the progress to zero.

See also: getProgressResetByNotUpToDate()

◆ setRequiredSchedulerFeatures()

void setRequiredSchedulerFeatures ( const SchedulerFeatures & features )

virtual

Sets the features required in order to run this operation.

◆ setTerminateExecution()

void setTerminateExecution ( bool b )

Parameters

b	If true, any attempt to execute the operation will fail.

To prevent an operation from executing, the parameter can be set to true. This is normally part of a top-level process setting this to true for all operations to halt workspace execution. Once that top level process has confirmed that execution has stopped, it should then subsequently reset the status by passing a false parameter to this function for all operations.

The Workspace class overrides this function to make it behave recursively. No other subclass should override it.

Note: This function is thread-safe in the sense that it changes the value of a variable marked volatile in a way that is atomic.

See also: getTerminateExecution()

◆ setUiPath()

void setUiPath ( const QString & path )

◆ setUpToDate()

void setUpToDate ( bool b )

overridevirtual

Parameters

b	Boolean value specifying the operation's new up-to-date status.

If b is false, the call will also try to propagate forward the not up-to-date status for all the operation's outputs. Anything connected to one of the outputs is also marked as not up to date, following all connections and operations as far as possible until something is encountered which was already not up to date, or until all connections are exhausted.

This function also explicitly sets the progress to zero if b is false or to 100 if b is true.

Implements Updatable.

Reimplemented in Workspace.

◆ shouldPutInExtras()

bool shouldPutInExtras ( const QString & tagName ) const

protectedvirtual

Parameters

tagName The tag of the item being queried.

During a call to Operation::load(), the function iterates over all direct children of the serialized item being loaded. For those it recognises, it processes. For the rest, it calls shouldSaveInExtras() with its tag name and if shouldSaveInExtras() returns true, the item will be added to the operation's serialized "extras". Some special subclasses (notably Workspace and PolymorphicDataOperation) add their own specific tags to serialized items and because they process these tags in prepareForLoad(), etc., the tags do not need to be put into the extras (indeed it could involve considerable unnecessary storage if those tags were added).

The default implementation returns true, implying that all unrecognized items will be added to the extras data.

Returns: True if the item with the specified tagName should be added to the operation's extras data.

Reimplemented in RunPythonScript, and Workspace.

◆ update()

bool update ( Updater * updater = nullptr )

overridevirtual

This function first ensures that all required inputs are brought up to date and all outputs hold valid data objects. It then executes the operation by calling execute() and if that is successful, it will mark all outputs as up to date. If subclasses want to customise how the inputs are updated, they should override bringInputsUpToDate(), but this should only be necessary if only a subset of the inputs may be needed for the operation to update itself.

It should be explicitly noted that because inputs may need to be brought up to date, calling an operation's update() function could be expensive, depending on how costly it is to update each of its inputs. There is no restriction on how costly that might be, since users could create an arbitrary combination of operations and connections to supply an input.

In very rare cases, it may be necessary for subclasses to override update() to implement some special sort of update behaviour. One example is the for loop operation, where the inputs and outputs are updated in a specific order and usually more than once until a certain input holds a true value. Only then will the update() function actually return. Overriding update() is, however, not necessary in most instances. Authors of Operation subclasses are strongly advised not to override it.

Returns: True if the update was successful.

Implements Updatable.

Reimplemented in Workspace.

Classes

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ difference_type

◆ size_type

Member Enumeration Documentation

◆ ConfigStatus

◆ GraphicsSize

◆ IndexCountingOption

Constructor & Destructor Documentation

◆ ~Operation()

◆ Operation()

Member Function Documentation

◆ addInput()

◆ addOutput()

◆ assignInput()

◆ bringArrayOfInputsUpToDate() [1/2]

◆ bringArrayOfInputsUpToDate() [2/2]

◆ bringInputsUpToDate()

◆ bringInputUpToDate()

◆ cancelExecution()

◆ canSerialize()

◆ connectProgressEvents()

◆ createCustomPropertiesHandler()

◆ ensureHasData()

◆ execute()

◆ finishInputsOutputsAfterLoad()

◆ getBroadcastUpdateEvents()

◆ getColor()

◆ getCurrentUpdater()

◆ getDefaultIconPath()

◆ getDefaultUiPath()

◆ getDeprecationMessage()

◆ getDescription()

◆ getExtras()

◆ getFactory()

◆ getFromPath()

◆ getGraphicsSize()

◆ getHelpPage()

◆ getIconPath()

◆ getId()

◆ getIdPath() [1/2]

◆ getIdPath() [2/2]

◆ getIndex() [1/2]

◆ getIndex() [2/2]

◆ getIndexPair()

◆ getInput() [1/4]

◆ getInput() [2/4]

◆ getInput() [3/4]

◆ getInput() [4/4]

◆ getInputArray() [1/2]

◆ getInputArray() [2/2]

◆ getInputs() [1/2]

◆ getInputs() [2/2]

◆ getInputScalar() [1/2]

◆ getInputScalar() [2/2]

◆ getInputValue() [1/2]

◆ getInputValue() [2/2]

◆ getLabel()

◆ getLabelRelativeToRoot()

◆ getOutput() [1/4]

◆ getOutput() [2/4]

◆ getOutput() [3/4]

◆ getOutput() [4/4]

◆ getOutputs() [1/2]

◆ getOutputs() [2/2]

◆ getOutputValue() [1/2]

◆ getOutputValue() [2/2]

◆ getProfilingEnabled()

◆ getProgress()

◆ getProgressContribution()

◆ getProgressResetByNotUpToDate()

◆ getRenamedInput()

◆ getRenamedOutput()

◆ getRequiredSchedulerFeatures()

◆ getScalarInput()