hipDNN frontend handle C++ API

hipDNN frontend handle C++ API#

2026-03-31

3 min read time

Applies to Linux and Windows

RAII handle management for hipDNN backend.

A hipDNN handle is a GPU context that holds the state needed to run operations on a particular device. Every Graph::build() and Graph::execute() call requires a handle.

This file provides RAII wrappers so the handle is automatically destroyed when it goes out of scope (no manual cleanup needed).

// Minimal usage
auto [handle, err] = hipdnn_frontend::createHipdnnHandle();
graph.build(*handle);
graph.execute(*handle, variantPack, workspace);
// handle is destroyed automatically at end of scope

By default the handle uses the default HIP stream. To enqueue work on a stream you created with hipStreamCreate(), pass the stream to createHipdnnHandle() or call setHipdnnHandleStream() afterwards.

namespace hipdnn_frontend

Typedefs

using HipdnnHandlePtr = std::unique_ptr<hipdnnHandle_t, HipdnnHandleDeleter>#: RAII smart pointer to a hipDNN handle; automatically calls destroy on scope exit.

using hipdnn_handle_deleter = HipdnnHandleDeleter #: snake_case alias for HipdnnHandleDeleter

using hipdnn_handle_ptr = HipdnnHandlePtr #: snake_case alias for HipdnnHandlePtr

Functions

inline Error createHipdnnHandle(HipdnnHandlePtr &handle, hipStream_t stream = nullptr)#

Create a hipDNN handle (output-parameter style)

Initializes the backend and populates handle with a newly created hipDNN handle. On failure, handle is unchanged if backend creation fails, or reset to empty if stream binding fails.

HipdnnHandlePtr handle;
auto err = createHipdnnHandle(handle);
if (err.is_bad()) {
    // handle error
}

See also

createHipdnnHandle(hipStream_t) for structured-binding style

Parameters:

handle – Output smart pointer that receives the created handle
stream – HIP stream to bind (nullptr = default stream)

Returns:

Error indicating success or failure

inline std::pair<HipdnnHandlePtr, Error> createHipdnnHandle(hipStream_t stream = nullptr)#

Create a hipDNN handle (structured-binding style)

Same as the output-parameter overload, but returns a pair so you can use C++17 structured bindings.

auto [handle, err] = createHipdnnHandle();
if (err.is_bad()) {
    // handle error
}

Parameters:: stream – HIP stream to bind (nullptr = default stream)
Returns:: Pair of (handle, error); handle is null on failure

inline Error setHipdnnHandleStream(const HipdnnHandlePtr &handle, hipStream_t stream)#

Bind a HIP stream to an existing handle.

All subsequent operations using this handle will be enqueued on the given stream.

Parameters:

handle – The handle to reconfigure
stream – The HIP stream to bind

Returns:

Error indicating success or failure

inline Error getHipdnnHandleStream(const HipdnnHandlePtr &handle, hipStream_t *stream)#

Query which HIP stream a handle is currently bound to.

Parameters:

handle – The handle to query
stream – Output pointer that receives the bound stream

Returns:

Error indicating success or failure

inline auto create_hipdnn_handle(hipStream_t stream = nullptr)#: snake_case alias for createHipdnnHandle() (structured-binding style)

inline Error create_hipdnn_handle(HipdnnHandlePtr &handle, hipStream_t stream = nullptr)#: snake_case alias for createHipdnnHandle() (output-parameter style)

inline Error set_hipdnn_handle_stream(const HipdnnHandlePtr &h, hipStream_t s)#: snake_case alias for setHipdnnHandleStream()

inline Error get_hipdnn_handle_stream(const HipdnnHandlePtr &h, hipStream_t *s)#: snake_case alias for getHipdnnHandleStream()

struct HipdnnHandleDeleter#

#include <Handle.hpp>

Custom deleter for RAII management of hipDNN handles.

Destroys the backend handle and frees the pointer when the owning unique_ptr goes out of scope.

Public Functions

inline void operator()(hipdnnHandle_t *handlePtr) const#: Destroys the hipDNN handle and deletes the pointer.

hipDNN frontend handle C++ API

Contents

hipDNN frontend handle C++ API#