Array
Programming interface
- 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 ofreset()methods that are used to re-assign an array to another external memory block.
- The group ofreset()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<typenameT>classarray
- Template Parameters
- T– The type of the memory block elements within the array.Tcan represent any type.
Public Static Methods- staticarray<T>empty(std::int64_tcount)
- 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 typeDatato allocate memory for.
- Preconditions
count > 0
- 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 typeTto 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.
- staticarray<T>zeros(std::int64_tcount)
- 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 typeDatato allocate memory for.
- Preconditions
count > 0
- 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 typeDatain the memory block.
- Preconditions
data != nullptr
count > 0
Constructors- array()
- Creates a new instance of the class without memory allocation:mutable_dataanddatapointers should be set tonullptr,countshould be zero; the pointer to the ownership structure should be set tonullptr.
- Creates a new array instance that shares an ownership withotheron its memory block.
- Movesdata,mutable_datapointers,count, and pointer to the ownership structure inotherto the new array instance.
- Creates a new array instance which owns a memory block of externally-allocated mutable data. The ownership structure is created for a block, the inputdeleteris assigned to it.
- Template Parameters
- Deleter– The type of a deleter used to free theData. The deleter providesvoid operator()(Data*)member function.
- Parameters
- data– The pointer to externally-allocated memory block.
- count– The number of elements of typeDatain the memory block.
- deleter– The object used to freeData.
- Creates a new array instance which owns a memory block of externally-allocated immutable data. The ownership structure is created for a block, the inputdeleteris assigned to it.
- Template Parameters
- ConstDeleter– The type of a deleter used to free theData. The deleter implementsvoid operator()(const Data*)member function.
- Parameters
- data– The pointer to externally-allocated memory block.
- count– The number of elements of typeDatain theData.
- deleter– The object used to freeData.
- array(conststd::shared_ptr<T> &data, std::int64_tcount)
- 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 typeDatain the memory block.
- array(conststd::shared_ptr<constT> &data, std::int64_tcount)
- 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 typeDatain the memory block.
- An aliasing constructor: creates a new array instance that storesDatapointer, assigns the pointer to the ownership structure ofrefto the new instance. Array returnsDatapointer as its mutable or immutable block depending on theDatatype.
- Template Parameters
- Y– The type of elements in the referenced array.
- K– EitherTor
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 typeTin theData.
- Preconditions
std::is_same_v || std::is_same_v
Public Methods- array<T>operator=(constarray<T> &other)
- Replaces thedata,mutable_datapointers,count, and pointer to the ownership structure in the array instance by the values inother.
- Postconditions
data == other.data
mutable_data == other.mutable_data
count == other.count
- array<T>operator=(array<T> &&other)
- Swaps the values ofdata,mutable_datapointers,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
- constT *get_data()constnoexcept
- The pointer to the memory block holding immutable data.
- boolhas_mutable_data()constnoexcept
- Returns whether array containsmutable_dataor 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 atdata. Creates the ownership structure for allocated memory block and stores the pointer.
- Postconditions
has_mutable_data() == true
- std::int64_tget_count()constnoexcept
- The number of elements of typeTin a memory block.
- std::int64_tget_size()constnoexcept
- The size of memory block in bytes.
- voidreset()
- Resets ownership structure pointer tonullptr, setscountto zero,dataandmutable_datatonullptr.
- voidreset(std::int64_tcount)
- 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 typeDatato allocate memory for.
- Creates the ownership structure for memory block of externally-allocated mutable data, assigns inputdeleterobject to it, setsdataandmutable_datapointers to this block.
- Template Parameters
- Deleter– The type of a deleter used to free theData. The deleter implementsvoid operator()(Data*)member function.
- Parameters
- data– The mutable memory block pointer to be assigned inside the array.
- count– The number of elements of typeDatainto the block.
- deleter– The object used to freeData.
- template<typenameConstDeleter> voidreset(constT *data, std::int64_tcount, ConstDeleter &&deleter)
- Creates the ownership structure for memory block of externally-allocated immutable data, assigns inputdeleterobject to it, setsdatapointer to this block.
- Template Parameters
- ConstDeleter– The type of a deleter used to free. The deleter implementsvoid operator()(const Data*)`member function.
- Parameters
- data– The immutable memory block pointer to be assigned inside the array.
- count– The number of elements of typeDatainto the block.
- deleter– The object used to freeData.
- Initializesdataandmutable_datawith data pointer,countwith inputcountvalue, initializes the pointer to ownership structure with the one from ref. Array returnsDatapointer 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 typeTin theData.
- Initializesdatawith data pointer,countwith inputcountvalue, initializes the pointer to ownership structure with the one from ref. Array returnsDatapointer 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 typeTin theData.
- constT &operator[](std::int64_tindex)constnoexcept
- Provides a read-only access to the elements of array. Does not perform boundary checks.
Usage example
#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;
}