Skip to main content

sycl_rs/
queue.rs

1//
2// Copyright (C) 2026 Intel Corporation
3//
4// Under the MIT License or the Apache License v2.0.
5// See LICENSE-MIT and LICENSE-APACHE for license information.
6// SPDX-License-Identifier: MIT OR Apache-2.0
7//
8
9use crate::Result;
10use bytemuck::Pod;
11use sycl_rs_sys::{queue::ffi, types::ffi::EventPtr};
12
13use crate::{
14    context::Context,
15    device::Device,
16    event::Event,
17    kernel::{Kernel, KernelArgumentList},
18    range::{NdRange, ValidDimension},
19    usm::{UsmAlloc, UsmAllocator},
20    usmbox::{
21        DeviceUsmBox, EnqueuedDeviceUsmBox, EnqueuedHostUsmBox, EnqueuedSharedUsmBox,
22        EnqueuedUsmBox, HostUsmBox, SharedUsmBox, UsmBox,
23    },
24};
25
26/// The `Queue` connects a host program to a single device. Programs submit tasks to a device via the
27/// `Queue` and may monitor the `Queue` for completion. A program initiates the task by submitting
28/// a kernel.
29pub struct Queue(pub(crate) cxx::UniquePtr<ffi::Queue>);
30
31impl Queue {
32    /// Construct a `Queue` based on the device returned from the default selector.
33    pub fn new() -> Self {
34        Self(ffi::new_queue())
35    }
36
37    /// Construct an immediate `Queue` based on the device returned from the default selector.
38    pub fn new_immediate() -> Self {
39        Self(ffi::new_queue_immediate())
40    }
41
42    /// Returns the SYCL queue’s context.
43    pub fn get_context(&self) -> Context {
44        ffi::get_context(&self.0).into()
45    }
46
47    /// Allocates zeroed memory and creates a host-side [`UsmBox`] that can store an array of T.
48    pub fn alloc_host<T: Pod>(&mut self, len: usize) -> Result<EnqueuedHostUsmBox<T>> {
49        unsafe {
50            let mut array = self.alloc_uninit_host(len);
51            self.memset(&mut array, 0)
52                .map(|event| EnqueuedUsmBox::new(array, event))
53        }
54    }
55
56    /// Allocates zeroed memory and creates a shared [`UsmBox`] that can store an array of T.
57    pub fn alloc_shared<T: Pod>(&mut self, len: usize) -> Result<EnqueuedSharedUsmBox<T>> {
58        unsafe {
59            let mut array = self.alloc_uninit_shared(len);
60            self.memset(&mut array, 0)
61                .map(|event| EnqueuedUsmBox::new(array, event))
62        }
63    }
64
65    /// Allocates zeroed memory and creates a device [`UsmBox`] that can store an array of T.
66    pub fn alloc_device<T: Pod>(&mut self, len: usize) -> Result<EnqueuedDeviceUsmBox<T>> {
67        unsafe {
68            let mut array = self.alloc_uninit_device(len);
69            self.memset(&mut array, 0)
70                .map(|event| EnqueuedUsmBox::new(array, event))
71        }
72    }
73
74    /// Allocates memory and creates a host-side [`UsmBox`] that can store an array of T.
75    /// Safety: the array contents are uninitialized.
76    pub unsafe fn alloc_uninit_host<T>(&self, len: usize) -> HostUsmBox<T> {
77        let allocator = UsmAllocator::from(self);
78        unsafe { UsmBox::new(allocator, len) }
79    }
80
81    /// Allocates memory and creates a shared [`UsmBox`] that can store an array of T.
82    /// Safety: the array contents are uninitialized.
83    pub unsafe fn alloc_uninit_shared<T>(&self, len: usize) -> SharedUsmBox<T> {
84        let allocator = UsmAllocator::from(self);
85        unsafe { UsmBox::new(allocator, len) }
86    }
87
88    /// Allocates memory and creates a device-side [`UsmBox`] that can store an array of T.
89    /// Safety: the array contents are uninitialized.
90    pub unsafe fn alloc_uninit_device<T>(&self, len: usize) -> DeviceUsmBox<T> {
91        let allocator = UsmAllocator::from(self);
92        unsafe { UsmBox::new(allocator, len) }
93    }
94
95    /// Sets memory allocated with USM allocations.
96    /// Safety: the caller must make sure the underlying memory isn't being aliased somewhere else.
97    pub unsafe fn memset<T, A: UsmAlloc>(
98        &mut self,
99        array: &mut UsmBox<T, A>,
100        value: i32,
101    ) -> Result<Event> {
102        unsafe { self.memset_with_deps(array, value, &[]) }
103    }
104
105    /// Sets memory allocated with USM allocations after all specified events finish.
106    /// Safety: the caller must make sure the underlying memory isn't being aliased somewhere else.
107    pub unsafe fn memset_with_deps<T, A: UsmAlloc>(
108        &mut self,
109        array: &mut UsmBox<T, A>,
110        value: i32,
111        dep_events: &[&Event],
112    ) -> Result<Event> {
113        let ptr = array.get_byte_ptr();
114        let num_bytes = array.get_byte_size();
115        let dep_events = dep_events
116            .iter()
117            .map(|e| EventPtr {
118                ptr: (*e).clone().0,
119            })
120            .collect::<Vec<_>>();
121        unsafe { ffi::memset(&mut self.0, ptr, value, num_bytes, dep_events) }.map(Into::into)
122    }
123
124    /// Submits a barrier to the queue.
125    pub fn barrier(&mut self) -> Result<Event> {
126        self.barrier_with_deps(&[]).map(Into::into)
127    }
128
129    /// Submits a barrier to the queue after all specified events finish.
130    pub fn barrier_with_deps(&mut self, dep_events: &[&Event]) -> Result<Event> {
131        let dep_events = dep_events
132            .iter()
133            .map(|e| EventPtr {
134                ptr: (*e).clone().0,
135            })
136            .collect::<Vec<_>>();
137        ffi::barrier(&mut self.0, dep_events).map(Into::into)
138    }
139
140    /// Performs a blocking wait for the completion of all enqueued tasks in the queue. Returns an
141    /// error if a synchronous SYCL exception occurs.
142    ///
143    /// Dropping the queue does not wait for its completion.
144    pub fn wait(&mut self) -> Result<()> {
145        ffi::wait(&mut self.0)
146    }
147
148    /// Enqueues a kernel object to the queue as an ND-range kernel, using the number of work-items
149    /// specified by the [`NdRange`] nd_range.
150    ///
151    /// Safety: The caller must make sure each argument matches the launched SYCL kernel's
152    /// signature, including their respective size, layout and alignment.
153    pub unsafe fn launch<const ARGC: usize, const DIMENSIONS: usize>(
154        &mut self,
155        nd_range: NdRange<DIMENSIONS>,
156        kernel: &Kernel,
157        args: impl KernelArgumentList<ARGC>,
158    ) -> Result<Event>
159    where
160        NdRange<DIMENSIONS>: ValidDimension,
161    {
162        unsafe { nd_range.launch(self, kernel, args) }
163    }
164
165    /// Copies the contents of the source array to the destination array.
166    ///
167    /// Panics if the source and destination array lengths differ.
168    pub fn copy<T, A1, A2>(&mut self, src: &UsmBox<T, A1>, dst: &mut UsmBox<T, A2>) -> Result<Event>
169    where
170        T: Pod,
171        A1: UsmAlloc,
172        A2: UsmAlloc,
173    {
174        self.copy_with_deps(src, dst, &[])
175    }
176
177    /// Copies the contents of the source array to the destination array after all specified
178    /// events finish.
179    ///
180    /// Panics if the source and destination array lengths differ.
181    pub fn copy_with_deps<T, A1, A2>(
182        &mut self,
183        src: &UsmBox<T, A1>,
184        dst: &mut UsmBox<T, A2>,
185        dep_events: &[&Event],
186    ) -> Result<Event>
187    where
188        T: Pod,
189        A1: UsmAlloc,
190        A2: UsmAlloc,
191    {
192        assert_eq!(
193            src.get_len(),
194            dst.get_len(),
195            "source and destination array lengths differ"
196        );
197
198        // TODO: Resolve the C++ lifetime elision issue
199        let dep_events = dep_events
200            .iter()
201            .map(|e| EventPtr {
202                ptr: (*e).clone().0,
203            })
204            .collect::<Vec<_>>();
205
206        let num_bytes = src.get_len() * size_of::<T>();
207        unsafe {
208            ffi::memcpy(
209                &mut self.0,
210                dst.get_byte_ptr(),
211                src.get_byte_ptr(),
212                num_bytes,
213                dep_events,
214            )
215        }
216        .map(Into::into)
217    }
218}
219
220impl From<&Device> for Queue {
221    fn from(value: &Device) -> Self {
222        Self(ffi::new_queue_from_device(&value.0))
223    }
224}
225
226impl From<cxx::UniquePtr<ffi::Queue>> for Queue {
227    fn from(value: cxx::UniquePtr<ffi::Queue>) -> Self {
228        Self(value)
229    }
230}
231
232impl Clone for Queue {
233    fn clone(&self) -> Self {
234        ffi::clone(&self.0).into()
235    }
236}