From ae6db7c303d5f581601a5bc2727ff06fea4d00d2 Mon Sep 17 00:00:00 2001 From: kliegeois Date: Wed, 16 Sep 2026 14:24:59 -0600 Subject: [PATCH] docs(rocsparse): publish rocsparse_handle_create/destroy reference rocsparse_handle_create and rocsparse_handle_destroy were added to the public header with complete Doxygen comments, but no Breathe directive ever referenced them, so they never appeared on the documentation site. Users searching for the stream-ordered handle constructor found nothing. Add the missing doxygenfunction sections to the auxiliary reference, list both functions in the exported-function table, and describe the stream-ordered alternative in the handle management section of the user guide. Co-authored-by: Cursor --- projects/rocsparse/docs/how-to/using-rocsparse.rst | 7 +++++++ projects/rocsparse/docs/reference/api.rst | 4 ++++ projects/rocsparse/docs/reference/auxiliary.rst | 14 ++++++++++++++ 3 files changed, 25 insertions(+) diff --git a/projects/rocsparse/docs/how-to/using-rocsparse.rst b/projects/rocsparse/docs/how-to/using-rocsparse.rst index dc8be0c29cca..29aaaa8529a4 100644 --- a/projects/rocsparse/docs/how-to/using-rocsparse.rst +++ b/projects/rocsparse/docs/how-to/using-rocsparse.rst @@ -30,6 +30,13 @@ consumed by the rocSPARSE library. You **cannot** switch devices between :ref:`rocsparse_create_handle_` and :ref:`rocsparse_destroy_handle_`. To change the device, you must destroy the current handle and create another rocSPARSE handle on a new device. +:ref:`rocsparse_create_handle_` blocks the calling thread until the handle is ready. +If you want handle creation to be stream-ordered instead, use :ref:`rocsparse_handle_create_`, +which binds the handle to a user-provided stream and enqueues all setup work on that stream +without blocking the host. Handles created this way are destroyed with +:ref:`rocsparse_handle_destroy_`, which also reports an optional error descriptor. +Neither routine can be called during HIP graph stream capture. + .. note:: :cpp:func:`hipSetDevice` and :cpp:func:`hipGetDevice` are not part of the rocSPARSE API. diff --git a/projects/rocsparse/docs/reference/api.rst b/projects/rocsparse/docs/reference/api.rst index 776809eb8e2e..ce6d73118d91 100644 --- a/projects/rocsparse/docs/reference/api.rst +++ b/projects/rocsparse/docs/reference/api.rst @@ -78,8 +78,12 @@ Auxiliary functions +-----------------------------------------------------+ |:cpp:func:`rocsparse_create_handle` | +-----------------------------------------------------+ +|:cpp:func:`rocsparse_handle_create` | ++-----------------------------------------------------+ |:cpp:func:`rocsparse_destroy_handle` | +-----------------------------------------------------+ +|:cpp:func:`rocsparse_handle_destroy` | ++-----------------------------------------------------+ |:cpp:func:`rocsparse_set_stream` | +-----------------------------------------------------+ |:cpp:func:`rocsparse_get_stream` | diff --git a/projects/rocsparse/docs/reference/auxiliary.rst b/projects/rocsparse/docs/reference/auxiliary.rst index 38070c0635f0..2ac581978a63 100644 --- a/projects/rocsparse/docs/reference/auxiliary.rst +++ b/projects/rocsparse/docs/reference/auxiliary.rst @@ -20,6 +20,13 @@ rocsparse_create_handle() .. doxygenfunction:: rocsparse_create_handle +.. _rocsparse_handle_create_: + +rocsparse_handle_create() +------------------------- + +.. doxygenfunction:: rocsparse_handle_create + .. _rocsparse_destroy_handle_: rocsparse_destroy_handle() @@ -27,6 +34,13 @@ rocsparse_destroy_handle() .. doxygenfunction:: rocsparse_destroy_handle +.. _rocsparse_handle_destroy_: + +rocsparse_handle_destroy() +-------------------------- + +.. doxygenfunction:: rocsparse_handle_destroy + .. _rocsparse_set_stream_: rocsparse_set_stream()