oneapi_rs/
lib.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
9//! # oneAPI-rs
10//! oneAPI-rs is a set of (mostly) safe Rust bindings for SYCL - an open, royalty-free,
11//! cross-platform abstraction layer that enables code for heterogeneous and offload processors to
12//! be written using modern ISO C++, and provides APIs and abstractions to find devices
13//! (CPUs, GPUs, FPGAs ...) on which code can be executed, and to manage data resources and code
14//! execution on those devices.
15//!
16//! # System dependencies
17//! Make sure to install the [Intel oneAPI toolkit](https://www.intel.com/content/www/us/en/developer/tools/oneapi/oneapi-toolkit-download.html).
18//! Then source the `setvars.sh` file:
19//! ```bash
20//! source <oneapi_install_directory>/setvars.sh
21//! ```
22//!
23//! # Getting started
24//! ### Building the crate
25//! Before building this crate you need to source the `setvars.sh` file. You can then build it as
26//! usual with cargo:
27//! ```bash
28//! cargo build --release
29//! ```
30//!
31//! You must also source `setvars.sh` before running any SYCL program.
32//!
33//! ### Hello world
34//! 1. Create a [`Queue`](crate::queue::Queue). It's the main entry point to the SYCL API.
35//! ```rust,ignore
36//! let mut queue = Queue::new();
37//! ```
38//!
39//! 2. Create an [USM buffer](crate::buffer::Buffer) for your data.
40//! ```rust,ignore
41//! let mut device_buffer = queue.alloc_device::<f64>(1024).wait();
42//! ```
43//!
44//! 3. Build a SYCL kernel.
45//! ```rust,ignore
46//! let kernel = queue
47//!     .get_context()
48//!     .create_kernel_bundle_from_source(IOTA_SRC)
49//!     .build()
50//!     .get_kernel("iota");
51//! ```
52//!
53//! 4. Launch your kernel.
54//! ```rust,ignore
55//! unsafe {
56//!     queue.launch(
57//!         NdRange::new([1024], [16]),
58//!         &kernel,
59//!         (3.14, &mut device_buffer),
60//!     )
61//! }
62//! .wait();
63//! ```
64//!
65//! 5. Copy your data to the host.
66//! ```rust,ignore
67//! let mut host_buffer = queue.alloc_host::<f64>(1024).wait();
68//! queue.copy(&device_buffer, &mut host_buffer).wait();
69//! ```
70//!
71//! You can access your host data just like a normal Rust slice.
72//! ```rust,ignore
73//! for e in host_buffer.iter() {
74//!     print!("{e} ");
75//! }
76//! println!();
77//! ```
78//!
79//! # Safety model
80//! - USM allocations are represented by a zero-cost `Buffer` type managed through RAII.
81//!   - Note: Unlike SYCL buffers, oneAPI-rs buffers do not rely on accessors.
82//! - Buffers are zero-initialized by default.
83//! - Buffers can only store types that implement [`bytemuck::Pod`].
84//! - Kernel launch is inherently unsafe.
85//!
86//! # Asynchronous programming model
87//! Each queue operation returns an [`Event`](`crate::event::Event`). You can synchronously
88//! [`.wait()`](crate::event::Event::wait) for it, or asynchronously `.await` it.
89//!
90//! You can also synchronously call [`Queue::wait()`](crate::queue::Queue::wait) to wait for a
91//! [`Queue`](crate::queue::Queue) directly. To do the same asynchronously you have to `.await` an
92//! event returned by [`Queue::barrier()`](crate::queue::Queue::barrier).
93
94pub mod buffer;
95pub mod context;
96pub mod device;
97pub mod event;
98pub mod info;
99pub mod kernel;
100pub mod platform;
101pub mod prelude;
102pub mod queue;
103pub mod range;
104pub mod usm;
105
106mod private {
107    pub trait Sealed {}
108}
oneapi_rs/lib.rs

oneapi_rs/
lib.rs
