template struct dnnl::handle

Overview

oneDNN C API handle wrapper class. More…

#include <dnnl_common.hpp>

template <typename T, typename traits = handle_traits<T>>
struct handle
{
    // construction

    handle();
    handle(const handle<T, traits>&);
    handle(handle<T, traits>&&);
    handle(T t, bool weak = false);

    // methods

    handle<T, traits>& operator = (const handle<T, traits>&);
    handle<T, traits>& operator = (handle<T, traits>&&);
    void reset(T t, bool weak = false);
    T get(bool allow_empty = false) const;
    operator T () const;
    operator bool () const;
    bool operator == (const handle<T, traits>& other) const;
    bool operator != (const handle& other) const;
};

// direct descendants

struct desc;
struct engine;
struct memory;
struct post_ops;
struct primitive;
struct primitive_attr;
struct primitive_desc_base;
struct stream;

Detailed Documentation

oneDNN C API handle wrapper class.

This class is used as the base class for primitive (dnnl::primitive), engine (dnnl::engine), and stream (dnnl::stream) classes, as well as others. An object of the dnnl::handle class can be passed by value.

A handle can be weak, in which case it follows std::weak_ptr semantics. Otherwise, it follows std::shared_ptr semantics.

Note

The implementation stores oneDNN C API handles in a std::shared_ptr with deleter set to a dummy function in the weak mode.

Construction

handle()

Constructs an empty handle object.

Warning

Uninitialized object cannot be used in most library calls and is equivalent to a null pointer. Any attempt to use its methods, or passing it to the other library function, will cause an exception to be thrown.

handle(const handle<T, traits>&)

Copy constructor.

handle(handle<T, traits>&&)

Move constructor.

handle(T t, bool weak = false)

Constructs a handle wrapper object from a C API handle.

Parameters:

t

The C API handle to wrap.

weak

A flag specifying whether to construct a weak wrapper; defaults to false.

Methods

handle<T, traits>& operator = (const handle<T, traits>&)

Assignment operator.

handle<T, traits>& operator = (handle<T, traits>&&)

Move assignment operator.

void reset(T t, bool weak = false)

Resets the handle wrapper objects to wrap a new C API handle.

Parameters:

t

The new value of the C API handle.

weak

A flag specifying whether the wrapper should be weak; defaults to false.

T get(bool allow_empty = false) const

Returns the underlying C API handle.

Parameters:

allow_empty

A flag signifying whether the method is allowed to return an empty (null) object without throwing an exception.

Returns:

The underlying C API handle.

operator T () const

Converts a handle to the underlying C API handle type.

Does not throw and returns nullptr if the object is empty.

Returns:

The underlying C API handle.

operator bool () const

Checks whether the object is not empty.

Returns:

Whether the object is not empty.

bool operator == (const handle<T, traits>& other) const

Equality operator.

Parameters:

other

Another handle wrapper.

Returns:

true if this and the other handle wrapper manage the same underlying C API handle, and false otherwise. Empty handle objects are considered to be equal.

bool operator != (const handle& other) const

Inequality operator.

Parameters:

other

Another handle wrapper.

Returns:

true if this and the other handle wrapper manage different underlying C API handles, and false otherwise. Empty handle objects are considered to be equal.