vtkExecutionScheduler.h

/*=========================================================================

  Program:   Visualization Toolkit
  Module:    vtkExecutionScheduler.h

  Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
  All rights reserved.
  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.

     This software is distributed WITHOUT ANY WARRANTY; without even
     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
     PURPOSE.  See the above copyright notice for more information.

=========================================================================*/
/*-------------------------------------------------------------------------
  Copyright (c) 2008, 2009 by SCI Institute, University of Utah.
  
  This is part of the Parallel Dataflow System originally developed by
  Huy T. Vo and Claudio T. Silva. For more information, see:

  "Parallel Dataflow Scheme for Streaming (Un)Structured Data" by Huy
  T. Vo, Daniel K. Osmari, Brian Summa, Joao L.D. Comba, Valerio
  Pascucci and Claudio T. Silva, SCI Institute, University of Utah,
  Technical Report #UUSCI-2009-004, 2009.

  "Multi-Threaded Streaming Pipeline For VTK" by Huy T. Vo and Claudio
  T. Silva, SCI Institute, University of Utah, Technical Report
  #UUSCI-2009-005, 2009.
-------------------------------------------------------------------------*/
// .NAME vtkExecutionScheduler - Scheduling execution with
// thread/computing resources distributing
// .SECTION Description
// This is a class for balancing the computing resources throughout
// the network

// .SECTION See Also
// vtkComputingResources vtkThreadedStreamingPipeline

#ifndef __vtkExecutionScheduler_h
#define __vtkExecutionScheduler_h

#include "vtkObject.h"

class vtkExecutive;
class vtkComputingResources;
class vtkMultiThreader;
class vtkMutexLock;
class vtkThreadMessager;
class vtkInformation;
class vtkInformationIntegerKey;
class vtkExecutiveCollection;

class VTK_FILTERING_EXPORT vtkExecutionScheduler : public vtkObject
{
public:
  static vtkExecutionScheduler* New();
  vtkTypeMacro(vtkExecutionScheduler,vtkObject);
  void PrintSelf(ostream &os, vtkIndent indent);

  // Description:
  // Return the global instance of the scheduler 
  static vtkExecutionScheduler *GetGlobalScheduler();

 // Description:
  // Key to store the priority of a task
  static vtkInformationIntegerKey* TASK_PRIORITY();

  // Description:  
  // Put the current set of executives (modules) to the be scheduled given its
  // dependency graph which will be used to compute the set
  // topological orders
  void Schedule(vtkExecutiveCollection *execs, vtkInformation *info);
  
  // Description:
  // Put the current set of executives (modules) to the be scheduled
  // given its dependency graph which will be used to compute the set
  // topological orders. Then wait for their execution to be complete
  void SchedulePropagate(vtkExecutiveCollection *execs, vtkInformation *info);
  
  // Description:
  // Wait until the current set of executives (modules) have finished executing
  void WaitUntilDone(vtkExecutiveCollection *execs);
  
  // Description:  
  // Wait until the current set of executives (modules) have their inputs released
  void WaitUntilReleased(vtkExecutiveCollection *execs);

  // Description:
  // Wait for all tasks to be done
  void WaitUntilAllDone();
  
  // Description:
  // Wait for a task that is on the scheduling queue to be done. If
  // the task is not there, this will return immediately. If the exec
  // is NULL, any task that is done will trigger this the return
  void WaitForTaskDone(vtkExecutive *exec);
  
  // Description:
  // Similar to WaitForTaskDone but return whenever input connections
  // of a task are released instead of done computing. But exec cannot
  // be NULL.
  void WaitForInputsReleased(vtkExecutive *exec);
  
  // Description:
  // Return the thread messager reserved for the given exec to notify
  // when it is done
  vtkThreadMessager* GetTaskDoneMessager(vtkExecutive *exec);

  // Description:
  // Return the thread messager reserved for the given exec to notify
  // when it releases its inputs
  vtkThreadMessager* GetInputsReleasedMessager(vtkExecutive *exec);

  // Description:
  // Return the mutex lock reserved for the given exec to notify
  // when it releases its inputs
  vtkMutexLock* GetInputsReleasedLock(vtkExecutive *exec);

  // Description:
  // Release the resources that are being used by the given exec
  void ReleaseResources(vtkExecutive *exec);

  // Description:
  // Re-acquire the resource released earlier by ReleaseResource
  void ReacquireResources(vtkExecutive *exec);

  // Description:  
  // Redistribute the thread resources over the network from a sink
  // with a maximum resource
  void RescheduleNetwork(vtkExecutive *sink);
  
  // Description:  
  // Redistribute the thread resources from a sink given a certain
  // amount of resource
  void RescheduleFrom(vtkExecutive *sink, vtkComputingResources *resources);

protected:
  vtkExecutionScheduler();
  ~vtkExecutionScheduler();

  vtkComputingResources       *Resources;
  vtkThreadMessager           *ScheduleMessager;
  vtkThreadMessager           *ResourceMessager;
  vtkMutexLock                *ScheduleLock;
  vtkMultiThreader            *ScheduleThreader;
  int                          ScheduleThreadId;

//BTX
  class implementation;
  implementation* const Implementation;
  friend class implementation;

  // Description:  
  // The scheduling thread that is responsible for queueing up module
  // execution in the right order
  friend void * vtkExecutionScheduler_ScheduleThread(void *data);

  // Description:  
  // Execute thread function that is responsible for forking process
  // for each module
  friend void * vtkExecutionScheduler_ExecuteThread(void *data);

//ETX

private:
  vtkExecutionScheduler(const vtkExecutionScheduler&);  // Not implemented.
  void operator=(const vtkExecutionScheduler&);  // Not implemented.
  
};

#endif