Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference

ID 767253
Date 11/07/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

n_container

Template class for N-dimensional container. The contained primitive type, exact memory layout and container shape are defined via template arguments.

Syntax

template <typename PrimitiveT, 
          typename LayoutT, 
          typename ExtentsT,
          typename AllocatorT >
class n_container;

Description

N-dimensional container of PrimitiveT elements with predefined memory layout and shape. Provides accessor interface suitable for flexible and efficient data access inside SIMD loops

The following table provides information on the template arguments for n_container

Template Argument

Description

typename PrimitiveT

The type that each cell in the multi-dimensional container will store.

Requirements: PrimitiveT must be previously declared with the SDLT_PRIMITIVE macro.

typename LayoutT

The in-memory data layout of cells in the container.

Requirements: LayoutT must be a class from layout namespace.

typename ExtentsT

The shape of the container.

Requirements: ExtentsT must be a concrete type of n_extent_t variadic template.

class AllocatorT = allocator::default_alloc

[Optional] Specify type of allocator to be used.

allocator::default_alloc is currently the only allocator supported.

The following table provides information on the types defined as members of n_container

Member Type

Description

typedef PrimitiveT primitive_type;

Type inside each cell of the container.

typedef PrimitiveT allocator_type;

Type of allocator used by the container.

typedef implementation-defined accessor

Type of an accessor that can write or read cells to and from this container.

typedef implementation-defined const_accessor;

Type of a const_accessor that can read cells from this container.

The following table provides information on the methods of n_container

Member

Description

n_container (
    const ExtentsT &a_extents,
     buffer_offset_in_cachelines  buffer_offset
        =buffer_offset_in_cachelines(0),
     const AllocatorT &an_allocator=AllocatorT())

Constructs an uninitialized container of the shape defined as a_extents, using optionally specified number of cache lines to offset the start of the buffer in memory to allow management of 4k cache aliasing, using optionally specified allocator instance.

n_container (buffer_offset_in_cachelines buffer_offset = buffer_offset_in_cachelines(0), 
const AllocatorT &an_allocator=AllocatorT())

Constructs an uninitialized container of the shape, defined via template parameter ExtentsT using optionally specified number of cache lines to offset the start of the buffer in memory to allow management of 4k cache aliasing, using optionally specified allocator instance.

ExtentsT must be default constructible. Only true when ExtentsT is made up enitrely of fixed<NumberT> types.

n_container(n_container&& donor)

Transfers ownership of the donor's currently owned buffers and organization, if any. Any outstanding accessors on the donor are no longer valid.

n_container & operator = (n_container&& donor)

Frees any existing buffers, then transfers ownership of the donor's currently owned buffers and organization, if any. Any outstanding accessors on the donor are no longer valid.

Returns: Reference to this instance.

const ExtentsT& n_extent () const

Provides the shape of the container. Alternatively, the free template function extent_d<int DimenstionT>(const n_container &) could be used.

Returns: Constant reference to ExtentsT instance describing the shape of the container.

const_accessor const_access();

Constructs an const_accessor with knowledge of the underlying data organization to read cells inside the container.

Returns:const_accessor for the container

accessor access();

Constructs an accessor with knowledge of the underlying data organization to write or read cells inside the container.

Returns:accessor for the container

The following table provides information about the friend functions of n_container.

Friend Function Description
std::ostream& 
          operator << (std::ostream& output_stream, const
          n_container & a_container)

Append string representation of a_container's extents values to a_output_stream.

Returns: Reference to a_output_stream for chained calls.