Intel® oneAPI Data Analytics Library Developer Guide and Reference

Developer Guide and Reference

  • 2021.1
  • 12/04/2020
  • Public Content
Contents

Array

The array is a simple concept over the data in oneDAL. It represents a storage that:
  1. Holds the data allocated inside it or references to the external data. The data are organized as one homogeneous and contiguous memory block.
  2. Contains information about the memory block’s size.
  3. Supports both immutable and mutable data.
  4. Provides an ability to change the data state from immutable to mutable one.
  5. Holds ownership information on the data (see the dm data ownership requirements section).
  6. Ownership information on the data can be shared between several arrays. It is possible to create a new array from another one without any data copies.

Usage example

The following listing provides a brief introduction to the array API and an example of basic usage scenario:
#include <CL/sycl.hpp>
#include <iostream>
#include <string>
#include "oneapi/dal/array.hpp"

using namespace oneapi;

void print_property(const std::string& description, const auto& property) {
   std::cout << description << ": " << property << std::endl;
}

int main() {
   sycl::queue queue { sycl::default_selector() };

   constexpr std::int64_t data_count = 4;
   const float data[] = { 1.0f, 2.0f, 3.0f, 4.0f };

   // Creating an array from immutable user-defined memory
   auto arr_data = dal::array<float>::wrap(data, data_count);

   // Creating an array from internally allocated memory filled by ones
   auto arr_ones = dal::array<float>::full(queue, data_count, 1.0f);

   print_property("Is arr_data mutable", arr_data.has_mutable_data()); // false
   print_property("Is arr_ones mutable", arr_ones.has_mutable_data()); // true

   // Creating new array from arr_data without data copy - they share ownership information.
   dal::array<float> arr_mdata = arr_data;

   print_property("arr_mdata elements count", arr_mdata.get_count()); // equal to data_count
   print_property("Is arr_mdata mutable", arr_mdata.has_mutable_data()); // false

   /// Copying data inside arr_mdata to new mutable memory block.
   /// arr_data still refers to the original data pointer.
   arr_mdata.need_mutable_data(queue);

   print_property("Is arr_data mutable", arr_data.has_mutable_data()); // false
   print_property("Is arr_mdata mutable", arr_mdata.has_mutable_data()); // true

   queue.submit([&](sycl::handler& cgh){
      auto mdata = arr_mdata.get_mutable_data();
      auto cones = arr_ones.get_data();
      cgh.parallel_for<class array_addition>(sycl::range<1>(data_count), [=](sycl::id<1> idx) {
         mdata[idx[0]] += cones[idx[0]];
      });
   }).wait();

   std::cout << "arr_mdata values: ";
   for(std::int64_t i = 0; i < arr_mdata.get_count(); i++) {
      std::cout << arr_mdata[i] << ", ";
   }
   std::cout << std::endl;

   return 0;
}

Data ownership requirements

The array supports the following requirements on the internal data management:
  1. An array owns two properties representing raw pointers to the data:
  2. If an array owns mutable data, both properties point to the same memory block.
  3. If an array owns immutable data,
    mutable_data
     is
    nullptr
    .
  4. An array stores the number of elements in the block it owns and updates the
    count
     property when a new memory block is assigned to the array.
  5. An array stores a pointer to the
    ownership structure
     of the data:
    • The
      reference count
       indicating how many array objects refer to the same memory block.
    • The
      deleter
       object used to free the memory block when reference count is zero.
  6. An array creates the ownership structure for a new memory block not associated with such structure.
  7. An array decrements the number of references to the memory block when the array goes out of the scope. If the number of references is zero, the array calls the deleter on this memory block and free the ownership structure.
  8. An array stores the pointer to the ownership structure created by another array when they share the data. An array increments the reference count for it to be equal to the number of array objects sharing the same data.

Programming interface

All types and functions in this section are declared in the
oneapi::dal
 namespace and be available via inclusion of the
oneapi/dal/array.hpp
 header file.
All the
array
 class methods can be divided into several groups:
  1. Constructors that are used to create an array from external, mutable or immutable memory.
  2. Constructors and assignment operators that are used to create an array that shares its data with another one.
  3. The group of
    reset()
     methods that are used to re-assign an array to another external memory block.
  4. The group of
    reset()
     methods that are used to re-assign an array to an internally allocated memory block.
  5. The methods that are used to access the data.
  6. Static methods that provide simplified ways to create an array either from external memory or by allocating it within a new object.
