org.bytedeco.dnnl

Class memory

java.lang.Object

org.bytedeco.javacpp.Pointer

org.bytedeco.dnnl.dnnl_memory_handle

org.bytedeco.dnnl.memory

All Implemented Interfaces:

AutoCloseable

@Namespace(value="dnnl")
 @Properties(inherit=dnnl.class)
public class memory
extends dnnl_memory_handle

\} dnnl_api_stream

\addtogroup dnnl_api_memory Memory A container that describes and stores data. Memory objects can contain data of various types and formats. There are two levels of abstraction: 1. **Memory descriptor** -- engine-agnostic logical description of data (number of dimensions, dimension sizes, and data type), and, optionally, the information about the physical format of data in memory. If this information is not known yet, a memory descriptor can be created with #dnnl::memory::format_tag::any. This allows compute-intensive primitives to choose the best format for computation. The user is responsible for reordering the data into the chosen format when formats do not match. A memory descriptor can be initialized either by specifying dimensions and a memory format tag or strides for each of them, or by manipulating the dnnl_memory_desc_t structure directly. \warning The latter approach requires understanding how the physical data representation is mapped to the structure and is discouraged. This topic is discussed in \ref dev_guide_understanding_memory_formats. The user can query the amount of memory required by a memory descriptor using the #dnnl::memory::desc::get_size() function. The size of data in general cannot be computed as the product of dimensions multiplied by the size of the data type. So users are required to use this function for better code portability. Two memory descriptors can be compared using the equality and inequality operators. The comparison is especially useful when checking whether it is necessary to reorder data from the user's data format to a primitive's format. 2. **Memory object** -- an engine-specific object that handles the data and its description (a memory descriptor). For the CPU aengine, the data handle is simply a pointer to \c void. The data handle can be queried using #dnnl::memory::get_data_handle() and set using #dnnl::memory::set_data_handle(). A memory object can also be queried for the underlying memory descriptor and for its engine using #dnnl::memory::get_desc() and dnnl::memory::get_engine(). Along with ordinary memory descriptors with all dimensions being positive, the library supports *zero-volume* memory descriptors with one or more dimensions set to zero. This is used to support the NumPy\* convention. If a zero-volume memory is passed to a primitive, the primitive typically does not perform any computations with this memory. For example: - A concatenation primitive would ignore all memory object with zeroes in the concat dimension / axis. - A forward convolution with a source memory object with zero in the minibatch dimension would always produce a destination memory object with a zero in the minibatch dimension and perform no computations. - However, a forward convolution with a zero in one of the weights dimensions is ill-defined and is considered to be an error by the library because there is no clear definition of what the output values should be. Data handle of a zero-volume memory is never accessed. \{

Memory object. A memory object encapsulates a handle to a memory buffer allocated on a specific aengine, 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	memory.data_type Data type specification.
static class	memory.desc A memory descriptor.
static class	memory.format_kind Memory format kind
static class	memory.format_tag Memory format tag specification.

Nested classes/interfaces inherited from class org.bytedeco.javacpp.Pointer

Pointer.CustomDeallocator, Pointer.Deallocator, Pointer.NativeDeallocator, Pointer.ReferenceCounter

Field Summary

Fields inherited from class org.bytedeco.javacpp.Pointer

address, capacity, limit, position

Constructor Summary

Constructors

Constructor and Description
memory() Default constructor.
memory(long size) Native array allocator.
memory(memory.desc md, engine aengine) Constructs a memory object.
memory(memory.desc md, engine aengine, Pointer handle) Constructs a memory object.
memory(Pointer p) Pointer cast constructor.

Method Summary

Modifier and Type	Method and Description
static int	convert_to_c(memory.data_type adata_type)
static int	convert_to_c(memory.format_tag format)
Pointer	get_data_handle() Returns the underlying memory buffer.
memory.desc	get_desc() Returns the associated memory descriptor.
engine	get_engine() Returns the associated engine.
memory	getPointer(long i)
memory	position(long position)
void	set_data_handle(Pointer handle) Sets the underlying memory buffer.
void	set_data_handle(Pointer handle, stream astream) Sets the underlying memory buffer.
void	unmap_data(Pointer mapped_ptr) Unmaps a memory object and writes back any changes made to the previously mapped memory buffer.

Methods inherited from class org.bytedeco.dnnl.dnnl_memory_handle

asBoolean, asDnnl_memory, equals, get, get, notEquals, put, reset, reset

Methods inherited from class org.bytedeco.javacpp.Pointer

address, asBuffer, asByteBuffer, availablePhysicalBytes, calloc, capacity, capacity, close, deallocate, deallocate, deallocateReferences, deallocator, deallocator, equals, fill, formatBytes, free, getPointer, getPointer, getPointer, hashCode, isNull, isNull, limit, limit, malloc, maxBytes, maxPhysicalBytes, memchr, memcmp, memcpy, memmove, memset, offsetof, offsetof, parseBytes, physicalBytes, position, put, realloc, referenceCount, releaseReference, retainReference, setNull, sizeof, sizeof, toString, totalBytes, totalCount, totalPhysicalBytes, withDeallocator, zero

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

memory

public memory(Pointer p)

Pointer cast constructor. Invokes Pointer.Pointer(Pointer).

memory

public memory(long size)

Native array allocator. Access with Pointer.position(long).

memory

public memory()

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

memory

public memory(@Const @ByRef
              memory.desc md,
              @Const @ByRef
              engine aengine,
              Pointer handle)

Constructs a memory object. Unless \p 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 as an underlying storage. - 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

public memory(@Const @ByRef
              memory.desc md,
              @Const @ByRef
              engine aengine)

Constructs a memory object. The underlying storage for the memory will be allocated by the library.

Parameters:

md - Memory descriptor.

aengine - Engine to store the data on.

Method Detail

position

public memory position(long position)

Overrides:

position in class dnnl_memory_handle

getPointer

public memory getPointer(long i)

Overrides:

getPointer in class dnnl_memory_handle

get_desc

@ByVal
public memory.desc get_desc()

Returns the associated memory descriptor.

get_engine

@ByVal
public engine get_engine()

Returns the associated engine.

get_data_handle

public Pointer get_data_handle()

Returns the underlying memory buffer. On the CPU engine this is a pointer to the allocated memory.

set_data_handle

public void set_data_handle(Pointer handle,
                            @Const @ByRef
                            stream astream)

Sets the underlying memory buffer. This function may write zero values to the memory specified by the \p 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 \ref dev_guide_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 \p handle parameter cannot and does not have a const qualifier.

Parameters:

handle - Data handle. For the CPU aengine, the data handle is a pointer to the actual data. For OpenCL it is a cl_mem.

astream - Stream to use to execute padding in.

set_data_handle

public void set_data_handle(Pointer handle)

Sets the underlying memory buffer. See documentation for #dnnl::memory::set_data_handle(void *, const stream &) const for more information.

Parameters:

handle - Data handle. For the CPU aengine, the data handle is a pointer to the actual data. For OpenCL it is a cl_mem.

unmap_data

public void unmap_data(Pointer mapped_ptr)

Unmaps a memory object and writes back any changes made to the previously mapped memory buffer. The pointer to the mapped buffer must be obtained via the dnnl::memory::map_data() call. \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 map_data().

convert_to_c

@Cast(value="dnnl_data_type_t")
public static int convert_to_c(memory.data_type adata_type)

convert_to_c

@Cast(value="dnnl_format_tag_t")
public static int convert_to_c(memory.format_tag format)