classPiiOperation
#include <PiiOperation.h>
A superclass for operations that can be run by Ydin.
Inherits QObject
Inherited by PiiBasicOperation, PiiOperationCompound
Description
Operations can be roughly divided into produces, consumers, and transformations. An image source, such as a camera, is a producer (an input), image processing operations are transforms, and a connection to a process control system is a consumer (an output). There are however operations that can work in many roles simultaneously.
Each operation can be seen as a process that receives some input data and produces some results after processing. An operation may also have no inputs or no outputs, in which case it is considered a producer or a consumer, respectively.
Operations can work either synchronously or asynchronously. For example, an image source can emit images in its own internal frequency, irrespective of any consumers of the image data (asynchronous operation). The receivers process the data if they aren't too busy doing other things. In most cases it is however necessary to process all images captured. In this case the image source halts until all processing has been done before it sends the next image.
Each operation can have any number (0-N) of inputs and outputs called sockets (see PiiSocket). Each socket has a data type or multiple data types associated with it. That is, each socket handles certain types of objects. Input and output sockets with matching types can be connected to each other, and an output can be connected to multiple inputs.
Sockets are automatically destroyed with their parent operation. Furthermore, all connections between deleted sockets are automatically deleted. Thus, one doesn't need to care about deleting anything but the operation itself.
Public types
|
enum
|
{ WriteAlways, WriteWhenStoppedOrPaused, WriteWhenStopped,
WriteNotAllowed }
Protection levels for setting properties. |
|
enum
|
{ Stopped, Starting, Running, Pausing, Paused, Stopping,
Interrupted }
The state of an operation can assume six different values: |
Signals
|
void
|
Signals an error. |
|
void
|
(
Indicates that the state of this operation has changed. |
Constructors and destructor
|
( )
Constructs a new PiiOperation. |
|
|
( )
|
Public member functions
|
virtual void
|
(
Checks that the necessary preconditions for processing are met. |
|
virtual Q_INVOKABLE PiiOperation *
|
( )
Creates a clone of this operation. |
|
Q_INVOKABLE bool
|
A convenience function for connecting a named output socket to a named input socket in another operation. |
|
Q_INVOKABLE void
|
Disconnects all inputs. |
|
Q_INVOKABLE void
|
Disconnects all outputs. |
|
virtual Q_INVOKABLE PiiAbstractInputSocket
*
|
Returns a pointer to the input associated with name. |
|
virtual Q_INVOKABLE int
|
( )
Returns the number of input sockets. |
|
Q_INVOKABLE QStringList
|
( )
Returns the names of all inputs. |
|
virtual Q_INVOKABLE QList< PiiAbstractInputSocket
* >
|
( )
= 0
Returns a list of all input sockets connected to this operation. |
|
virtual void
|
( )
= 0
Interrupts the execution. |
|
virtual Q_INVOKABLE PiiAbstractOutputSocket
*
|
Returns a pointer to the output associated with name. |
|
virtual Q_INVOKABLE int
|
( )
Returns the number of output sockets. |
|
Q_INVOKABLE QStringList
|
( )
Returns the names of all outputs. |
|
virtual Q_INVOKABLE QList< PiiAbstractOutputSocket
* >
|
( )
= 0
Returns a list of all output sockets connected to this operation. |
|
virtual void
|
( )
= 0
Pauses the operation. |
|
virtual QVariant
|
(
Virtual version of QObject::property(). |
|
(
Returns the protection level of property. |
|
|
bool
|
A convenience function that automatically creates a QVariant out of a PiiVariant. |
|
virtual bool
|
Virtual version of QObject::setProperty(). |
|
Q_INVOKABLE QString
|
Returns the name of a socket in the context of this operation. |
|
virtual QVariant
|
Returns meta information associated with socket. |
|
Q_INVOKABLE QVariant
|
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. |
|
virtual void
|
( )
= 0
Starts the operation and executes it until interrupted or paused. |
|
virtual Q_INVOKABLE State
|
( )
= 0
Returns the current state of the operation. |
|
virtual void
|
( )
= 0
Stops the operation. |
|
virtual bool
|
(
Waits for this operation to stop running. |
Static public member functions
|
static const char *
|
Returns a string presentation of the given state. |
Protected member functions
|
( )
Constructs a new PiiOperation. |
|
|
void
|
Sets the protection level of property to level. |
|
QMutex *
|
( )
Returns a pointer to the mutex that prevents concurrent access to the state of this operation. |
Enumeration details
-
enum ProtectionLevel
Protection levels for setting properties.
-
WriteAlways- setting the value of a property is always allowed. This is the default value for all properties. -
WriteWhenStoppedOrPaused- setting the value of a property is allowed only if the state of the operation is eitherStoppedorPaused. -
WriteWhenStopped- setting the value of a property is allowed only if the state of the operation isStopped. -
WriteNotAllowed- setting the value of a property is not allowed at all. This value makes it possible for subclasses to make the properties of a superclass read-only even if they had a setter function.
-
-
enum State
The state of an operation can assume six different values:
-
Stopped- the operation is not running. -
Starting- the operation has received a start() signal, but it is not running yet. -
Running- the operation is running. -
Pausing- the operation has received a pause() signal, but it hasn't finished execution yet. -
Paused- the operation has finished execution due to a pause() command. -
Stopping- the operation has received a stop() signal, but it hasn't stopped yet. -
Interrupted- the operation has received an interrupt() signal, but it hasn't stopped yet.
-
Function details
-
PiiOperation
()[protected]Constructs a new PiiOperation.
-
~PiiOperation
() -
PII_DEFAULT_SERIALIZATION_FUNCTION
-
virtual void check
(- bool reset
[pure virtual]Checks that the necessary preconditions for processing are met.
This function is called by before processing is started. It is followed by a start() call, provided that all operations in an engine have been successfully initialized. The function should check, for example, that all required inputs are connected.
This function is called by PiiEngine once for all operations before any of them is started. This ensures there will be no input into any operation before each of them have been checked.
Parameters
- reset
-
if
true, reset the operation to its initial state. This flag is true whenever the operation was interrupted and started again. If the operation was just paused, the reset flag is set tofalse, and the operation should continue where ever it was left.
Exceptions
- PiiExecutionException&
-
if the operation cannot be run.
-
Creates a clone of this operation.
The default implementation uses the serialization library to find a factory object for the class. Once an instance is created it iterates over all properties and copies their values to the new operation instance.
Returns
a deep copy of the operation, or 0 if no factory was found.
-
Q_INVOKABLE bool connectOutput
A convenience function for connecting a named output socket to a named input socket in another operation.
This is (almost) analogous to:
output("output")->connectInput(other->input(input));
The difference is in that this function returns
falsein case of a failure.Parameters
- output
-
the name of the output socket
- other
-
the operation that contains the input we need to connect to
- input
-
the name of the input socket in
other
Returns
trueif both sockets were found,falseotherwise -
Q_INVOKABLE void disconnectAllInputs
()Disconnects all inputs.
-
Q_INVOKABLE void disconnectAllOutputs
()Disconnects all outputs.
-
Returns a pointer to the input associated with name.
Returns
a pointer to the input socket or 0 if no socket matches name
-
virtual Q_INVOKABLE int inputCount
()[virtual]Returns the number of input sockets.
The default implementation returns inputs().size().
-
Q_INVOKABLE QStringList inputNames
()Returns the names of all inputs.
-
Returns a list of all input sockets connected to this operation.
The order in which the sockets are returned should be "intuitive", but no strict restrictions are imposed.
-
virtual void interrupt
()[pure virtual] -
Returns a pointer to the output associated with name.
Returns
a pointer to the output socket or 0 if no socket matches name
-
virtual Q_INVOKABLE int outputCount
()[virtual]Returns the number of output sockets.
The default implementation returns outputs().size().
-
Q_INVOKABLE QStringList outputNames
()Returns the names of all outputs.
-
Returns a list of all output sockets connected to this operation.
Analogous to inputs().
-
virtual void pause
()[pure virtual]Pauses the operation.
The operation should change its state to
Pausing. Pausing has direct effect on producer operations only. If a producer is inPausingstate, it'll finish its current processing round, turn toPausedstate and inform all connected operations that it is now safe to pause. This will finally turn all operations in a pipeline toPausedstate. Before the next start() call, check() will be called with theresetparameter set tofalse.Note that pause() has no effect if the operation is not in
Runningstate. -
Virtual version of QObject::property().
Making a non-virtual function virtual in a subclass is baad. But we need to be able to override this function.
-
ProtectionLevel protectionLevel
(- const char * property
Returns the protection level of property.
-
bool setProperty
A convenience function that automatically creates a QVariant out of a PiiVariant.
PiiOperation* op = ...; op->setProperty("property", Pii::createVariant(PiiMatrix<int>(4,4)));
-
Virtual version of QObject::setProperty().
Making a non-virtual function virtual in a subclass is baad. But we need to be able to override this function to support dotted property names and mutual exclusion.
See also
-
Q_INVOKABLE QString socketName
Returns the name of a socket in the context of this operation.
The name of a socket may change based on nesting level. The same socket may be accessed with multiple names, if it is exported to the interface of an operation compound.
Operations are free to implement any scheme for naming their sockets. For example, PiiBasicOperation uses the
objectNameproperty of the socket, and PiiOperationCompound keeps an internal map of socket aliases. Since there is no default naming scheme, the default implementation returns an empty string.This is a convenience function that calls socketProperty(socket, "name").
Parameters
- socket
-
the socket whose name is to be found
Returns
the name of the socket or an empty string if the socket is not owned by this operation.
-
Returns meta information associated with socket.
This function can be used to query named properties of input and output sockets. Operations are required to provide at least the
nameproperty. Other properties can be used depending on application. Below is a short list of commonly used properies:-
name- the name of the socket in the context of this operation. See socketName(). -
min- the minimum possible scalar value a socket can send/receive -
max- the maximum possible scalar value a socket can send/receive -
resolution- the resolution of the value. Integers have a resolution of 1. If the value can take values only in known steps, theresolutionproperty specifies the step size. -
displayName- a user-displayable name of the socket. May be translated.
Parameters
- socket
-
the socket whose properties are queried
- name
Returns
the value of the property, or an invalid QVariant if the socket is not owned by this operation or the named property does not exist.
See also
-
PiiYdin::isNameProperty()
-
-
Q_INVOKABLE QVariant socketProperty
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
-
virtual void start
()[pure virtual]Starts the operation and executes it until interrupted or paused.
The operation should prepare itself for work and change state to
StartingorRunning.This function will be called not only on start-up but also before restarting after a pause() call.
Note that PiiOperationCompound (and PiiEngine) commands child operations in an arbitrary order. Therefore, objects may appear in the inputs of a operation before start() is invoked. Any resetting action should take place in check().
-
Returns the current state of the operation.
-
virtual void stop
()[pure virtual]Stops the operation.
The operation should change its state to
Stopping. Stopping and pausing work similarly in most cases. Usually, the only difference is in the final state of the operation. Overriding this function makes it possible for an operation to prepare for stopping. The difference betweenstop()and interrupt() is in that the former performs a "clean" stop, which won't leave any object currently being processed in the pipeline.Note that stop() has no effect if the operation is not in
Runningstate. -
virtual bool wait
(- unsigned long time = ULONG_MAX
[pure virtual]Waits for this operation to stop running.
The calling function blocks until the operation stops running or
timemilliseconds has elapsed. By default, the call will never time out. Note that the state of the operation may not have changed yet when this function returns.Returns
trueif the operation exited withintimemilliseconds,falseif the call timed out. -
Returns a string presentation of the given state.
-
Sets the protection level of property to level.
This function is a generic way of controlling write access to properties. By default, all properties writable independent of the state of the operation. Some properties do however affect the internal structure of an operation in a manner that cannot be handled at run time. For example, the number of sockets cannot be changed on the fly without careful handling of the internal synchronization mechanism.
MyOperation::MyOperation() : PiiDefaultOperation(Simple) { // Disallow changing of the processing mode setWritePermission("processingMode", WriteNever); }
Protection is only effective if properties are set through setProperty(). Calling property setters directly bypasses the protection mechanism.
-
Returns a pointer to the mutex that prevents concurrent access to the state of this operation.
void MyOperation::stop() { synchronized (stateLock()) { if (state() == Running) setState(Stopping); } }
-
Signals an error.
The message should be a user-friendly explanation of the cause of the error. sender is the original source of the message.
-
void stateChanged
(- int state
[signal]Indicates that the state of this operation has changed.
If you connect to this signal from outside, make sure you either run an event loop in the receiving thread or create a direct connection. This is needed because the signal will most likely be emitted from another thread. If you create a queued connection and don't run an event loop in the receiving thread, the signal will be lost. If you create a direct connection, you must explicitly implement a mutual exclusion mechanism in the receiving slot.
Add a note
Not a single note added yet. Be the first, add yours.