oneapi::mkl::sparse::release_matrix_handle¶
Releases internal data in the provided oneapi::mkl::sparse::matrix_handle_t
object and then frees the handle itself.
Description¶
The oneapi::mkl::sparse::release_matrix_handle
routine releases (also waits for the dependencies to
be finished when provided) any internal data that the oneapi::mkl::sparse::matrix_handle_t
object
holds. It then frees the object itself.
Note
For oneMKL 2023.2 and beyond: Although the address of the matrix_handle_t object is
passed in (matrix_handle_t *p_handle
), it is dereferenced (matrix_handle_t handle = *p_handle;
)
and updated to null
synchronously and then the handle
is passed into the asynchronously scheduled
destruction routines ensuring that asynchronous destruction is safe.
In previous releases, the dereferencing occured asynchronously, which can cause segmentation faults
if p_handle
is a stack variable (such as &handle
) and goes out of scope before the asynchronous
execution (including the dereferencing) begins.
Note
Refer to Error Handling for a detailed description of the possible exceptions thrown.
A recommended usage model is the following
using namespace oneapi::mkl;
// set newly created handle to nullptr before sending to
// init_matrix_handle for initialization
sparse::matrix_handle_t handle = nullptr;
sparse::init_matrix_handle(&handle);
// handle is now initialized and can be filled and used
sparse::set_csr_data(queue, handle, /*matrix sizes and arrays */);
// when finished, clean up the handle
sycl::event ev_release = sparse::release_matrix_handle(queue, &handle, dependencies);
ev_release.wait(); // make it blocking or pass event along to others
API¶
Syntax¶
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 = {});
// deprecated in 2023.0
void release_matrix_handle (
oneapi::mkl::sparse::matrix_handle_t *p_handle,
const std::vector<sycl::event> &dependencies ={});
}
Include Files¶
oneapi/mkl/spblas.hpp
Input Parameters¶
- queue
Specifies the SYCL command queue which will be used for SYCL kernels execution.
- p_handle
The address of the
sparse::matrix_handle_t
handle to object to be released, containing the sparse matrix and other internal data, initialized withoneapi::mkl::sparse::init_matrix_handle
routine, and filled with user data using one of theoneapi::mkl::sparse::set_<sparse_matrix_type>_data
routines. Theoneapi::mkl::sparse::optimize_xyz
routines may have also created additional internally allocated data which would be released in this call.Note
Currently, the only supported case for <sparse_matrix_type> is csr.
- dependencies
A vector of type
const std::vector<sycl::event>
containing the list of any events that thehandle
depends on before executing the release of the matrix handle.
Output Parameters¶
- p_handle
The address of the
sparse::matrix_handle_t
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
SYCL event which can be waited upon or added as a dependency for the completion of the deallocation cleanup routines.
Return Values (deprecated version)¶
In the deprecated version, no sycl::event
is returned and the API is blocking.