Module tornado.api
Package uk.ac.manchester.tornado.api

Class TornadoExecutionPlan

java.lang.Object
uk.ac.manchester.tornado.api.TornadoExecutionPlan
All Implemented Interfaces:
AutoCloseable
Direct Known Subclasses:
ExecutionPlanType
public sealed class TornadoExecutionPlan extends Object implements AutoCloseable permits ExecutionPlanType
Class to create and optimize execution plans for running a set of immutable tasks-graphs on modern hardware. An executor plan contains an executor object, which in turn, contains a set of immutable task-graphs. All actions applied to the execution plan affect to all the immutable graphs associated with it.
Since:
v0.15

  • Field Details

    • DEFAULT_DEVICE

      public static TornadoDevice DEFAULT_DEVICE
      Method to obtain the default device in TornadoVM. The default one corresponds to the device assigned to the driver (backend) with index 0 and device 0.

    • tornadoExecutor

      protected uk.ac.manchester.tornado.api.TornadoExecutor tornadoExecutor
      The TornadoVM executor is a list of chain of actions to be performed. Each action can enable/disable runtime features, influence the compiler, influence the code optimization, adapt runtime parameters, etc.

    • executionFrame

      protected ExecutorFrame executionFrame

    • rootNode

      protected TornadoExecutionPlan rootNode
      Reference to the Root of the List.

    • planResults

      protected List<TornadoExecutionResult> planResults

  • Constructor Details

    • TornadoExecutionPlan

      public TornadoExecutionPlan(ImmutableTaskGraph... immutableTaskGraphs)
      Create an Execution Plan: Object to create and optimize an execution plan for running a set of immutable tasks-graphs. An executor plan contains an executor object, which in turn, contains a set of immutable task-graphs. All actions applied to the execution plan affect to all the immutable graphs associated with it.
      Parameters:
      immutableTaskGraphs - ImmutableTaskGraph

  • Method Details

    • getDevice

      public static TornadoDevice getDevice(int driverIndex, int deviceIndex)
      Method to obtain a specific device using the driver index (backend index) and device index.
      Parameters:
      driverIndex - Integer value that identifies the backend to be used.
      deviceIndex - Integer value that identifies the device within the backend to be used.
      Returns:
      TornadoDevice

    • getTotalPlans

      public static int getTotalPlans()
      Method to return the total number of execution plans instantiated in a single JVM instance.
      Returns:
      int
      Since:
      1.0.2

    • getTornadoDeviceMap

      public static TornadoDeviceMap getTornadoDeviceMap()
      Return a data structure that contains all drivers and devices that the TornadoVM Runtime can access.
      Returns:
      TornadoDeviceMap

    • execute

      public TornadoExecutionResult execute()
      Execute an execution plan. It returns a TornadoExecutionPlan for further build different optimization after the execution as well as obtain the profiler results.
      Returns:
      TornadoExecutionPlan

    • withGraph

      public TornadoExecutionPlan withGraph(int graphIndex)
      Select a graph from the TornadoExecutionPlan to execute. This method allows developers to select a specific graph from the execution plan to launch. Developers can choose which graph from the input list to use (passed in the constructor).
      Parameters:
      graphIndex -
      Returns:
      TornadoExecutionPlan
      Since:
      1.0.9

    • withAllGraphs

      public TornadoExecutionPlan withAllGraphs()
      Select all graphs from the TornadoExecutionPlan. This method has an effect if the withGraph(int) method was invoked.
      Returns:
      TornadoExecutionPlan
      Since:
      1.0.9

    • withPreCompilation

      public TornadoExecutionPlan withPreCompilation()
      It invokes the JIT compiler for all immutable tasks-graphs associated to an executor.
      Returns:
      TornadoExecutionPlan

    • withDevice

      public TornadoExecutionPlan withDevice(TornadoDevice device)
      It selects a specific device for all immutable tasks graphs associated to an executor.
      Returns:
      TornadoExecutionPlan

    • printTraceExecutionPlan

      public void printTraceExecutionPlan()
      Print all operations enabled/disabled from the Execution Plan.
      Since:
      1.0.8

    • getTraceExecutionPlan

      public String getTraceExecutionPlan()
      Returns a string with all the operations enabled/disabled from the Execution Plan.
      Since:
      1.0.8

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • withDevice

      public TornadoExecutionPlan withDevice(String taskName, TornadoDevice device)
      It selects a specific device for one particular task of the task-graph.
      Parameters:
      taskName - The task-name is identified by the task-graph name followed by a dot (".") and the task name. For example: "graph.task1".
      device - The device is an instance of a TornadoDevice
      Returns:
      TornadoExecutionPlan

    • withConcurrentDevices

      public TornadoExecutionPlan withConcurrentDevices()
      It enables multiple tasks in a task graph to run concurrently on the same or different devices. Note that the TornadoVM runtime does not check for data dependencies across tasks when using this API call. Thus, it is the responsibility of the programmer to provide tasks with no data dependencies when invoking the method withConcurrentDevices().
      Returns:
      TornadoExecutionPlan

    • withoutConcurrentDevices

      public TornadoExecutionPlan withoutConcurrentDevices()
      It disables multiple tasks in a task graph to run concurrently on the same or different devices.
      Returns:
      TornadoExecutionPlan

    • getDevice

      public TornadoDevice getDevice(int immutableTaskGraphIndex)
      It obtains the device for a specific immutable task-graph. Note that, ideally, different task immutable task-graph could be executed on different devices.
      Parameters:
      immutableTaskGraphIndex - Index of a specific immutable task-graph
      Returns:
      TornadoExecutionPlan

    • freeDeviceMemory

      public TornadoExecutionPlan freeDeviceMemory()
      Mark all device buffers that correspond to the current execution plan as free in order for the TornadoVM runtime system to reuse those buffers and avoid continuous device memory deallocation and allocation.

      Note that, in this context, "free device memory" means the TornadoVM runtime system marks device buffers to be reusable, thus, for the runtime system, device buffers are no longer linked to the current execution plan.

      Returns:
      TornadoExecutionPlan

    • withGridScheduler

      public TornadoExecutionPlan withGridScheduler(GridScheduler gridScheduler)
      Use a GridScheduler for thread dispatch. The same GridScheduler will be applied to all tasks within the executor. Note that the grid-scheduler API can specify all workers for each task-graph.
      Parameters:
      gridScheduler - GridScheduler
      Returns:
      TornadoExecutionPlan

    • withDefaultScheduler

      public TornadoExecutionPlan withDefaultScheduler()
      Notify the TornadoVM runtime system to utilize the default thread scheduler.
      Returns:
      TornadoExecutionPlan

    • withBatch

      public TornadoExecutionPlan withBatch(String batchSize)
      Enable batch processing. TornadoVM will split the iteration space in smaller batches (with batch size specified by the user). This is used mainly when users want to execute big data applications that do not fit on the device's global memory.
      Parameters:
      batchSize - String in the format a number + "MB" Example "512MB".
      Returns:
      TornadoExecutionPlan

    • withProfiler

      public TornadoExecutionPlan withProfiler(ProfilerMode profilerMode)
      Enables the profiler. The profiler includes options to query device kernel time, data transfers and compilation at different stages (JIT, driver compilation, Graal, etc.).
      Parameters:
      profilerMode - ProfilerMode
      Returns:
      TornadoExecutionPlan

    • withoutProfiler

      public TornadoExecutionPlan withoutProfiler()
      Disables the profiler if previous execution plan had the profiler enabled.
      Returns:
      TornadoExecutionPlan

    • withMemoryLimit

      public TornadoExecutionPlan withMemoryLimit(String memoryLimit)
      This method sets a limit to the amount of memory used on the target hardware accelerator. The TornadoVM runtime will check that the current instance of the TornadoExecutionPlan does not exceed the limit that was specified.
      Parameters:
      memoryLimit - Specify the limit in a string format. E.g., "1GB", "512MB".
      Returns:
      TornadoExecutionPlan

    • withoutMemoryLimit

      public TornadoExecutionPlan withoutMemoryLimit()
      It disables the memory limit for the current instance of an TornadoExecutionPlan. This is the default action. If the memory limit is not set, then the maximum memory to use is set to the maximum buffer allocation (e.g., 1/4 of the total capacity using the OpenCL backend), or the maximum memory available on the target device.
      Returns:
      TornadoExecutionPlan

    • resetDevice

      public TornadoExecutionPlan resetDevice()
      Reset the execution context for the current execution plan. The TornadoVM runtime system will clean the code cache and all events associated with the current execution. It resets the internal GPU/FPGA/CPU execution context to its default values.
      Returns:
      TornadoExecutionPlan

    • getId

      public long getId()
      Obtains the ID that was assigned to the execution plan.

    • getGlobalExecutionPlansCounter

      public long getGlobalExecutionPlansCounter()
      Obtains the total number of execution plans instantiated in a TornadoVM application.

    • clearProfiles

      public TornadoExecutionPlan clearProfiles()
      Clean all events associated with previous executions.
      Returns:
      TornadoExecutionPlan

    • withThreadInfo

      public TornadoExecutionPlan withThreadInfo()
      Enable printing of the Thread-Block Deployment for the generated kernels.
      Returns:
      TornadoExecutionPlan
      Since:
      1.0.2

    • withoutThreadInfo

      public TornadoExecutionPlan withoutThreadInfo()
      Disable printing of the Thread-Block Deployment for the generated kernels.
      Returns:
      TornadoExecutionPlan
      Since:
      1.0.2

    • withPrintKernel

      public TornadoExecutionPlan withPrintKernel()
      Enable printing of the generated kernels for each task in a task-graph.
      Returns:
      TornadoExecutionPlan
      Since:
      1.0.2

    • withoutPrintKernel

      public TornadoExecutionPlan withoutPrintKernel()
      Disable printing of the generated kernels for each task in a task-graph.
      Returns:
      TornadoExecutionPlan
      Since:
      1.0.2

    • withCompilerFlags

      public TornadoExecutionPlan withCompilerFlags(TornadoVMBackendType backend, String compilerFlags)
      Set compiler flags for each backend.
      Parameters:
      backend - TornadoVMBackendType
      compilerFlags - String
      Returns:
      TornadoExecutionPlan
      Since:
      1.0.7

    • close

      public void close() throws TornadoExecutionPlanException
      Specified by:
      close in interface AutoCloseable
      Throws:
      TornadoExecutionPlanException
      Since:
      1.0.4

    • getCurrentDeviceMemoryUsage

      public long getCurrentDeviceMemoryUsage()
      It returns the current memory usage on the device in bytes.
      Returns:
      long Number of bytes used.

    • getPlanResult

      public TornadoExecutionResult getPlanResult(int index)

    • mapOnDeviceMemoryRegion

      public void mapOnDeviceMemoryRegion(Object destTornadoArray, Object srcTornadoArray, long offset, int fromGraphIndex, int toGraphIndex)
      This function maps the device memory region that corresponds to a TornadoVM object to another on-device memory region. This call instructs the TornadoVM runtime to avoid transferring data between `device` -> `host` -> `device`. Instead, it can update the corresponding device pointers.

      The semantics are as follows: there is the source object, and the destination object. This call maps the dest object to the source object from a given offset. The source object is passed from the task-graph `fromGraphIndex`, and the destination object is taken from the `toGraphIndex`. This method can be invoked in a multi-task-graph execution plan. It will not work if there is only one task-graph in the execution plan.

      Parameters:
      destTornadoArray -
      srcTornadoArray -
      offset -
      fromGraphIndex -
      toGraphIndex -
      Since:
      v1.1.0

    • withWarmUpTime

      public TornadoExecutionPlan withWarmUpTime(long milliseconds) throws InterruptedException
      This function allows developers to warm up the whole execution plan before running it. This covers copy in and out data, compiling all tasks and executing all tasks once for the specified amount of time.
      Parameters:
      milliseconds - Amount of time to warm up the execution plan. This amount means that the execution plan will run, at least for the specified amount of time. if the tasks within the task-graphs takes longer to execute, in a second run, the code will not be dispatched.
      Returns:
      TornadoExecutionPlan
      Throws:
      InterruptedException

    • withWarmUpIterations

      public TornadoExecutionPlan withWarmUpIterations(int iterations)
      This function allows developers to warm up the whole execution plan before running it. This covers copy in and out data, compiling all tasks and executing all tasks once for the specified amount of time.
      Parameters:
      iterations - Number of iterations to run the whole execution plan as warm-up.
      Returns:
      TornadoExecutionPlan