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 with oneapi::mkl::sparse::init_matrix_handle routine, and filled with user data using one of the oneapi::mkl::sparse::set_<sparse_matrix_type>_data routines. The oneapi::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 the handle 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.