7.17. Clara Pipeline Driver

Application code looking to make use of Clara’s pipeline orchestration must create an instance of Nvidia.Clara.Pipeline.Driver. It is the context by which all other interactions with the Clara Pipeline API are made.

The Driver class constructor accepts a number of method delegates, or “callback handlers”, as well as an object reference to application managed data. The application data reference is the primary method by which the application can pass state to itself as part of the pipeline operator life-cycle.

As the operator life-cycle progresses, each event callback will provide a reference to the instance of Nvidia.Clara.Pipeline.IDriver orchestrating the life-cycle. Using the Nvidia.Clara.Pipeline.IDriver reference, application code can access its application data; thus providing state to itself during the operator life-cycle.

see also: Clara Pipeline Driver Callbacks

7.17.1. Clara Operator Life-Cycle

  1. Prepare

    Called once, before stage inputs are ready.

    delegate bool DriverPrepareDelegate(IDriver driver);
    
  2. Execute

    Called once, after prepare once stage inputs are ready.

    delegate bool DriverExecuteDelegate(IDriver driver, IPayload payload);
    
  3. Cleanup

    Called once, after execute before the operator life-cycle terminates.

    delegate bool DriverCleanupDelegate(IDriver driver);
    

Additionally, a callback handler for notifications can be supplied. The driver will pass notifications to application code whenever a significant event or error occurs. This is a useful way for application code to know what is happening “inside” the driver, and a useful tool when trying to debug issues involving Clara Pipeline Driver interaction.

see also: Clara Pipeline Driver Callbacks

7.17.1.1. Application Data

Gets the application data reference provided to the Nvidia.Clara.Pipeline.Driver constructor; or null if one was not.

Return

Returns a System.Object reference.

object ApplicationData { get; }

7.17.1.2. Job Identity

Gets the unique identity of the currently executing pipeline job.

Return

Returns a System.Guid.

Guid JobId { get; }

7.17.1.3. Job Name

Gets the name of the currently executing pipeline job.

Return

Returns a System.String reference.

string JobName { get; }

7.17.1.4. Stage Name

Gets the name of the currently executing pipeline stage.

Return

Returns a System.String reference.

string  StageName { get; }

7.17.1.5. Stage Timeout

Gets the maximum amount of time the currently executing pipeline stage is alloted.

Return

Returns a System.TimeSpan.

TimeSpan StageTimeout { get; }

7.17.1.6. Start

Starts the Clara Pipeline Driver operator life-cycle.

.Start() should only be called once per instance of Nvidia.Clara.Pipeline.IDriver, additional calls will throw an exception.

Once called the Clara Pipeline Driver will begin work immediately using its own internal thread-pool. Any event callback handlers will be called using the driver’s thread-pool. This means that once .Start() is called, the application should not terminate before the driver has completed its work. The easiest way to ensure the driver has completed all work is to use .WaitForCompletion().

void Start()

7.17.1.7. Wait for Completion

Calling .WaitForCompletion() blocks the calling thread until the operator life-cycle has completed. Requires the operator life-cycle has been started using .Start().

Calling this method before calling .Start() will result in an exception being throw; and the calling thread will not be blocked.

Calling this method after the operator life-cycle has complete is safe, and will return immediately.

void WaitForCompletion()