Struct blaze_rs::buffer::Buffer

pub struct Buffer<T, C: Context = Global> { /* private fields */ }

Buffers

The Buffer type is a wrapper arround a RawBuffer that provides extra functionality and safety guarantees. It has the following signature:

pub struct Buffer<T: Copy, C: Context = Global> {
    inner: RawBuffer,
    ctx: C,
    phtm: PhantomData<T>
}

Example

use std::ptr::NonNull;
use blaze_rs::{prelude::*, context::SimpleContext, buffer::BufferRange};

#[global_context]
static CONTEXT : SimpleContext = SimpleContext::default();

fn with_buffer () -> Result<()> {
    let values = [1, 2, 3, 4, 5];
    let buffer = Buffer::new(&values, MemAccess::READ_ONLY, false)?;

    let read: Vec<i32> = buffer.read_blocking(.., None)?;
    assert_eq!(values.as_slice(), read.as_slice());

    Ok(())
}

fn without_buffer () -> Result<()> {
    let values = [1, 2, 3, 4, 5];

    let buffer = RawBuffer::new(
        values.len() * core::mem::size_of::<i32>(), 
        MemFlags::new(MemAccess::READ_ONLY, HostPtr::COPY), 
        NonNull::new(values.as_ptr() as *mut _)
    )?;
    
    let mut read = Vec::<i32>::with_capacity(values.len());
    unsafe {
        let evt : RawEvent = buffer.read_to_ptr(BufferRange::from_parts::<i32>(0, 5)?, read.as_mut_ptr().cast(), None)?;
        let _ : () = evt.join_by_ref()?;
        read.set_len(values.len());
    }

    assert_eq!(values.as_slice(), read.as_slice());
    Ok(())
}

Implementations

impl<T> Buffer<T>

pub fn new(v: &[T], access: MemAccess, alloc: bool) -> Result<Self>where T: Copy,

Creates a new buffer with the given values and flags.

pub fn new_uninit( len: usize, access: MemAccess, alloc: bool ) -> Result<Buffer<MaybeUninit<T>>>

Creates a new uninitialized buffer with the given size and flags.

pub fn new_zeroed( len: usize, access: MemAccess, alloc: bool ) -> Result<Buffer<MaybeUninit<T>>>

Creates a new zero-filled, uninitialized buffer with the given size and flags. If using OpenCL 1.2 or higher, this uses the fill event. Otherwise, a regular write is used.

pub unsafe fn create( len: usize, flags: MemFlags, host_ptr: Option<NonNull<T>> ) -> Result<Self>

Creates a new buffer with the given custom parameters.

impl<T, C: Context> Buffer<T, C>

pub fn new_in(ctx: C, v: &[T], access: MemAccess, alloc: bool) -> Result<Self>where T: Copy,

Creates a new buffer with the given values and flags.

pub fn new_uninit_in( ctx: C, len: usize, access: MemAccess, alloc: bool ) -> Result<Buffer<MaybeUninit<T>, C>>

Creates a new uninitialized buffer with the given size and flags.

pub fn new_zeroed_in( ctx: C, len: usize, access: MemAccess, alloc: bool ) -> Result<Buffer<MaybeUninit<T>, C>>

Creates a new zero-filled, uninitialized buffer with the given size and flags. If using OpenCL 1.2 or higher, this uses the fill event. Otherwise, a regular write is used.

pub unsafe fn create_in( ctx: C, len: usize, flags: MemFlags, host_ptr: Option<NonNull<T>> ) -> Result<Self>

Creates a new buffer with the given custom parameters.

pub fn len(&self) -> Result<usize>

Number of elements inside the buffer

pub fn context(&self) -> &C

Returns a reference to the Buffer’s underlying Context.

pub fn slice<R: IntoRange>(&self, range: R) -> Result<Buf<'_, T, C>>where C: Clone,

Available on crate feature cl1_1 only.

Creates a shared slice of this buffer.

pub fn slice_mut<R: IntoRange>(&mut self, range: R) -> Result<BufMut<'_, T, C>>where C: Clone,

Available on crate feature cl1_1 only.

Creates a mutable slice of this buffer.

pub fn chunks_exact(&self, offset: usize, len: usize) -> ChunksExact<'_, T, C> where C: Clone,

Available on crate feature cl1_1 only.

