Array#
Refer to Developer Guide: Array.
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:
Constructors that are used to create an array from external, mutable or immutable memory.
Constructors and assignment operators that are used to create an array that shares its data with another one.
The group of
reset()
methods that are used to re-assign an array to another external memory block.The group of
reset()
methods that are used to re-assign an array to an internally allocated memory block.The methods that are used to access the data.
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.
T
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 data ownership requirements).
- Parameters:
count – The number of elements of type
Data
to allocate memory for.
- Preconditions
- count > 0
-
static array<T> empty(const sycl::queue &queue, std::int64_t count, const sycl::usm::alloc &alloc = sycl::usm::alloc::shared)#
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 data ownership requirements).
- Parameters:
queue – The SYCL* queue object.
count – The number of elements of type
T
to allocate memory for.alloc – The kind of USM to be allocated.
- 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 data ownership requirements).
- Parameters:
count – The number of elements of type
T
to allocate memory for.element – The value that is used to fill a memory block.
- Preconditions
- count > 0Elements of type T are constructible from the Element type.
-
template<typename K>
static array<T> full(sycl::queue &queue, std::int64_t count, K &&element, const sycl::usm::alloc &alloc = sycl::usm::alloc::shared)# 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 data ownership requirements).
- Parameters:
queue – The SYCL* queue object.
count – The number of elements of type
Data
to allocate memory for.element – The value that is used to fill a memory block.
alloc – The kind of USM to be allocated.
- Preconditions
- count > 0Elements of type Data 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 data ownership requirements).
- Parameters:
count – The number of elements of type
Data
to allocate memory for.
- Preconditions
- count > 0
-
static array<T> zeros(sycl::queue &queue, std::int64_t count, const sycl::usm::alloc &alloc = sycl::usm::alloc::shared)#
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 data ownership requirements).
- Parameters:
queue – The SYCL* queue object.
count – The number of elements of type
T
to allocate memory for.alloc – The kind of USM to be allocated.
- 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
Data
in the memory block.
- Preconditions
-
template<typename Y>
static array<T> wrap(Y *data, std::int64_t count, const std::vector<sycl::event> &dependencies)# 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
Data
in the memory block.dependencies – Events indicating availability of the
Data
for reading or writing.
- Preconditions
-
template<typename Y>
static array<T> wrap(const sycl::queue &queue, Y *data, std::int64_t count, const std::vector<sycl::event> &dependencies = {})# 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:
queue – The SYCL* queue object.
data – The pointer to externally-allocated memory block.
count – The number of elements of type
T
in the memory block.dependencies – Events indicating availability of the
Data
for reading or writing.
- Preconditions
Constructors
-
array()#
Creates a new instance of the class without memory allocation:
mutable_data
anddata
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> &other)#
Creates a new array instance that shares an ownership with
other
on its memory block.
-
array(array<T> &&other)#
Moves
data
,mutable_data
pointers,count
, and pointer to the ownership structure inother
to the new array instance.
-
~array() = default#
-
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
deleter
is assigned to it.- Template Parameters:
Deleter – The type of a deleter used to free the
Data
. The deleter provides void operator()(Data*) member function.- Parameters:
data – The pointer to externally-allocated memory block.
count – The number of elements of type
Data
in the memory block.deleter – The object used to free
Data
.
-
template<typename Deleter>
array(const sycl::queue &queue, T *data, std::int64_t count, Deleter &&deleter, const std::vector<sycl::event> &dependencies = {})# 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
deleter
is assigned to it.- Template Parameters:
Deleter – The type of a deleter used to free the
Data
. The deleter provides void operator()(Data*) member function.- Parameters:
queue – The SYCL* queue object.
data – The pointer to externally-allocated memory block.
count – The number of elements of type
Data
in the memory block.deleter – The object used to free
Data
.dependencies – Events that indicate when
Data
becomes ready to be read or written.
-
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
deleter
is assigned to it.- Template Parameters:
ConstDeleter – The type of a deleter used to free the
Data
. 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
Data
in theData
.deleter – The object used to free
Data
.
-
template<typename ConstDeleter>
array(const sycl::queue &queue, const T *data, std::int64_t count, ConstDeleter &&deleter, const std::vector<sycl::event> &dependencies = {})# 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
deleter
is assigned to it.- Template Parameters:
ConstDeleter – The type of a deleter used to free the
Data
. The deleter implements void operator()(const Data*) member function.- Parameters:
queue – The SYCL* queue object.
data – The pointer to externally-allocated memory block.
count – The number of elements of type
Data
in theData
.deleter – The object used to free
Data
.dependencies – Events that indicate when
Data
becomes ready to be read or written.
Creates a new array instance that shares ownership with the user-provided shared pointer.
- Parameters:
data – The shared pointer to externally-allocated memory block.
count – The number of elements of type
Data
in the memory block.
Creates a new array instance that shares ownership with the user-provided shared pointer.
- Parameters:
queue – The SYCL* queue object.
data – The shared pointer to externally-allocated memory block.
count – The number of elements of type
Data
in the memory block.dependencies – Events that indicate when
Data
becomes ready to be read or written.
Creates a new array instance that shares ownership with the user-provided shared pointer.
- Parameters:
data – The shared pointer to externally-allocated memory block.
count – The number of elements of type
Data
in the memory block.
Creates a new array instance that shares ownership with the user-provided shared pointer.
- Parameters:
queue – The SYCL* queue object.
data – The shared pointer to externally-allocated memory block.
count – The number of elements of type
Data
in the memory block.dependencies – Events that indicate when
Data
becomes ready to be read or written.
-
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
Data
pointer, assigns the pointer to the ownership structure ofref
to the new instance. Array returnsData
pointer as its mutable or immutable block depending on theData
type.- Template Parameters:
Y – The type of elements in the referenced array.
K – Either
T
or \(const T\) 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
T
in theData
.
- Preconditions
-
array(impl_t *impl)#
Creates array from impl.
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 inother
.- Postconditions
-
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 andother
.
-
T *get_mutable_data() const#
The pointer to the memory block holding mutable data.
- Preconditions
- has_mutable_data() == true, othewise throws domain_error
-
const T *get_data() const noexcept#
The pointer to the memory block holding immutable data.
-
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
-
array &need_mutable_data(sycl::queue &queue, const sycl::usm::alloc &alloc = sycl::usm::alloc::shared)#
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.- Parameters:
queue – The SYCL* queue object.
alloc – The kind of USM to be allocated.
- Postconditions
- has_mutable_data() == true
-
std::int64_t get_count() const noexcept#
The number of elements of type
T
in a memory block.
-
std::int64_t get_size() const noexcept#
The size of memory block in bytes.
-
void reset()#
Resets ownership structure pointer to nullptr, sets
count
to zero,data
andmutable_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
Data
to allocate memory for.
-
void reset(const sycl::queue &queue, std::int64_t count, const sycl::usm::alloc &alloc = sycl::usm::alloc::shared)#
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:
queue – The SYCL* queue object.
count – The number of elements of type
T
to allocate memory for.alloc – The kind of USM to be allocated.
-
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
deleter
object to it, setsdata
andmutable_data
pointers to this block.- Template Parameters:
Deleter – The type of a deleter used to free the
Data
. 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
Data
into the block.deleter – The object used to free
Data
.
-
template<typename Deleter>
void reset(const sycl::queue &queue, T *data, std::int64_t count, Deleter &&deleter, const std::vector<sycl::event> &dependencies = {})# Creates the ownership structure for memory block of externally-allocated mutable data, assigns input
deleter
object to it, setsdata
andmutable_data
pointers to this block.- Template Parameters:
Deleter – The type of a deleter used to free the
Data
. The deleter implements void operator()(Data*) member function.- Parameters:
queue – The SYCL* queue object.
data – The mutable memory block pointer to be assigned inside the array.
count – The number of elements of type
Data
into the block.deleter – The object used to free
Data
.dependencies – Events that indicate when
Data
becomes ready to be read or written.
-
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
deleter
object to it, setsdata
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
Data
into the block.deleter – The object used to free
Data
.
-
template<typename ConstDeleter>
void reset(const sycl::queue &queue, const T *data, std::int64_t count, ConstDeleter &&deleter, const std::vector<sycl::event> &dependencies = {})# Creates the ownership structure for memory block of externally-allocated immutable data, assigns input
deleter
object to it, setsdata
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:
queue – The SYCL* queue object.
data – The immutable memory block pointer to be assigned inside the array.
count – The number of elements of type
Data
into the block.deleter – The object used to free
Data
.dependencies – Events that indicate when
Data
becomes ready to be read or written.
-
template<typename Y>
void reset(const array<Y> &ref, T *data, std::int64_t count)# Initializes
data
andmutable_data
with data pointer,count
with inputcount
value, initializes the pointer to ownership structure with the one from ref. Array returnsData
pointer as its mutable block.- Template Parameters:
Y – The type of elements in the referenced array.
- 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
T
in theData
.
-
template<typename Y>
void reset(const array<Y> &ref, const T *data, std::int64_t count)# Initializes
data
with data pointer,count
with inputcount
value, initializes the pointer to ownership structure with the one from ref. Array returnsData
pointer as its immutable block.- Template Parameters:
Y – The type of elements in the referenced array.
- 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
T
in theData
.
-
const T &operator[](std::int64_t index) const noexcept#
Provides a read-only access to the elements of array. Does not perform boundary checks.
-
std::optional<sycl::queue> get_queue() const#
Returns a queue that was used to create array object. If no queue was provided at the array construction phase, returns empty
std::optional
object.
-
array<T> get_slice(std::int64_t first, std::int64_t last) const#
Creates slice of this array.
Usage Example#
The following listing provides a brief introduction to the array API and an example of basic usage scenario:
#include <sycl/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;
}