Contents

struct dnnl::memory

Overview

Memory object. More…

#include <dnnl.hpp>

struct memory: public dnnl::handle
{
    // typedefs

    typedef dnnl_dim_t dim;
    typedef std::vector<dim> dims;

    // enums

    enum data_type;
    enum format_kind;
    enum format_tag;

    // structs

    struct desc;

    // construction

    memory();
    memory(const desc& md, const engine& aengine, void* handle);
    memory(const desc& md, const engine& aengine);

    // methods

    template <typename T>
    static void validate_dims(
        const std::vector<T>& v,
        int min_size = 0
        );

    static size_t data_type_size(data_type adata_type);
    static dnnl_data_type_t convert_to_c(data_type adata_type);
    static dnnl_format_tag_t convert_to_c(format_tag format);
    desc get_desc() const;
    engine get_engine() const;
    void* get_data_handle() const;
    void set_data_handle(void* handle, const stream& astream) const;
    void set_data_handle(void* handle) const;

    template <typename T = void>
    T* map_data() const;

    void unmap_data(void* mapped_ptr) const;
    handle();
    handle();
    handle();
    handle();
};

Inherited Members

public:
    // 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;

Detailed Documentation

Memory object.

A memory object encapsulates a handle to a memory buffer allocated on a specific engine, tensor dimensions, data type, and memory format, which is the way tensor indices map to offsets in linear memory space. Memory objects are passed to primitives during execution.

Typedefs

typedef dnnl_dim_t dim

Integer type for representing dimension sizes and indices.

typedef std::vector<dim> dims

Vector of dimensions.

Implementations are free to force a limit on the vector’s length.

Construction

memory()

Default constructor.

Constructs an empty memory object, which can be used to indicate absence of a parameter.

memory(const desc& md, const engine& aengine, void* handle)

Constructs a memory object.

Unless handle is equal to DNNL_MEMORY_NONE, the constructed memory object will have the underlying buffer set. In this case, the buffer will be initialized as if dnnl::memory::set_data_handle() had been called.

Parameters:

md

Memory descriptor.

aengine

Engine to store the data on.

handle

Handle of the memory buffer to use.

  • A pointer to the user-allocated buffer. In this case the library doesn’t own the buffer.

  • The DNNL_MEMORY_ALLOCATE special value. Instructs the library to allocate the buffer for the memory object. In this case the library owns the buffer.

  • DNNL_MEMORY_NONE to create dnnl::memory without an underlying buffer.

See also:

memory::set_data_handle()

memory(const desc& md, const engine& aengine)

Constructs a memory object.

The underlying buffer for the memory will be allocated by the library.

Parameters:

md

Memory descriptor.

aengine

Engine to store the data on.

Methods

template <typename T>
static void validate_dims(
    const std::vector<T>& v,
    int min_size = 0
    )

Helper function that validates that an std::vector of dimensions can be safely converted to the C API array dnnl_dims_t.

Throws if validation fails.

Parameters:

v

Vector of dimensions.

min_size

Minimum expected size of the vector.

 
static size_t data_type_size(data_type adata_type)

Returns size of data type in bytes.

Returns:

The number of bytes occupied by data type.

desc get_desc() const

Returns the associated memory descriptor.

engine get_engine() const

Returns the associated engine.

void* get_data_handle() const

Returns the underlying memory buffer.

On the CPU engine, or when using USM, this is a pointer to the allocated memory.

void set_data_handle(void* handle, const stream& astream) const

Sets the underlying memory buffer.

This function may write zero values to the memory specified by the handle if the memory object has a zero padding area. This may be time consuming and happens each time this function is called. The operation is always blocking and the stream parameter is a hint.

Note

The zero padding is required by memory objects created with blocked memory format tags like dnnl_aBcd8b when any of the dimensions is not a multiple of the corresponding block size. For “plain” formats like dnnl::memory::format_tag::nchw or dnnl::memory::format_tag::nhwc zero padding area needs to be set up explicitly when creating the corresponding memory descriptors. See Understanding Memory Formats for more details.

Note

Even when the memory object is used to hold values that stay constant during the execution of the program (pre-packed weights during inference, for example), the function will still write zeroes to the padding area if it exists. Hence, the handle parameter cannot and does not have a const qualifier.

Parameters:

handle

Memory buffer to use. On the CPU engine or when USM is used, the memory buffer is a pointer to the actual data. For OpenCL it is a cl_mem. It must have at least dnnl::memory::desc::get_size() bytes allocated.

astream

Stream to use to execute padding in.

 
void set_data_handle(void* handle) const

Sets the underlying memory buffer.

See documentation for dnnl::memory::set_data_handle(void *, const stream &) const for more information.

Parameters:

handle

Memory buffer to use. For the CPU engine, the memory buffer is a pointer to the actual data. For OpenCL it is a cl_mem. It must have at least dnnl::memory::desc::get_size() bytes allocated.

 
template <typename T = void>
T* map_data() const

Maps a memory object and returns a host-side pointer to a memory buffer with a copy of its contents.

Mapping enables read/write directly from/to the memory contents for engines that do not support direct memory access.

Mapping is an exclusive operation - a memory object cannot be used in other operations until it is unmapped via dnnl::memory::unmap_data() call.

Note

Any primitives working with the memory should be completed before the memory is mapped. Use dnnl::stream::wait() to synchronize the corresponding execution stream.

Note

The map_data and unmap_data functions are provided mainly for debug and testing purposes and their performance may be suboptimal.

Parameters:

T

Data type to return a pointer to.

Returns:

Pointer to the mapped memory.

void unmap_data(void* mapped_ptr) const

Unmaps a memory object and writes back any changes made to the previously mapped memory buffer.

Note

The map_data and unmap_data functions are provided mainly for debug and testing purposes and their performance may be suboptimal.

Parameters:

mapped_ptr

A pointer previously returned by dnnl::memory::map_data().

 
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()

Copy constructor.

handle()

Move constructor.

handle()

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.
struct dnnl_wino_desc_t enum dnnl::memory::data_type