Skip to main content

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