Returns an iterator over chunks of size len of the buffer, starting at offset.

pub fn chunks_exact_mut( &mut self, offset: usize, len: usize ) -> ChunksExactMut<'_, T, C> where C: Clone,

Available on crate feature cl1_1 only.

Returns an iterator over mutable chunks of size len of the buffer, starting at offset.

This is usefull for situations where you want to write to the same buffer in parallel, in regions that don’t overlap.

pub unsafe fn transmute<U>(self) -> Buffer<U, C>

Reinterprets the bits of the buffer to another type.

Safety

This function has the same safety as transmute

pub fn into_uninit(self) -> Buffer<MaybeUninit<T>, C>

Converts Buffer<T,C> into Buffer<MaybeUninit<T>,C>

pub const fn as_uninit(&self) -> &Buffer<MaybeUninit<T>, C>

Converts &Buffer<T,C> to &Buffer<MaybeUninit<T>,C>

pub fn as_mut_uninit(&mut self) -> &mut Buffer<MaybeUninit<T>, C>

Converts &mut Buffer<T,C> to &mut Buffer<MaybeUninit<T>,C>

pub fn try_clone(&self, wait: WaitList<'_>) -> Result<Self>where T: Clone, C: Clone,

pub async fn try_clone_async<'a>(&self, wait: WaitList<'a>) -> Result<Self>where T: Clone, C: Clone,

Available on crate feature futures only.

pub fn eq_buffer(&self, other: &Buffer<T, C>) -> bool

Checks if the buffer pointer is the same in both buffers.

impl<T: 'static + Copy + Send + Sync, C: Context> Buffer<MaybeUninit<T>, C>

pub fn write_init<'scope, 'env, O: Into<Option<usize>>>( &'env mut self, scope: &'scope Scope<'scope, 'env, C>, offset: O, src: &'env [T], wait: WaitList<'_> ) -> Result<WriteEvent<'scope, MaybeUninit<T>, C>>

Convenience method for writing to an unitialized buffer. See write.

