7.8. Clara Pipeline Payload

Application code looking to make use of Clara’s pipeline orchestration should utilize of Clara Pipeline Driver life-cycle and register an execute callback handler. Since the nvidia_clara_payload type is opaque, application code must rely passing a nvidia_clara_cpd_execute_callback function pointer to nvidia_clara_cpd__start. When the function is called, a pointer to the current stage’s payload (nvidia_clara_payload) will be passed to application code.

Application code should not free any nvidia_clara_payload* pointers, nor should application code retain such pointers beyond the lifetime of the application supplied execution callback handler.

Using the supplied pointer enables application code to iterate through the list of name / path pairs for both inputs and outputs.

see also: Clara Pipeline Driver and Clara Pipeline Driver Callbacks

7.8.1. Input Entries

Returns an array of nvidia_clara_payload_entry pointers. The array is NULL terminated, which is to say that the last entry in the array will be a NULL pointer.

The set of input entries returned when calling this function is determined by the pipeline definition. Pipeline definitions declare a set of input values for each operator. Those input values are represented as payload entries.

Payload entries and the array they’re returned in should not be freed by application code. The driver will handle all resource clean up of these resources.

see also: Payload Entry

Parameters

  • payload

    type: nvidia_clara_payload *

    direction: In

    Pointer to the current stage’s pipeline payload.

  • entries_out

    type: nvidia_clara_payload_entry ***

    direction: Out

    Pointer to a null terminated array of nvidia_clara_payload_entry pointers.

Return

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

result nvidia_clara_payload__input_entries(
  IN nvidia_clara_payload *payload,
  OUT nvidia_clara_payload_entry ***entries_out
);

Iterating the array requires the iterator to keep track of the index, and to check of the current index is NULL or not before processing it.

example:

int application_execution_callback(nvidia_clara_cpd *cpd, nvidia_clara_payload *payload) {
  nvidia_clara_payload_entry **entries;
  result r = 0;

  // Get input entries from the payload.
  r = nvidia_clara_payload__input_entries(payload, &entries);
  if (r != 0) {
    printf("Failed to read input entries from payload (%d)\n", r);
    goto exit;
  }

  for (int i = 0; entries[i]; i += 1) {
    // do something with input entries here.
  }

exit:

  /* !!! Do not free cpd, payload, or entry pointers !!! */

  return r;
}

7.8.2. Output Entries

Returns an array of nvidia_clara_payload_entry pointers. The array is NULL terminated, which is to say that the last entry in the array will be a NULL pointer.

The set of output entries returned when calling this function is determined by the pipeline definition. Pipeline definitions declare a set of output values for each operator. Those output values are represented as payload entries.

Payload entries and the array they’re returned in should not be freed by application code. The driver will handle all resource clean up of these resources.

see also: Payload Entry

Parameters

  • payload

    type: nvidia_clara_payload *

    direction: In

    Pointer to the current stage’s pipeline payload.

  • entries_out

    type: nvidia_clara_payload_entry ***

    direction: Out

    Pointer to a null terminated array of nvidia_clara_payload_entry pointers.

Return

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

result nvidia_clara_payload__output_entries(
  IN nvidia_clara_payload *payload,
  OUT nvidia_clara_payload_entry ***entries_out
);

Iterating the array requires the iterator to keep track of the index, and to check of the current index is NULL or not before processing it.

example:

int application_execution_callback(nvidia_clara_cpd *cpd, nvidia_clara_payload *payload) {
  nvidia_clara_payload_entry **entries;
  result r = 0;

  // Get output entries from the payload.
  r = nvidia_clara_payload__output_entries(payload, &entries);
  if (r != 0) {
    printf("Failed to read output entries from payload (%d)\n", r);
    goto exit;
  }

  for (int i = 0; entries[i]; i += 1) {
    // do something without output entries
  }

exit:

  /* !!! Do not free cpd, payload, or entry pointers !!! */

  return r;
}

7.8.3. Fast I/O Context

Returns the nvidia_clara_fastio_context* that is being provided by the pipeline payload.

Application code should not free any nvidia_clara_fastio_context* pointers, nor should application code retain such pointers beyond the lifetime of the application supplied execution callback handler.

see also: Fast I/O Context

Parameters

  • payload

    type: nvidia_clara_payload *

    direction: In

    Pointer to the current stage’s pipeline payload.

  • context_out

    type: nvidia_clara_fastio_context **

    direction: Out

    Pointer to the payload’s Fast I/O context.

Return

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

result nvidia_clara_payload__fastio_context(
    IN nvidia_clara_payload *payload,
    OUT nvidia_clara_fastio_context **context_out
);

7.8.4. Fast I/O Input Entries

Returns an array of nvidia_clara_fastio_entry pointers. The array is NULL terminated, which is to say that the last entry in the array will be a NULL pointer.

The set of input entries returned when calling this function is determined by the pipeline definition. Pipeline definitions declare a set of input values for each operator. Those input values with type = {array, string} or any Clara primitives (uint8,uint16,uint32,uint64,int8,int16,int32,int64,float16,float32,float64) are represented as FastIO payload input entries.

FastIO payload input entries and the array they’re returned in should not be freed by application code. The driver will handle all resource clean up.

see also: FastIO Entry

Parameters

  • payload

    type: nvidia_clara_payload *

    direction: In

    Pointer to the current stage’s pipeline payload.

  • context_out

    type: nvidia_clara_fastio_entry ***

    direction: Out

    Pointer to the payload’s Fast I/O Input Entries.

Return

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

result nvidia_clara_payload__fastio_input_entries(
        IN nvidia_clara_payload *payload,
       OUT nvidia_clara_fastio_entry ***entries_out)

7.8.5. Fast I/O Output Entries

Returns an array of nvidia_clara_fastio_entry pointers. The array is NULL terminated, which is to say that the last entry in the array will be a NULL pointer.

The set of output entries returned when calling this function is determined by the pipeline definition. Pipeline definitions declare a set of output values for each operator. Those output values with type = {array, string} or any Clara primitives (uint8,uint16,uint32,uint64,int8,int16,int32,int64,float16,float32,float64) are represented as FastIO payload output entries.

FastIO payload output entries and the array they’re returned in should not be freed by application code. The driver will handle all resource clean up.

see also: FastIO Entry

Parameters

  • payload

    type: nvidia_clara_payload *

    direction: In

    Pointer to the current stage’s pipeline payload.

  • context_out

    type: nvidia_clara_fastio_entry ***

    direction: Out

    Pointer to the payload’s Fast I/O Output Entries.

Return

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

result nvidia_clara_payload__fastio_output_entries(
        IN nvidia_clara_payload *payload,
       OUT nvidia_clara_fastio_entry ***entries_out)