7.2. Clara Pipeline Callbacks

The Clara Pipeline Driver is a event based workflow. The set and ordering of the workflow’s event is referred to as the operator life-cycle. The operator life-cycle consists of the following three event as ordered below.

For each event, application (operator) code is allowed to register a callback function with the driver. Callback registration happens as part of nvidia_clara_cpd__start (see: driver). Application code can ignore an event by passing a NULL pointer, instead of a function pointer, to nvidia_clara_cpd__start.

7.2.1. Operator Life-cycle

  1. Prepare

    Called before stage inputs are ready.

    Application code should perform any pre-execute setup or preparation work possible.

    Payload inputs and outputs are not yet available.

  2. Execute

    Called after prepare once stage inputs are ready.

    Application code should perform all core pipeline operator work during this event.

    Payload inputs and outputs are available during this event.

  3. Cleanup

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

    Application code should perform any post-execute clean-up work.

    Payload inputs and outputs are no longer available.

7.2.2. Prepare Callback

Provided by application code to the driver when calling nvidia_clara_cpd__start, and called by the driver once driver initialization has completed. Application code is expected to perform any preparation or setup steps necessary when this function is called.

Providing a preparation callback to the driver is optional. When no callback is provided, the driver will move directly from initialization to waiting for inputs for execution.

see also: Clara Pipeline Driver Start

Parameters

  • cpd

    type: nvidia_clara_cpd *

    direction: In

    Pointer to the Clara Pipeline Driver instance which is calling this function.

Return

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

typedef result (*nvidia_clara_cpd_prepare_callback)(
  IN nvidia_clara_cpd *cpd
);

7.2.3. Execute Callback

Provided by application code to the driver when calling nvidia_clara_cpd__start, and called by the driver once inputs are ready for consumption. Application code will be provided a nvidia_clara_payload pointer which can be used to obtain information about the payload.

Providing an execution callback to the driver is optional. When no callback is provided, the driver will move directly from waiting for inputs to clean-up.

see also: Clara Pipeline Driver Start

Parameters

  • cpd

    type: nvidia_clara_cpd *

    direction: In

    Pointer to the Clara Pipeline Driver instance which is calling this function.

  • payload

    type: nvidia_clara_payload *

    direction: In

    Pointer to the current stage’s payload.

Return

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

typedef result (*nvidia_clara_cpd_execute_callback)(
  IN nvidia_clara_cpd *cpd
  IN nvidia_clara_payload *payload
);

7.2.4. Cleanup Callback

Provided by application code to the driver when calling nvidia_clara_cpd__start, and called by the driver after execution is complete and internal driver clean up has completed. The application is expected to perform any clean or finalization steps during this callback event.

Providing a clean-up callback to the driver is optional. When no callback is provided, the driver will move directly from clean-up to internal finalization.

see also: Clara Pipeline Driver Start

Parameters

  • cpd

    type: nvidia_clara_cpd *

    direction: In

    Pointer to the Clara Pipeline Driver instance which is calling this function.

Return

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

typedef result (*nvidia_clara_cpd_cleanup_callback)(
  IN nvidia_clara_cpd *cpd
);

7.2.5. Notification Callback

Provided by application code to the driver when calling nvidia_clara_cpd__create, and called by the driver when any noteworthy event happens. This includes internal errors.

Providing a notification callback to the driver is optional. When no callback is provided, the driver will be unable to notify application code of any internal errors or critical state changes.

see also: Clara Pipeline Driver Create

Parameters

  • cpd

    type: nvidia_clara_cpd *

    direction: In

    Pointer to the Clara Pipeline Driver instance which is calling this function.

  • result

    type: typedef signed int result

    direction: In

    The return value of the failing function.

  • message

    type: const char *

    direction: In

    String containing a description of the error.

  • is_fatal

    type: int

    direction: In

    Non-zero if the error is fatal; otherwise the error is not fatal.

    When is_fatal indicates that the notification is fatal, the driver will terminate the operator life-cycle once the application code returns from the event handler. In the event of a fatal event, no further life-cycle callbacks handlers (prepare, execute, cleanup) will be invoked.

Return

The notification callback handler cannot return a value to the driver when called.

typedef void (*nvidia_clara_cpd_notification_callback)(
  IN nvidia_clara_cpd *cpd,
  IN result result,
  IN const char *message,
  IN int is_fatal
);