Into

Modules

Documentation

classPiiDefaultFlowController

#include <PiiDefaultFlowController.h>

The default flow controller handles inter-operation synchronization by grouping synchronous sockets and injecting special synchronization tags into the sockets.

Inherits PiiFlowController

Description

It handles hierarchical relations between synchronized socket groups. Due to the extra checking needed for this, PiiDefaultFlowController is used by PiiDefaultOperation only if there is no more efficient specialization available.

See also

Classes

struct
PiiDefaultFlowController::Relation

A structure for storing information about parent-child relationships.

Public types

typedef QList< Relation >
RelationList

Constructors and destructor

PiiDefaultFlowController
( )

Create a new flow controller.

~PiiDefaultFlowController
( )

Public member functions

virtual FlowState
prepareProcess
( )

Prepare the sockets for processing.

virtual void
sendSyncEvents
( )

Send queued sync events to listener.

Static public member functions

static Relation
looseRelation
(
  • int parent
  • int child
)

A utility function that creates a loose relationship between two groups, denoted by parent and child.

static Relation
strictRelation
(
  • int parent
  • int child
)

A utility function that creates a strict relationship between two groups, denoted by parent and child.

Function details

  • PiiDefaultFlowController

    ( )

    Create a new flow controller.

    The relations parameter is used to assign parent-child relations between input groups. PiiDefaultFlowController can handle many independent groups of synchronized sockets. This parameter makes it possible to place restrictions to inter-group synchronization.

    There are two types of parent-child relationships: strict and loose. In a strict relationship, a child group can only receive data once its parent has received data. This is sometimes necessary, but requires special care in building the configuration to prevent deadlocks. For example, PiiObjectReplicator needs to receive the object to be replicated before it can replicate it. In a loose relationship, either the parent or the child may become first. In both cases, a sync event will be sent just before an object in a parent group or any of its children is to be processed. The parent group will be suspended until all data related to the object(s) in the parent group has been processed by the child groups. Once this happens, another sync event will be sent with the parent's group id. 

     MyOperation::MyOperation()
 {
   // Receives large images
   PiiInputSocket* imageInput = new PiiInputSocket("image");
   // Receives smaller pieces of the large image, for example
   // via a PiiImageSplitter
   PiiInputSocket* pieceInput = new PiiInputSocket("subimage");
   // Receives the locations of the image pieces.
   PiiInputSocket* locationInput = new PiiInputSocket("location");

   addSocket(imageInput);
   addSocket(pieceInput);
   addSocket(locationInput);

   // Group the inputs. (imageInput remains is the default group 0)
   pieceInput->setGroupId(1);
   locationInput->setGroupId(1);
   // The default implementation of createFlowController() would
   // assign a loose relationship between groups 0 and 1. We want
   // a strict relationship.
 }

 PiiFlowController* MyOperation::createFlowController()
 {
   // Establish a strict parent-child relationship.
   PiiDefaultFlowController::RelationList lstRelations;
   lstRelations << PiiDefaultFlowController::strictRelation(0, 1);
   return new PiiDefaultFlowController(_lstInputs,
                                       _lstOutputs,
                                       lstRelations);
 }
    Parameters
    inputs

    a list of inputs to be controlled

    outputs

    the a list of outputs to be controlled

    relations

    a list of parent-child relations. Each entry in the list assigns a parent-child relationship between the given two group ids.

  • ~PiiDefaultFlowController

    ()

  • virtual FlowState prepareProcess

    ()
    [virtual]

    Prepare the sockets for processing.

    This function is called by PiiOperationProcessor just before it starts a processing round. If processing can be performed, this function places the necessary objects into the input sockets.

    If you reimplement this function yourself, you must conform to the following:

    • If any of the connected sockets in a group does not contain an object, IncompleteState must be returned.

    • If all inputs contain sync tags, they need to be passed to synchronized outputs (PiiOutputSocket::emitObject()) and SynchronizedState must be returned. The inputs must be released (PiiInputSocket::release()).

    • If all inputs contain stop/pause/resume tags, the operation must be either stopped, paused or resumed. The function must return FinishedState, PausedState, or ResumedState, respectively. The caller is responsible for passing the control objects in these cases. PiiOperationProcessor uses PiiBasicOperation::operationStopped(), PiiBasicOperation::operationPaused(), and PiiBasicOperation::operationResumed() helper functions for this. The inputs must be released.

    • If all inputs in a group contain ordinary objects (PiiYdin::isNonControlType()), move objects to be processed from incoming to outgoing slots with PiiInputSocket::release() and return ProcessableState. Only one group can be processed at once. The caller is responsible for re-invoking this function to make sure all processable groups will be handled. Set the active group to the group id of the active group.

    • If a group of synchronized inputs contains mixed inputs (e.g. ordinary objects and sync tags), a PiiExecutionException must be thrown.

    • Synchronization events (if any) should be queued. The sendSyncEvents(SyncListener*) function empties the queue.

    Returns

    If all inputs contain stop, pause, or resume tags, either FinishedState or PausedState, or ResumedState will be returned. Otherwise, returns ProcessableState when a processing round can be performed and IncompleteState when not. Processing can be performed if a group of synchronized sockets is filled with ordinary objects. If a group is filled with synchronization objects, SynchronizedState will be returned.

    Exceptions
    PiiExecutionException&

    if a synchronization error occurs or the listener's inputInSync() function throws.

    Reimplemented from PiiFlowController.

  • virtual void sendSyncEvents

    ( )
    [virtual]

    Send queued sync events to listener.

    Empty the event queue. The default implementation does nothing.

    Reimplemented from PiiFlowController.

  • static Relation looseRelation

    (
    • int parent
    • int child
    )
    [static]

    A utility function that creates a loose relationship between two groups, denoted by parent and child.

  • static Relation strictRelation

    (
    • int parent
    • int child
    )
    [static]

    A utility function that creates a strict relationship between two groups, denoted by parent and child.

Notes (0)

Add a note

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