% -*- latex -*-

\chapter{Execution Objects}
\label{chap:ExecutionObjects}

\index{worklet|(}
\index{worklet!creating|(}

\index{execution object|(}
\index{worklet!execution object|(}
\index{control signature!execution object|(}

Although passing whole arrays and cell sets into a worklet is a convenient way to provide data to a worklet that is not divided by the input or output domain, they are sometimes not the best structures to represent data.
Thus, all worklets support a another type of argument called an \keyterm{execution object}, or exec object for short, that provides a user-defined object directly to each invocation of the worklet.
This is defined by an \sigtag{ExecObject} tag in the \controlsignature.

The execution object must be a subclass of \vtkmcont{ExecutionObjectBase}.
Also, it must implement a \classmember*{ExecutionObjectBase}{PrepareForExecution} method declared with \vtkmcontmodifier.
\classmember*{ExecutionObjectBase}{PrepareForExecution} should take two arguments.
The first argument is the device adapter tag.
The second argument is a \vtkmcont{Token} object that should be used to scope any execution objects created internally.

The \classmember*{ExecutionObjectBase}{PrepareForExecution} function creates an execution object that can be passed from the control environment to the execution environment and be usable in the execution environment, and any method of the produced object used within the worklet must be declared with \vtkmexecmodifier or \vtkmexeccontmodifier.

An execution object can refer to an array, but the array reference must be through an array portal for the execution environment.
This can be retrieved from the \classmember{ArrayHandle}{PrepareForInput} method as described in Section \ref{sec:ArrayHandle:InterfaceToExecutionEnvironment}.
Other \VTKm data objects, such as the subclasses of \vtkmcont{CellSet}, have similar methods.

Returning to the example we have in Section \ref{sec:WholeArrays}, we are computing triangle quality quickly by looking up the value in a table.
In Example \ref{ex:TriQualityWholeArray} (page \pageref{ex:TriQualityWholeArray}) the table is passed directly to the worklet as a whole array.
However, there is some additional code involved to get the appropriate index into the table for a given triangle.
Let us say that we want to have the ability to compute triangle quality in many different worklets.
Rather than pass in a raw array, it would be better to encapsulate the functionality in an object.

We can do that by creating an execution object with a \classmember*{ExecutionObjectBase}{PrepareForExecution} method that creates an object that has the table stored inside and methods to compute the triangle quality.
The following example uses the table built in Example \ref{ex:TriQualityWholeArray} to create such an object.

\vtkmlisting[ex:TriQualityExecObject]{Using \protect\sigtag{ExecObject} to access a lookup table in a worklet.}{TriangleQualityExecObject.cxx}

\index{control signature!execution object|)}
\index{worklet!execution object|)}
\index{execution object|)}

\index{worklet!creating|)}
\index{worklet|)}
