Buffers

sycl::buffer

template <typename T, int dimensions = 1,
          typename AllocatorT = sycl::buffer_allocator>
class buffer;

Template parameters

T

Type of data in buffer

dimensions

Dimensionality of data: 1, 2, or 3

AllocatorT

Allocator for buffer data

Buffers are containers for data that can be read/written by both kernel and host. Data in a buffer cannot be accessed directly via pointers. Instead, a program creates an sycl::accessor (buffer) that references the buffer. The accessor provides array-like interfaces to read/write actual data. Accessors indicate when they read or write data. When a program creates an accessor for a buffer, the SYCL runtime copies the data to where it is needed, either the host or the device. If the accessor is part of a device command group, then the runtime delays execution of the kernel until the data movement is complete. If the host creates an accessor, it will pause until the data is available on the host. As a result data and kernels can execute asynchronously and in parallel, only requiring the program to specify the data dependencies.

Initialization

Buffers can be automatically initialized via host data, iterator, or as a slice of another buffer. The constructor determines the initialization method.

Write back

The destructor for a buffer can optionally write the data back to host memory, either by pointer or iterator. set_final_data and set_write_back control the write back of data.

Memory allocation

The SYCL runtimes uses the default allocator for buffer memory allocation, unless the constructor provides an allocator.

Member types

value_type

type of buffer element

reference

reference type of buffer element

const_reference

const reference type of buffer element

allocator_type

type of allocator for buffer data

See also

SYCL Specification Section 4.7.2

(constructors)

buffer(const sycl::range<dimensions> &bufferRange,
       const sycl::property_list &propList = {});
buffer(const sycl::range<dimensions> &bufferRange, AllocatorT allocator,
       const sycl::property_list &propList = {});
buffer(T hostData, const sycl::range<dimensions> &bufferRange,
       const sycl::property_list &propList = {});
buffer(T *hostData, const sycl::range<dimensions> &bufferRange,
       AllocatorT allocator, const sycl::property_list &propList = {});
buffer(const T *hostData, const sycl::range<dimensions> &bufferRange,
       const sycl::property_list &propList = {});
buffer(const T *hostData, const sycl::range<dimensions> &bufferRange,
       AllocatorT allocator, const sycl::property_list &propList = {});
buffer(const shared_ptr_class<T> &hostData,
       const sycl::range<dimensions> &bufferRange, AllocatorT allocator,
       const sycl::property_list &propList = {});
buffer(const shared_ptr_class<T> &hostData,
       const sycl::range<dimensions> &bufferRange,
       const sycl::property_list &propList = {});
buffer(buffer<T, dimensions, AllocatorT> b, const id<dimensions> &baseIndex,
       const sycl::range<dimensions> &subRange);

*Available only when:
 dimensions == 1

template <class InputIterator>
buffer<T, 1>(InputIterator first, InputIterator last, AllocatorT allocator,
             const sycl::property_list &propList = {});
template <class InputIterator>
buffer<T, 1>(InputIterator first, InputIterator last,
             const sycl::property_list &propList = {});
buffer(cl_mem clMemObject, const sycl::context &syclContext,
       event availableEvent = {});

Construct a buffer.

Buffers can be initialized by a host data pointer. While the buffer exists, it owns the host data and direct access of the host data pointer during that time is undefined. The SYCL runtime performs a write back of the buffer data back to the host data pointer when the buffer is destroyed. Buffers can also be initialized as a slice of another buffer, by specifying the origin of the data and the dimensions.

A constructor can also accept cl_mem or iterators to initialize a buffer.

Template parameters

InputIterator

type of iterator used to initialize the buffer

Parameters

bufferRange

sycl::range specifies the dimensions of the buffer

allocator

Allocator for buffer data

propList

See Buffer properties

hostData

Pointer to host memory to hold data

first

Iterator to initialize buffer

last

Iterator to initialize buffer

b

Buffer used to initialize this buffer

baseIndx

Origin of sub-buffer

subRange

Dimensions of sub-buffer

get_range

sycl::range<dimensions> get_range() const;

Returns the dimensions of the buffer.

get_count

size_t get_count() const;

Returns the total number of elements in the buffer.

get_size

size_t get_size() const;

Returns the size of the buffer storage in bytes.

get_allocator

AllocatorT get_allocator() const;

Returns the allocator provided to the buffer.

get_access

template <sycl::access::mode mode, sycl::access::target target = sycl::access::target::global_buffer>
accessor<T, dimensions, mode, target> get_access(
    sycl::handler &commandGroupHandler);
template <sycl::access::mode mode>
accessor<T, dimensions, mode, sycl::access::target::host_buffer> get_access();
template <sycl::access::mode mode, sycl::access::target target = sycl::access::target::global_buffer>
accessor<T, dimensions, mode, target> get_access(
    sycl::handler &commandGroupHandler, sycl::range<dimensions> accessRange,
    id<dimensions> accessOffset = {});
template <sycl::access::mode mode>
accessor<T, dimensions, mode, sycl::access::target::host_buffer> get_access(
  sycl::range<dimensions> accessRange, sycl::id<dimensions> accessOffset = {});

Returns a accessor to the buffer.

Template parameters

mode

See sycl::access::mode

target

See sycl::access::target

Parameters

commandGroupHandler

Command group that uses the accessor

accessRange

Dimensions of the sub-buffer that is accessed

accessOffset

Origin of the sub-buffer that is accessed

set_final_data

template <typename Destination = std::nullptr_t>
void set_final_data(Destination finalData = nullptr);

Template parameters

Destination

std::weak_ptr<T> or output iterator

Parameters

finalData

Indicates where data is copied at destruction time

Set the final data location. Final data controls the location for write back when the buffer is destroyed.

set_write_back

void set_write_back(bool flag = true);

Parameters

flag

True to force write back

Set the write back.

is_sub_buffer

bool is_sub_buffer() const;

Returns True if this is a sub-buffer.

reinterpret

template <typename ReinterpretT, int ReinterpretDim>
buffer<ReinterpretT, ReinterpretDim, AllocatorT>
reinterpret(range<ReinterpretDim> reinterpretRange) const;

Template parameters

ReinterpretT

Type of new buffer element

ReinterpretDim

Dimensions of new buffer

Parameters

ReinterpretRange

Dimensionality of new buffer

Creates a new buffer with the requested element type and dimensionality, containing the data of the passed buffer or sub-buffer.

Exceptions

errc::invalid_object_error

Size in bytes of new buffer does not match original buffer.

Buffer properties

sycl::propery::buffer:use_host_ptr

class use_host_ptr;

Use the provided host pointer and do not allocate new data on the host.

(constructors)

use_host_ptr();

sycl::property::use_mutex

class use_mutex;

Adds the requirement that the memory owned by the SYCL buffer can be shared with the application via a std::mutex provided to the property.

(constructors)

use_mutex();

get_mutex_ptr

sycl::mutex_class *get_mutex_ptr() const;

sycl::property::buffer::context_bound

class context_bound;

The buffer can only be associated with a single SYCL context provided to the property.

(constructors)

use_mutex();

get_context

sycl::context get_context() const;