Into

Modules

Documentation

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
(
  • int state
)

Indicates that the state of this operation has changed.

Constructors and destructor

Constructs a new PiiOperation.

Public member functions

virtual void
(
  • bool reset
)  = 0

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 *
( )  = 0

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 *
( )  = 0

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
(
  • const char * name
)

Virtual version of QObject::property().

(
  • const char * property
)

Returns the protection level of property.

bool
( )

A convenience function that automatically creates a QVariant out of a PiiVariant.

virtual bool
(
  • const char * name
  • const QVariant & value
)

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
(
  • unsigned long time = ULONG_MAX
)  = 0

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 either Stopped or Paused.

    • WriteWhenStopped - setting the value of a property is allowed only if the state of the operation is Stopped.

    • 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 to false, and the operation should continue where ever it was left.

    Exceptions
    PiiExecutionException&

    if the operation cannot be run.

  • virtual Q_INVOKABLE PiiOperation * clone

    ()
    [virtual]

    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 false in 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

    true if both sockets were found, false otherwise

  • Q_INVOKABLE void disconnectAllInputs

    ()

    Disconnects all inputs.

  • Q_INVOKABLE void disconnectAllOutputs

    ()

    Disconnects all outputs.

  • virtual Q_INVOKABLE PiiAbstractInputSocket * input

    ( )
    [pure virtual]

    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.

  • virtual Q_INVOKABLE QList< PiiAbstractInputSocket * > inputs

    ()
    [pure virtual]

    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]

    Interrupts the execution.

    Calling this function should stop the execution of this operation as soon as possible, even in the middle of a processing round. After an interrupt, the next start() call will be preceded by a check() call with the reset parameter set to true.

  • virtual Q_INVOKABLE PiiAbstractOutputSocket * output

    ( )
    [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.

  • virtual Q_INVOKABLE QList< PiiAbstractOutputSocket * > outputs

    ()
    [pure virtual]

    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 in Pausing state, it'll finish its current processing round, turn to Paused state and inform all connected operations that it is now safe to pause. This will finally turn all operations in a pipeline to Paused state. Before the next start() call, check() will be called with the reset parameter set to false.

    Note that pause() has no effect if the operation is not in Running state.

  • virtual QVariant property

    (
    • const char * name
    )
    [virtual]

    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 bool setProperty

    (
    • const char * name
    • const QVariant & value
    )
    [virtual]

    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 objectName property 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.

  • virtual QVariant socketProperty

    ( )
    [virtual]

    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 name property. 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, the resolution property 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 Starting or Running.

    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().

  • virtual Q_INVOKABLE State state

    ()
    [pure virtual]

    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 between stop() 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 Running state.

  • 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 time milliseconds 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

    true if the operation exited within time milliseconds, false if the call timed out.

  • static const char * stateName

    ( )
    [static]

    Returns a string presentation of the given state.

  • void setProtectionLevel

    ( )
    [protected]

    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.

  • QMutex * stateLock

    ()
    [protected]

    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);
       }
     }
    
  • void errorOccured

    ( )
    [signal]

    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.

Notes (0)

Add a note

Not a single note added yet. Be the first, add yours.