template<typename
T
>
class
array
Template Parameters
T
 – The type of the memory block elements within the array. LaTex Math image. can represent any type.
Public Static Methods
static
 array<T>
empty
(std::int64_t
count
)
Allocates a new memory block for mutable data, does not initialize it, creates a new array instance by passing a pointer to the memory block. The array owns the memory block (for details, see dm data ownership requirements).
Parameters
count
 – The number of elements of type LaTex Math image. to allocate memory for.
Preconditions


count > 0

template<typename
K
>
static
 array<T>
full
(std::int64_t
count
, K &&
element
)
Allocates a new memory block for mutable data, fills it with a scalar value, creates a new array instance by passing a pointer to the memory block. The array owns the memory block (for details, see dm data ownership requirements).
Parameters
  • count
     – The number of elements of type LaTex Math image. to allocate memory for.
  • element
     – The value that is used to fill a memory block.
Preconditions


count > 0
Elements of type T are constructible from the Element type.

static
 array<T>
zeros
(std::int64_t
count
)
Allocates a new memory block on mutable data, fills it with zeros, creates a new array instance by passing a pointer to the memory block. The array owns the memory block (for details, see dm data ownership requirements).
Parameters
count
 – The number of elements of type LaTex Math image. to allocate memory for.
Preconditions


count > 0

template<typename
Y
>
static
 array<T>
wrap
(Y *
data
, std::int64_t
count
)
Creates a new array instance by passing the pointer to externally-allocated memory block for mutable data. It is the responsibility of the calling application to free the memory block as the array does not free it when the reference count is zero.
Parameters
  • data
     – The pointer to externally-allocated memory block.
  • count
     – The number of elements of type LaTex Math image. in the memory block.
Preconditions


data != nullptr
count > 0

Constructors
array
()
Creates a new instance of the class without memory allocation:
mutable_data
 and
data
 pointers should be set to
nullptr
,
count
 should be zero; the pointer to the ownership structure should be set to
nullptr
.
array
(
const
array<T> &
a
)
Creates a new array instance that shares an ownership with LaTex Math image. on its memory block.
array
(array<T> &&
a
)
Moves
data
,
mutable_data
 pointers,
count
, and pointer to the ownership structure in LaTex Math image. to the new array instance.
template<typename
Deleter
>
array
(T *
data
, std::int64_t
count
, Deleter &&
deleter
)
Creates a new array instance which owns a memory block of externally-allocated mutable data. The ownership structure is created for a block, the input LaTex Math image. is assigned to it.
Template Parameters
Deleter
 – The type of a deleter used to free the LaTex Math image. . The deleter provides
void operator()(Data*)
 member function.
Parameters
  • data
     – The pointer to externally-allocated memory block.
  • count
     – The number of elements of type LaTex Math image. in the memory block.
  • deleter
     – The object used to free LaTex Math image. .
template<typename
ConstDeleter
>
array
(
const
 T *
data
, std::int64_t
count
, ConstDeleter &&
deleter
)
Creates a new array instance which owns a memory block of externally-allocated immutable data. The ownership structure is created for a block, the input LaTex Math image. is assigned to it.
Template Parameters
ConstDeleter
 – The type of a deleter used to free the LaTex Math image. . The deleter implements
void operator()(const Data*)
 member function.
Parameters
  • data
     – The pointer to externally-allocated memory block.
  • count
     – The number of elements of type LaTex Math image. in the LaTex Math image. .
  • deleter
     – The object used to free LaTex Math image. .
template<typename
Y
, typename
K
>
array
(
const
array<Y> &
ref
, K *
data
, std::int64_t
count
)
An aliasing constructor: creates a new array instance that stores LaTex Math image. pointer, assigns the pointer to the ownership structure of LaTex Math image. to the new instance. Array returns LaTex Math image. pointer as its mutable or immutable block depending on the LaTex Math image. type.
Parameters
  • ref
     – The array which shares ownership structure with created one.
  • data
     – Mutable or immutable unmanaged pointer hold by created array.
  • count
     – The number of elements of type LaTex Math image. in the LaTex Math image. .
Preconditions


std::is_same_v || std::is_same_v

