.. _oneapi-mkl-sparse-release_matrix_handle:

oneapi::mkl::sparse::release_matrix_handle
==========================================


Releases internal data and sets ``oneapi::mkl::sparse::matrix_handle_t``
object to NULL.


.. contents::
    :local:
    :depth: 1

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 and sets it with default values, otherwise throws an exception.

.. note::
   Refer to :ref:`Exceptions <exceptions>` for a detailed description of the exceptions thrown.



API
***

Syntax
------

.. code-block:: cpp

    namespace oneapi::mkl::sparse {
        void release_matrix_handle (
            oneapi::mkl::sparse::matrix_handle_t *handle,
            const std::vector<cl::sycl::event> & dependencies ={});
    }



Include Files
-------------

-  oneapi/mkl/spblas.hpp


Input Parameters
----------------

handle
   Handle to object 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>_data`` 
   routines.  The ``oneapi::mkl::sparse::optimize_xxx`` routines may have also created 
   additional internally allocated data which would need to be released.  User provided data is 
   not release, but ownership passes back to the user for proper handling.

   .. note::
      Currently, the only supported case for `<sparse_matrix_type>` is csr.

dependencies
   A vector of type ``std::vector<cl::sycl::event>``
   containing the list of events that handle depends on before
   resetting it to default values.