Batch I/O API reference

Batch I/O API reference#

The hipFile batch I/O API lets you create batch contexts, submit multiple I/O requests in a single call, poll for completion, cancel pending operations, and tear down batch handles. All batch types and functions belong to the batch Doxygen group declared in hipfile.h.

Warning

The batch API is not currently supported on the AMD backend. hipFileBatchIOGetStatus, hipFileBatchIOCancel, and hipFileBatchIODestroy are not implemented and return errors or perform no operation. The maximum batch size is 128 operations.

For related API surfaces, see Synchronous read and write API reference, Asynchronous I/O API reference, and Error handling API reference.

Batch I/O types and functions#

Enumerations, structures, and handles used by batch I/O operations, together with the functions to create, submit, poll, cancel, and destroy batch I/O contexts.

enum hipFileOpcode_t#

The direction of data movement in a batch IO request.

Values:

enumerator hipFileBatchRead#

Read batch IO operation.

enumerator hipFileBatchWrite#

Write batch IO operation.

enum hipFileStatus_t#

The status of a batch IO operation.

Values:

enumerator hipFileWaiting#

Batch IO operation pending acceptance.

enumerator hipFilePending#

Batch IO operation accepted and queued.

enumerator hipFileInvalid#

Batch IO operation was rejected for being invalid or could not be queued.

enumerator hipFileCanceled#

Batch IO operation was canceled.

enumerator hipFileComplete#

Batch IO operation completed.

enumerator hipFileTimeout#

Batch IO operation timed out.

enumerator hipFileFailed#

Batch IO operation failed.

enum hipFileBatchMode_t#

Mode of a batch IO operation.

Values:

enumerator hipFileBatch#

Normal batch IO operation.

typedef void *hipFileBatchHandle_t#

Opaque batch operations handle.

HIPFILE_API hipFileError_t hipFileBatchIOSetUp(hipFileBatchHandle_t *batch_idp, unsigned max_nr)#

Prepare the system to perform a batch IO operation.

Parameters:

  • batch_idp – [out] Opaque handle for batch operations

  • max_nr – [in] Maximum number of requests that can be submitted to this batch handle

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileBatchIOSubmit(hipFileBatchHandle_t batch_idp, unsigned nr, hipFileIOParams_t *iocbp, unsigned flags)#

Enqueue a batch of IO requests for the GPU to complete asynchronously.

Parameters:

  • batch_idp – [in] Opaque handle for batch operations

  • nr – [in] Number of batch IO requests to submit

  • iocbp – [in] An array of nr batch IO requests to submit to the GPU. Data will be read into or written from the buffer specified in each request.

  • flags – [in] Control Flags for the batch IO. Currently unused.

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileBatchIOGetStatus(hipFileBatchHandle_t batch_idp, unsigned min_nr, unsigned *nr, hipFileIOEvents_t *iocbp, struct timespec *timeout)#

Poll for the status of completed batch IO operations.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

  • batch_idp – [in] Opaque handle for batch operations

  • min_nr – [in] Minimum number of batch operation statuses that should be returned. If timeout is exceeded, fewer statuses may be returned.

  • nr – [inout] Maximum number of batch operation statuses that can be returned. This is parameter is modified to return the number of statuses returned in iocbp.

  • iocbp – [out] An array containing up to nr statuses from the overall batch operation

  • timeout – [in] Maximum amount of time this function should poll for status updates

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileBatchIOCancel(hipFileBatchHandle_t batch_idp)#

Cancels all pending batch IO operations.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

batch_idp – [in] Opaque handle for batch operations

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API void hipFileBatchIODestroy(hipFileBatchHandle_t batch_idp)#

Destroys the batch IO handle and frees the associated resources.

Warning

This function is only a stub on AMD and has no effect

Parameters:

batch_idp – [in] Opaque handle for batch operations

struct hipFileIOParams_t#
#include <hipfile.h>

Input parameters for a batch IO request.

struct hipFileIOEvents_t#
#include <hipfile.h>

Status of a batch IO operation.

Contents