Document new Buffer methods

Author: szymon-zadworny

oneapi-rs/src/buffer.rs

@@ -81,12 +81,13 @@ impl<T, A: UsmAlloc> Drop for Buffer<T, A> {
     }
 }
 
-pub struct BufferInProgress<T, A: UsmAlloc> {
+/// A [`Buffer`] whose initialization has been enqueued. You need to wait/await it.
+pub struct EnqueuedBuffer<T, A: UsmAlloc> {
     buffer: Buffer<T, A>,
     event: Event
 }
 
-impl<T, A: UsmAlloc> BufferInProgress<T, A> {
+impl<T, A: UsmAlloc> EnqueuedBuffer<T, A> {
     pub(crate) fn new(buffer: Buffer<T, A>, event: Event) -> Self {
         Self {
             buffer,
@@ -95,14 +96,16 @@ impl<T, A: UsmAlloc> BufferInProgress<T, A> {
     }
 }
 
-impl<T, A: UsmAlloc> BufferInProgress<T, A> {
+impl<T, A: UsmAlloc> EnqueuedBuffer<T, A> {
+    /// Waits for [`Buffer`] initialization to finish.
     pub fn wait(mut self) -> Buffer<T, A> {
         self.event.wait();
         self.buffer
     }
 }
 
 #[pin_project]
+/// A [`Future`] which represents a pending [`Buffer`] allocation.
 pub struct BufferFuture<T, A: UsmAlloc> {
     buffer: Option<Buffer<T, A>>,
     #[pin]
@@ -117,7 +120,7 @@ impl<T, A: UsmAlloc> Future for BufferFuture<T, A> {
     }
 }
 
-impl<T, A: UsmAlloc> IntoFuture for BufferInProgress<T, A> {
+impl<T, A: UsmAlloc> IntoFuture for EnqueuedBuffer<T, A> {
     type Output = Buffer<T, A>;
     type IntoFuture = BufferFuture<T, A>;
 

oneapi-rs/src/queue.rs

@@ -9,7 +9,7 @@
 use bytemuck::Pod;
 use oneapi_rs_sys::{queue::ffi, types::ffi::EventPtr};
 
-use crate::{buffer::{Buffer, BufferInProgress}, device::Device, event::Event, usm::{HostAllocator, SharedAllocator, UsmAlloc, UsmAllocator}};
+use crate::{buffer::{Buffer, EnqueuedBuffer}, device::Device, event::Event, usm::{HostAllocator, SharedAllocator, UsmAlloc, UsmAllocator}};
 
 /// The `Queue` connects a host program to a single device. Programs submit tasks to a device via the
 /// `Queue` and may monitor the `Queue` for completion. A program initiates the task by submitting
@@ -28,20 +28,20 @@ impl Queue {
     }
 
     /// Allocates zeroed memory and creates a host-side [`Buffer`] that can store an array of T.
-    pub fn alloc_host<T: Pod>(&mut self, len: usize) -> BufferInProgress<T, UsmAllocator<HostAllocator>> {
+    pub fn alloc_host<T: Pod>(&mut self, len: usize) -> EnqueuedBuffer<T, UsmAllocator<HostAllocator>> {
         unsafe {
             let mut buffer = self.alloc_uninit_host(len);
             let event = self.memset(&mut buffer, 0);
-            BufferInProgress::new(buffer, event)
+            EnqueuedBuffer::new(buffer, event)
         }
     }
 
     /// Allocates zeroed memory and creates a shared [`Buffer`] that can store an array of T.
-    pub fn alloc_shared<T: Pod>(&mut self, len: usize) -> BufferInProgress<T, UsmAllocator<SharedAllocator>> {
+    pub fn alloc_shared<T: Pod>(&mut self, len: usize) -> EnqueuedBuffer<T, UsmAllocator<SharedAllocator>> {
         unsafe {
             let mut buffer = self.alloc_uninit_shared(len);
             let event = self.memset(&mut buffer, 0);
-            BufferInProgress::new(buffer, event)
+            EnqueuedBuffer::new(buffer, event)
         }
     }