.. index:: pair: struct; dnnl::memory .. _doxid-structdnnl_1_1memory: struct dnnl::memory =================== .. toctree:: :hidden: enum_dnnl_memory_data_type.rst enum_dnnl_memory_format_kind.rst enum_dnnl_memory_format_tag.rst enum_dnnl_memory_sparse_encoding.rst struct_dnnl_memory_desc-2.rst Overview ~~~~~~~~ Memory object. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block #include struct memory: public :ref:`dnnl::handle` { // typedefs typedef :ref:`dnnl_dim_t` :ref:`dim`; typedef std::vector<:ref:`dim`> :ref:`dims`; // enums enum :ref:`data_type`; enum :ref:`format_kind`; enum :ref:`format_tag`; enum :ref:`sparse_encoding`; // structs struct :ref:`desc`; // construction :ref:`memory`(); :ref:`memory`(const :ref:`desc`& md, const :ref:`engine`& aengine, void* handle); :ref:`memory`(const :ref:`desc`& md, const :ref:`engine`& aengine, std::vector handles); :ref:`memory`(const :ref:`desc`& md, const :ref:`engine`& aengine); // methods template static void :ref:`validate_dims`( const std::vector& v, int min_size = 0 ); static size_t :ref:`data_type_size`(:ref:`data_type` adata_type); static :ref:`dnnl_data_type_t` :target:`convert_to_c`(:ref:`data_type` adata_type); static :ref:`dnnl_format_tag_t` :target:`convert_to_c`(:ref:`format_tag` format); :ref:`desc` :ref:`get_desc`() const; :ref:`engine` :ref:`get_engine`() const; void* :ref:`get_data_handle`(int index = 0) const; void :ref:`set_data_handle`(void* handle, int index = 0) const; template T* :ref:`map_data`(int index = 0) const; void :ref:`unmap_data`(void* mapped_ptr, int index = 0) const; :ref:`handle`(); :ref:`handle`(); :ref:`handle`(); :ref:`handle`(); }; Inherited Members ----------------- .. ref-code-block:: cpp :class: doxyrest-overview-inherited-code-block public: // methods :ref:`handle`& :ref:`operator =` (const :ref:`handle`&); :ref:`handle`& :ref:`operator =` (:ref:`handle`&&); void :ref:`reset`(T t, bool weak = false); T :ref:`get`(bool allow_empty = false) const; :ref:`operator T` () const; :ref:`operator bool` () const; bool :ref:`operator ==` (const :ref:`handle`& other) const; bool :ref:`operator !=` (const :ref:`handle`& other) const; .. _details-structdnnl_1_1memory: 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 -------- .. index:: pair: typedef; dim .. _doxid-structdnnl_1_1memory_1a6ad818e4699872cc913474fa5f122cd5: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef :ref:`dnnl_dim_t` dim Integer type for representing dimension sizes and indices. .. index:: pair: typedef; dims .. _doxid-structdnnl_1_1memory_1afdd20764d58c0b517d5a31276672aeb8: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef std::vector<:ref:`dim`> dims Vector of dimensions. Implementations are free to force a limit on the vector's length. Construction ------------ .. index:: pair: function; memory .. _doxid-structdnnl_1_1memory_1a5f509ba0d38054c147f1dceef1a42d44: .. ref-code-block:: cpp :class: doxyrest-title-code-block memory() Default constructor. Constructs an empty memory object, which can be used to indicate absence of a parameter. .. index:: pair: function; memory .. _doxid-structdnnl_1_1memory_1a7463ff54b529ec2b5392230861212a09: .. ref-code-block:: cpp :class: doxyrest-title-code-block memory(const :ref:`desc`& md, const :ref:`engine`& aengine, void* handle) Constructs a memory object. Unless ``handle`` is equal to :ref:`DNNL_MEMORY_NONE `, the constructed memory object will have the underlying buffer set. In this case, the buffer will be initialized as if :ref:`dnnl::memory::set_data_handle() ` had been called. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - 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 :ref:`DNNL_MEMORY_ALLOCATE ` special value. Instructs the library to allocate the buffer for the memory object. In this case the library owns the buffer. * :ref:`DNNL_MEMORY_NONE ` to create :ref:`dnnl::memory ` without an underlying buffer. .. rubric:: See also: :ref:`memory::set_data_handle() ` .. index:: pair: function; memory .. _doxid-structdnnl_1_1memory_1adfb0936410dd301a28fd2883ae97f01f: .. ref-code-block:: cpp :class: doxyrest-title-code-block memory(const :ref:`desc`& md, const :ref:`engine`& aengine, std::vector handles) Constructs a memory object with multiple handles. Unless ``handle`` is equal to :ref:`DNNL_MEMORY_NONE `, the constructed memory object will have the underlying buffer set. In this case, the buffer will be initialized as if :ref:`dnnl::memory::set_data_handle() ` had been called. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - md - Memory descriptor. * - aengine - Engine to store the data on. * - handles - Handles of the memory buffers to use. For each element of the ``handles`` vector the following applies: * A pointer to the user-allocated buffer. In this case the library doesn't own the buffer. * The :ref:`DNNL_MEMORY_ALLOCATE ` special value. Instructs the library to allocate the buffer for the memory object. In this case the library owns the buffer. * :ref:`DNNL_MEMORY_NONE ` Instructs the library to skip allocation of the memory buffer. .. rubric:: See also: :ref:`memory::set_data_handle() ` .. index:: pair: function; memory .. _doxid-structdnnl_1_1memory_1ab0892880e22c2cced48c44f405ced029: .. ref-code-block:: cpp :class: doxyrest-title-code-block memory(const :ref:`desc`& md, const :ref:`engine`& aengine) Constructs a memory object. The underlying buffer(s) for the memory will be allocated by the library. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - md - Memory descriptor. * - aengine - Engine to store the data on. Methods ------- .. index:: pair: function; validate_dims .. _doxid-structdnnl_1_1memory_1a5a02c4d5aa4a07650977ba57ed65bd9a: .. ref-code-block:: cpp :class: doxyrest-title-code-block template static void validate_dims( const std::vector& v, int min_size = 0 ) Helper function that validates that an ``std::vector`` of dimensions can be safely converted to the C API array :ref:`dnnl_dims_t `. Throws if validation fails. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - v - Vector of dimensions. * - min_size - Minimum expected size of the vector. .. index:: pair: function; data_type_size .. _doxid-structdnnl_1_1memory_1ac4064e92cc225fbb6a0431b90004511c: .. ref-code-block:: cpp :class: doxyrest-title-code-block static size_t data_type_size(:ref:`data_type` adata_type) Returns size of data type in bytes. .. rubric:: Returns: The number of bytes occupied by data type. .. index:: pair: function; get_desc .. _doxid-structdnnl_1_1memory_1ad8a1ad28ed7acf9c34c69e4b882c6e92: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`desc` get_desc() const Returns the associated memory descriptor. .. index:: pair: function; get_engine .. _doxid-structdnnl_1_1memory_1a9074709c5af8dc9d25dd9a98c4d1dbd3: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`engine` get_engine() const Returns the associated engine. .. index:: pair: function; get_data_handle .. _doxid-structdnnl_1_1memory_1a24aaca8359e9de0f517c7d3c699a2209: .. ref-code-block:: cpp :class: doxyrest-title-code-block void* get_data_handle(int index = 0) const Returns an underlying memory buffer that corresponds to the given index. On the CPU engine, or when using USM, this is a pointer to the allocated memory. .. index:: pair: function; set_data_handle .. _doxid-structdnnl_1_1memory_1a34d1c7dbe9c6302b197f22c300e67aed: .. ref-code-block:: cpp :class: doxyrest-title-code-block void set_data_handle(void* handle, int index = 0) const Sets an underlying memory buffer that corresponds to the given index. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - 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 :ref:`dnnl::memory::desc::get_size() ` bytes allocated. * - index - Memory index to attach the buffer. Defaults to 0. .. index:: pair: function; map_data .. _doxid-structdnnl_1_1memory_1a65ef31e805fe967e6924868d2b4a210a: .. ref-code-block:: cpp :class: doxyrest-title-code-block template T* map_data(int index = 0) const Maps a memory object and returns a host-side pointer to a memory buffer with a copy of its contents. The memory buffer corresponds to the given index. 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 :ref:`dnnl::memory::unmap_data() ` call. .. note:: Any primitives working with the memory should be completed before the memory is mapped. Use :ref:`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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - T - Data type to return a pointer to. * - index - Index of the buffer. Defaults to 0. .. rubric:: Returns: Pointer to the mapped memory. .. index:: pair: function; unmap_data .. _doxid-structdnnl_1_1memory_1a2b5abd181b3cb0394492458ac26de677: .. ref-code-block:: cpp :class: doxyrest-title-code-block void unmap_data(void* mapped_ptr, int index = 0) const Unmaps a memory object and writes back any changes made to the previously mapped memory buffer. The memory buffer corresponds to the given index. .. note:: The map_data and unmap_data functions are provided mainly for debug and testing purposes and their performance may be suboptimal. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - mapped_ptr - A pointer previously returned by :ref:`dnnl::memory::map_data() `. * - index - Index of the buffer. Defaults to 0. .. index:: pair: function; handle .. _doxid-structdnnl_1_1memory_1a5c631f7e5e4c92a13edb8e3422d3a973: .. ref-code-block:: cpp :class: doxyrest-title-code-block 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. .. index:: pair: function; handle .. _doxid-structdnnl_1_1memory_1a022001b5b9c8940a1326a02b61fc4860: .. ref-code-block:: cpp :class: doxyrest-title-code-block handle() Copy constructor. .. index:: pair: function; handle .. _doxid-structdnnl_1_1memory_1aa13f3ecf4db240717074814412c7e70c: .. ref-code-block:: cpp :class: doxyrest-title-code-block handle() Move constructor. .. index:: pair: function; handle .. _doxid-structdnnl_1_1memory_1a9c408c09fce1278f5cb0d1fa9818fc86: .. ref-code-block:: cpp :class: doxyrest-title-code-block handle() Constructs a handle wrapper object from a C API handle. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - t - The C API handle to wrap. * - weak - A flag specifying whether to construct a weak wrapper; defaults to ``false``.