strided_basic/execution.rs
1//! Execution contract for operation-family implementations.
2//!
3//! This module is the shared kernel-extension interface, not a public mirror
4//! of implementation modules. Prevalidated entries require the caller to prove
5//! the exact destination geometry and every omitted shape check. A layout marker
6//! alone does not prove those obligations. Ordinary callers should use the
7//! checked APIs at the crate root. Every family that can fan out takes the same
8//! [`Exec`] placement token as its last parameter.
9//!
10//! # Examples
11//!
12//! ```
13//! use strided_basic::{Exec, StridedArray, execution::*};
14//! let src = StridedArray::<f64>::col_major(&[2]);
15//! let mut dst = StridedArray::<f64>::col_major(&[2]);
16//! let marker = validate_destination_layout_without_alloc(&[2], &[1]).unwrap();
17//! // SAFETY: both arrays have shape [2], distinct storage, and the checked layout.
18//! unsafe { map_into_validated(&mut dst.view_mut(), &src.view(), |x| x, marker, Exec::serial()) }.unwrap();
19//! ```
20//!
21//! A marker alone does not make the prevalidated entry safe to call, which is
22//! why every prevalidated entry is `unsafe`: the compiler rejects a call that
23//! does not acknowledge the caller's obligation.
24//!
25//! ```compile_fail,E0133
26//! use strided_basic::{Exec, StridedArray, execution::*};
27//! let src = StridedArray::<f64>::col_major(&[2]);
28//! let mut dst = StridedArray::<f64>::col_major(&[2]);
29//! let marker = validate_destination_layout_without_alloc(&[2], &[1]).unwrap();
30//! map_into_validated(&mut dst.view_mut(), &src.view(), |x| x, marker, Exec::serial()).unwrap();
31//! ```
32pub use crate::cost::{parallel_width, tree_width, KernelClass};
33pub use crate::erased_common::{
34 check_dtype, check_static_indexing_dtype, erased_view, validate_uninit_no_overlap,
35};
36pub use crate::kernel::{ensure_same_shape, KernelPlan, SMALL_TENSOR_THRESHOLD};
37pub use crate::layout_check::is_injective_layout;
38pub use crate::map_view::{
39 validate_destination_layout, validate_destination_layout_without_alloc,
40 ValidatedDestinationLayout,
41};
42pub use crate::threading::{parallel_map_reduce, SendPtr};
43
44use crate::{ElementOp, Exec, InlineVec, OperandVec, Result, StridedView, StridedViewMut};
45
46/// Prevalidated build plan fused for kernel-family implementations.
47///
48/// `elem_size` is the element size in bytes of *every* operand. The typed
49/// entries whose operands differ in size plan through one crate-internal
50/// helper that passes each operand's own size to the block model instead.
51///
52/// # Safety
53/// All rank-indexed arrays must have matching lengths and a valid destination
54/// index (when present). Shape products, stride magnitudes, cost arithmetic,
55/// and every intermediate offset used by planning/iteration must be representable.
56/// Iteration blocks must be positive and offsets must correspond to the supplied
57/// layouts; threaded partitioning additionally requires positive
58/// costs. Callback memory accesses must be valid for each generated
59/// block, with disjoint mutable regions when partitions execute concurrently.
60///
61/// # Examples
62///
63/// ```
64/// use strided_basic::execution::*;
65/// // SAFETY: the example supplies matching bounded layouts and disjoint storage.
66/// let (dims, _, plan) = unsafe { build_plan_fused(&[2, 3], &[&[1, 2]], Some(0), 8) };
67/// assert_eq!(dims.iter().product::<usize>(), 6);
68/// assert_eq!(plan.block.len(), dims.len());
69/// ```
70#[inline]
71pub unsafe fn build_plan_fused(
72 dims: &[usize],
73 strides_list: &[&[isize]],
74 dest_index: Option<usize>,
75 elem_size: usize,
76) -> (InlineVec<usize>, OperandVec<InlineVec<isize>>, KernelPlan) {
77 // SAFETY: the caller supplies the same invariants as the owning checked entry.
78 // A uniform slice: inline up to `INLINE_RANK` operands, no heap allocation.
79 let mut elem_sizes: InlineVec<usize> = InlineVec::new();
80 elem_sizes.resize(strides_list.len(), elem_size);
81 crate::kernel::build_plan_fused(dims, strides_list, dest_index, &elem_sizes)
82}
83
84/// Prevalidated build plan fused small for kernel-family implementations.
85///
86/// # Safety
87/// All rank-indexed arrays must have matching lengths and a valid destination
88/// index (when present). Shape products, stride magnitudes, cost arithmetic,
89/// and every intermediate offset used by planning/iteration must be representable.
90/// Iteration blocks must be positive and offsets must correspond to the supplied
91/// layouts; threaded partitioning additionally requires positive
92/// costs. Callback memory accesses must be valid for each generated
93/// block, with disjoint mutable regions when partitions execute concurrently.
94///
95/// # Examples
96///
97/// ```
98/// use strided_basic::execution::*;
99/// // SAFETY: the example supplies matching bounded layouts and disjoint storage.
100/// let (dims, _, _) = unsafe { build_plan_fused_small(&[2, 3], &[&[1, 2]]) };
101/// assert_eq!(dims.iter().product::<usize>(), 6);
102/// ```
103#[inline]
104pub unsafe fn build_plan_fused_small(
105 dims: &[usize],
106 strides_list: &[&[isize]],
107) -> (InlineVec<usize>, OperandVec<InlineVec<isize>>, KernelPlan) {
108 // SAFETY: the caller supplies the same invariants as the owning checked entry.
109 crate::kernel::build_plan_fused_small(dims, strides_list)
110}
111
112/// Prevalidated for each inner block preordered for kernel-family implementations.
113///
114/// # Safety
115/// All rank-indexed arrays must have matching lengths and a valid destination
116/// index (when present). Shape products, stride magnitudes, cost arithmetic,
117/// and every intermediate offset used by planning/iteration must be representable.
118/// Iteration blocks must be positive and offsets must correspond to the supplied
119/// layouts; threaded partitioning additionally requires positive
120/// costs. Callback memory accesses must be valid for each generated
121/// block, with disjoint mutable regions when partitions execute concurrently.
122///
123/// # Examples
124///
125/// ```
126/// use strided_basic::execution::*;
127/// // SAFETY: the example supplies matching bounded layouts and disjoint storage.
128/// let mut count = 0;
129/// unsafe { for_each_inner_block_preordered(&[4], &[4], &[vec![1]], &[0], |_, n, _| { count += n; Ok(()) }) }.unwrap();
130/// assert_eq!(count, 4);
131/// ```
132///
133/// # Errors
134///
135/// Performs no validation of its own, so the only error it can return is the
136/// one `f` returns; the block walk itself cannot fail. Callers must still
137/// satisfy the safety contract before invoking this prevalidated entry.
138#[inline]
139pub unsafe fn for_each_inner_block_preordered<S: AsRef<[isize]>, F>(
140 dims: &[usize],
141 blocks: &[usize],
142 strides: &[S],
143 initial_offsets: &[isize],
144 f: F,
145) -> Result<()>
146where
147 F: FnMut(&[isize], usize, &[isize]) -> Result<()>,
148{
149 // SAFETY: the caller supplies the same invariants as the owning checked entry.
150 crate::kernel::for_each_inner_block_preordered::<S, F>(
151 dims,
152 blocks,
153 strides,
154 initial_offsets,
155 f,
156 )
157}
158
159/// Prevalidated map into validated for kernel-family implementations.
160///
161/// # Safety
162/// All input shapes must match the destination. `validated` must have been
163/// obtained for this destination's current geometry, proving injectivity;
164/// possessing a marker from another layout is not sufficient. View/descriptor
165/// bounds and aliasing contracts must continue to hold throughout replay.
166///
167/// # Examples
168///
169/// ```
170/// use strided_basic::execution::*;
171/// // SAFETY: the example supplies matching bounded layouts and disjoint storage.
172/// use strided_basic::StridedArray;
173/// let src = StridedArray::<f64>::from_parts(vec![2.0; 2], &[2], &[1], 0).unwrap();
174/// let mut dst = StridedArray::<f64>::col_major(&[2]);
175/// let checked = validate_destination_layout_without_alloc(&[2], &[1]).unwrap();
176/// unsafe { map_into_validated(&mut dst.view_mut(), &src.view(), |a| a, checked, strided_basic::Exec::serial()) }.unwrap();
177/// assert_eq!(dst.get(&[1]), 2.0);
178/// ```
179///
180/// # Errors
181///
182/// Returns `StridedError::RankMismatch` or `StridedError::ShapeMismatch`
183/// when the source view does not have the destination's ranks and extents,
184/// the only checks the entry keeps. The destination layout is not
185/// re-validated: `validated` is taken as proof of injectivity, and a marker
186/// for this geometry also excludes an unrepresentable element count.
187/// Callers must still satisfy the safety contract before invoking this
188/// prevalidated entry.
189#[inline]
190pub unsafe fn map_into_validated<D: Copy + Send + Sync, A: Copy + Send + Sync, Op: ElementOp<A>>(
191 dest: &mut StridedViewMut<D>,
192 src: &StridedView<A, Op>,
193 f: impl crate::MapFn<A, D>,
194 validated: ValidatedDestinationLayout,
195 exec: Exec<'_>,
196) -> Result<()> {
197 // SAFETY: the caller supplies the same invariants as the owning checked entry.
198 crate::map_view::map_into_validated::<D, A, Op>(dest, src, f, validated, exec)
199}
200
201/// Prevalidated zip map2 into validated for kernel-family implementations.
202///
203/// # Safety
204/// All input shapes must match the destination. `validated` must have been
205/// obtained for this destination's current geometry, proving injectivity;
206/// possessing a marker from another layout is not sufficient. View/descriptor
207/// bounds and aliasing contracts must continue to hold throughout replay.
208///
209/// # Examples
210///
211/// ```
212/// use strided_basic::execution::*;
213/// // SAFETY: the example supplies matching bounded layouts and disjoint storage.
214/// use strided_basic::StridedArray;
215/// let src = StridedArray::<f64>::from_parts(vec![2.0; 2], &[2], &[1], 0).unwrap();
216/// let mut dst = StridedArray::<f64>::col_major(&[2]);
217/// let checked = validate_destination_layout_without_alloc(&[2], &[1]).unwrap();
218/// unsafe { zip_map2_into_validated(&mut dst.view_mut(), &src.view(), &src.view(), |a, b| a + b, checked, strided_basic::Exec::serial()) }.unwrap();
219/// assert_eq!(dst.get(&[1]), 4.0);
220/// ```
221///
222/// # Errors
223///
224/// Performs no shape or destination-layout check of its own and returns
225/// `Ok(())` for every call that satisfies the safety contract: matching
226/// source extents come from that contract, destination injectivity from
227/// `validated`, and a marker for this geometry also excludes an
228/// unrepresentable element count. Callers must still satisfy the safety
229/// contract before invoking this prevalidated entry.
230#[inline]
231pub unsafe fn zip_map2_into_validated<
232 D: Copy + Send + Sync,
233 A: Copy + Send + Sync,
234 B: Copy + Send + Sync,
235 OpA: ElementOp<A>,
236 OpB: ElementOp<B>,
237>(
238 dest: &mut StridedViewMut<D>,
239 a: &StridedView<A, OpA>,
240 b: &StridedView<B, OpB>,
241 f: impl Fn(A, B) -> D + Sync,
242 validated: ValidatedDestinationLayout,
243 exec: Exec<'_>,
244) -> Result<()> {
245 // SAFETY: the caller supplies the same invariants as the owning checked entry.
246 crate::map_view::zip_map2_into_validated::<D, A, B, OpA, OpB>(dest, a, b, f, validated, exec)
247}
248
249/// Prevalidated zip map3 into validated for kernel-family implementations.
250///
251/// # Safety
252/// All input shapes must match the destination. `validated` must have been
253/// obtained for this destination's current geometry, proving injectivity;
254/// possessing a marker from another layout is not sufficient. View/descriptor
255/// bounds and aliasing contracts must continue to hold throughout replay.
256///
257/// # Examples
258///
259/// ```
260/// use strided_basic::execution::*;
261/// // SAFETY: the example supplies matching bounded layouts and disjoint storage.
262/// use strided_basic::StridedArray;
263/// let src = StridedArray::<f64>::from_parts(vec![2.0; 2], &[2], &[1], 0).unwrap();
264/// let mut dst = StridedArray::<f64>::col_major(&[2]);
265/// let checked = validate_destination_layout_without_alloc(&[2], &[1]).unwrap();
266/// unsafe { zip_map3_into_validated(&mut dst.view_mut(), &src.view(), &src.view(), &src.view(), |a, b, c| a + b + c, checked, strided_basic::Exec::serial()) }.unwrap();
267/// assert_eq!(dst.get(&[1]), 6.0);
268/// ```
269///
270/// # Errors
271///
272/// Returns `StridedError::RankMismatch` or `StridedError::ShapeMismatch`
273/// when any source view does not have the destination's ranks and extents,
274/// the only checks the entry keeps. The destination layout is not
275/// re-validated: `validated` is taken as proof of injectivity, and a marker
276/// for this geometry also excludes an unrepresentable element count.
277/// Callers must still satisfy the safety contract before invoking this
278/// prevalidated entry.
279#[inline]
280pub unsafe fn zip_map3_into_validated<
281 D: Copy + Send + Sync,
282 A: Copy + Send + Sync,
283 B: Copy + Send + Sync,
284 C: Copy + Send + Sync,
285 OpA: ElementOp<A>,
286 OpB: ElementOp<B>,
287 OpC: ElementOp<C>,
288>(
289 dest: &mut StridedViewMut<D>,
290 a: &StridedView<A, OpA>,
291 b: &StridedView<B, OpB>,
292 c: &StridedView<C, OpC>,
293 f: impl Fn(A, B, C) -> D + Sync,
294 validated: ValidatedDestinationLayout,
295 exec: Exec<'_>,
296) -> Result<()> {
297 // SAFETY: the caller supplies the same invariants as the owning checked entry.
298 crate::map_view::zip_map3_into_validated::<D, A, B, C, OpA, OpB, OpC>(
299 dest, a, b, c, f, validated, exec,
300 )
301}
302
303/// Prevalidated zip map4 into validated for kernel-family implementations.
304///
305/// # Safety
306/// All input shapes must match the destination. `validated` must have been
307/// obtained for this destination's current geometry, proving injectivity;
308/// possessing a marker from another layout is not sufficient. View/descriptor
309/// bounds and aliasing contracts must continue to hold throughout replay.
310///
311/// # Examples
312///
313/// ```
314/// use strided_basic::execution::*;
315/// // SAFETY: the example supplies matching bounded layouts and disjoint storage.
316/// use strided_basic::StridedArray;
317/// let src = StridedArray::<f64>::from_parts(vec![2.0; 2], &[2], &[1], 0).unwrap();
318/// let mut dst = StridedArray::<f64>::col_major(&[2]);
319/// let checked = validate_destination_layout_without_alloc(&[2], &[1]).unwrap();
320/// unsafe { zip_map4_into_validated(&mut dst.view_mut(), &src.view(), &src.view(), &src.view(), &src.view(), |a, b, c, d| a + b + c + d, checked, strided_basic::Exec::serial()) }.unwrap();
321/// assert_eq!(dst.get(&[1]), 8.0);
322/// ```
323///
324/// # Errors
325///
326/// Returns `StridedError::RankMismatch` or `StridedError::ShapeMismatch`
327/// when any source view does not have the destination's ranks and extents,
328/// the only checks the entry keeps. The destination layout is not
329/// re-validated: `validated` is taken as proof of injectivity, and a marker
330/// for this geometry also excludes an unrepresentable element count.
331/// Callers must still satisfy the safety contract before invoking this
332/// prevalidated entry.
333#[inline]
334// Four source views with their element ops, the destination, the closure, the
335// `validated` marker and the token.
336#[allow(clippy::too_many_arguments)]
337pub unsafe fn zip_map4_into_validated<
338 D: Copy + Send + Sync,
339 A: Copy + Send + Sync,
340 B: Copy + Send + Sync,
341 C: Copy + Send + Sync,
342 E: Copy + Send + Sync,
343 OpA: ElementOp<A>,
344 OpB: ElementOp<B>,
345 OpC: ElementOp<C>,
346 OpE: ElementOp<E>,
347>(
348 dest: &mut StridedViewMut<D>,
349 a: &StridedView<A, OpA>,
350 b: &StridedView<B, OpB>,
351 c: &StridedView<C, OpC>,
352 e: &StridedView<E, OpE>,
353 f: impl Fn(A, B, C, E) -> D + Sync,
354 validated: ValidatedDestinationLayout,
355 exec: Exec<'_>,
356) -> Result<()> {
357 // SAFETY: the caller supplies the same invariants as the owning checked entry.
358 crate::map_view::zip_map4_into_validated::<D, A, B, C, E, OpA, OpB, OpC, OpE>(
359 dest, a, b, c, e, f, validated, exec,
360 )
361}
362
363/// Prevalidated map raw into validated for kernel-family implementations.
364///
365/// # Safety
366/// All input shapes must match the destination. `validated` must have been
367/// obtained for this destination's current geometry, proving injectivity;
368/// possessing a marker from another layout is not sufficient. View/descriptor
369/// bounds and aliasing contracts must continue to hold throughout replay.
370///
371/// # Examples
372///
373/// ```
374/// use strided_basic::execution::*;
375/// // SAFETY: the example supplies matching bounded layouts and disjoint storage.
376/// use strided_basic::{RawStridedRef, RawStridedMut, Identity};
377/// let values = [2.0_f64; 2];
378/// let src = RawStridedRef::new(&values, &[2], &[1], 0).unwrap();
379/// let mut output = [0.0; 2];
380/// let mut dst = RawStridedMut::new(&mut output, &[2], &[1], 0).unwrap();
381/// let checked = validate_destination_layout_without_alloc(&[2], &[1]).unwrap();
382/// unsafe { map_raw_into_validated::<f64, f64, Identity>(&mut dst, &src, |a| a, checked, strided_basic::Exec::serial()) }.unwrap();
383/// assert_eq!(output, [2.0; 2]);
384/// ```
385///
386/// # Errors
387///
388/// Returns `StridedError::RankMismatch` or `StridedError::ShapeMismatch`
389/// when the source does not have the destination's ranks and extents, the
390/// only checks the entry keeps. The destination layout is not re-validated:
391/// `validated` is taken as proof of injectivity, and a marker for this
392/// geometry also excludes an unrepresentable element count. Callers must
393/// still satisfy the safety contract before invoking this prevalidated
394/// entry.
395#[inline]
396pub unsafe fn map_raw_into_validated<
397 D: Copy + Send + Sync,
398 A: Copy + Send + Sync,
399 Op: ElementOp<A>,
400>(
401 dest: &mut crate::RawStridedMut<'_, D>,
402 src: &crate::RawStridedRef<'_, A>,
403 f: impl Fn(A) -> D + Sync,
404 validated: ValidatedDestinationLayout,
405 exec: Exec<'_>,
406) -> Result<()> {
407 // SAFETY: the caller supplies the same invariants as the owning checked entry.
408 crate::map_view::map_raw_into_validated::<D, A, Op>(dest, src, f, validated, exec)
409}
410
411/// Prevalidated zip map2 raw into validated for kernel-family implementations.
412///
413/// # Safety
414/// All input shapes must match the destination. `validated` must have been
415/// obtained for this destination's current geometry, proving injectivity;
416/// possessing a marker from another layout is not sufficient. View/descriptor
417/// bounds and aliasing contracts must continue to hold throughout replay.
418///
419/// # Examples
420///
421/// ```
422/// use strided_basic::execution::*;
423/// // SAFETY: the example supplies matching bounded layouts and disjoint storage.
424/// use strided_basic::{RawStridedRef, RawStridedMut, Identity};
425/// let values = [2.0_f64; 2];
426/// let src = RawStridedRef::new(&values, &[2], &[1], 0).unwrap();
427/// let mut output = [0.0; 2];
428/// let mut dst = RawStridedMut::new(&mut output, &[2], &[1], 0).unwrap();
429/// let checked = validate_destination_layout_without_alloc(&[2], &[1]).unwrap();
430/// unsafe { zip_map2_raw_into_validated::<f64, f64, f64, Identity, Identity>(&mut dst, &src, &src, |a, b| a + b, checked, strided_basic::Exec::serial()) }.unwrap();
431/// assert_eq!(output, [4.0; 2]);
432/// ```
433///
434/// # Errors
435///
436/// Returns `StridedError::RankMismatch` or `StridedError::ShapeMismatch`
437/// when either source does not have the destination's ranks and extents,
438/// the only checks the entry keeps. The destination layout is not
439/// re-validated: `validated` is taken as proof of injectivity, and a marker
440/// for this geometry also excludes an unrepresentable element count.
441/// Callers must still satisfy the safety contract before invoking this
442/// prevalidated entry.
443#[inline]
444pub unsafe fn zip_map2_raw_into_validated<
445 D: Copy + Send + Sync,
446 A: Copy + Send + Sync,
447 B: Copy + Send + Sync,
448 OpA: ElementOp<A>,
449 OpB: ElementOp<B>,
450>(
451 dest: &mut crate::RawStridedMut<'_, D>,
452 a: &crate::RawStridedRef<'_, A>,
453 b: &crate::RawStridedRef<'_, B>,
454 f: impl Fn(A, B) -> D + Sync,
455 validated: ValidatedDestinationLayout,
456 exec: Exec<'_>,
457) -> Result<()> {
458 // SAFETY: the caller supplies the same invariants as the owning checked entry.
459 crate::map_view::zip_map2_raw_into_validated::<D, A, B, OpA, OpB>(
460 dest, a, b, f, validated, exec,
461 )
462}
463
464/// Prevalidated compute costs for kernel-family implementations.
465///
466/// # Safety
467/// All rank-indexed arrays must have matching lengths and a valid destination
468/// index (when present). Shape products, stride magnitudes, cost arithmetic,
469/// and every intermediate offset used by planning/iteration must be representable.
470/// Iteration blocks must be positive and offsets must correspond to the supplied
471/// layouts; threaded partitioning additionally requires positive
472/// costs. Callback memory accesses must be valid for each generated
473/// block, with disjoint mutable regions when partitions execute concurrently.
474///
475/// # Examples
476///
477/// ```
478/// use strided_basic::execution::*;
479/// // SAFETY: the example supplies matching bounded layouts and disjoint storage.
480/// let costs = unsafe { compute_costs(&[vec![1, 4], vec![1, 8]]) };
481/// assert_eq!(costs.as_slice(), [2, 8]);
482/// ```
483#[inline]
484pub unsafe fn compute_costs<S: AsRef<[isize]>>(all_strides: &[S]) -> InlineVec<isize> {
485 // SAFETY: the caller supplies the same invariants as the owning checked entry.
486 crate::fuse::compute_costs::<S>(all_strides)
487}
488
489/// Prevalidated mapreduce threaded for kernel-family implementations.
490///
491/// `class` is the serial cost class of the leaf (see [`KernelClass`]); every node
492/// of the split runs in parallel only when a fork of its region pays for that
493/// class.
494///
495/// # Safety
496/// All rank-indexed arrays must have matching lengths and a valid destination
497/// index (when present). Shape products, stride magnitudes, cost arithmetic,
498/// and every intermediate offset used by planning/iteration must be representable.
499/// Iteration blocks must be positive and offsets must correspond to the supplied
500/// layouts; threaded partitioning additionally requires positive
501/// costs. Callback memory accesses must be valid for each generated
502/// block, with disjoint mutable regions when partitions execute concurrently.
503///
504/// # Examples
505///
506/// ```
507/// use strided_basic::execution::*;
508/// // SAFETY: the example supplies matching bounded layouts and disjoint storage.
509/// use std::sync::atomic::{AtomicUsize, Ordering};
510/// let count = AtomicUsize::new(0);
511/// unsafe { mapreduce_threaded(&[4], &[4], &[vec![1]], &[0], &[2], KernelClass::Map, strided_basic::Exec::serial(), &|dims, _, _, _| { count.fetch_add(dims.iter().product::<usize>(), Ordering::Relaxed); Ok(()) }) }.unwrap();
512/// assert_eq!(count.load(Ordering::Relaxed), 4);
513/// ```
514///
515/// # Errors
516///
517/// Returns `StridedError::OffsetOverflow` when the element count of `dims`
518/// cannot be represented, and otherwise only the error `f` returns; the
519/// splitter itself cannot fail. Callers must still satisfy the safety
520/// contract before invoking this prevalidated entry.
521// Splitter entry: the traversal's dims, blocks, per-operand strides and offsets,
522// the costs, the class, the token and the leaf closure.
523#[allow(clippy::too_many_arguments)]
524#[inline]
525pub unsafe fn mapreduce_threaded<S: AsRef<[isize]>, F>(
526 dims: &[usize],
527 blocks: &[usize],
528 strides_list: &[S],
529 offsets: &[isize],
530 costs: &[isize],
531 class: KernelClass,
532 exec: Exec<'_>,
533 f: &F,
534) -> Result<()>
535where
536 F: Fn(&[usize], &[usize], &[&[isize]], &[isize]) -> Result<()> + Sync,
537{
538 // SAFETY: the caller supplies the same invariants as the owning checked entry.
539 crate::threading::mapreduce_threaded::<S, F>(
540 dims,
541 blocks,
542 strides_list,
543 offsets,
544 costs,
545 class,
546 exec,
547 f,
548 )
549}
550
551/// Full-overwrite indexed replay for an operation-family adapter.
552///
553/// # Safety
554/// The adapter must reject input/output overlap before creating the input
555/// references. All descriptor allocation and initialization contracts must
556/// remain valid for the call. Output slots may be uninitialized; the owning
557/// plan retains its checked layout/index validation and private initialization
558/// receipt. No initialized reference to the output backing may be formed.
559/// Gather into uninitialized output without exposing an initialization receipt.
560///
561/// # Examples
562///
563/// ```
564/// use strided_basic::{RawStridedRef, RawStridedMut};
565/// use strided_basic::execution::*;
566/// use core::mem::MaybeUninit;
567/// use strided_basic::{GatherPlan, GatherSpec};
568/// let spec = GatherSpec { offset_dims: vec![], collapsed_slice_dims: vec![0], start_index_map: vec![0], index_vector_dim: 1, slice_sizes: vec![1] };
569/// let plan = GatherPlan::compile(&[3], &[1], &[2, 1], &[1, 2], &[2], &[1], spec).unwrap();
570/// let src = RawStridedRef::new(&[1_i32, 2, 3], &[3], &[1], 0).unwrap();
571/// let indices = RawStridedRef::new(&[0_i32, 2], &[2, 1], &[1, 2], 0).unwrap();
572/// let mut values = [MaybeUninit::<i32>::uninit(); 2];
573/// let mut dst = RawStridedMut::new(&mut values, &[2], &[1], 0).unwrap();
574/// // SAFETY: input and output allocations are disjoint and layouts match the plan.
575/// unsafe { gather_into_uninit(&plan, &mut dst, &src, &indices, strided_basic::Exec::serial()) }.unwrap();
576/// assert_eq!(unsafe { values[1].assume_init() }, 3);
577/// ```
578///
579/// # Errors
580///
581/// Returns `StridedError::PlanLayoutMismatch` when the destination, operand,
582/// or start-index view does not carry the plan's compiled extents and
583/// strides, before any destination write, and
584/// `StridedError::OffsetOverflow` when a replay offset cannot be
585/// represented. Out-of-range start indices are clamped, not rejected.
586#[inline]
587pub unsafe fn gather_into_uninit<T, I>(
588 plan: &crate::GatherPlan,
589 dest: &mut crate::RawStridedMut<'_, core::mem::MaybeUninit<T>>,
590 operand: &crate::RawStridedRef<'_, T>,
591 start_indices: &crate::RawStridedRef<'_, I>,
592 exec: Exec<'_>,
593) -> Result<()>
594where
595 T: Copy + Send + Sync,
596 I: crate::GatherIndex,
597{
598 plan.execute_uninit(dest, operand, start_indices, exec)
599}
600
601/// Full-overwrite indexed replay for an operation-family adapter.
602///
603/// # Safety
604/// The adapter must reject input/output overlap before creating the input
605/// references. All descriptor allocation and initialization contracts must
606/// remain valid for the call. Output slots may be uninitialized; the owning
607/// plan retains its checked layout/index validation and private initialization
608/// receipt. No initialized reference to the output backing may be formed.
609///
610/// # Examples
611///
612/// ```
613/// use strided_basic::execution::*;
614/// // SAFETY: the example supplies matching bounded layouts and disjoint storage.
615/// use strided_basic::{DynamicSlicePlan, RawStridedRef, RawStridedMut};
616/// use core::mem::MaybeUninit;
617/// let plan = DynamicSlicePlan::compile(&[3], &[1], &[1], &[1], &[2], &[1], &[2]).unwrap();
618/// let src = RawStridedRef::new(&[1_i32, 2, 3], &[3], &[1], 0).unwrap();
619/// let starts = RawStridedRef::new(&[1_i32], &[1], &[1], 0).unwrap();
620/// let mut values = [MaybeUninit::<i32>::uninit(); 2];
621/// let mut dst = RawStridedMut::new(&mut values, &[2], &[1], 0).unwrap();
622/// unsafe { dynamic_slice_into_uninit(&plan, &mut dst, &src, &starts, strided_basic::Exec::serial()) }.unwrap();
623/// assert_eq!(unsafe { values[1].assume_init() }, 3);
624/// ```
625///
626/// # Errors
627///
628/// Returns `StridedError::PlanLayoutMismatch` when the destination, operand,
629/// or start view does not carry the plan's compiled extents and strides,
630/// before any destination write. That is the only rejection: an empty
631/// operand returns before any offset arithmetic, and a non-empty one carries
632/// the bounds its constructor validated, so the replay arithmetic cannot
633/// overflow. Out-of-range start values are clamped, not rejected.
634#[inline]
635pub unsafe fn dynamic_slice_into_uninit<T, I>(
636 plan: &crate::DynamicSlicePlan,
637 dest: &mut crate::RawStridedMut<'_, core::mem::MaybeUninit<T>>,
638 operand: &crate::RawStridedRef<'_, T>,
639 starts: &crate::RawStridedRef<'_, I>,
640 exec: Exec<'_>,
641) -> Result<()>
642where
643 T: Copy + Send + Sync,
644 I: crate::GatherIndex,
645{
646 plan.execute_uninit(dest, operand, starts, exec)
647}
648
649/// Full-overwrite indexed replay for an operation-family adapter.
650///
651/// # Safety
652/// The adapter must reject input/output overlap before creating the input
653/// references. All descriptor allocation and initialization contracts must
654/// remain valid for the call. Output slots may be uninitialized; the owning
655/// plan retains its checked layout/index validation and private initialization
656/// receipt. No initialized reference to the output backing may be formed.
657/// Copy the operand and overwrite its selected window.
658///
659/// # Examples
660///
661/// ```
662/// use strided_basic::{RawStridedRef, RawStridedMut};
663/// use strided_basic::execution::*;
664/// use core::mem::MaybeUninit;
665/// use strided_basic::DynamicUpdateSlicePlan;
666/// let plan = DynamicUpdateSlicePlan::compile(&[3], &[1], &[1], &[1], &[1], &[1], &[3], &[1]).unwrap();
667/// let src = RawStridedRef::new(&[1_i32, 2, 3], &[3], &[1], 0).unwrap();
668/// let update = RawStridedRef::new(&[9_i32], &[1], &[1], 0).unwrap();
669/// let starts = RawStridedRef::new(&[1_i32], &[1], &[1], 0).unwrap();
670/// let mut values = [MaybeUninit::<i32>::uninit(); 3];
671/// let mut dst = RawStridedMut::new(&mut values, &[3], &[1], 0).unwrap();
672/// // SAFETY: all inputs are initialized and disjoint from the matching output.
673/// unsafe { dynamic_update_into_uninit(&plan, &mut dst, &src, &update, &starts, strided_basic::Exec::serial()) }.unwrap();
674/// assert_eq!(unsafe { values[1].assume_init() }, 9);
675/// ```
676///
677/// # Errors
678///
679/// Returns `StridedError::PlanLayoutMismatch` when the destination, operand,
680/// update, or start view does not carry the plan's compiled extents and
681/// strides, before any destination write. The clamped update window is
682/// preflighted next, still before any destination write, and rejects a window
683/// that does not fit `isize`: an empty destination returns before that offset
684/// arithmetic, and a non-empty one carries the bounds its constructor
685/// validated, so a checked view never reaches that rejection. Out-of-range
686/// start values are clamped, not rejected.
687#[inline]
688pub unsafe fn dynamic_update_into_uninit<'a, T, I>(
689 plan: &crate::DynamicUpdateSlicePlan,
690 dest: &'a mut crate::RawStridedMut<'a, core::mem::MaybeUninit<T>>,
691 operand: &crate::RawStridedRef<'_, T>,
692 update: &crate::RawStridedRef<'_, T>,
693 starts: &crate::RawStridedRef<'_, I>,
694 exec: Exec<'_>,
695) -> Result<()>
696where
697 T: Copy + Send + Sync,
698 I: crate::GatherIndex,
699{
700 plan.execute_uninit(dest, operand, update, starts, exec)
701}
702
703/// Full-overwrite indexed replay for an operation-family adapter.
704///
705/// # Safety
706/// The adapter must reject input/output overlap before creating the input
707/// references. All descriptor allocation and initialization contracts must
708/// remain valid for the call. Output slots may be uninitialized; the owning
709/// plan retains its checked layout/index validation and private initialization
710/// receipt. No initialized reference to the output backing may be formed.
711/// Copy the operand before additive scatter into its initialized logical slots.
712///
713/// # Examples
714///
715/// ```
716/// use strided_basic::{RawStridedRef, RawStridedMut};
717/// use strided_basic::execution::*;
718/// use core::mem::MaybeUninit;
719/// use strided_basic::{ScatterPlan, ScatterSpec};
720/// let spec = ScatterSpec { update_window_dims: vec![], inserted_window_dims: vec![0], scatter_dims_to_operand_dims: vec![0], index_vector_dim: 1 };
721/// let plan = ScatterPlan::compile(&[3], &[1], &[1, 1], &[1, 1], &[1], &[1], &[3], &[1], spec).unwrap();
722/// let src = RawStridedRef::new(&[1_i32, 2, 3], &[3], &[1], 0).unwrap();
723/// let update = RawStridedRef::new(&[9_i32], &[1], &[1], 0).unwrap();
724/// let indices = RawStridedRef::new(&[1_i64], &[1, 1], &[1, 1], 0).unwrap();
725/// let mut values = [MaybeUninit::<i32>::uninit(); 3];
726/// let mut dst = RawStridedMut::new(&mut values, &[3], &[1], 0).unwrap();
727/// // SAFETY: all inputs are initialized and disjoint from the matching output.
728/// unsafe { scatter_into_uninit(&plan, &mut dst, &src, &indices, &update, i32::wrapping_add, strided_basic::Exec::serial()) }.unwrap();
729/// assert_eq!(unsafe { values[1].assume_init() }, 11);
730/// ```
731///
732/// # Errors
733///
734/// Returns `StridedError::PlanLayoutMismatch` when the destination, operand,
735/// scatter-index, or update view does not carry the plan's compiled extents
736/// and strides, before any destination write. That is the only rejection: an
737/// empty batch or window skips the replay entirely, so no offset arithmetic
738/// runs, and a non-empty one carries the bounds its constructor validated.
739/// Out-of-range scatter indices are clamped, not rejected.
740#[inline]
741pub unsafe fn scatter_into_uninit<'a, T, I>(
742 plan: &crate::ScatterPlan,
743 dest: &'a mut crate::RawStridedMut<'a, core::mem::MaybeUninit<T>>,
744 operand: &crate::RawStridedRef<'_, T>,
745 scatter_indices: &crate::RawStridedRef<'_, I>,
746 updates: &crate::RawStridedRef<'_, T>,
747 combine: fn(T, T) -> T,
748 exec: Exec<'_>,
749) -> Result<()>
750where
751 T: Copy + core::ops::Add<Output = T> + Send + Sync,
752 I: crate::GatherIndex,
753{
754 plan.execute_uninit(dest, operand, scatter_indices, updates, combine, exec)
755}