pub fn write_init_blocking( &mut self, offset: impl Into<Option<usize>>, src: &[T], wait: WaitList<'_> ) -> Result<()>

Convenience method for writing to an unitialized buffer. See write_blocking.

pub fn copy_from_init<'scope, 'env, Dst: Into<Option<usize>>, Src: Into<Option<usize>>, Size: Into<Option<usize>>>( &'env mut self, scope: &'scope Scope<'scope, 'env, C>, dst_offset: Dst, src: &'env Buffer<T, C>, src_offset: Src, size: Size, wait: WaitList<'_> ) -> Result<CopyEvent<'scope, MaybeUninit<T>, C>>

Convenience method for copying to an unitialized buffer. See copy_from.

pub fn copy_from_init_blocking( &mut self, dst_offset: impl Into<Option<usize>>, src: &Buffer<T, C>, src_offset: impl Into<Option<usize>>, size: impl Into<Option<usize>>, wait: WaitList<'_> ) -> Result<()>where T: Copy + Send + Sync,

Convenience method for copying to an unitialized buffer. See copy_from_blocking.

pub fn fill_init<'scope, 'env, R: IntoRange>( &'env mut self, scope: &'scope Scope<'scope, 'env, C>, v: T, range: R, wait: WaitList<'_> ) -> Result<FillEvent<'scope, MaybeUninit<T>, C>>

Available on crate feature cl1_2 only.

Convenience method for filling an unitialized buffer. See fill.

pub fn fill_init_blocking( &mut self, v: T, range: impl IntoRange, wait: WaitList<'_> ) -> Result<()>

Available on crate feature cl1_2 only.

Convenience method for filling an unitialized buffer. See fill_blocking.

impl<T, C: Context> Buffer<MaybeUninit<T>, C>

pub unsafe fn assume_init(self) -> Buffer<T, C>

Extracts the value from Buffer<MaybeUninit<T>> to Buffer<T>

Safety

This function has the same safety as MaybeUninit’s assume_init

impl<T: 'static + Copy + Send + Sync, C: Context> Buffer<T, C>

pub fn get_blocking(&self, idx: usize, wait: WaitList<'_>) -> Result<T>

Reads the contents of the buffer at the specified index, blocking the current thread until the operation has completed.

pub fn get<'scope, 'env>( &'env self, scope: &'scope Scope<'scope, 'env, C>, idx: usize, wait: WaitList<'_> ) -> Result<GetEvent<'scope, T, C>>where T: 'static + Send,

Reads the contents of the buffer at the specified index, blocking the current thread until the operation has completed.

pub fn read<'scope, 'env, R: IntoRange>( &'env self, scope: &'scope Scope<'scope, 'env, C>, range: R, wait: WaitList<'_> ) -> Result<ReadEvent<'scope, T, C>>

Reads the contents of the buffer.

pub fn read_blocking<R: IntoRange>( &self, range: R, wait: WaitList<'_> ) -> Result<Vec<T>>

Reads the contents of the buffer, blocking the current thread until the operation has completed.

pub fn read_into<'scope, 'env, O: Into<Option<usize>>>( &'env self, s: &'scope Scope<'scope, 'env, C>, offset: O, dst: &'env mut [T], wait: WaitList<'_> ) -> Result<ReadIntoEvent<'scope, T, C>>

Reads the contents of the buffer into dst.

pub fn read_into_blocking( &self, offset: impl Into<Option<usize>>, dst: &mut [T], wait: WaitList<'_> ) -> Result<()>

Reads the contents of the buffer into dst, blocking the current thread until the operation has completed.

pub fn write<'scope, 'env, O: Into<Option<usize>>>( &'env mut self, scope: &'scope Scope<'scope, 'env, C>, offset: O, src: &'env [T], wait: WaitList<'_> ) -> Result<WriteEvent<'scope, T, C>>

Writes the contents of src into the buffer

pub fn write_blocking( &mut self, offset: impl Into<Option<usize>>, src: &[T], wait: WaitList<'_> ) -> Result<()>

Writes the contents of src into the buffer, blocking the current thread until the operation has completed.

pub fn copy_to<'scope, 'env, Src: Into<Option<usize>>, Dst: Into<Option<usize>>, Size: Into<Option<usize>>>( &'env self, scope: &'scope Scope<'scope, 'env, C>, src_offset: Src, dst: &'env mut Self, dst_offset: Dst, size: Size, wait: WaitList<'_> ) -> Result<CopyEvent<'scope, T, C>>

Copies the contents from self to dst

pub fn copy_to_blocking( &self, src_offset: impl Into<Option<usize>>, dst: &mut Self, dst_offset: impl Into<Option<usize>>, size: impl Into<Option<usize>>, wait: WaitList<'_> ) -> Result<()>

Copies the contents from self to dst, blocking the current thread until the operation has completed.

pub fn copy_from<'scope, 'env, Dst: Into<Option<usize>>, Src: Into<Option<usize>>, Size: Into<Option<usize>>>( &'env mut self, s: &'scope Scope<'scope, 'env, C>, dst_offset: Dst, src: &'env Self, src_offset: Src, size: Size, wait: WaitList<'_> ) -> Result<CopyEvent<'scope, T, C>>

Copies the contents from src to self

pub fn copy_from_blocking( &mut self, dst_offset: impl Into<Option<usize>>, src: &Self, src_offset: impl Into<Option<usize>>, size: impl Into<Option<usize>>, wait: WaitList<'_> ) -> Result<()>

Copies the contents from src to self, blocking the current thread until the operation has completed.

pub fn fill<'scope, 'env, R: IntoRange>( &'env mut self, scope: &'scope Scope<'scope, 'env, C>, v: T, range: R, wait: WaitList<'_> ) -> Result<FillEvent<'scope, T, C>>

Available on crate feature cl1_2 only.

Fills a region of the buffer with v

pub fn fill_blocking<R: IntoRange>( &mut self, v: T, range: R, wait: WaitList<'_> ) -> Result<()>

Available on crate feature cl1_2 only.

Fills a region of the buffer with v, blocking the current thread until the operation has completed.

impl<T, C: Context> Buffer<T, C>

pub fn map<'scope, 'env, R: IntoRange>( &'env self, s: &'scope Scope<'scope, 'env, C>, range: R, wait: WaitList<'_> ) -> Result<BufferMapEvent<'scope, 'env, T, C>>

pub fn map_blocking<'a, R: IntoRange>( &'a self, range: R, wait: WaitList<'_> ) -> Result<MapGuard<'a, T, C>>

pub fn map_mut<'scope, 'env, R: IntoRange>( &'env mut self, s: &'scope Scope<'scope, 'env, C>, range: R, wait: WaitList<'_> ) -> Result<BufferMapMutEvent<'scope, 'env, T, C>>

pub fn map_mut_blocking<'a, R: IntoRange>( &'a mut self, range: R, wait: WaitList<'_> ) -> Result<MapMutGuard<'a, T, C>>

Methods from Deref<Target = RawBuffer>

pub unsafe fn create_sub_buffer( &self, flags: MemAccess, region: BufferRange ) -> Result<RawBuffer>

Available on crate feature cl1_1 only.

Creates a new buffer object (referred to as a sub-buffer object) from an existing buffer object.

pub unsafe fn read_to_ptr( &self, range: BufferRange, dst: *mut c_void, wait: WaitList<'_> ) -> Result<RawEvent>

pub unsafe fn read_rect_to_ptr( &self, buffer_origin: [usize; 3], host_origin: [usize; 3], region: [usize; 3], buffer_row_pitch: Option<usize>, buffer_slice_pitch: Option<usize>, host_row_pitch: Option<usize>, host_slice_pitch: Option<usize>, dst: *mut c_void, wait: WaitList<'_> ) -> Result<RawEvent>

Available on crate feature cl1_1 only.

pub unsafe fn write_from_ptr( &mut self, range: BufferRange, src: *const c_void, wait: WaitList<'_> ) -> Result<RawEvent>

pub unsafe fn write_rect_from_ptr( &mut self, buffer_origin: [usize; 3], host_origin: [usize; 3], region: [usize; 3], buffer_row_pitch: Option<usize>, buffer_slice_pitch: Option<usize>, host_row_pitch: Option<usize>, host_slice_pitch: Option<usize>, src: *const c_void, wait: WaitList<'_> ) -> Result<RawEvent>

Available on crate feature cl1_1 only.

pub unsafe fn copy_from( &mut self, dst_offset: usize, src: &RawBuffer, src_offset: usize, size: usize, wait: WaitList<'_> ) -> Result<RawEvent>

pub unsafe fn fill_raw<T: Copy>( &mut self, v: T, range: BufferRange, wait: WaitList<'_> ) -> Result<RawEvent>

Available on crate feature cl1_2 only.

pub unsafe fn map_read( &self, range: BufferRange, wait: WaitList<'_> ) -> Result<(*const c_void, RawEvent)>

pub unsafe fn map_write( &self, range: BufferRange, wait: WaitList<'_> ) -> Result<(*mut c_void, RawEvent)>

pub unsafe fn map_read_write( &self, range: BufferRange, wait: WaitList<'_> ) -> Result<(*mut c_void, RawEvent)>

pub unsafe fn read_to_ptr_in( &self, range: BufferRange, dst: *mut c_void, queue: &RawCommandQueue, wait: WaitList<'_> ) -> Result<RawEvent>

Reads the contents of this

pub unsafe fn read_rect_to_ptr_in( &self, buffer_origin: [usize; 3], host_origin: [usize; 3], region: [usize; 3], buffer_row_pitch: Option<usize>, buffer_slice_pitch: Option<usize>, host_row_pitch: Option<usize>, host_slice_pitch: Option<usize>, dst: *mut c_void, queue: &RawCommandQueue, wait: WaitList<'_> ) -> Result<RawEvent>

Available on crate feature cl1_1 only.

pub unsafe fn write_from_ptr_in( &mut self, range: BufferRange, src: *const c_void, queue: &RawCommandQueue, wait: WaitList<'_> ) -> Result<RawEvent>

pub unsafe fn write_rect_from_ptr_in( &mut self, buffer_origin: [usize; 3], host_origin: [usize; 3], region: [usize; 3], buffer_row_pitch: Option<usize>, buffer_slice_pitch: Option<usize>, host_row_pitch: Option<usize>, host_slice_pitch: Option<usize>, src: *const c_void, queue: &RawCommandQueue, wait: WaitList<'_> ) -> Result<RawEvent>

Available on crate feature cl1_1 only.

pub unsafe fn copy_from_in( &mut self, dst_offset: usize, src: &RawBuffer, src_offset: usize, size: usize, queue: &RawCommandQueue, wait: WaitList<'_> ) -> Result<RawEvent>

pub unsafe fn copy_from_rect_raw_in( &mut self, dst_origin: [usize; 3], src_origin: [usize; 3], region: [usize; 3], dst_row_pitch: Option<usize>, dst_slice_pitch: Option<usize>, src_row_pitch: Option<usize>, src_slice_pitch: Option<usize>, src: &RawBuffer, queue: &RawCommandQueue, wait: WaitList<'_> ) -> Result<RawEvent>

Available on crate feature cl1_1 only.

pub unsafe fn fill_raw_in<T>( &mut self, v: T, range: BufferRange, queue: &RawCommandQueue, wait: WaitList<'_> ) -> Result<RawEvent>

Available on crate feature cl1_2 only.

pub unsafe fn map_read_in( &self, range: BufferRange, queue: &RawCommandQueue, wait: WaitList<'_> ) -> Result<(*const c_void, RawEvent)>

pub unsafe fn map_write_in( &self, range: BufferRange, queue: &RawCommandQueue, wait: WaitList<'_> ) -> Result<(*mut c_void, RawEvent)>

pub unsafe fn map_read_write_in( &self, range: BufferRange, queue: &RawCommandQueue, wait: WaitList<'_> ) -> Result<(*mut c_void, RawEvent)>

Methods from Deref<Target = RawMemObject>

pub unsafe fn retain(&self) -> Result<()>

pub fn id(&self) -> cl_mem

pub fn id_ref(&self) -> &cl_mem

pub fn id_ref_mut(&mut self) -> &mut cl_mem

pub fn ty(&self) -> Result<MemObjectType>

Returns the memory obejct’s type

pub fn associated_memobject(&self) -> Result<Option<RawMemObject>>

Available on crate feature cl1_1 only.

Return memory object from which memobj is created.

pub fn flags(&self) -> Result<MemFlags>

Return the flags argument value specified when memobj is created.

pub fn size(&self) -> Result<usize>

Return actual size of the data store associated with memobj in bytes.

pub fn host_ptr(&self) -> Result<Option<NonNull<c_void>>>

If memobj is created with a host_ptr specified, return the host_ptr argument value specified when memobj is created.

pub fn map_count(&self) -> Result<u32>

Map count. The map count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for debugging.

pub fn reference_count(&self) -> Result<u32>

Return memobj reference count. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

pub fn context(&self) -> Result<RawContext>

Return context specified when memory object is created.

pub fn offset(&self) -> Result<usize>

Available on crate feature cl1_1 only.

Return offset if memobj is a sub-buffer object created using create_sub_buffer. Returns 0 if memobj is not a subbuffer object.

pub fn uses_svm_pointer(&self) -> Result<bool>

Available on crate feature cl2 only.

Return true if memobj is a buffer object that was created with CL_MEM_USE_HOST_PTR or is a sub-buffer object of a buffer object that was created with CL_MEM_USE_HOST_PTR and the host_ptr specified when the buffer object was created is a SVM pointer; otherwise returns false.

pub fn on_destruct(&self, f: impl 'static + FnOnce() + Send) -> Result<()>

Available on crate feature cl1_1 only.

Adds a callback to be executed when the memory object is destructed by OpenCL.

pub fn on_destruct_boxed(&self, f: Box<dyn FnOnce() + Send>) -> Result<()>

Available on crate feature cl1_1 only.

pub unsafe fn on_destruct_raw( &self, f: unsafe extern "C" fn(memobj: cl_mem, user_data: *mut c_void), user_data: *mut c_void ) -> Result<()>

Available on crate feature cl1_1 only.

Trait Implementations

impl<T: Clone, C: Context + Clone> Clone for Buffer<T, C>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug, C: Context> Debug for Buffer<T, C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, C: Context> Deref for Buffer<T, C>

type Target = RawBuffer

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T, C: Context> DerefMut for Buffer<T, C>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T: Copy + Sync, C: Context> KernelPointer<T> for Buffer<T, C>

unsafe fn set_arg( &self, kernel: &mut RawKernel, _wait: &mut Vec<RawEvent>, idx: u32 ) -> Result<()>

fn complete(&self, _event: &RawEvent) -> Result<()>

impl<T: PartialEq, C: Context> PartialEq<Buffer<T, C>> for Buffer<T, C>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Eq, C: Context> Eq for Buffer<T, C>