8.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
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;
}
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;
}
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
);
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)
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)