Public Methods
array<T>
operator=
(
const
 array<T> &
other
)
Replaces the
data
,
mutable_data
 pointers,
count
, and pointer to the ownership structure in the array instance by the values in LaTex Math image. .
Postconditions


data == other.data
mutable_data == other.mutable_data
count == other.count

array<T>
operator=
(array<T> &&
other
)
Swaps the values of
data
,
mutable_data
 pointers,
count
, and pointer to the ownership structure in the array instance and LaTex Math image. .
bool
has_mutable_data
()
const
noexcept
Returns whether array contains
mutable_data
 or not.
array &
need_mutable_data
()
Returns mutable_data, if array contains it. Otherwise, allocates a memory block for mutable data and fills it with the data stored at
data
. Creates the ownership structure for allocated memory block and stores the pointer.
Postconditions


has_mutable_data() == true

void
reset
()
Resets ownership structure pointer to
nullptr
, sets
count
 to zero,
data
 and
mutable_data
 to
nullptr
.
void
reset
(std::int64_t
count
)
Allocates a new memory block for mutable data, does not initialize it, creates ownership structure for this block, assigns the structure inside the array. The array owns allocated memory block.
Parameters
count
 – The number of elements of type LaTex Math image. to allocate memory for.
template<typename
Deleter
> void
reset
(T *
data
, std::int64_t
count
, Deleter &&
deleter
)
Creates the ownership structure for memory block of externally-allocated mutable data, assigns input LaTex Math image. object to it, sets and
mutable_data
 pointers to this block.
Template Parameters
Deleter
 – The type of a deleter used to free the LaTex Math image. . The deleter implements
void operator()(Data*)
 member function.
Parameters
  • data
     – The mutable memory block pointer to be assigned inside the array.
  • count
     – The number of elements of type LaTex Math image. into the block.
  • deleter
     – The object used to free LaTex Math image. .
template<typename
ConstDeleter
> void
reset
(
const
 T *
data
, std::int64_t
count
, ConstDeleter &&
deleter
)
Creates the ownership structure for memory block of externally-allocated immutable data, assigns input LaTex Math image. object to it, sets pointer to this block.
Template Parameters
ConstDeleter
 – The type of a deleter used to free. The deleter implements
void operator()(const Data*)`
 member function.
Parameters
  • data
     – The immutable memory block pointer to be assigned inside the array.
  • count
     – The number of elements of type LaTex Math image. into the block.
  • deleter
     – The object used to free LaTex Math image. .
template<typename
Y
> void
reset
(
const
 array<Y> &
ref
, T *
data
, std::int64_t
count
)
Initializes and
mutable_data
 with data pointer, with input LaTex Math image. value, initializes the pointer to ownership structure with the one from ref. Array returns LaTex Math image. pointer as its mutable block.
Parameters
  • ref
     – The array which is used to share ownership structure with current one.
  • data
     – Mutable unmanaged pointer to be assigned to the array.
  • count
     – The number of elements of type LaTex Math image. in the LaTex Math image. .
template<typename
Y
> void
reset
(
const
 array<Y> &
ref
,
const
 T *
data
, std::int64_t
count
)
Initializes with data pointer, with input LaTex Math image. value, initializes the pointer to ownership structure with the one from ref. Array returns LaTex Math image. pointer as its immutable block.
Parameters
  • ref
     – The array which is used to share ownership structure with current one.
  • data
     – Immutable unmanaged pointer to be assigned to the array.
  • count
     – The number of elements of type LaTex Math image. in the LaTex Math image. .
const
 T &
operator[]
(std::int64_t
index
)
const
noexcept
Provides a read-only access to the elements of array. Does not perform boundary checks.
Properties
T *
mutable_data
The pointer to the memory block holding mutable data.
Getter & Setter


T * get_mutable_data() const

Invariants


mutable_data != nullptr if has_mutable_data() && count > 0

const
 T *
data
The pointer to the memory block holding immutable data.
Getter & Setter


const T * get_data() const noexcept

Invariants


data != nullptr if count > 0
if has_mutable_data() == true then data == mutable_data

std::int64_t
count
The number of elements of type LaTex Math image. in a memory block.
Getter & Setter


std::int64_t get_count() const noexcept

std::int64_t
size
The size of memory block in bytes.
Getter & Setter


std::int64_t get_size() const noexcept

Invariants


size == count * sizeof(T)

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.