oneapi::mkl::sparse::release_matrix

oneMKL - Data Parallel C++ Developer Reference

Download PDF

ID 772045

Date 6/24/2024

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-367BBD8E-1868-4537-AD35-F01145236AAF

View Details

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
API

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_spMat), it is dereferenced (matrix_handle_t handle = *p_spMat;) 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_spMat 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 spMat = nullptr;
sparse::init_matrix_handle(&spMat);

// handle is now initialized and can be filled and used

sparse::set_csr_data(queue, spMat, /*matrix sizes and arrays */);

// when finished, clean up the handle
sycl::event ev_release = sparse::release_matrix_handle(queue, &spMat, 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_spMat,
        const std::vector<sycl::event> &dependencies = {});

    // deprecated in 2023.0
    [[deprecated("Use oneapi::mkl::sparse::release_matrix_handle(queue, p_spMat, dependencies) instead.")]]
    void release_matrix_handle (
        oneapi::mkl::sparse::matrix_handle_t *p_spMat,
        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_spMat: 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:
The supported cases for <sparse_matrix_type> are csr and coo on both CPU and GPU devices.
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_spMat: 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.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

oneMKL - Data Parallel C++ Developer Reference

oneapi::mkl::sparse::release_matrix_handle

Description

API