Releases internal data and sets matrix_handle_t object to NULL.

Description and Assumptions

The oneapi::mkl::sparse::release_matrix_handle releases any internal data that the matrix_handle_t object holds and sets it with defaults values, otherwise it throws an exception. The routine also waits for the dependencies to be finished before releasing any data in case of USM.


namespace oneapi::mkl::sparse {

   sycl::event release_matrix_handle (sycl::queue                           &queue,
                                      oneapi::mkl::sparse::matrix_handle_t  *p_handle,
                                      const std::vector<sycl::event>        &dependencies = {});


Input parameters


The SYCL command queue which will be used for SYCL kernels execution.


The address of the sparse::matrix_handle_t p_handle object to be released, containing sparse matrix and other internal data. Initialized with oneapi::mkl::sparse::init_matrix_handle routine, and filled with user data using one of the oneapi::mkl::sparse::set_<sparse_matrix_type>_structure routines.


List of events that p_handle depends on. The call waits on the events(if any) before resetting the p_handle to default values.

Output parameters


The address of the sparse::matrix_handle_t p_handle that will be scheduled to be updated to point to a null object and the passed in handle will be scheduled for deallocation and cleanup.

Return Values


SYCL event which can be waited upon or added as a dependency for the completion of the deallocation and cleanup routines.


This routine shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here.