Skip to content

docs(linalg): fill in the empty Safety section on load_unaligned - #8885

Open
LuciferYang wants to merge 1 commit into
lance-format:mainfrom
LuciferYang:docs/simd-load-unaligned-safety
Open

docs(linalg): fill in the empty Safety section on load_unaligned#8885
LuciferYang wants to merge 1 commit into
lance-format:mainfrom
LuciferYang:docs/simd-load-unaligned-safety

Conversation

@LuciferYang

@LuciferYang LuciferYang commented Aug 31, 2026

Copy link
Copy Markdown
Contributor

What this changes

SIMD::load_unaligned had a # Safety heading with nothing under it:

    /// Load unaligned data from memory.
    ///
    /// # Safety
    unsafe fn load_unaligned(ptr: *const T) -> Self;

Its two neighbours in the same trait, load and store, both say what they require. The trait is pub, so this renders as an empty section, and clippy::missing_safety_doc is satisfied by the heading alone and says nothing.

The section now states the pointer requirement plus the one a caller cannot guess: five of the six implementations reach an intrinsic that needs a target feature the build's baseline may not provide, and none of them check at runtime. On x86_64 that is _mm256_loadu_*, which carries #[target_feature(enable = "avx")] in core::arch, so calling it without AVX is undefined behaviour rather than a wrong answer. That is the gap in #8872.

u8x16 is called out separately because it is the exception: _mm_loadu_si128 is SSE2, vld1q_u8 is baseline NEON, and everywhere else it is a scalar loop, so it needs nothing extra on any target. Lumping it in with the others would push callers of the one safe implementation into detection they do not need.

Why the section is longer than the bug

Two shorter versions were each wrong in a different direction, and both are worth recording so the next person does not retry them.

"Unlike [SIMD::load] it carries no alignment requirement" is false for most implementations, because for most types the two methods are the same code: on aarch64 load calls load_unaligned directly for f32x8, f32x16, f64x4 and f64x8, and on x86_64 i32x8::load and u8x16::load use the same unaligned intrinsic. The alignment distinction exists only in the four x86_64 _mm256_load_ps / _mm256_load_pd arms, so the sentence would also have ratified load's own doc, which claims the crash for every type.

"An implementation may also require target features the generic baseline does not imply" is true but not dischargeable. A caller writing unsafe { u8x16::load_unaligned(p) } has to satisfy the stated obligation, and an existential over unnamed features on unnamed targets leaves only two readings: assume the worst, or ignore the clause. Naming the features, the granularity (the build's baseline, not the architecture: .cargo/config.toml sets target-cpu=haswell for x86_64-unknown-linux-gnu, so in-repo builds do imply AVX while a downstream build of the published crate does not) and the mechanism is what makes it usable. The sibling docs in the same module already name is_x86_feature_detected! this way.

The pre-existing wording on load and store is left alone. Correcting it is a decision about what those methods should promise, not a docs fix.

Test plan

Documentation only, no behavior change.

  • RUSTDOCFLAGS="-D warnings -D rustdoc::broken_intra_doc_links" cargo doc -p lance-linalg --no-deps: clean
  • cargo fmt --all -- --check and cargo clippy -p lance-linalg --all-targets -- -D warnings: clean
  • Each claim in the list checked against the body of every load_unaligned implementation: f32.rs:214 and :612, f64.rs:111 and :467, i32.rs:118, u8.rs:157

@github-actions github-actions Bot added A-index Vector index, linalg, tokenizer documentation Improvements or additions to documentation labels Aug 31, 2026
lance-gatekeeper[bot]

This comment was marked as outdated.

@lance-gatekeeper lance-gatekeeper Bot added the K-changes Latest Gatekeeper recommendation requests changes. label Aug 31, 2026
@LuciferYang
LuciferYang force-pushed the docs/simd-load-unaligned-safety branch from b5de0d0 to 4caed81 Compare August 31, 2026 04:13
@lance-gatekeeper lance-gatekeeper Bot removed the K-changes Latest Gatekeeper recommendation requests changes. label Aug 31, 2026
lance-gatekeeper[bot]

This comment was marked as outdated.

@lance-gatekeeper lance-gatekeeper Bot added the K-changes Latest Gatekeeper recommendation requests changes. label Aug 31, 2026
@LuciferYang
LuciferYang force-pushed the docs/simd-load-unaligned-safety branch from 4caed81 to f65685f Compare August 31, 2026 04:19
@LuciferYang

Copy link
Copy Markdown
Contributor Author

Taking the first of your two options rather than the ordering: the contract now requires the target features generically, so it is complete for LASX, for x86 AVX, and for any arm added later, and it does not go stale when #8874 lands.

Not gating this on #8874 merging first. #8874 fixes three of the four x86 register types, u8x16 was already baseline-safe with _mm_loadu_si128, and neither touches the loongarch LASX arms, so a docs change that waits for it would still need this sentence afterwards.

@lance-gatekeeper lance-gatekeeper Bot removed the K-changes Latest Gatekeeper recommendation requests changes. label Aug 31, 2026
lance-gatekeeper[bot]

This comment was marked as outdated.

@lance-gatekeeper lance-gatekeeper Bot added the K-approved Latest Gatekeeper recommendation permits acceptance. label Aug 31, 2026
@LuciferYang
LuciferYang force-pushed the docs/simd-load-unaligned-safety branch from f65685f to 7dc671d Compare August 31, 2026 04:47
@lance-gatekeeper lance-gatekeeper Bot removed the K-approved Latest Gatekeeper recommendation permits acceptance. label Aug 31, 2026

@lance-gatekeeper lance-gatekeeper Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Gate recommendation: approve with a non-blocking risk.

This head accurately documents the current pointer, AVX, LASX, and baseline-safe u8x16 obligations. The explicit x86 matrix is coupled to #8874, which replaces those AVX loads but does not yet update this text; that PR should revise the x86 requirement when it rebases or merges. No change is required here before this revision can land.

@lance-gatekeeper lance-gatekeeper Bot added K-approved Latest Gatekeeper recommendation permits acceptance. K-risk Latest Gatekeeper recommendation includes a non-blocking risk. labels Aug 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-index Vector index, linalg, tokenizer documentation Improvements or additions to documentation K-approved Latest Gatekeeper recommendation permits acceptance. K-risk Latest Gatekeeper recommendation includes a non-blocking risk.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant