7.3. Clara Pipeline Driver

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

Since the nvidia_clara_cpd type is opaque, application code must use nvidia_clara_cpd__create to create a new instance; and nvidia_clara_cpd__release to release an instance after usage is complete.

see also: Clara Pipeline Driver Callbacks

Header: clara_cpd.h

Creates a new instance of Clara Pipeline Driver. When an application provides a notification callback, it will receive state change updates, and error information from the driver. When no callback is provided, the driver will not send updates to the application.

When an instance of Clara Pipeline Driver is created, application code can optionally register a pointer to application_data. This pointer will be made available to provided event handlers when they are called. The intent of this pointer to enable application code to avoid the use of global or static allocations as a method of managing data context in a callback driven model.

see also: Clara Pipeline Driver Callbacks

Parameters

• notification_callback

  type: nvidia_clara_cpd_notification_callback

  direction: In

  Function pointer. Used to pass runtime and error details to the caller. Use NULL to disable this event notification.

• application_data

  type: void *

  direction: In

  Pointer which is passed to event handlers.

• cpd_out

  type: nvidia_clara_cpd **

  direction: Out

  Pointer to a newly allocated and initialized nvidia_clara_cpd *.

Return

Returns zero if successful; otherwise a non-zero value.

            

            
result nvidia_clara_cpd__create(
  IN nvidia_clara_cpd_notification_callback notification_callback,
  IN void *application_data,
  OUT nvidia_clara_cpd **cpd_out
);
        

Queries Clara Pipeline Driver for pipeline job and stage information. Information is always returned as a string written to the buffer argument. Additionally, the size of the information (string length plus terminating \0 character) len_out argument.

The buffer to which the information is written must be allocated by the application prior to calling this function. When called, if the buffer argument is NULL or the value of buffer_size is insufficient, the call will fail. The minimum buffer size will still be returned via len_out, and application code can use this behavior to query the minimum size of buffer before allocating.

Parameters

• cpd

  type: nvidia_clara_cpd *

  direction: In

  Pointer to a Clara Pipeline Driver instance.

• info_kind

  type: nvidia_clara_info

  direction: In

  Enumeration value indicating which information to return.

• buffer

  type: char *

  direction: In

  Character buffer which to write the information to.

• buffer_size

  type: size_t

  direction: In

  The size, in bytes, of buffer.

• len_out

  type: size_t *

  direction: Out

  The size, in bytes, of the information, including any trailing ‘0’.

Return

Returns zero if successful; otherwise a non-zero value.

            

            
result nvidia_clara_cpd__query(
  IN nvidia_clara_cpd *cpd,
  IN nvidia_clara_info info_kind,
  IN char *buffer,
  IN size_t buffer_size,
  OUT size_t *len_out
);
        

7.3.2.1. Clara Query Enumeration

Application code can query the pipeline driver for information about the current pipeline. Clara Query Interface supports the following queries.

1. Job Identity

   Application code can query the identity of the current pipeline job. This value is generated by the Clara Platform when the job is created, and is available to all operators executing as part of a pipeline job.

2. Job Name

   Application code can query the name of the current pipeline job. This value is either passed to the Clara Platform or generated by Clara Platform when the job is created, and is available to all operators executing as part of a pipeline job.

3. Stage Name

   Application code can query the name of the current executing operator, or stage. This value is declared as part of the executing pipeline’s pipeline definition. Each operator, or stage, can query the name assigned to it, but has no access to the names of other stages.

4. Stage Timeout

   Application code can query the maximum alloted allocated for the current pipeline stage. Each operator can query the alloted time alloted for its stage, but has no access the timeout values assigned to other stages.

            

            
typedef enum nvidia_clara_info_t
{
  NVIDIA_CLARA_INFO_JOB_ID = 1,
  NVIDIA_CLARA_INFO_JOB_NAME = 2,
  NVIDIA_CLARA_INFO_STAGE_NAME = 3,
  NVIDIA_CLARA_INFO_STAGE_TIMEOUT = 4,
  NVIDIA_CLARA_INFO_MAX,
} nvidia_clara_info;
        

Releases all resources associated with an instance of Clara Pipeline Driver. This function should only be called once an operator has completed all assigned work. If this function is called while an operator is processing work, the results are non-deterministic.

Parameters

• cpd

  type: nvidia_clara_cpd *

  direction: In

  Pointer to the Clara Pipeline Driver instance to be released.

Return

Returns zero if successful; otherwise a non-zero value.

            

            
result nvidia_clara_cpd__release(
  IN nvidia_clara_cpd *cpd
);
        

Starts the operator life-cycle. Once nvidia_clara_cpd__start has been called, the driver will perform internal initialization, then the ‘prepare callback’. Next the driver will wait until all inputs are available before calling the ‘execute callback’. Finally, the driver will clean up execution-payload resources before calling the ‘cleanup callback’.

When calling nvidia_clara_cpd__start a valid nvidia_clara_cpd pointer initialized by nvidia_clara_cpd__create is required. Additionally, three optional life-cycle callback function pointers can be passed.

1. Prepare

   Called before stage inputs are ready.

2. Execute

   Called after prepare once stage inputs are ready.

3. Cleanup

   Called after execute before the driver’s stage life-cycle terminates.

see also: Clara Pipeline Driver Callbacks

Parameters

• cpd

  type: nvidia_clara_cpd *

  direction: In

  Pointer to a Clara Pipeline Driver instance.

• prepare_callback

  type: nvidia_clara_cpd_prepare_callback

  direction: In

  Function pointer. Calls the provided function when the prepare event occurs. Use NULL to ignore this event.

• execute_callback

  type: nvidia_clara_cpd_execute_callback

  direction: In

  Function pointer. Calls the provided function when the execute event occurs. Use NULL to ignore this event.

• cleanup_callback

  type: nvidia_clara_cpd_cleanup_callback

  direction: In

  Function pointer. Calls the provided function when the cleanup event occurs. Use NULL to ignore this event.

Return

Returns zero if successful; otherwise a non-zero value.

            

            
result nvidia_clara_cpd__start(
  IN nvidia_clara_cpd *cpd,
  IN nvidia_clara_cpd_prepare_callback prepare_callback,
  IN nvidia_clara_cpd_execute_callback execute_callback,
  IN nvidia_clara_cpd_cleanup_callback cleanup_callback
);
        

Blocks the calling thread until the stage life-cycle has completed. Requires an initialized nvidia_clara_cpd pointer using nvidia_clara_cpd__create, and the stage’s life-cycle has been started using nvidia_clara_cpd__start.

This utility function is not a required, and it provided as a means of waiting for callbacks without exiting a process.

Calling this function before calling nvidia_clara_cpd__start will result in an error code being returned; and the calling thread will not be blocked.

Return

Returns zero if successful; otherwise a non-zero value.

            

            
result nvidia_clara_cpd__wait_for_completion(
  /* [in] Pointer to the cpd instance to block on. */
  IN nvidia_clara_cpd *cpd
);