Add L4 predictor queue skeleton

[WIP] Add documentation for MagicSpinner's chapter design

.cr/team/Editor/Formatting/Braces.CSharp.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Root Type="DevExpress.CodeRush.Formatting.UI.Options.BracesOptionsContainer">
+  <Options Language="C#">
+    <Options>
+      <Item Id="{3920243c-1bac-46ce-960d-e4186d99c187}" Type="DevExpress.CodeRush.Formatting.UI.Options.Conversion.PropertyBracesOption">
+        <WrapOpenBrace>
+          <Option>Wrap</Option>
+        </WrapOpenBrace>
+        <WrapCloseBrace>
+          <Option>Wrap</Option>
+        </WrapCloseBrace>
+      </Item>
+      <Item Id="{692dd27b-3066-4dd3-beac-516a569f5203}" Type="DevExpress.CodeRush.Formatting.UI.Options.Conversion.SimplePropertyBracesOption">
+        <WrapOpenBrace>
+          <Option>Wrap</Option>
+        </WrapOpenBrace>
+        <WrapCloseBrace>
+          <Option>Wrap</Option>
+        </WrapCloseBrace>
+      </Item>
+    </Options>
+  </Options>
+</Root>

.editorconfig

@@ -1,12 +1,5 @@
-[*]
-end_of_line = lf
-charset = utf-8
-insert_final_newline = true
-trim_trailing_whitespace = true
-
-[*.{bat,cmd,ps1}]
-end_of_line = crlf
+root = true
 
 [*.cs]
-# CS1591: 缺少对公共可见类型或成员的 XML 注释
-dotnet_diagnostic.CS1591.severity = suggestion
+dotnet_diagnostic.IDE0032.severity = none
+dotnet_diagnostic.IDE0055.severity = none

.gitignore

@@ -29,7 +29,7 @@ build.ninja
 BenchmarkDotNet.Artifacts/
 
 # Khronos OpenGL Registry input is supplied locally; keep only its instructions.
-/tools/Nitload.GenerateGL/xml/*
+/tools/*GenerateGL/xml/*
 !/tools/Nitload.GenerateGL/xml/README.md
 
 /src/Nitload.Native/lib/*

Directory.Build.targets

@@ -1,19 +1,37 @@
 <Project>
 
+  <!-- Native builds are opt-in for executable hosts, not repeated by every library project. -->
+  <Target Name="BuildNativeLibrary"
+          BeforeTargets="PrepareForBuild"
+          Condition="'$(BuildNativeBeforeManaged)'=='true' And '$(DesignTimeBuild)'!='true'">
+    <PropertyGroup>
+      <NativeCMakePreset Condition="'$(NativeCMakePreset)'=='' And '$(Configuration)'=='Debug'">clang-debug</NativeCMakePreset>
+      <NativeCMakePreset Condition="'$(NativeCMakePreset)'==''">clang-release</NativeCMakePreset>
+      <NativeCMakeBuildDir Condition="'$(NativeCMakeBuildDir)'==''">$(SolutionRoot)cmake_build/$(NativeCMakePreset)</NativeCMakeBuildDir>
+      <_NativeCMakeOutputDir>$([System.String]::Copy('$(NativeBuildDir)').Replace('\', '/'))</_NativeCMakeOutputDir>
+    </PropertyGroup>
+    <Exec Command="cmake --preset &quot;$(NativeCMakePreset)&quot; -S &quot;$(SolutionRoot)src/Nitload.Native&quot; -B &quot;$(NativeCMakeBuildDir)&quot; &quot;-DNFN_BUILD_OUTPUT_DIR:PATH=$(_NativeCMakeOutputDir)&quot; &quot;-DNFN_EXPECTED_RID:STRING=$(BuildRid)&quot;" />
+    <Exec Command="cmake --build &quot;$(NativeCMakeBuildDir)&quot; --target &quot;$(NativeLibName)&quot;" />
+    <Error Condition="!Exists('$(NativeBuildDir)$(NativeFileName)')"
+           Text="CMake did not produce the expected native library: $(NativeBuildDir)$(NativeFileName). Check the target OS, architecture and output name." />
+  </Target>
+
   <!-- ════════════════════════════════════════════════════════ -->
   <!--  编译后：把 C# 输出拷贝到 bin/<rid>/ 目录                 -->
   <!--  替代原来的 xcopy PostBuild                               -->
   <!-- ════════════════════════════════════════════════════════ -->
   <Target Name="CopyOutputToBuildDir"
           AfterTargets="Build"
-          Condition="'$(DisablePostBuildCopy)'!='true'">
+          Condition="'$(DisablePostBuildCopy)'!='true' And '$(MSBuildProjectExtension)'=='.csproj' And '$(DesignTimeBuild)'!='true'">
 
     <MakeDir Directories="$(ManagedBuildDir)" />
 
     <!-- 拷贝所有编译输出（DLL + PDB + XML + deps.json） -->
     <ItemGroup>
-      <_OutputFiles Include="$(OutputPath)**\*.*"
-                    Exclude="$(OutputPath)**\*.user" />
+      <!-- Native artifacts flow from CMake to hosts only. Never copy an old deployed DLL
+           back over the authoritative CMake output, including pre-rename artifacts. -->
+      <_OutputFiles Include="$(TargetDir)**\*.*"
+                    Exclude="$(TargetDir)**\*.user;$(TargetDir)**\$(NativeLibName).*;$(TargetDir)**\lib$(NativeLibName).*;$(TargetDir)**\StgSharp.Native.*;$(TargetDir)**\libStgSharp.Native.*" />
     </ItemGroup>
 
     <Copy SourceFiles="@(_OutputFiles)"
@@ -30,7 +48,11 @@
   <!-- ════════════════════════════════════════════════════════ -->
   <Target Name="CopyNativeToProjectOutput"
           AfterTargets="Build"
-          Condition="'$(DisableNativeCopy)'!='true'">
+          BeforeTargets="CopyOutputToBuildDir"
+          Condition="'$(DisableNativeCopy)'!='true' And '$(MSBuildProjectExtension)'=='.csproj' And '$(DesignTimeBuild)'!='true'">
+
+    <Error Text="Native library not found at $(NativeBuildDir)$(NativeFileName). Build Nitload.Native with CMake, or enable BuildNativeBeforeManaged."
+           Condition="'$(RequireNativeLibrary)'=='true' And !Exists('$(NativeBuildDir)$(NativeFileName)')" />
 
     <!-- native 库文件 -->
     <ItemGroup>
@@ -45,12 +67,12 @@
     </ItemGroup>
 
     <Copy SourceFiles="@(_NativeLibFile);@(_NativeSymFile)"
-          DestinationFolder="$(OutputPath)"
+          DestinationFolder="$(TargetDir)"
           SkipUnchangedFiles="true"
           Condition="'@(_NativeLibFile)'!='' Or '@(_NativeSymFile)'!=''" />
 
     <Message Importance="high"
-             Text="[Nitload] Native $(NativeFileName) ($(BuildRid)) → $(OutputPath)"
+             Text="[Nitload] Native $(NativeFileName) ($(BuildRid)) → $(TargetDir)"
              Condition="'@(_NativeLibFile)'!=''" />
 
     <Warning Text="[Nitload] Native library not found at $(NativeBuildDir)$(NativeFileName). Build Nitload.Native first!"

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Nitload StgSharp Team
+Copyright (c) 2024 Nitload
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -20,9 +20,9 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-StgSharp program uses the following open source projects,
-I'd like to refer to them here and show my sincere appreciation,
-while the names are sorted in no particular order
+The nFramework project uses the following open-source projects.
+Their respective license notices are reproduced below,
+and the projects are listed in no particular order.
 
 1. GLFW
 

Nitload.nuspec

@@ -11,7 +11,7 @@
     <projectUrl>https://github.com/Nitload-NSI/StgSharp</projectUrl>
     <description>No des right now</description>
     <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
-    <copyright>Nitload reserve</copyright>
+    <copyright>Copyright (c) 2024 Nitload</copyright>
     <tags>OpenGL C#</tags>
   </metadata>
   <files>

ReadMe.md

@@ -1,16 +1,16 @@
-# StgSharp
+![nFramework Logo](logo/nFramework-horizontal-light.png)
 
-![StgSharp Logo](STG%23LOGO.png)
+# nFramework
 
-StgSharp is an experimental .NET framework for graphics, numerical computing, language analysis, and other performance-sensitive applications. It began as the foundation of a next-generation STG (shoot 'em up) engine, but the current repository focuses on reusable low-level infrastructure rather than a complete, ready-to-use game engine.
+nFramework (formerly StgSharp, now also nitload.Framework) is an experimental framework built on .NET for graphics, numerical computing, language analysis, and other performance-sensitive applications. It combines managed C# libraries with a C native runtime, targets .NET 8, and provides Windows and Linux native implementations.
 
 ## Overview
 
-The framework combines managed C# APIs with a C native library. Its current work includes OpenGL bindings and rendering infrastructure, generic matrix and vector types, SIMD-accelerated native kernels, custom allocators and collections, regular-language analysis, and state-oriented UI infrastructure. StgSharp targets .NET 8; platform and architecture coverage varies by module, with Windows and Linux as the principal native targets.
+nFramework combines managed C# APIs with a C native library. Its current work includes OpenGL bindings and rendering infrastructure, generic matrix and vector types, SIMD-accelerated native kernels, custom allocators and collections, regular-language analysis, and state-oriented UI infrastructure. nFramework targets .NET 8; platform and architecture coverage varies by module, with Windows and Linux as the principal native targets.
 
 ## Core Modules
 
-### StgSharp.Common
+### Nitload.Common
 
 The foundational library containing shared functionality:
 
@@ -20,7 +20,7 @@ The foundational library containing shared functionality:
 - **Pipeline and State**: Processing pipelines and reusable state-machine primitives
 - **Environment**: Platform abstraction and system integration
 
-### StgSharp.Mathematics (Numeric)
+### Nitload.Mathematics (Numeric)
 
 Numerics and linear algebra built on top of the core library:
 
@@ -28,17 +28,29 @@ Numerics and linear algebra built on top of the core library:
 - **Numeric Utilities**: Core numeric helpers and algorithms
 - **SIMD-Friendly Kernels**: Data layouts optimized for hardware acceleration
 
-### StgSharp.RegularAnalysis
+### Nitload.RegularAnalysis
 
 Nitload General Regular Analysis (NGRA) infrastructure for recognizing and processing regular languages:
 
-- **Regex/Automata Core**: Regular expression processing and automata utilities
+- **NFA Direction**: Planned generic ε-NFA sequence execution, followed by weighted automata and NGRA-Tensor research
 - **Parsing Primitives**: Reusable tokenizer and grammar building blocks
 - **Analysis Pipeline**: Structured processing for language-like inputs
 
-NGRA is a foundation for higher-level language tooling. It does not replace `StgSharp.Script`; the planned Script implementation depends on NGRA and has not started yet. The source currently under `StgSharp.Script` is retained from the earlier EXPRESS implementation and is not part of the active core solution.
+NGRA is a foundation for higher-level language tooling. It does not replace `Nitload.Script`; the planned Script implementation depends on NGRA and has not started yet. The source currently under `Nitload.Script` is retained from the earlier EXPRESS implementation and is not part of the active core solution.
 
-### StgSharp.Graphics
+The former Text Regex parser, matcher, and source generator are [archived](src/Nitload.RegularAnalysis/Legacy/README.md)
+and excluded from compilation. Generic AST and token infrastructure remain active.
+
+Although Text Regex development is frozen, it produced valuable reusable results: the five-link
+AST model, tree normalization and merging techniques, token/analysis infrastructure, and practical
+experience with COUNT continuations, group boundaries, and rollback. These results remain available
+to inform the new NFA architecture.
+
+Future string-regex functionality will use .NET `GeneratedRegex`. NGRA will no longer pursue
+custom `Span<char>` or SIMD optimizations for string matching; its research focus is generalized
+sequence analysis and, later, weighted relation networks.
+
+### Nitload.Graphics
 
 Managed graphics infrastructure built on Common and Mathematics:
 
@@ -47,7 +59,7 @@ Managed graphics infrastructure built on Common and Mathematics:
 - **Shader Support**: Shader compilation, program management, and shader-generation utilities
 - **Window Integration**: GLFW-based window and input access
 
-### StgSharp.Native
+### Nitload.Native
 
 Native library integration:
 
@@ -56,7 +68,7 @@ Native library integration:
 - **Matrix Kernels**: Optimized matrix computation routines
 - **Platform Runtime**: Native thread and platform support for Windows and Linux
 
-### StgSharp.TerminalDialogue
+### Nitload.TerminalDialogue
 
 Terminal-based user interface application and components:
 
@@ -64,7 +76,7 @@ Terminal-based user interface application and components:
 - **Dialogue System**: User interaction and input handling
 - **Terminal Graphics**: Text-based UI rendering
 
-> Note: `StgSharp.Script` is planned as a consumer of NGRA and has not started yet. Its existing EXPRESS sources belong to the earlier implementation. `StgSharp.Model` is currently an empty placeholder while its design is being reconsidered.
+> Note: `Nitload.Script` is planned as a consumer of NGRA and has not started yet. Its existing EXPRESS sources belong to the earlier implementation. `Nitload.Model` is currently an empty placeholder while its design is being reconsidered.
 
 ## Key Features
 
@@ -113,7 +125,7 @@ The benchmark reports normalized time per allocation/free operation. Each iterat
 ### Data Processing
 
 - **NGRA**: Regex analysis, intermediate representation, optimization, and source generation
-- **EXPRESS (legacy/inactive)**: The repository retains an earlier experimental EXPRESS parser/compiler under `StgSharp.Script`
+- **EXPRESS (legacy/inactive)**: The repository retains an earlier experimental EXPRESS parser/compiler under `Nitload.Script`
 - **Script (planned)**: A future language layer intended to build on NGRA; development has not started
 
 ## Requirements
@@ -125,7 +137,7 @@ The benchmark reports normalized time per allocation/free operation. Each iterat
 
 ## Installation
 
-StgSharp is currently in development and requires compilation from source. **NuGet packages are not yet available** - you must build the project from source code.
+nFramework is currently in development and requires compilation from source. **NuGet packages are not yet available** - you must build the project from source code.
 
 ### Prerequisites
 
@@ -159,7 +171,7 @@ StgSharp is currently in development and requires compilation from source. **NuG
    dotnet build Nitload.sln
    ```
 
-   Managed builds copy an existing native binary into their output directory. They do not invoke CMake automatically, so build `StgSharp.Native` first when native functionality is required.
+   Managed library builds copy an existing native binary into their output directory. Build `Nitload.Native` first when native functionality is required. The `StgSharpDebug` executable is an exception: its project enables an incremental CMake build before managed compilation and requires the native DLL for the normal runtime path.
 
 ### Build Configuration
 
@@ -168,7 +180,7 @@ StgSharp is currently in development and requires compilation from source. **NuG
 
 ### Notes
 
-- CMake is the maintained build path for `StgSharp.Native`; the checked-in presets primarily target Clang
+- CMake is the maintained build path for `Nitload.Native`; the checked-in presets primarily target Clang
 - The Visual Studio C project may be opened with MSVC tooling, but MSVC IntelliSense behavior and MSVC-produced binaries are not maintained or guaranteed
 - Windows and Linux platform implementations exist; actual feature and architecture coverage may differ
 - x86-64 currently has the most complete optimized kernel coverage
@@ -187,8 +199,8 @@ StgSharp is currently in development and requires compilation from source. **NuG
 ### Matrix Operations
 
 ```csharp
-using StgSharp.HighPerformance.Memory;
-using StgSharp.Mathematics.Numeric;
+using Nitload.Common.HighPerformance.Memory;
+using Nitload.Mathematics.Numeric;
 
 // Matrix storage is allocated explicitly from a native-memory arena.
 using var allocator = new TwoLayerSegregatedFitAllocator(64 * 1024 * 1024);
@@ -207,7 +219,7 @@ General matrix arithmetic does not currently provide operator overloads. Because
 ### Memory Management
 
 ```csharp
-using StgSharp.HighPerformance.Memory;
+using Nitload.Common.HighPerformance.Memory;
 
 // Create a 64 MiB TLSF arena
 using var allocator = new TwoLayerSegregatedFitAllocator(64 * 1024 * 1024);
@@ -231,7 +243,7 @@ allocator.Free(handle);
 
 ## Contributing
 
-StgSharp is developed by Nitload Space. Contributions are welcome, particularly in:
+nFramework is developed by Nitload Space under the Nitload brand. Contributions are welcome, particularly in:
 
 - Performance optimizations
 - Cross-platform compatibility
@@ -240,7 +252,7 @@ StgSharp is developed by Nitload Space. Contributions are welcome, particularly
 
 ## License
 
-StgSharp is licensed under the MIT License. See [LICENSE](LICENSE) for details.
+nFramework is licensed under the MIT License. See [LICENSE](LICENSE) for details.
 
 ## Future Plans
 

doc/L4_design.md

@@ -1,762 +0,0 @@
-# L4 Software Cache Design Specification
-
-> Project: StgSharp  
-> Author: Nitload  
-> Version: Draft v0.3  
-> Date: 2026-03-10
-
----
-
-## 1. Purpose
-
-### 1.1 Problem Background
-
-StgSharp's matrix computation system is migrating from a "single global context table" to a
-"per-thread context" architecture to adapt to the scheduling characteristics of hybrid-architecture
-CPUs (e.g., Intel P-Core / E-Core). After the migration, each thread independently holds its own
-computation context, but matrix data may still be allocated by the HLSF allocator or global
-`malloc` on a remote NUMA node, resulting in significantly increased cross-node access latency.
-
-At the same time, in matrix multiplication (FMA), the core row data of matrix A in the
-checkerboard-shaped kernel grid layout must be repacked (Packed) into a micro-kernel-friendly
-contiguous arrangement. In libraries such as OpenBLAS, this Pack operation is re-executed on
-every tile switch, whereas L4 can cache the Pack results to avoid repeated reordering.
-
-Additionally, the segmented accumulation (segment) of matrix multiplication requires storing
-intermediate partial sums locally to avoid cross-NUMA writes to the target matrix on every
-segment. L4 can serve as a local accumulation buffer for partial sums, writing them back in a
-single operation after all segments complete locally.
-
-### 1.2 Solution
-
-The L4 cache is a purely software-implemented **data caching layer** logically positioned
-between the CPU hardware caches (L1/L2/L3) and main memory. Its core responsibilities:
-
-1. **Pack result caching**: Cache the repack results of FMA core rows in matrix A to avoid repeated Pack operations
-2. **NUMA migration cache**: Migrate data from remote NUMA nodes to local memory and cache it, eliminating cross-node latency
-3. **Segment accumulation buffer**: Temporarily store partial sums from FMA segmented computation to reduce remote write operations
-4. **PLU intermediate data buffer**: Provide a local contiguous workspace for PLU decomposition
-
-### 1.3 Design Goals
-
-- Provide NUMA-friendly local data access for per-thread matrix computation contexts
-- Fixed capacity (64 MB), no runtime expansion, deterministic latency
-- Transparent pointer redirection: upper-layer code queries via original pointers; L4 returns local cache pointers
-- Cache eviction policy based on **RRPV mask + windowed OPT prediction**
-- Support both **StreamTransparent** and **CacheBuffer** working modes
-- Support **writable cache lines** that invoke registered callback functions for pre-processing and write-back upon eviction or explicit flush
-
----
-
-## 2. Overall Architecture
-
-### 2.1 Three-Component Model
-
-```
-┌���─────────────────────────────────────────────────────────────────┐
-│                              L4                                  │
-│                                                                  │
-│  ┌──────────────┐  ┌────────────────────┐  ┌──────────────────┐  │
-│  │  CacheLine    │  │     L4 Core        │  │    Predictor     │  │
-│  │  Handle       │  │     Cache          │  │    Prefetch      │  │
-│  │              │  │                    │  │    Predictor     │  │
-│  │ • local addr  │  │ • Swiss Table      │  │ • 2048-entry buf │  │
-│  │ • ref count   │  │ • Slab Allocator   │  │ • threshold 1024 │  │
-│  │ • Dispose     │  │ • RRPV mask        │  │ • windowed OPT   │  │
-│  │   drops ref   │  │ • SIMD eviction    │  │ • active key set │  │
-│  │              │  │ • writeback mgmt   │  │                  │  │
-│  └──────────────┘  └────────────────────┘  └──────────────────┘  │
-│                                                                  │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-### 2.2 Data Access Path
-
-```
-Compute thread accessing data:
-
-  ┌─────────────────────────────────────────────────────────┐
-  │  Read-only path: L4.Map(originKey)                      │
-  │     ├─ StreamTransparent + no repack needed?            │
-  │     │  └─ Yes → return original pointer directly        │
-  │     │          (zero overhead)                          │
-  │     │                                                   │
-  │     └─ CacheBuffer mode                                 │
-  │        ├─ Swiss Table lookup (2.6ns, lock-free)         │
-  │        ├─ Hit → update RRPV=0, return CacheLine handle  │
-  │        └─ Miss → SpinWait for Predictor prefetch        │
-  ├─────────────────────────────────────────────────────────┤
-  │  Writable path: L4.MapWritable(originKey, preprocess, writeback) │
-  │     ├─ Hit → return existing partial sum cache line     │
-  │     └─ Miss → allocate zero-initialized cache line,     │
-  │        register writeback callbacks                     │
-  │        cache line marked dirty (dirty=1)                │
-  │        eviction invokes preprocess + writeback          │
-  ├─────────────────────────────────────────────────────────┤
-  │  After computation:                                     │
-  │  3. CacheLine.Dispose() (refCount--)                    │
-  │  4. L4.StepComplete()                                   │
-  │     ├─ Predictor.AdvanceExecutionPoint()                │
-  │     └─ Predictor.NeedsPrefetch?                         │
-  │        └─ Yes → CAS-acquire lock, execute prefetch      │
-  └─────────────────────────────────────────────────────────┘
-```
-
-### 2.3 Key Parameters
-
-| Parameter              | Value                    | Description                                          |
-|------------------------|--------------------------|------------------------------------------------------|
-| Total cache capacity   | 64 MB                    | Per-NUMA-node contiguous memory                      |
-| Cache line size        | 8192 Bytes               | = 64 × `double MAT_KERNEL`                           |
-| Cache line count       | 8192                     | 64MB / 8192B                                         |
-| Mapping table type     | Swiss Table              | 1024 buckets × 16 slots, SIMD-accelerated            |
-| Cache line pool        | Slab Allocator           | Non-concurrent, fixed capacity, no auto-expansion    |
-| Eviction policy        | RRPV mask + windowed OPT | SoA layout + SSE2 batch scan                         |
-| Prefetch policy        | Predictor windowed OPT   | 2048-entry buffer, 1024-step lookahead               |
-| Writeback policy       | Callback-driven          | Invokes registered callbacks on dirty eviction/flush |
-
----
-
-## 3. Key Components
-
-### 3.1 Swiss Table (Pointer Mapping Table)
-
-**Responsibility**: Maintains the `original pointer → cache pointer` mapping.
-
-- Key: original pointer `nint`, pointing to data allocated by HLSF/malloc on a remote node
-- Value: cache pointer `nint`, pointing to locally Slab-allocated cache line
-- Hash: hardware `CRC32C` instruction on the 64-bit pointer
-  - Low 10 bits → bucket index (1024 buckets)
-  - Bits 10-16 → H2 control byte (used for SIMD pre-filtering)
-- Scan: SSE2 `pmovmskb` instruction for parallel comparison of 16 control bytes
-- Tombstone mechanism: deleted entries set ctrl to `0xFE`, preserving probe chain integrity
-- Capacity: 1024 × 16 = 16,384 mappings, significantly larger than total cache line count (8192 lines),
-  ensuring extremely low hash collision rate
-
-**Measured Performance** (Ryzen 7 6800H, .NET 8, BenchmarkDotNet):
-
-| Operation                | Swiss Table  | Dictionary  | Speedup |
-|--------------------------|-------------|-------------|---------|
-| Zipfian Lookup (8192×)   | 20.0 μs     | 76.1 μs     | 3.8×   |
-| Uniform Lookup (8192×)   | 18.6 μs     | 50.6 μs     | 2.7×   |
-| Insert (4096 entries)    | 18.5 μs     | 46.5 μs     | 2.5×   |
-| SteadyState (4096 ops)   | 25.3 μs     | 68.3 μs     | 2.7×   |
-
-Single lookup latency ≈ 2.6 ns, GC allocation = 0.
-
-### 3.2 Slab Allocator (Cache Line Pool)
-
-**Responsibility**: Manages allocation and reclamation of fixed-size (8192B) cache lines.
-
-- Mode: **Non-concurrent, fixed capacity** (`FixedSlabAllocator<T>` mode),
-  reusing the existing `SlabAllocator.FromBuffer<T>()` interface
-- No auto-expansion: capacity is fixed at initialization (64MB / 8192B = 8192 lines);
-  allocation failure triggers eviction rather than expansion
-- Allocation complexity: O(1), pops from free stack
-- Reclamation complexity: O(1), pushes back to free stack
-- Alignment: all cache lines are 64B aligned, ensuring no cross-hardware-cache-line boundaries
-
-### 3.3 Eviction Metadata (SoA Layout + RRPV Mask + Writeback Callbacks)
-
-**Responsibility**: Tracks per-cache-line reference state, heat, and writeback information to determine eviction priority.
-
-Replaces the four-level circular linked list from v0.1 with parallel arrays in Structure-of-Arrays layout:
-
-```
-SoA Layout — Parallel Arrays
-
-  _refFlags[i]       : byte      Reference count snapshot (0=free, non-zero=held)
-  _evictionFlags[i]  : byte      dirty(1bit) + RRPV(2bit) + costClass(1bit)
-  _originKeys[i]     : nuint     Original pointer (reverse-deregisters Swiss Table entry on eviction)
-  _preprocess[i]     : nint      Writeback pre-processing function pointer (called before dirty eviction)
-  _writeback[i]      : nint      Writeback function pointer (called during dirty eviction)
-  _callbackCtx[i]    : nuint     Callback context (passed to preprocess/writeback)
-```
-
-**Eviction Flag Bit Layout** (`_evictionFlags[i]`):
-
-The RRPV array uses byte storage for each cache line's usage state; the low 2 bits encode the RRPV value.
-
-**RRPV Semantics**:
-
-| RRPV | Meaning                         | Eviction Priority         |
-|------|---------------------------------|---------------------------|
-| 0    | Will be re-accessed very soon   | Lowest (do not evict)     |
-| 1    | Will be accessed shortly        | Low                       |
-| 2    | Will be accessed in a while     | Medium                    |
-| 3    | May never be accessed again     | Highest (evict first)     |
-
-**RRPV Update Events**:
-
-| Event              | Operation                       | Description                                          |
-|--------------------|---------------------------------|------------------------------------------------------|
-| Load (insert)      | RRPV = 0                        | Freshly loaded data will be used soon                |
-| Hit                | `_evictionFlags[i] = 0`         | Bits 1-2 cleared, RRPV reset to 0                    |
-| Eviction scan      | Find lines with RRPV=3 to evict | If none found, increment all RRPV +1 (aging)         |
-
-**Advantages over the v0.1 four-level circular linked list**:
-
-| Comparison           | v0.1 Circular List                  | v0.3 RRPV Mask + Callbacks           |
-|----------------------|-------------------------------------|--------------------------------------|
-| Data structure       | 4 doubly-linked lists + next ptrs   | Byte array + function pointer arrays |
-| Warm-up operation    | Unlink + relink (4 pointer writes)  | `+= 1` (1-byte write)                |
-| Aging operation      | Per-node list migration             | SIMD batch +1 (16 entries/cycle)     |
-| Eviction scan        | Iterate list head (pointer chasing) | SIMD pattern matching (16/cycle)     |
-| Cache friendliness   | Poor (pointer chasing)              | Good (contiguous memory scan)        |
-| Reference protection | None                                | Lines with refCount > 0 not evicted  |
-| Writeback support    | None                                | Callback-function driven             |
-
-### 3.4 Writeback Callback Mechanism
-
-**Responsibility**: Provides flexible writeback strategies for writable cache lines, using native function pointers to avoid managed overhead.
-
-**Design Principle**: All writable cache lines are treated as dirty by default. On eviction or explicit flush,
-L4 itself does not manage the writeback strategy; instead, the bound predictor is responsible for implementing it.
-
-The predictor is defined via the following interface:
-
-```
-    public interface IPrefetchPredict
-    {
-
-        int Predict(
-            Span<CacheLinePrediction> node
-        );
-
-        bool Prefetch(
-             nuint origin,
-             ulong policy,
-             nuint cache
-        );
-
-        void WriteBack(
-             nuint origin,
-             ulong policy,
-             nuint cache
-        );
-
-    }
-```
-
-**Typical Callback Implementations**:
-
-```
-Scenario 1: Segment accumulation (FMA partial sum)
-  preprocess = null  (no pre-processing needed; data is already a double array)
-  writeback  = AccumulateAdd  (element-wise dst[i] += src[i], AVX2-vectorized)
-
-Scenario 2: Writeback of packed intermediate results
-  preprocess = UnpackKernelRow  (reverse-repack from Pack format to row-major order)
-  writeback  = AccumulateAdd
-
-Scenario 3: PLU decomposition intermediate data
-  preprocess = null
-  writeback  = DirectCopy  (direct overwrite memcpy)
-```
-
-### 3.5 CacheLine (Cache Line Handle)
-
-**Responsibility**: A cache line access handle held by the compute thread; prevents in-use lines from being evicted via reference counting.
-
-```csharp
-public ref struct CacheLine : IDisposable
-{
-    private ref int _activeCount;    // L4 global active count
-    private ref int _refCount;       // Per-line reference count
-    private nuint   _handle;         // Local cache data address
-
-    // Construction: Interlocked.Increment(ref _activeCount)
-    //               Interlocked.Increment(ref _refCount)
-    // Dispose:      Interlocked.Decrement on both counters
-}
-```
-
-- `ref struct` ensures it cannot escape to the heap
-- Reference counts use `Interlocked` atomic operations for thread safety
-- Lines with `_refCount > 0` are skipped during eviction scans
-- StreamTransparent mode returns a CacheLine that does not occupy a cache slot
-- Both read-only and writable paths return the same CacheLine type,
-  callers decide read/write behavior via `.Address`
-
-### 3.6 Predictor (Prefetch Predictor)
-
-**Responsibility**: Provides deterministic prefetch predictions for L4 based on the windowed OPT strategy.
-
-**Core Principle**: Matrix computation task sequences are deterministic — the scheduler pre-allocates
-task blocks `(kr, kc, zz)` for each thread, allowing precise computation of the cache line keys
-required at each future step. This gives L4 a predictive capability that hardware caches cannot
-possess: **direct visibility into the future**, rather than inferring the future from history as
-strategies like Hawkeye do.
-
-```
-Predictor Sliding Window:
-
-  Task sequence: ... [T_now] [T+1] [T+2] ... [T+1023] ... [T+2047]
-                      ↑ execution point                  ↑ buffer tail
-
-  Window capacity      = 2048 prediction entries
-  Prefetch trigger threshold = trigger refill when prefetch frontier
-                               leads execution point by fewer than 1024 steps
-  Refill batch size    = 64 entries (avoids excessive single-refill latency)
-```
-
-**数据结构**：
-
-```csharp
-internal class Predictor
-{
-    private const int WindowCapacity = 2048;
-    private const int RefillThreshold = 1024;
-
-    private PrefetchEntry[] _buffer;      // Circular prediction buffer
-    private int _head;                     // Prefetch frontier (prefetched up to here)
-    private int _tail;                     // Production position (scheduler fills up to here)
-    private int _executed;                 // Execution point (compute thread has completed up to here)
-
-    private HashSet<nuint> _activeKeys;    // All active keys within the window (deduplicated)
-}
-
-struct PrefetchEntry
-{
-    public nuint Key;              // Cache line identifier
-    public nuint SourceAddress;    // Source data address
-    public bool  NeedsRepack;      // Whether non-contiguous repacking is needed
-}
-```
-
-**Cooperation with Eviction Policy**:
-
-```
-Eviction priority (from highest to lowest priority):
-
-  1. refCount==0, not in window, RRPV==3, dirty==0  ← First (zero-cost eviction)
-  2. refCount==0, not in window, RRPV==3, dirty==1  ← Second (needs writeback but cold)
-  3. refCount==0, not in window, RRPV<3,  dirty==0  ← Ordered by RRPV
-  4. refCount==0, not in window, RRPV<3,  dirty==1  ← Ordered by RRPV
-  5. refCount==0, in window                          ← Avoid evicting if possible
-  6. refCount>0                                      ← Never evict
-```
-
-Windowed OPT means most eviction decisions do not depend on RRPV — "not in window" alone is
-sufficient to determine evictability. RRPV provides fine-grained differentiation among
-out-of-window lines; the dirty bit preferentially evicts clean lines at equal RRPV to avoid writeback overhead.
-
-### 3.7 Concurrency Model
-
-L4 uses a **no-extra-threads** design; all operations are performed by compute threads themselves:
-
-| Operation                          | Executor                        | Concurrency                          |
-|------------------------------------|---------------------------------|--------------------------------------|
-| Lookup (Swiss Table read)          | Any compute thread              | ✅ Fully parallel, lock-free         |
-| HIT RRPV update                    | Any compute thread              | ✅ Single-byte write, no sync needed |
-| refCount increment/decrement       | Any compute thread              | ✅ Interlocked atomic operations     |
-| Prefetch refresh (eviction + load) | CAS-winner thread               | Serial (only one thread enters)      |
-| Dirty writeback                    | CAS-winner thread               | Serial (within eviction flow)        |
-| FlushAllDirty                      | Single thread after computation | Serial (no concurrency)              |
-
-**Prefetch Refresh CAS Lock**:
-
-```csharp
-private int _refreshLock;  // 0=free, 1=locked
-
-private void TryRefreshPrefetch()
-{
-    if (Interlocked.CompareExchange(ref _refreshLock, 1, 0) != 0)
-        return;  // Another thread is doing it; current thread continues computing
-    try { /* eviction + prefetch */ }
-    finally { Volatile.Write(ref _refreshLock, 0); }
-}
-```
-
-**Swiss Table Concurrent Read Safety Guarantee**: The prefetch refresh thread follows strict write ordering
-on insertion: write Slab data first, then write eviction metadata and callback pointers, `sfence`, then
-write the Swiss Table control byte and key/value, ensuring that when a compute thread reads the control
-byte, the data is already fully visible.
-
----
-
-## 4. Operation Flows
-
-### 4.1 Cache Lookup (Read-Only Hit)
-
-1. Compute CRC32C hash of the original pointer
-2. Swiss Table lookup: SIMD scan ctrl → compare key → return cache pointer
-3. Update RRPV: `_evictionFlags[slot] &= 0xF9` (RRPV zeroed, dirty bit unchanged)
-4. Construct CacheLine handle (refCount++)
-5. Return CacheLine; upper-layer code accesses local data via `.Address`
-
-### 4.2 Cache Lookup (Writable Hit)
-
-1. Swiss Table lookup hits
-2. Update RRPV: `_evictionFlags[slot] &= 0xF9`
-3. Construct CacheLine handle (refCount++)
-4. Return CacheLine; upper-layer code reads/writes the cache line via `.Address` (e.g., partial sum +=)
-
-### 4.3 Cache Miss (Read-Only)
-
-1. Swiss Table lookup misses
-2. Compute thread enters `Thread.Sleep(0)` spin loop
-3. Wait for Predictor-driven prefetch refresh to load the line into L4
-4. Exit wait loop when Swiss Table shows a hit
-5. Construct CacheLine handle and return
-
-Under normal operation, the Predictor always leads the execution point by 1024+ steps,
-misses occur only during cold start or extreme bursts.
-
-### 4.4 Cache Miss (Writable)
-
-1. Swiss Table lookup misses
-2. Allocate a cache line from Slab
-3. If Slab has no free slots → trigger eviction (see 4.6)
-4. Zero-initialize the cache line (`Unsafe.InitBlock(dest, 0, 8192)`)
-5. Register writeback callbacks: `_preprocess[slot]`, `_writeback[slot]`, `_callbackCtx[slot]`
-6. Set eviction flags: `dirty=1, RRPV=0`
-7. Write `_originKeys[slot]`
-8. `sfence`
-9. Write Swiss Table mapping
-10. Construct CacheLine handle and return
-
-### 4.5 Prefetch Refresh
-
-Triggered by compute threads in `StepComplete()`; CAS lock ensures single-thread execution:
-
-1. Synchronize refFlags snapshot (`_refCounts[i] > 0 → _refFlags[i] = 1`)
-2. Retrieve pending prefetch entries from Predictor (up to 64 at a time)
-3. For each entry:
-   - Swiss Table hit → mark RRPV=0 (hot-line protection)
-   - Swiss Table miss → execute load:
-     a. Allocate cache line from Slab
-     b. If Slab has no free slots → trigger eviction (see 4.6)
-     c. Execute Pack reorder or memcpy based on `NeedsRepack` flag
-     d. Write eviction metadata (originKey, RRPV=0, dirty=0, callbacks=null)
-     e. `sfence`
-     f. Write Swiss Table mapping
-
-### 4.6 Cache Eviction (SIMD Scan + Writeback)
-
-```
-Eviction scan pseudocode:
-
-  Pass 1: Find refCount==0, RRPV==3, dirty==0 (zero-cost eviction)
-    for i in range(scanCursor, CacheLineCount), step=16:
-      refChunk = SSE2.Load(refFlags + i)
-      refFreeMask = SSE2.MoveMask(SSE2.CompareEqual(refChunk, zero))
-
-      evChunk = SSE2.Load(evictionFlags + i)
-      // RRPV==3 and dirty==0 → byte & 0x07 == 0x06
-      masked = SSE2.And(evChunk, 0x07)
-      coldCleanMask = SSE2.MoveMask(SSE2.CompareEqual(masked, 0x06))
-
-      candidates = refFreeMask & coldCleanMask
-      while candidates != 0:
-        bit = TrailingZeroCount(candidates)
-        idx = i + bit
-        if originKeys[idx] not in Predictor.ActiveKeys:
-          evict(idx)    // No writeback, discard directly
-          return
-        candidates &= candidates - 1
-
-  Pass 2: Find refCount==0, RRPV==3, dirty==1 (needs writeback)
-    Same as above, but match byte & 0x07 == 0x07
-    evict triggers writeback callbacks
-
-  Pass 3: Increment all RRPV+1 (aging), retry
-    Up to 3 rounds
-```
-
-**逐出执行**：
-
-```csharp
-private void Evict(int slot)
-{
-    byte flags = _evictionFlags[slot];
-
-    // Dirty writeback
-    if ((flags & 0x01) != 0)
-    {
-        nuint origin = _originKeys[slot];
-        nuint cached = SlotAddressFromIndex(slot);
-        nuint ctx    = _callbackCtx[slot];
-
-        // 1. Pre-processing (optional)
-        var preprocess = (delegate* unmanaged<nuint, nuint, void>)_preprocess[slot];
-        if (preprocess != null)
-            preprocess(cached, ctx);
-
-        // 2. Writeback
-        var writeback = (delegate* unmanaged<nuint, nuint, nuint, void>)_writeback[slot];
-        if (writeback != null)
-            writeback(origin, cached, ctx);
-    }
-
-    // Standard eviction
-    _map.TryRemove(_originKeys[slot], out _);
-    _slab.Free(SlotAddressFromIndex(slot));
-    _evictionFlags[slot] = 0;
-    _originKeys[slot] = 0;
-    _preprocess[slot] = 0;
-    _writeback[slot] = 0;
-    _callbackCtx[slot] = 0;
-}
-```
-
-### 4.7 显式刷新
-
-```csharp
-/// <summary>
-/// Explicitly writes back the specified dirty cache line. Called after all segments complete.
-/// </summary>
-public void FlushDirty(nuint originKey)
-{
-    if (_map.TryGet(originKey, out nuint addr))
-    {
-        int slot = SlotIndex(addr);
-        if ((_evictionFlags[slot] & 0x01) != 0)
-        {
-            // Execute pre-processing + writeback
-            InvokeWriteBack(slot);
-            _evictionFlags[slot] &= 0xFE;  // Clear dirty bit
-        }
-    }
-}
-
-/// <summary>
-/// Writes back all dirty cache lines in bulk. Called after entire matrix computation completes.
-/// </summary>
-public void FlushAllDirty()
-{
-    for (int i = 0; i < CacheLineCount; i++)
-    {
-        if ((_evictionFlags[i] & 0x01) != 0 && _originKeys[i] != 0)
-        {
-            InvokeWriteBack(i);
-            _evictionFlags[i] &= 0xFE;
-        }
-    }
-}
-```
-
-### 4.8 Working Mode Switch
-
-```csharp
-public enum L4Mode
-{
-    /// <summary>
-    /// Pass-through mode: Map() returns the original pointer directly; L4 does not intervene.
-    /// Suitable for single-NUMA + no-repack scenarios (e.g., vector addition, scalar multiplication).
-    /// </summary>
-    StreamTransparent,
-
-    /// <summary>
-    /// Buffer mode: full lookup/Pack/cache/eviction pipeline.
-    /// Suitable for FMA scenarios requiring repacking or multi-NUMA scenarios.
-    /// </summary>
-    CacheBuffer
-}
-```
-
-Mode is determined at construction time and does not change at runtime. Decision logic:
-
-- Requires Pack reordering (FMA core rows of matrix A) → CacheBuffer
-- Multiple NUMA nodes → CacheBuffer
-- Requires segment accumulation → CacheBuffer
-- Single NUMA + no reordering + no segment → StreamTransparent
-
----
-
-## 5. Segment Accumulation Scenario
-
-### 5.1 Problem
-
-For matrix multiplication `C = A × B` when the K dimension is large, segmented accumulation is required:
-
-```
-segment 0:  C_partial  = A[kr, 0..KC]    × B[0..KC, kc]
-segment 1:  C_partial += A[kr, KC..2KC]  × B[KC..2KC, kc]
-...
-segment N:  C_partial += A[kr, N*KC..K]  × B[N*KC..K, kc]
-
-Final: C[kr, kc] = Σ all segment partial sums
-```
-
-If each segment's result is `+=` directly to the C matrix,
-and C resides on a remote NUMA node, every segment incurs cross-node write latency.
-
-### 5.2 L4 Solution
-
-Temporarily store C's partial sums in L4's writable cache lines:
-
-```
-segment 0: c = l4.MapWritable(C_key, null, &AccumulateAdd)
-           // First miss → allocate zero-initialized cache line
-           FMA(c.Address, a.Address, b.Address)  // c += a*b
-           c.Dispose()
-
-segment 1: c = l4.MapWritable(C_key, null, &AccumulateAdd)
-           // Hit! Returns existing partial sum cache line
-           FMA(c.Address, a.Address, b.Address)  // c += a*b
-           c.Dispose()
-
-... after all segments complete ...
-
-l4.FlushDirty(C_key)
-// Calls AccumulateAdd(C_origin, cacheline, ctx)
-// → Adds local partial sum back to remote C matrix in one shot
-```
-
-### 5.3 Benefits
-
-```
-Without segment buffering (OpenBLAS approach):
-  Each segment writes C matrix across NUMA
-  Remote writes per output tile = Zk times
-  Per-write latency = ~200-300ns (cross-node)
-
-With L4 segment buffering:
-  All segment += operations complete locally in L4 cache lines
-  Partial sums likely remain in L1/L2 (8KB << L1 capacity)
-  Remote writes per output tile = 1 (final FlushDirty)
-  Writeback uses AVX2-vectorized stores: 8192B = 32 × 256-bit stores
-
-  Reduction ratio = Zk : 1
-```
-
----
-
-## 6. Uniqueness and Advantages
-
-### 6.1 Deterministic Prefetch (Windowed OPT)
-
-Essential difference from hardware cache replacement policies (LRU, RRIP, Hawkeye):
-
-| Policy              | Information Source      | Prediction Method             | Accuracy                  |
-|---------------------|-------------------------|-------------------------------|---------------------------|
-| LRU                 | Past access order       | Least recently used           | Moderate                  |
-| RRIP                | Insert/hit markers      | Predict reuse distance        | Moderate-High             |
-| Hawkeye             | OPTgen retrospection    | Learn past to infer future    | High                      |
-| **L4 Predictor**    | **Future task queue**   | **Direct future visibility**  | **Perfect** (within window) |
-
-L4's Predictor is a **deterministic Oracle** — it does not predict; it knows.
-Because matrix computation task sequences are fully determined at scheduler allocation time.
-
-### 6.2 NUMA Adaptability
-
-The same code automatically gains NUMA benefits on different hardware configurations:
-
-| Hardware Configuration  | L4 Behavior                                                 |
-|-------------------------|-------------------------------------------------------------|
-| Single-socket CPU       | Pack cache + segment accumulation buffer                    |
-| Dual-socket CPU         | Pack cache + NUMA migration cache + segment accum.          |
-| Hybrid-architecture CPU | Pack cache + cross-domain migration cache + segment accum.  |
-
-### 6.3 Callback-Driven Writeback Strategy
-
-Using native function pointers for writeback avoids:
-
-- Virtual method call overhead
-- Interface dispatch overhead
-- Delegate GC pressure
-- Hard-coding specific writeback logic
-
-Callers register `preprocess` and `writeback` callbacks at `MapWritable` time,
-L4 invokes them directly through function pointers on eviction or Flush,
-**zero managed overhead, zero virtual dispatch, performance equivalent to C function calls**.
-
-### 6.4 Reference Count Protection
-
-Through `CacheLine` handle reference counting, cache lines actively in use by compute threads are
-absolutely never evicted (including writeback not being triggered). The SIMD eviction scan skips
-lines with `refCount > 0` immediately via the `_refFlags` array, without checking linked lists or acquiring locks.
-
-### 6.5 Cache Line Size Aligned to Matrix Kernel
-
-The 8192B cache line size is not arbitrary:
-
-- 1 `double MAT_KERNEL` (4×4 double matrix) = 128 Bytes
-- 1 cache line = 64 `MAT_KERNEL` units
-- Matrix multiplication micro-kernels operate on data sizes perfectly aligned to cache lines
-- Compute kernel functions operate on cache lines as units; no cross-cache-line accesses occur
-
-### 6.6 Fixed-Capacity Determinism
-
-- Slab allocator never expands → memory footprint upper bound is known (64 MB)
-- SIMD eviction scan → latency upper bound is known (at most 3 aging rounds × 512 SIMD comparisons)
-- Swiss Table fixed 16,384 slots → lookup latency upper bound is known
-- Writeback callback latency is controlled by the caller → predictable
-- Worst-case L4 latency = lookup + eviction (incl. writeback) + allocation + memcpy, all statically computable
-
-### 6.7 Reuse of Existing StgSharp Infrastructure
-
-| L4 Component          | Reused StgSharp Infrastructure                        |
-|-----------------------|-------------------------------------------------------|
-| Mapping table         | `SwissTable` (implemented and benchmark-validated)    |
-| Mapping table SIMD    | `IBucketScanner` + `SIMDID` architecture detection    |
-| Cache line alloc      | `SlabAllocator.FromBuffer<T>()`                       |
-| Hash computation      | Hardware `CRC32C` instruction                         |
-| Memory allocation     | `NativeMemory.AlignedAlloc`                           |
-| Future multi-platform | `IBucketScanner` + NRGA compilation pipeline         |
-
-### 6.8 Originality Analysis
-
-After surveying existing mainstream numerical computation libraries, L4's design has
-**no direct precedent or equivalent in known public implementations**.
-
-#### NUMA Strategy Comparison with Existing Libraries
-
-| Library / Framework | NUMA Strategy                       | Software Cache Layer | Mapping Table   | Eviction Policy         | Dirty Writeback    |
-|---------------------|-------------------------------------|---------------------|-----------------|-------------------------|--------------------|
-| Intel MKL           | Thread pinning + `numactl`          | None                | None            | None                    | None               |
-| OpenBLAS            | Thread affinity + block alignment   | None                | None            | None                    | None               |
-| BLIS                | Multi-level block alignment L1/L2/L3| None                | None            | None                    | None               |
-| Eigen               | No explicit NUMA handling           | None                | None            | None                    | None               |
-| cuBLAS / rocBLAS    | GPU memory (hardware-solved)        | None                | None            | None                    | None               |
-| **StgSharp L4**     | **Software-managed thread-local cache** | **Yes**         | **Swiss Table** | **RRPV + windowed OPT** | **Callback-driven** |
-
----
-
-## 7. 从 v0.1 到 v0.3 的变更摘要
-
-| 项目             | v0.1                          | v0.3                                 |
-|-----------------|-------------------------------|---------------------------------------|
-| 逐出数据结构     | 4 级环形双向链表               | RRPV 2-bit 掩码 + 8KB SoA 数组        |
-| 逐出扫描方式     | 链表头指针遍历                 | SSE2 批量模式匹配（16 行/周期）         |
-| 热���更新         | 链表节点摘插（4 指针写）        | 单字节位运算 `&= 0x03`                |
-| 老化操作         | 逐节点移链表                   | SIMD 批量 +1                          |
-| 引用保护         | 无                            | refCount > 0 时 SIMD 扫描跳过          |
-| 预取策略         | 无                            | Predictor 窗口 OPT（2048 条缓冲）      |
-| 线程模型         | L4 服务线程 + Command Queue    | 无额外线程，CAS 抢锁                   |
-| 命令队列         | 链式 CommandCache 分段          | 不需要（预取刷新替代命令驱动）           |
-| 缓存行元数据     | Slab 分配的 CacheLineHead 结构 | SoA 平行数组 + 函数指针数组             |
-| 工作模式         | 单一模式                       | StreamTransparent / CacheBuffer 切换   |
-| 写回策略         | 无（只读缓存）                  | dirty 位 + preprocess/writeback 回调   |
-| 写回机制         | 无                            | 本机函数指针，零托管开销                |
-
----
-
-## 8. 未来工作
-
-- [ ] L4 根类型重构（组合 Swiss Table、Slab、SoA 元数据、Predictor）
-- [ ] Predictor 与矩阵乘法调度器的集成
-- [ ] Segment 累加写回的 AVX2 向量化实现
-- [ ] SIMD 逐出扫描的 AVX2 升级（32 行/周期）
-- [ ] Swiss Table ARM NEON 实现
-- [ ] Swiss Table AVX-512 升级（64 槽扫描从 16 次降至 4 次）
-- [ ] 墓碑累积监控与自动 rehash 策略
-- [ ] 性能基准测试（NUMA 本地 vs 远端访问延迟对比）
-- [ ] Segment 累加 vs 直接写回的 benchmark 对比
-- [ ] 与逐线程矩阵上下文的集成验证
-- [ ] 双路 6242R 环境下的 NUMA 搬运性能验证
-- [ ] 远期：PPC64LE 平台的 VSX 原生 Swiss Table 扫描支持
-
----
-
-## 9. 参考
-
-- Google Abseil Swiss Tables Design Notes
-- HP Labs RRIP (Re-Reference Interval Prediction) 论文
-- Hawkeye: Efficient Cache Replacement via OPTgen (ISCA 2017)
-- StgSharp HLSF Allocator 设计文档
-- StgSharp SIMD Architecture (`SIMDID` 体系)
-- StgSharp NRGA Roadmap
-- StgSharp `SlabAllocator<T>` 实现
-- StgSharp `SwissTable` 实现及 Benchmark

future/NGRA_Transformation_Plan.md

@@ -0,0 +1,916 @@
+# NGRA 转型计划
+
+> 面向本地 Codex / 项目维护者的快速架构说明  
+> 项目：Nitload General Regular Analyzer（NGRA）
+
+## 1. 转型结论
+
+NGRA 不再以“高性能字符串正则表达式引擎”为主要目标。
+
+原先围绕 `Span<char>`、专用字符串匹配、复杂回溯、Source Generator 等方向继续投入的收益已经明显下降。后续核心工作转向：
+
+1. 以 **ε-NFA / NFA** 为基础执行模型；
+2. 将输入从 `char` 推广为任意可比较、可判定类别的序列元素；
+3. 面向 Token Stream、语法前端、半上下文模式分析等场景；
+4. 支持自动机归并、分层自动机、状态/断言/前序引用；
+5. 在此基础上继续研究 **Weighted Automaton / NGRA-Tensor**。
+
+因此，Text Regex 从“主架构”降级为“兼容前端 / 参考实现 / 测试子系统”。
+
+---
+
+## 2. 当前代码处理原则
+
+### 2.1 保留现有 Text Regex 半成品
+
+当前 Text Regex Source Generator、COUNT/CONCAT/ALT lowering、生成式 matcher 等代码不删除。
+
+原因：
+
+- 五角星 AST 模型仍然是有效成果；
+- AST 搜索、规范化、旋转、合并等代码仍可复用；
+- 当前实现记录了 COUNT continuation、group boundary、rollback 等真实工程问题；
+- 可作为未来自动机 IR 与旧实现行为的对照；
+- 删除会丢失大量探索成果。
+
+建议：
+
+- 将旧生成器移动到 `Legacy` / `Experimental` / `Archive` 目录；
+- 通过 `.csproj` 的 `Compile Remove` 或独立非构建项目，使其暂时不参与主编译；
+- 不再优先修补完整 `.NET Regex` 兼容性。
+
+### 2.2 五角星 AST 继续保留
+
+现有节点关系：
+
+```text
+          Parent
+            ↑
+Previous ← Node → Next
+          ↙    ↘
+       Left    Right
+```
+
+继续作为通用语法树 / 结构树基础设施。
+
+需要坚持：
+
+- AST 用于表达语法和结构；
+- 自动机 / CFG / Relation Graph 用于表达执行与传播；
+- 不再要求 AST 本身承担全部 backtracking / continuation 语义。
+
+---
+
+## 3. 新主线：ε-NFA
+
+第一阶段优先实现一个简单、正确、无性能野心的 ε-NFA 模拟器。
+
+### 3.1 基础状态模型
+
+```text
+Current Active States
+        ↓
+ε-closure
+        ↓
+consume(input)
+        ↓
+Next Active States
+        ↓
+ε-closure
+```
+
+核心状态：
+
+```text
+State
+Transition
+StartState
+AcceptStates
+ActiveStateSet
+```
+
+Transition 分为：
+
+```text
+ε transition
+matched transition
+```
+
+输入类型不能写死为 `char`。
+
+建议：
+
+```csharp
+EpsilonNfa<TInput>
+```
+
+或：
+
+```csharp
+EpsilonNfa<TScalar>
+```
+
+匹配条件可以抽象为：
+
+```csharp
+bool Match(in TInput input)
+```
+
+或者后续升级为更明确的 Predicate / Category Matcher。
+
+### 3.2 第一阶段支持的 Pattern
+
+第一版只要求：
+
+```text
+literal / predicate
+concat
+alternation
+*
++
+?
+{m,n}
+ordinary grouping
+```
+
+暂不追求：
+
+```text
+capture rollback
+复杂 greedy / lazy 行为
+lookaround
+backreference
+完整 .NET Regex compatibility
+```
+
+其中 `{m,n}` 可以优先在构造期展开为 NFA 结构，而不是运行时维护复杂 COUNT 控制流。
+
+---
+
+## 4. 为什么以 NFA 为主，而不是 DFA
+
+DFA 仍然有价值，但不再是必须经过的阶段。
+
+核心路线：
+
+```text
+Pattern
+  ↓
+ε-NFA
+  ↓
+NFA execution
+  ↓
+Weighted NFA
+  ↓
+NGRA-Tensor
+```
+
+DFA 只作为可选 specialization：
+
+```text
+Boolean
+Static
+No dynamic relation
+No weighted state
+```
+
+满足这些条件的局部子图，可以由编译器确定化为 DFA fast path。
+
+总体原则：
+
+> NFA 是主语义模型，DFA 是可选优化后端。
+
+原因：
+
+普通 NFA 的活动状态：
+
+```text
+a_i ∈ {0,1}
+```
+
+加权机可自然推广为：
+
+```text
+a_i ∈ R
+```
+
+Tensor 版本可以继续推广为：
+
+```text
+a_i ∈ R^d
+```
+
+多状态同时活跃不再是需要“消除的非确定性”，而会成为模型本身的状态表示。
+
+---
+
+## 5. NGRA 的目标：广义序列分析
+
+NGRA 不再局限于字符串。
+
+典型输入：
+
+```text
+char
+token
+syntax node
+semantic node
+sensor frame
+event
+instruction-like object
+```
+
+Pattern 的作用也从：
+
+```text
+“这个字符串是不是符合 regex”
+```
+
+扩展为：
+
+```text
+“这个序列在当前状态、历史、类别和上下文条件下，
+是否满足某个结构化模式”
+```
+
+---
+
+## 6. 半上下文 Token Analyzer
+
+NGRA 的近期目标之一，是成为一种介于普通 Regex 与完整 Parser 之间的 Token Stream Analyzer。
+
+可用能力包括：
+
+```text
+Token 类别匹配
+Token 属性匹配
+前序状态引用
+局部断言
+Pattern 状态
+符号绑定
+分层子自动机
+局部上下文
+```
+
+因此它适合作为：
+
+```text
+Lexer 后端
+Token Regex
+语法前端
+编译器预分析器
+DSL Parser Frontend
+结构化流分析器
+```
+
+“半上下文”的含义不是严格的形式语言分类，而是：
+
+> Pattern 不只依赖当前 token，也可以依赖有限的已知状态、绑定、前序结果和结构信息，但不要求一开始就构造完整通用 Parser。
+
+---
+
+## 7. 自动机归并
+
+大量 Pattern 应优先在 NFA 层归并，而不是各自独立执行。
+
+例如：
+
+```text
+             ε → Pattern A
+            /
+GlobalStart ─ε → Pattern B
+            \
+             ε → Pattern C
+```
+
+Accepting State 可以附带：
+
+```text
+PatternId
+MatchKind
+Payload
+```
+
+后续目标：
+
+- 合并公共路径；
+- 消除冗余 ε 边；
+- 状态压缩；
+- bitset active state；
+- pattern priority；
+- 多层自动机组合。
+
+---
+
+## 8. 分层自动机
+
+后续重点不是继续增加字符串 Regex 特性，而是建立分层自动机。
+
+示意：
+
+```text
+Scalar / Token Layer
+        ↓
+Local Pattern Layer
+        ↓
+Phrase / Region Layer
+        ↓
+Sentence / Structure Layer
+        ↓
+Semantic / Relation Layer
+```
+
+低层自动机可以生成高层节点，高层节点继续作为新序列输入。
+
+即：
+
+```text
+Input Stream
+   ↓
+Automaton L0
+   ↓
+Derived Nodes
+   ↓
+Automaton L1
+   ↓
+Higher-level Nodes
+```
+
+这应成为 NGRA 进入编译器前端、自然语言结构分析和复杂流分析的主路径。
+
+---
+
+## 9. Assertion / Context 的重新定义
+
+不再围绕字符串 Regex 的 lookahead / lookbehind 设计核心架构。
+
+通用定义应更接近：
+
+```text
+Assert(Context) -> bool
+```
+
+或者：
+
+```text
+RelationGate(State, Context, History) -> bool
+```
+
+因此：
+
+- 字符串前瞻/后顾只是特殊情况；
+- 前序引用只是状态引用的一种；
+- group/capture 不是核心抽象；
+- Context / Binding / Region / History 才是可推广概念。
+
+---
+
+# NGRA-Tensor 构想
+
+## 10. 基本方向
+
+NGRA-Tensor 不是简单地“给 NFA 边加 float”。
+
+它希望把：
+
+```text
+Boolean multi-state automaton
+```
+
+推广为：
+
+```text
+Weighted / Tensor Relation Network
+```
+
+基础演化：
+
+```text
+NFA
+a_i ∈ {0,1}
+
+↓ weighted
+
+Weighted Automaton
+a_i ∈ R
+
+↓ tensor/state
+
+NGRA-Tensor
+a_i ∈ R^d
+```
+
+---
+
+## 11. Relation 成为一等对象
+
+不再采用固定 `Port4` 作为核心语义。
+
+推荐模型：
+
+```text
+Source Node
+    ↓
+[ Relation ]
+    ↓
+Destination Node
+```
+
+Relation 包含：
+
+```text
+Source
+Destination
+Type
+Parameters
+Weight / Weight Function
+Optional State
+Eligibility / Gate
+```
+
+语义上：
+
+```text
+Relation:
+决定一条联系是否生效，
+以及它如何把 Source 信息贡献给 Destination。
+```
+
+Node 负责保存状态。
+
+Blend 负责汇合多条 Relation 的贡献。
+
+---
+
+## 12. Pull，而不是主动广播
+
+GPU / 执行层优先采用 destination pull：
+
+```text
+Destination Node
+    ↓
+请求自己依赖的 Relations
+    ↓
+读取 Source states
+    ↓
+Relation Eval
+    ↓
+Blend
+```
+
+而不是：
+
+```text
+Source Node
+    ↓
+主动向大量 Destination 广播
+```
+
+优点：
+
+- 减少 scatter；
+- 减少原子写冲突；
+- 减少 readiness 管理；
+- 更适合 GPU destination-centric execution。
+
+---
+
+## 13. Relation 的三段语义
+
+推荐拆成：
+
+```text
+Eligibility
+    ↓
+Compatibility
+    ↓
+Transfer
+```
+
+即：
+
+1. **Eligibility**：这条 Relation 当前能不能参与；
+2. **Compatibility**：参与后有多重要；
+3. **Transfer**：真正传递什么信息。
+
+形式上：
+
+```text
+gate_ij = G(state, context, relation)
+score_ij = F(query, key, relation)
+value_ij = T(source_state, relation)
+```
+
+最终：
+
+```text
+output_i = Blend(gate_ij * weight_ij * value_ij)
+```
+
+---
+
+## 14. 与 Attention / QKV 的关系
+
+QKV 可以作为 Relation 内部算子的第一种 baseline，但不应决定 NGRA-Tensor 的外层拓扑。
+
+标准 Attention：
+
+```text
+Q = “我需要什么”
+K = “我适不适合被引用”
+V = “真正传递的内容”
+```
+
+数学上：
+
+```text
+score_ij = q_i · k_j
+weight_ij = softmax(score_ij)
+output_i = Σ weight_ij * v_j
+```
+
+NGRA-Tensor 的差异：
+
+- Relation 是显式、长期存在、可带类型的；
+- 候选关系通常是稀疏的；
+- 不一定对全部 node 做 dense attention；
+- Relation 可以有自己的参数、状态、类型和 gate；
+- Attention 可以只是某种 Relation Eval backend。
+
+---
+
+## 15. 稀疏关系，而不是全连接爆破
+
+Transformer 的典型关系空间：
+
+```text
+L × L
+```
+
+NGRA-Tensor 的目标：
+
+```text
+E << N²
+```
+
+即只计算显式 Relation。
+
+但必须承认：
+
+- 稀疏图带来 gather；
+- 不规则访问会伤害 GPU；
+- 小算子过多会降低吞吐。
+
+因此不能简单逐 Relation 启动 kernel。
+
+---
+
+## 16. Relation Tile / 脑区式分块
+
+后续 GPU backend 应研究：
+
+```text
+Semantic Relation Graph
+        ↓
+Graph Partition
+        ↓
+Relation Tiles
+        ↓
+Block-sparse / Dense subgraph execution
+```
+
+目标：
+
+> 块内允许不规则访问，块间尽量转成规则张量传输。
+
+示意：
+
+```text
+Dense / semi-dense local region
+        ↓
+少量跨区 Relation
+        ↓
+another dense / semi-dense region
+```
+
+类似“脑区”：
+
+- 区内关系较密；
+- 区间关系较稀；
+- 每个区可以编译成中型 tensor operator；
+- 跨区使用显式 Relation。
+
+这可能成为 NGRA-Tensor 与传统 Transformer 之间的重要折中。
+
+---
+
+## 17. 语义稀疏 vs 物理稠密
+
+前端语义可以是：
+
+```text
+Sparse Relation Graph
+```
+
+GPU backend 可以通过：
+
+```text
+node reorder
+feature reorder
+relation reorder
+graph clustering
+block detection
+tile packing
+kernel fusion
+shared-memory staging
+```
+
+将其转为：
+
+```text
+Dense blocks
++
+Block-sparse blocks
++
+Irregular sparse tails
+```
+
+原则：
+
+> 模型的图结构不等于 GPU 必须逐边解释。
+
+---
+
+## 18. Node State 可以是高维 Tensor
+
+NGRA-Tensor 不等于“每个 Node 只有一个 scalar”。
+
+Node 可以持有：
+
+```text
+x_i = [f0, f1, ..., fN]
+```
+
+但 Relation 不一定读取全部 feature。
+
+因此可能存在两层稀疏：
+
+```text
+Topology sparsity
+Feature sparsity
+```
+
+Relation 可以只对特定 feature/subspace 感兴趣。
+
+例如：
+
+```text
+Relation A:
+Q features = [1, 2, 7]
+K features = [4, 8]
+V features = [16, 17, 18]
+```
+
+语义上只取这些 feature。
+
+物理执行时 GPU compiler 可以为了带宽一次读入更大的连续 block。
+
+---
+
+## 19. Tensor 观念
+
+后续 NGRA-Tensor 设计不要把 Tensor 只理解为“算子”。
+
+Tensor 可以同时是：
+
+```text
+状态
+参数
+关系
+mask
+中间结果
+数据集合
+算子
+```
+
+“算子”只是某个 Tensor 在某次 contraction 中扮演的角色。
+
+建议以“语义轴”理解 Tensor，例如：
+
+```text
+Node × Feature
+Destination × Source
+Relation × Feature
+Time × Node × Feature
+```
+
+优先思考：
+
+- 哪些轴保留；
+- 哪些轴被收缩；
+- 哪些轴表示关系；
+- 哪些轴表示 feature；
+- 哪些轴可以 sparse；
+- 哪些轴可以 dense。
+
+---
+
+## 20. 训练 / 运行时关系发现
+
+NGRA-Tensor 长期设想允许结构学习。
+
+训练阶段：
+
+```text
+短程强关系
+    ↓
+词 / Token 局部关系
+    ↓
+词组 / 短句
+    ↓
+长句 / 语义
+    ↓
+知识网络 / 长程弱关系
+```
+
+运行时：
+
+当现有网络：
+
+```text
+NoActivePath
+LowConfidence
+HighAmbiguity
+Unknown
+```
+
+可进入较慢的 Relation Discovery：
+
+```text
+Stable Graph
+    ↓
+Unknown
+    ↓
+Candidate Relation Search
+    ↓
+Candidate Graph
+    ↓
+验证
+    ↓
+可能固化进入 Stable Graph
+```
+
+不建议运行时每一步都修改主图。
+
+应区分：
+
+```text
+Fast inference time
+Slow structural learning time
+```
+
+---
+
+# 近期开发优先级
+
+## Phase 1 — ε-NFA Reference Runtime
+
+实现：
+
+```text
+EpsilonNfa<TInput>
+StateId
+Transition
+ε-closure
+Consume
+Accept
+```
+
+目标：
+
+- 语义简单；
+- 正确性优先；
+- 不做复杂性能优化；
+- 不绑定 `char`。
+
+## Phase 2 — Pattern → NFA Lowering
+
+从现有 AST / Pattern IR 构造 NFA：
+
+```text
+literal
+predicate
+concat
+alt
+repeat
+```
+
+## Phase 3 — NFA Merge
+
+实现：
+
+```text
+multi-pattern merge
+PatternId
+shared start
+accept payload
+```
+
+然后测试大量 Pattern 同时运行。
+
+## Phase 4 — Token Stream
+
+将输入切换到：
+
+```text
+Token
+```
+
+支持：
+
+```text
+Token kind
+Token value
+Token metadata
+simple binding
+context predicate
+```
+
+目标：作为编译器前端 / Token Regex 原型。
+
+## Phase 5 — Hierarchical Automata
+
+允许低层自动机输出高层节点，并再次进入更高层自动机。
+
+## Phase 6 — Weighted Automaton
+
+将：
+
+```text
+active : bool
+```
+
+推广为：
+
+```text
+activation : float
+```
+
+先不要急于引入复杂 Tensor。
+
+## Phase 7 — NGRA-Tensor Prototype
+
+研究：
+
+```text
+Node state tensor
+Typed Relation
+Eligibility
+Compatibility
+Transfer
+Blend
+Sparse / block-sparse execution
+```
+
+QKV/Attention 可作为 baseline Relation operator。
+
+---
+
+# 非目标
+
+近期不要优先投入：
+
+```text
+完整 .NET Regex 兼容
+极端 Span<char> 优化
+复杂 Source Generator matcher
+完整 capture rollback
+所有 lookaround/backreference
+为了 Regex 完整性设计核心 IR
+```
+
+这些功能如确实需要，可以：
+
+```text
+System.Text.RegularExpressions
+```
+
+作为字符串兼容层。
+
+这不是架构退让，而是目标调整。
+
+---
+
+# 一句话定位
+
+NGRA 的新定位：
+
+> **以 NFA 为基础的广义序列模式与分层自动机框架，并逐步推广到加权 Relation Network 与 NGRA-Tensor。**
+
+Text Regex：
+
+> 一个兼容前端 / 参考实现，不再定义 NGRA 的核心架构。
+
+NGRA-Tensor：
+
+> 把 Boolean NFA 的多状态传播推广为显式、稀疏、可加权、可训练、可分块执行的 Relation Network。

logo/README.md

@@ -0,0 +1,11 @@
+# nFramework Icon
+
+`nFramework-icon.svg` is the icon-only version of the nFramework mark.
+
+Copyright (c) 2026 Nitload.
+
+The artwork in this directory is licensed under the [Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License (CC BY-NC-ND 4.0)](https://creativecommons.org/licenses/by-nc-nd/4.0/).
+
+You may copy and redistribute the unmodified artwork for noncommercial purposes when you give appropriate credit and link to the license. This license does not permit distributing adaptations, and it does not grant permission for commercial use. Contact the copyright holder for other permissions.
+
+The repository's root MIT License applies to software, not the artwork in this directory. This copyright license does not grant trademark rights in the Nitload or nFramework names or marks, including the former StgSharp name, or imply endorsement.

logo/nFramework-horizontal-dark.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="616" height="104" viewBox="0 0 616 104" role="img" aria-labelledby="title desc">
+  <title id="title">nFramework</title>
+  <desc id="desc">Horizontal nFramework logo with the upright punctuation icon and an IBM Plex Mono Medium wordmark.</desc>
+  <g fill="#59B2DA" transform="translate(13.6 13.6) scale(0.8)"><polygon points="8,8 31,8 31,20 20,20 20,76 31,76 31,88 8,88" /><polygon points="97,8 120,8 120,88 97,88 97,76 108,76 108,20 97,20" /><polygon points="40,16 53,16 53,45 40,45" /><circle cx="80" cy="76" r="8" /></g>
+  <g fill="#E9EEF5"><path d="M146.384 78.524V39.308H154.668V45.996H155.048Q155.656 44.476 156.606 43.07Q157.556 41.664 158.924 40.638Q160.292 39.612 162.116 39.004Q163.94 38.396 166.372 38.396Q172.3 38.396 175.948 42.272Q179.596 46.148 179.596 53.292V78.524H171.312V54.508Q171.312 45.16 163.18 45.16Q161.584 45.16 160.064 45.578Q158.544 45.996 157.328 46.832Q156.112 47.668 155.39 48.96Q154.668 50.252 154.668 51.924V78.524Z"/><path d="M192.136 78.524V25.476H226.26V32.62H200.648V48.048H223.904V55.192H200.648V78.524Z"/><path d="M236.976 71.836H247.388V45.996H236.976V39.308H255.672V49.72H256.128Q256.66 47.668 257.648 45.768Q258.636 43.868 260.156 42.462Q261.676 41.056 263.88 40.182Q266.084 39.308 269.048 39.308H273.76V47.212H266.008Q261.448 47.212 258.56 49.91Q255.672 52.608 255.672 57.168V71.836H269.884V78.524H236.976Z"/><path d="M314.192 78.524Q310.62 78.524 308.834 76.7Q307.048 74.876 306.668 71.912H306.288Q305.148 75.484 302.146 77.46Q299.144 79.436 294.508 79.436Q288.504 79.436 284.932 76.282Q281.36 73.128 281.36 67.58Q281.36 61.88 285.578 58.878Q289.796 55.876 298.536 55.876H306.06V52.836Q306.06 44.856 297.624 44.856Q293.824 44.856 291.468 46.338Q289.112 47.82 287.516 50.252L282.576 46.224Q284.248 43.032 288.2 40.714Q292.152 38.396 298.384 38.396Q305.832 38.396 310.088 41.968Q314.344 45.54 314.344 52.304V71.988H319.284V78.524ZM296.864 73.356Q300.892 73.356 303.476 71.532Q306.06 69.708 306.06 66.82V61.12H298.688Q289.72 61.12 289.72 66.516V68.036Q289.72 70.696 291.62 72.026Q293.52 73.356 296.864 73.356Z"/><path d="M325.744 78.524V39.308H332.812V44.4H333.192Q334.104 41.892 335.814 40.144Q337.524 38.396 340.716 38.396Q343.832 38.396 345.542 40.106Q347.252 41.816 347.708 44.78H348.012Q349.076 42.12 350.976 40.258Q352.876 38.396 356.448 38.396Q361.008 38.396 362.794 41.588Q364.58 44.78 364.58 50.936V78.524H357.512V52Q357.512 47.896 356.524 46.338Q355.536 44.78 353.332 44.78Q351.356 44.78 350.026 46.11Q348.696 47.44 348.696 50.1V78.524H341.628V52Q341.628 47.896 340.678 46.338Q339.728 44.78 337.524 44.78Q335.472 44.78 334.142 46.11Q332.812 47.44 332.812 50.1V78.524Z"/><path d="M391.636 79.436Q387.152 79.436 383.58 77.992Q380.008 76.548 377.576 73.888Q375.144 71.228 373.852 67.466Q372.56 63.704 372.56 58.992Q372.56 54.28 373.89 50.48Q375.22 46.68 377.614 43.982Q380.008 41.284 383.428 39.84Q386.848 38.396 391.028 38.396Q395.132 38.396 398.476 39.802Q401.82 41.208 404.176 43.792Q406.532 46.376 407.786 49.948Q409.04 53.52 409.04 57.852V60.968H380.92V62.26Q380.92 66.896 383.808 69.822Q386.696 72.748 391.788 72.748Q395.588 72.748 398.286 71.114Q400.984 69.48 402.656 66.744L407.824 71.304Q405.848 74.724 401.782 77.08Q397.716 79.436 391.636 79.436ZM391.028 44.704Q388.824 44.704 386.962 45.464Q385.1 46.224 383.77 47.63Q382.44 49.036 381.68 50.936Q380.92 52.836 380.92 55.116V55.648H400.604V54.888Q400.604 50.252 397.982 47.478Q395.36 44.704 391.028 44.704Z"/><path d="M415.12 39.308H422.188L425.988 72.292H426.672L432.524 39.308H440.58L446.356 72.292H447.04L450.916 39.308H457.68L452.208 78.524H442.024L436.78 48.124H436.096L430.776 78.524H420.592Z"/><path d="M482 79.436Q477.668 79.436 474.21 77.992Q470.752 76.548 468.358 73.888Q465.964 71.228 464.672 67.428Q463.38 63.628 463.38 58.916Q463.38 54.204 464.672 50.404Q465.964 46.604 468.358 43.944Q470.752 41.284 474.21 39.84Q477.668 38.396 482 38.396Q486.332 38.396 489.79 39.84Q493.248 41.284 495.642 43.944Q498.036 46.604 499.328 50.404Q500.62 54.204 500.62 58.916Q500.62 63.628 499.328 67.428Q498.036 71.228 495.642 73.888Q493.248 76.548 489.79 77.992Q486.332 79.436 482 79.436ZM482 72.9Q486.56 72.9 489.258 70.126Q491.956 67.352 491.956 61.88V55.952Q491.956 50.48 489.258 47.706Q486.56 44.932 482 44.932Q477.44 44.932 474.742 47.706Q472.044 50.48 472.044 55.952V61.88Q472.044 67.352 474.742 70.126Q477.44 72.9 482 72.9Z"/><path d="M510.576 71.836H520.988V45.996H510.576V39.308H529.272V49.72H529.728Q530.26 47.668 531.248 45.768Q532.236 43.868 533.756 42.462Q535.276 41.056 537.48 40.182Q539.684 39.308 542.648 39.308H547.36V47.212H539.608Q535.048 47.212 532.16 49.91Q529.272 52.608 529.272 57.168V71.836H543.484V78.524H510.576Z"/><path d="M557.088 22.284H565.372V56.256H565.752L571.908 49.948L582.928 39.308H592.732L576.848 54.736L594.48 78.524H584.524L570.844 59.448L565.372 64.54V78.524H557.088Z"/></g>
+</svg>

logo/nFramework-horizontal-light.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="616" height="104" viewBox="0 0 616 104" role="img" aria-labelledby="title desc">
+  <title id="title">nFramework</title>
+  <desc id="desc">Horizontal nFramework logo with the upright punctuation icon and an IBM Plex Mono Medium wordmark.</desc>
+  <g fill="#59B2DA" transform="translate(13.6 13.6) scale(0.8)"><polygon points="8,8 31,8 31,20 20,20 20,76 31,76 31,88 8,88" /><polygon points="97,8 120,8 120,88 97,88 97,76 108,76 108,20 97,20" /><polygon points="40,16 53,16 53,45 40,45" /><circle cx="80" cy="76" r="8" /></g>
+  <g fill="#14202D"><path d="M146.384 78.524V39.308H154.668V45.996H155.048Q155.656 44.476 156.606 43.07Q157.556 41.664 158.924 40.638Q160.292 39.612 162.116 39.004Q163.94 38.396 166.372 38.396Q172.3 38.396 175.948 42.272Q179.596 46.148 179.596 53.292V78.524H171.312V54.508Q171.312 45.16 163.18 45.16Q161.584 45.16 160.064 45.578Q158.544 45.996 157.328 46.832Q156.112 47.668 155.39 48.96Q154.668 50.252 154.668 51.924V78.524Z"/><path d="M192.136 78.524V25.476H226.26V32.62H200.648V48.048H223.904V55.192H200.648V78.524Z"/><path d="M236.976 71.836H247.388V45.996H236.976V39.308H255.672V49.72H256.128Q256.66 47.668 257.648 45.768Q258.636 43.868 260.156 42.462Q261.676 41.056 263.88 40.182Q266.084 39.308 269.048 39.308H273.76V47.212H266.008Q261.448 47.212 258.56 49.91Q255.672 52.608 255.672 57.168V71.836H269.884V78.524H236.976Z"/><path d="M314.192 78.524Q310.62 78.524 308.834 76.7Q307.048 74.876 306.668 71.912H306.288Q305.148 75.484 302.146 77.46Q299.144 79.436 294.508 79.436Q288.504 79.436 284.932 76.282Q281.36 73.128 281.36 67.58Q281.36 61.88 285.578 58.878Q289.796 55.876 298.536 55.876H306.06V52.836Q306.06 44.856 297.624 44.856Q293.824 44.856 291.468 46.338Q289.112 47.82 287.516 50.252L282.576 46.224Q284.248 43.032 288.2 40.714Q292.152 38.396 298.384 38.396Q305.832 38.396 310.088 41.968Q314.344 45.54 314.344 52.304V71.988H319.284V78.524ZM296.864 73.356Q300.892 73.356 303.476 71.532Q306.06 69.708 306.06 66.82V61.12H298.688Q289.72 61.12 289.72 66.516V68.036Q289.72 70.696 291.62 72.026Q293.52 73.356 296.864 73.356Z"/><path d="M325.744 78.524V39.308H332.812V44.4H333.192Q334.104 41.892 335.814 40.144Q337.524 38.396 340.716 38.396Q343.832 38.396 345.542 40.106Q347.252 41.816 347.708 44.78H348.012Q349.076 42.12 350.976 40.258Q352.876 38.396 356.448 38.396Q361.008 38.396 362.794 41.588Q364.58 44.78 364.58 50.936V78.524H357.512V52Q357.512 47.896 356.524 46.338Q355.536 44.78 353.332 44.78Q351.356 44.78 350.026 46.11Q348.696 47.44 348.696 50.1V78.524H341.628V52Q341.628 47.896 340.678 46.338Q339.728 44.78 337.524 44.78Q335.472 44.78 334.142 46.11Q332.812 47.44 332.812 50.1V78.524Z"/><path d="M391.636 79.436Q387.152 79.436 383.58 77.992Q380.008 76.548 377.576 73.888Q375.144 71.228 373.852 67.466Q372.56 63.704 372.56 58.992Q372.56 54.28 373.89 50.48Q375.22 46.68 377.614 43.982Q380.008 41.284 383.428 39.84Q386.848 38.396 391.028 38.396Q395.132 38.396 398.476 39.802Q401.82 41.208 404.176 43.792Q406.532 46.376 407.786 49.948Q409.04 53.52 409.04 57.852V60.968H380.92V62.26Q380.92 66.896 383.808 69.822Q386.696 72.748 391.788 72.748Q395.588 72.748 398.286 71.114Q400.984 69.48 402.656 66.744L407.824 71.304Q405.848 74.724 401.782 77.08Q397.716 79.436 391.636 79.436ZM391.028 44.704Q388.824 44.704 386.962 45.464Q385.1 46.224 383.77 47.63Q382.44 49.036 381.68 50.936Q380.92 52.836 380.92 55.116V55.648H400.604V54.888Q400.604 50.252 397.982 47.478Q395.36 44.704 391.028 44.704Z"/><path d="M415.12 39.308H422.188L425.988 72.292H426.672L432.524 39.308H440.58L446.356 72.292H447.04L450.916 39.308H457.68L452.208 78.524H442.024L436.78 48.124H436.096L430.776 78.524H420.592Z"/><path d="M482 79.436Q477.668 79.436 474.21 77.992Q470.752 76.548 468.358 73.888Q465.964 71.228 464.672 67.428Q463.38 63.628 463.38 58.916Q463.38 54.204 464.672 50.404Q465.964 46.604 468.358 43.944Q470.752 41.284 474.21 39.84Q477.668 38.396 482 38.396Q486.332 38.396 489.79 39.84Q493.248 41.284 495.642 43.944Q498.036 46.604 499.328 50.404Q500.62 54.204 500.62 58.916Q500.62 63.628 499.328 67.428Q498.036 71.228 495.642 73.888Q493.248 76.548 489.79 77.992Q486.332 79.436 482 79.436ZM482 72.9Q486.56 72.9 489.258 70.126Q491.956 67.352 491.956 61.88V55.952Q491.956 50.48 489.258 47.706Q486.56 44.932 482 44.932Q477.44 44.932 474.742 47.706Q472.044 50.48 472.044 55.952V61.88Q472.044 67.352 474.742 70.126Q477.44 72.9 482 72.9Z"/><path d="M510.576 71.836H520.988V45.996H510.576V39.308H529.272V49.72H529.728Q530.26 47.668 531.248 45.768Q532.236 43.868 533.756 42.462Q535.276 41.056 537.48 40.182Q539.684 39.308 542.648 39.308H547.36V47.212H539.608Q535.048 47.212 532.16 49.91Q529.272 52.608 529.272 57.168V71.836H543.484V78.524H510.576Z"/><path d="M557.088 22.284H565.372V56.256H565.752L571.908 49.948L582.928 39.308H592.732L576.848 54.736L594.48 78.524H584.524L570.844 59.448L565.372 64.54V78.524H557.088Z"/></g>
+</svg>

logo/nFramework-icon.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="104" viewBox="0 0 128 104" role="img" aria-labelledby="title desc">
+  <title id="title">nFramework icon</title>
+  <desc id="desc">The geometric nFramework mark, with a diagonal slash suggesting an N.</desc>
+  <metadata>Copyright (c) 2026 Nitload. Licensed under CC BY-NC-ND 4.0: https://creativecommons.org/licenses/by-nc-nd/4.0/</metadata>
+  <g fill="#59B2DA" transform="translate(13.6 13.6) scale(0.8)">
+    <polygon points="8,8 31,8 31,20 20,20 20,76 31,76 31,88 8,88" />
+    <polygon points="97,8 120,8 120,88 97,88 97,76 108,76 108,20 97,20" />
+    <polygon points="40,16 53,16 53,45 40,45" />
+    <circle cx="80" cy="76" r="8" />
+  </g>
+</svg>

src/Nitload.Benchmark/Program.cs

@@ -9,16 +9,23 @@ using BenchmarkDotNet.Configs;
 using BenchmarkDotNet.Jobs;
 using BenchmarkDotNet.Loggers;
 using BenchmarkDotNet.Running;
-using BenchmarkDotNet.Toolchains.InProcess.Emit;
 using Nitload.Benchmark;
 
+if (args.Length > 0 && args[0] == "--disasm-swiss")
+{
+    IConfig disassemblyConfig = ManualConfig.Create(DefaultConfig.Instance)
+                                               .AddLogger(ConsoleLogger.Default)
+                                               .AddJob(Job.ShortRun.WithWarmupCount(6));
+    BenchmarkRunner.Run<SwissX86DisassemblyBench>(disassemblyConfig);
+    return;
+}
+
 IConfig config = ManualConfig.Create(DefaultConfig.Instance)
                              .AddLogger(ConsoleLogger.Default)
                              .AddJob(Job.Default
-                                        .WithToolchain(InProcessEmitToolchain.Instance)
                                         .WithLaunchCount(1)
                                         .WithWarmupCount(6)
                                         .WithIterationCount(15)
                                         .WithInvocationCount(3)
                                         .WithUnrollFactor(1));
-_ = BenchmarkRunner.Run<TlsfAllocatorBench>(config);
+BenchmarkSwitcher.FromAssembly(typeof(TlsfAllocatorBench).Assembly).Run(args, config);

src/Nitload.Benchmark/SwissBenchmark.cs

@@ -1,485 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="SwissBenchmark"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-using BenchmarkDotNet.Attributes;
-using Nitload.Common.Collections;
-using System;
-using System.Collections.Generic;
-using System.Runtime.CompilerServices;
-
-namespace Nitload.Benchmark
-{
-    /// <summary>
-    ///   Benchmark comparing SwissTable against <see cref="Dictionary{TKey, TValue}" /> under
-    ///   realistic L4 software cache address-mapping workloads. <para>///   L4 scenario
-    ///   characteristics: ///   - Keys are HLSF/malloc pointer addresses (large, 1024-byte aligned)
-    ///   ///   - Access pattern is Zipfian-skewed (20% hot cache lines receive 80% of lookups) /// 
-    ///   - Steady state: high hit-rate lookups dominate, with rare evict+refill on miss ///   -
-    ///   Working set: 512–4096 active cache line mappings /// </para>
-    /// </summary>
-    [MemoryDiagnoser]
-    public class SwissTableBench
-    {
-
-        /// <summary>
-        ///   L4 cache line size in bytes (per L4_design.md).
-        /// </summary>
-        private const int CacheLineSize = 1024;
-
-        /// <summary>
-        ///   Simulated heap base address for pointer-like keys.
-        /// </summary>
-        private const long HeapBase = 0x7FFF_0000_0000L;
-
-        /// <summary>
-        ///   Number of lookup operations per Lookup benchmark call.
-        /// </summary>
-        private const int LookupIterations = 8192;
-
-        /// <summary>
-        ///   Fraction of steady-state ops that are cache misses.
-        /// </summary>
-        private const double MissRate = 0.05;
-
-        /// <summary>
-        ///   Number of steady-state operations per call. Each op is either a lookup (hit) or an
-        ///   evict+insert+lookup (miss).
-        /// </summary>
-        private const int SteadyStateOps = 4096;
-
-        /// <summary>
-        ///   Indices into _residentKeys for eviction targets (cold entries, tail region).
-        /// </summary>
-        private int[] _evictOrder = null!;
-
-        /// <summary>
-        ///   Additional keys not in the table, for triggering misses.
-        /// </summary>
-        private nuint[] _externalKeys = null!;
-
-        // ── Pre-generated key arrays (pointer-like, 1024-byte aligned) ──
-
-        /// <summary>
-        ///   Keys for initial table fill (simulates cached addresses).
-        /// </summary>
-        private nuint[] _residentKeys = null!;
-
-        /// <summary>
-        ///   Pre-built steady-state operation script. Each entry: positive index → lookup
-        ///   _residentKeys[idx], negative value → cache miss trigger (evict + insert from
-        ///   _externalKeys).
-        /// </summary>
-        private int[] _steadyStateScript = null!;
-
-        /// <summary>
-        ///   Uniform random lookup sequence (baseline comparison).
-        /// </summary>
-        private nuint[] _uniformLookups = null!;
-
-        /// <summary>
-        ///   Zipfian-skewed lookup sequence (hot 20% accessed 80% of time).
-        /// </summary>
-        private nuint[] _zipfianLookups = null!;
-        private Dictionary<nuint, nuint> _dictLookup = null!;
-        private Dictionary<nuint, nuint> _freshDict = null!;
-
-        // ── Fresh instances for insert/mixed (rebuilt each iteration) ──
-
-        private SwissTable _freshSwiss = null!;
-
-        // ── Pre-filled lookup targets ──
-
-        private SwissTable _swissLookup = null!;
-
-        /// <summary>
-        ///   Active cache line count. Matches L4 capacity range: 5 MB / 1024B ≈ 5120,  10 MB /
-        ///   1024B ≈ 10240. 512 and 1024 test low-occupancy; 4096 tests near-capacity.
-        /// </summary>
-        [Params(512, 1024, 4096)]
-        public int KeyCount;
-
-        [GlobalCleanup]
-        public void Cleanup()
-        {
-            _dictLookup.Clear();
-            _dictLookup.TrimExcess();
-        }
-
-        // ════════════════════════════════════════════════════════════
-        // Insert — bulk fill with scattered pointer addresses
-        // Simulates L4 initial cache warm-up phase.
-        // ════════════════════════════════════════════════════════════
-
-        [Benchmark]
-        public void Dictionary_Insert()
-        {
-            Dictionary<nuint, nuint> dict = _freshDict;
-            nuint[] keys = _residentKeys;
-            for (int i = 0; i < keys.Length; i++) {
-                dict[keys[i]] = keys[i] ^ unchecked((nuint)0xDEAD_BEEF);
-            }
-        }
-
-        // ════════════════════════════════════════════════════════════
-        // Lookup — Uniform (baseline comparison)
-        // ════════════════════════════════════════════════════════════
-
-        [Benchmark]
-        public nuint Dictionary_Lookup_Uniform()
-        {
-            nuint sum = 0;
-            nuint[] keys = _uniformLookups;
-            Dictionary<nuint, nuint> dict = _dictLookup;
-            for (int i = 0; i < keys.Length; i++)
-            {
-                if (dict.TryGetValue(keys[i], out nuint value)) {
-                    sum += value;
-                }
-            }
-            return sum;
-        }
-
-        // ════════════════════════════════════════════════════════════
-        // Lookup — Zipfian (L4 hot path, skewed access)
-        // 20% of cache lines receive 80% of accesses.
-        // This is the most representative L4 benchmark.
-        // ════════════════════════════════════════════════════════════
-
-        [Benchmark(Baseline = true)]
-        public nuint Dictionary_Lookup_Zipfian()
-        {
-            nuint sum = 0;
-            nuint[] keys = _zipfianLookups;
-            Dictionary<nuint, nuint> dict = _dictLookup;
-            for (int i = 0; i < keys.Length; i++)
-            {
-                if (dict.TryGetValue(keys[i], out nuint value)) {
-                    sum += value;
-                }
-            }
-            return sum;
-        }
-
-        // ════════════════════════════════════════════════════════════
-        // SteadyState — the KEY L4 benchmark
-        // Pre-filled table at capacity, then 4096 operations:
-        // ~95% are lookups (cache hits)
-        // ~5%  are miss → evict cold entry → insert new entry → lookup new
-        // This directly simulates L4's main runtime loop.
-        // ════════════════════════════════════════════════════════════
-
-        [Benchmark]
-        public nuint Dictionary_SteadyState()
-        {
-            nuint sum = 0;
-            Dictionary<nuint, nuint> dict = _freshDict;
-            nuint[] resident = _residentKeys;
-            nuint[] external = _externalKeys;
-            int[] script = _steadyStateScript;
-            int[] evict = _evictOrder;
-            int evictCursor = 0;
-            int externalCursor = 0;
-
-            for (int i = 0; i < script.Length; i++)
-            {
-                int op = script[i];
-                if (op >= 0)
-                {
-                    // Cache hit: lookup existing entry
-                    if (dict.TryGetValue(resident[op], out nuint value))
-                    {
-                        sum += value;
-                    }
-                } else
-                {
-                    // Cache miss: evict a cold entry, insert a new one, then lookup
-                    int evictIdx = evict[evictCursor % evict.Length];
-                    evictCursor++;
-                    dict.Remove(resident[evictIdx]);
-
-                    int extIdx = externalCursor % external.Length;
-                    externalCursor++;
-                    nuint newKey = external[extIdx];
-                    nuint newVal = newKey ^ unchecked((nuint)0xDEAD_BEEF);
-                    dict[newKey] = newVal;
-
-                    if (dict.TryGetValue(newKey, out nuint v)) {
-                        sum += v;
-                    }
-                }
-            }
-            return sum;
-        }
-
-        [IterationSetup(Targets = [
-            nameof(SwissTable_Insert),
-            nameof(SwissTable_SteadyState),
-            nameof(Dictionary_Insert),
-            nameof(Dictionary_SteadyState)
-        ])]
-        public void IterationSetup()
-        {
-            _freshSwiss = SwissTable.Create();
-            _freshDict = new Dictionary<nuint, nuint>(KeyCount);
-
-            // Pre-fill for steady-state benchmarks
-            for (int i = 0; i < KeyCount; i++)
-            {
-                nuint key = _residentKeys[i];
-                nuint val = key ^ unchecked((nuint)0xDEAD_BEEF);
-                _freshSwiss.TryAddOrSet(key, val, out _);
-                _freshDict[key] = val;
-            }
-        }
-
-        // ════════════════════════════════════════════════════════════
-        // Setup / Teardown
-        // ════════════════════════════════════════════════════════════
-
-        [GlobalSetup]
-        public void Setup()
-        {
-            Random rng = new Random(42);
-
-            // ── Generate pointer-like keys (HeapBase + random_offset * 1024) ──
-            _residentKeys = GeneratePointerKeys(KeyCount, rng);
-            _externalKeys = GeneratePointerKeys(KeyCount, rng); // disjoint set for miss simulation
-
-            // ── Build lookup sequences ──
-            _zipfianLookups = GenerateZipfianLookups(_residentKeys, LookupIterations, rng);
-            _uniformLookups = GenerateUniformLookups(_residentKeys, LookupIterations, rng);
-
-            // ── Build steady-state operation script ──
-            _steadyStateScript = GenerateSteadyStateScript(KeyCount, SteadyStateOps, MissRate, rng);
-
-            // ── Build eviction order (cold tail entries first) ──
-            _evictOrder = new int[KeyCount];
-            for (int i = 0; i < KeyCount; i++) {
-                _evictOrder[i] = i;
-            }
-
-            // Shuffle so eviction isn't just sequential
-            Shuffle(_evictOrder, rng);
-
-            // ── Pre-fill lookup tables ──
-            _swissLookup = SwissTable.Create();
-            _dictLookup = new Dictionary<nuint, nuint>(KeyCount);
-
-            for (int i = 0; i < KeyCount; i++)
-            {
-                nuint key = _residentKeys[i];
-                nuint val = key ^ unchecked((nuint)0xDEAD_BEEF); // simulated cache pointer
-                _swissLookup.TryAddOrSet(key, val, out _);
-                _dictLookup[key] = val;
-            }
-        }
-
-        [Benchmark]
-        public void SwissTable_Insert()
-        {
-            SwissTable swiss = _freshSwiss;
-            nuint[] keys = _residentKeys;
-            for (int i = 0; i < keys.Length; i++) {
-                swiss.TryAddOrSet(keys[i], keys[i] ^ unchecked((nuint)0xDEAD_BEEF), out _);
-            }
-        }
-
-        [Benchmark]
-        public nuint SwissTable_Lookup_Uniform()
-        {
-            nuint sum = 0;
-            nuint[] keys = _uniformLookups;
-            SwissTable swiss = _swissLookup;
-            for (int i = 0; i < keys.Length; i++)
-            {
-                if (swiss.TryGet(keys[i], out nuint value)) {
-                    sum += value;
-                }
-            }
-            return sum;
-        }
-
-        [Benchmark]
-        public nuint SwissTable_Lookup_Zipfian()
-        {
-            nuint sum = 0;
-            nuint[] keys = _zipfianLookups;
-            SwissTable swiss = _swissLookup;
-            for (int i = 0; i < keys.Length; i++)
-            {
-                if (swiss.TryGet(keys[i], out nuint value)) {
-                    sum += value;
-                }
-            }
-            return sum;
-        }
-
-        [Benchmark]
-        public nuint SwissTable_SteadyState()
-        {
-            nuint sum = 0;
-            SwissTable swiss = _freshSwiss;
-            nuint[] resident = _residentKeys;
-            nuint[] external = _externalKeys;
-            int[] script = _steadyStateScript;
-            int[] evict = _evictOrder;
-            int evictCursor = 0;
-            int externalCursor = 0;
-
-            for (int i = 0; i < script.Length; i++)
-            {
-                int op = script[i];
-                if (op >= 0)
-                {
-                    // Cache hit: lookup existing entry
-                    if (swiss.TryGet(resident[op], out nuint value))
-                    {
-                        sum += value;
-                    }
-                } else
-                {
-                    // Cache miss: evict a cold entry, insert a new one, then lookup
-                    int evictIdx = evict[evictCursor % evict.Length];
-                    evictCursor++;
-                    swiss.TryRemove(resident[evictIdx], out _);
-
-                    int extIdx = externalCursor % external.Length;
-                    externalCursor++;
-                    nuint newKey = external[extIdx];
-                    nuint newVal = newKey ^ unchecked((nuint)0xDEAD_BEEF);
-                    swiss.TryAddOrSet(newKey, newVal, out _);
-
-                    if (swiss.TryGet(newKey, out nuint v)) {
-                        sum += v;
-                    }
-                }
-            }
-            return sum;
-        }
-
-        // ════════════════════════════════════════════════════════════
-        // Data generation helpers
-        // ════════════════════════════════════════════════════════════
-
-        /// <summary>
-        ///   Generate <paramref name="count" /> unique pointer-like keys. Each key = HeapBase +
-        ///   randomOffset * CacheLineSize, simulating HLSF-allocated 1024-byte aligned addresses
-        ///   scattered across a ~1 GB virtual address range.
-        /// </summary>
-        private static nuint[] GeneratePointerKeys(
-                               int count,
-                               Random rng
-        )
-        {
-            nuint[] keys = new nuint[count];
-            HashSet<long> used = new HashSet<long>(count);
-            for (int i = 0; i < count; i++)
-            {
-                long offset;
-                do
-                {
-                    // Random offset within ~1M cache lines (1 GB range)
-                    offset = (long)rng.Next(0, 1 << 20) * CacheLineSize;
-                } while (!used.Add(offset));
-                keys[i] = (nuint)(HeapBase + offset);
-            }
-            return keys;
-        }
-
-        /// <summary>
-        ///   Generate a steady-state operation script. Each entry: non-negative value = index into
-        ///   _residentKeys (lookup/hit), negative value (-1) = cache miss trigger (evict → insert →
-        ///   lookup). Lookup indices are Zipfian-skewed.
-        /// </summary>
-        private static int[] GenerateSteadyStateScript(
-                             int keyCount,
-                             int opCount,
-                             double missRate,
-                             Random rng
-        )
-        {
-            int hotSetSize = Math.Max(1, keyCount / 5);
-            int[] script = new int[opCount];
-            for (int i = 0; i < opCount; i++)
-            {
-                if (rng.NextDouble() < missRate)
-                {
-                    script[i] = -1; // miss
-                } else
-                {
-                    // Zipfian hit
-                    if (rng.NextDouble() < 0.8)
-                    {
-                        script[i] = rng.Next(0, hotSetSize);
-                    } else
-                    {
-                        script[i] = rng.Next(hotSetSize, keyCount);
-                    }
-                }
-            }
-            return script;
-        }
-
-        /// <summary>
-        ///   Generate uniform random lookup sequence (baseline for comparison with Zipfian).
-        /// </summary>
-        private static nuint[] GenerateUniformLookups(
-                               nuint[] sourceKeys,
-                               int count,
-                               Random rng
-        )
-        {
-            nuint[] lookups = new nuint[count];
-            for (int i = 0; i < count; i++) {
-                lookups[i] = sourceKeys[rng.Next(0, sourceKeys.Length)];
-            }
-            return lookups;
-        }
-
-        /// <summary>
-        ///   Generate Zipfian-skewed lookup sequence: 80% of accesses hit the hottest 20% of keys
-        ///   (sorted by index as "hotness proxy"), 20% of accesses hit the remaining 80%. This
-        ///   models matrix computation where a small panel working set is reused heavily.
-        /// </summary>
-        private static nuint[] GenerateZipfianLookups(
-                               nuint[] sourceKeys,
-                               int count,
-                               Random rng
-        )
-        {
-            int hotSetSize = Math.Max(1, sourceKeys.Length / 5);
-            nuint[] lookups = new nuint[count];
-            for (int i = 0; i < count; i++)
-            {
-                if (rng.NextDouble() < 0.8)
-                {
-                    lookups[i] = sourceKeys[rng.Next(0, hotSetSize)];
-                } else
-                {
-                    lookups[i] = sourceKeys[rng.Next(hotSetSize, sourceKeys.Length)];
-                }
-            }
-            return lookups;
-        }
-
-        /// <summary>
-        ///   Fisher-Yates shuffle.
-        /// </summary>
-        private static void Shuffle(
-                            int[] array,
-                            Random rng
-        )
-        {
-            for (int i = array.Length - 1; i > 0; i--)
-            {
-                int j = rng.Next(0, i + 1);
-                (array[i], array[j]) = (array[j], array[i]);
-            }
-        }
-
-    }
-}

src/Nitload.Benchmark/SwissX86Bench.cs

@@ -0,0 +1,306 @@
+// -----------------------------------------------------------------------------
+// file="SwissX86Bench"
+// Project: nFramework
+// Copyright (c) Nitload.
+// SPDX-License-Identifier: MIT
+// -----------------------------------------------------------------------------
+
+using BenchmarkDotNet.Attributes;
+using BenchmarkDotNet.Configs;
+using Nitload.Common.HighPerformance.Memory;
+using System;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Runtime.InteropServices;
+using System.Runtime.Intrinsics.X86;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Nitload.Benchmark
+{
+    [MemoryDiagnoser]
+    [GroupBenchmarksBy(BenchmarkLogicalGroupRule.ByCategory)]
+    [CategoriesColumn]
+    public unsafe class SwissX86Bench
+    {
+
+        private const int QueryCount = 1 << 21;
+        private const int ConcurrentQueryCount = QueryCount * 6;
+        private const int MaximumResidentCount = 8192;
+
+        private byte* _buffer;
+        private L4.SwissTable _swiss;
+        private Dictionary<L4.AddressSource, ulong> _dictionary = null!;
+        private ConcurrentDictionary<L4.AddressSource, ulong> _concurrentDictionary = null!;
+        private L4.AddressSource[] _hitQueries = [];
+        private L4.AddressSource[] _missQueries = [];
+        private L4.AddressSource[] _writerQueries = [];
+        private ulong[] _writerValues = [];
+        private byte* _readBuffer;
+        private byte* _writeBuffer;
+        private ParallelOptions _parallelOptions = null!;
+        private Func<ulong> _parallelLocalInit = null!;
+        private Func<int, ParallelLoopState, ulong, ulong> _swissParallelBody = null!;
+        private Func<int, ParallelLoopState, ulong, ulong> _concurrentDictionaryParallelBody = null!;
+        private Action<ulong> _parallelLocalFinally = null!;
+        private long _parallelChecksum;
+
+        [Params(25, 50, 100)]
+        public int LoadPercent { get; set; }
+
+        private int ResidentCount => MaximumResidentCount * LoadPercent / 100;
+
+        [GlobalSetup]
+        public void Setup()
+        {
+            if (!Sse42.X64.IsSupported)
+                throw new PlatformNotSupportedException("The Swiss X86 benchmark requires x64 SSE4.2.");
+
+            _buffer = (byte*)NativeMemory.AlignedAlloc((nuint)L4.BufferSize, 64);
+            if (_buffer == null)
+                throw new OutOfMemoryException("Could not allocate Swiss benchmark tables.");
+
+            _swiss = L4.SwissTable.Create(_buffer);
+            _dictionary = new Dictionary<L4.AddressSource, ulong>(ResidentCount);
+            _concurrentDictionary = new ConcurrentDictionary<L4.AddressSource, ulong>(
+                Math.Max(1, Math.Min(Environment.ProcessorCount, 8)),
+                ResidentCount);
+
+            L4.AddressSource[] residentKeys = new L4.AddressSource[ResidentCount];
+            for (int i = 0; i < ResidentCount; i++)
+            {
+                L4.AddressSource key = MakeKey(i);
+                ulong value = (ulong)i + 1;
+                residentKeys[i] = key;
+                if (!_swiss.TryAddOrSet(key, value))
+                    throw new InvalidOperationException($"Swiss insertion failed while seeding key {i}.");
+                _dictionary.Add(key, value);
+                _concurrentDictionary.TryAdd(key, value);
+            }
+
+            _swiss.SwapBuffers();
+            for (int i = 0; i < ResidentCount; i++)
+            {
+                if (!_swiss.TryAddOrSet(residentKeys[i], (ulong)i + 1))
+                    throw new InvalidOperationException($"Swiss writer-buffer seeding failed for key {i}.");
+            }
+
+            _readBuffer = _swiss.ReadBufferForLockFreeBenchmark;
+            _writeBuffer = _swiss.WriteBufferForLockFreeBenchmark;
+
+            _hitQueries = new L4.AddressSource[QueryCount];
+            _missQueries = new L4.AddressSource[QueryCount];
+            _writerQueries = new L4.AddressSource[QueryCount];
+            _writerValues = new ulong[QueryCount];
+            Random random = new(0x51_15_2026);
+            for (int i = 0; i < QueryCount; i++)
+            {
+                _hitQueries[i] = residentKeys[random.Next(ResidentCount)];
+                _missQueries[i] = MakeKey(MaximumResidentCount + i);
+                _writerQueries[i] = residentKeys[random.Next(ResidentCount)];
+                _writerValues[i] = (ulong)i + 0x10000;
+            }
+
+            _parallelOptions = new ParallelOptions
+            {
+                MaxDegreeOfParallelism = Math.Max(2, Math.Min(Environment.ProcessorCount, 8))
+            };
+            _parallelLocalInit = static() => 0UL;
+            _swissParallelBody = ReadSwissParallel;
+            _concurrentDictionaryParallelBody = ReadConcurrentDictionaryParallel;
+            _parallelLocalFinally = MergeParallelChecksum;
+
+            ValidateLookupResults();
+        }
+
+        [GlobalCleanup]
+        public void Cleanup()
+        {
+            _swiss.Dispose();
+            NativeMemory.AlignedFree(_buffer);
+            _buffer = null;
+        }
+
+        [Benchmark(Baseline = true, OperationsPerInvoke = QueryCount)]
+        [BenchmarkCategory("Hit lookup")]
+        public ulong DictionaryHitLookup()
+        {
+            ulong checksum = 0;
+            for (int i = 0; i < QueryCount; i++)
+                checksum += _dictionary[_hitQueries[i]];
+            return checksum;
+        }
+
+        [Benchmark(OperationsPerInvoke = QueryCount)]
+        [BenchmarkCategory("Hit lookup")]
+        public ulong SwissLockFreeHitLookup()
+        {
+            ulong checksum = 0;
+            for (int i = 0; i < QueryCount; i++)
+            {
+                if (!L4.SwissReaderX86.TryGet(_readBuffer, _hitQueries[i], out ulong value))
+                    throw new InvalidOperationException("Swiss table missed a seeded hit key.");
+                checksum += value;
+            }
+            return checksum;
+        }
+
+        [Benchmark(Baseline = true, OperationsPerInvoke = QueryCount)]
+        [BenchmarkCategory("Miss lookup")]
+        public int DictionaryMissLookup()
+        {
+            int misses = 0;
+            for (int i = 0; i < QueryCount; i++)
+                misses += _dictionary.TryGetValue(_missQueries[i], out _) ? 0 : 1;
+            return misses;
+        }
+
+        [Benchmark(OperationsPerInvoke = QueryCount)]
+        [BenchmarkCategory("Miss lookup")]
+        public int SwissLockFreeMissLookup()
+        {
+            int misses = 0;
+            for (int i = 0; i < QueryCount; i++)
+                misses += L4.SwissReaderX86.TryGet(_readBuffer, _missQueries[i], out _) ? 0 : 1;
+            return misses;
+        }
+
+        [Benchmark(Baseline = true, OperationsPerInvoke = ConcurrentQueryCount)]
+        [BenchmarkCategory("Concurrent hit lookup")]
+        public ulong ConcurrentDictionaryConcurrentHitLookup()
+        {
+            Interlocked.Exchange(ref _parallelChecksum, 0);
+            Parallel.For(
+                0,
+            ConcurrentQueryCount,
+                _parallelOptions,
+                _parallelLocalInit,
+                _concurrentDictionaryParallelBody,
+                _parallelLocalFinally);
+            return unchecked((ulong)Interlocked.Read(ref _parallelChecksum));
+        }
+
+        [Benchmark(OperationsPerInvoke = ConcurrentQueryCount)]
+        [BenchmarkCategory("Concurrent hit lookup")]
+        public ulong SwissLockFreeConcurrentHitLookup()
+        {
+            Interlocked.Exchange(ref _parallelChecksum, 0);
+            Parallel.For(
+                0,
+            ConcurrentQueryCount,
+                _parallelOptions,
+                _parallelLocalInit,
+                _swissParallelBody,
+                _parallelLocalFinally);
+            return unchecked((ulong)Interlocked.Read(ref _parallelChecksum));
+        }
+
+        [Benchmark(Baseline = true, OperationsPerInvoke = QueryCount)]
+        [BenchmarkCategory("Upsert existing")]
+        public ulong DictionaryUpsertExisting()
+        {
+            for (int i = 0; i < QueryCount; i++)
+                _dictionary[_writerQueries[i]] = _writerValues[i];
+            return _dictionary[_writerQueries[^1]];
+        }
+
+        [Benchmark(OperationsPerInvoke = QueryCount)]
+        [BenchmarkCategory("Upsert existing")]
+        public ulong SwissUpsertExisting()
+        {
+            ulong failures = 0;
+            for (int i = 0; i < QueryCount; i++)
+                failures += L4.SwissWriterX86.TryAddOrSet(_writeBuffer, _writerQueries[i], _writerValues[i]) ? 0UL : 1UL;
+            if (failures != 0 || !L4.SwissReaderX86.TryGet(_writeBuffer, _writerQueries[^1], out ulong value))
+                throw new InvalidOperationException("Swiss upsert failed to preserve the final value.");
+            return value;
+        }
+
+        [Benchmark(Baseline = true, OperationsPerInvoke = QueryCount)]
+        [BenchmarkCategory("Remove and reinsert")]
+        public ulong DictionaryRemoveAndReinsert()
+        {
+            ulong checksum = 0;
+            for (int i = 0; i < QueryCount; i++)
+            {
+                L4.AddressSource key = _writerQueries[i];
+                ulong value = _dictionary[key];
+                _dictionary.Remove(key);
+                _dictionary.Add(key, value + 1);
+                checksum += value;
+            }
+            return checksum;
+        }
+
+        [Benchmark(OperationsPerInvoke = QueryCount)]
+        [BenchmarkCategory("Remove and reinsert")]
+        public ulong SwissRemoveAndReinsert()
+        {
+            ulong checksum = 0;
+            for (int i = 0; i < QueryCount; i++)
+            {
+                L4.AddressSource key = _writerQueries[i];
+                if (!L4.SwissWriterX86.TryRemove(_writeBuffer, key, out ulong value) ||
+                    !L4.SwissWriterX86.TryAddOrSet(_writeBuffer, key, value + 1)) {
+                    throw new InvalidOperationException("Swiss remove/reinsert failed.");
+                }
+                checksum += value;
+            }
+            return checksum;
+        }
+
+        private static L4.AddressSource MakeKey(int index)
+        {
+            return new L4.AddressSource
+            {
+                Address = 0x1000_0000UL + ((ulong)index * 64UL),
+                Description = ((ulong)index * 0x9e37_79b9UL) ^ 0xd1b5_4a32_d192_ed03UL
+            };
+        }
+
+        private ulong ReadSwissParallel(int index, ParallelLoopState state, ulong checksum)
+        {
+            int queryIndex = index & (QueryCount - 1);
+            if (!L4.SwissReaderX86.TryGet(_readBuffer, _hitQueries[queryIndex], out ulong value))
+                throw new InvalidOperationException("Swiss table missed a seeded concurrent hit key.");
+            return checksum + value;
+        }
+
+        private ulong ReadConcurrentDictionaryParallel(int index, ParallelLoopState state, ulong checksum)
+        {
+            int queryIndex = index & (QueryCount - 1);
+            if (!_concurrentDictionary.TryGetValue(_hitQueries[queryIndex], out ulong value))
+                throw new InvalidOperationException("ConcurrentDictionary missed a seeded hit key.");
+            return checksum + value;
+        }
+
+        private void MergeParallelChecksum(ulong checksum)
+        {
+            _ = Interlocked.Add(ref _parallelChecksum, unchecked((long)checksum));
+        }
+
+        private void ValidateLookupResults()
+        {
+            for (int i = 0; i < _hitQueries.Length; i++)
+            {
+                bool dictionaryFound = _dictionary.TryGetValue(_hitQueries[i], out ulong dictionaryValue);
+                bool swissFound = L4.SwissReaderX86.TryGet(_readBuffer, _hitQueries[i], out ulong swissValue);
+                if (!dictionaryFound || !swissFound || dictionaryValue != swissValue)
+                    throw new InvalidOperationException("Swiss and Dictionary hit results differ.");
+
+                if (!_concurrentDictionary.TryGetValue(_hitQueries[i], out ulong concurrentValue) ||
+                    concurrentValue != dictionaryValue)
+                    throw new InvalidOperationException("ConcurrentDictionary and Dictionary hit results differ.");
+            }
+
+            for (int i = 0; i < _missQueries.Length; i++)
+            {
+                bool dictionaryFound = _dictionary.TryGetValue(_missQueries[i], out _);
+                bool swissFound = L4.SwissReaderX86.TryGet(_readBuffer, _missQueries[i], out _);
+                if (dictionaryFound || swissFound)
+                    throw new InvalidOperationException("Swiss and Dictionary miss results differ.");
+            }
+        }
+
+    }
+}

src/Nitload.Benchmark/SwissX86DisassemblyBench.cs

@@ -0,0 +1,135 @@
+// -----------------------------------------------------------------------------
+// file="SwissX86DisassemblyBench"
+// Project: nFramework
+// Copyright (c) Nitload.
+// SPDX-License-Identifier: MIT
+// -----------------------------------------------------------------------------
+
+using BenchmarkDotNet.Attributes;
+using BenchmarkDotNet.Diagnosers;
+using Nitload.Common.HighPerformance.Memory;
+using System;
+using System.Runtime.InteropServices;
+using System.Runtime.Intrinsics.X86;
+
+namespace Nitload.Benchmark
+{
+    [DisassemblyDiagnoser(maxDepth: 3, exportHtml: true)]
+    public unsafe class SwissX86DisassemblyBench
+    {
+
+        private const int ResidentCount = 8192;
+
+        private byte* _buffer;
+        private L4.SwissTable _table;
+        private byte* _readBuffer;
+        private byte* _writeBuffer;
+        private L4.AddressSource _hitKey;
+        private L4.AddressSource _missKey;
+        private ulong _value;
+
+        [GlobalSetup]
+        public void Setup()
+        {
+            if (!Sse42.X64.IsSupported)
+                throw new PlatformNotSupportedException("The Swiss X86 disassembly probe requires x64 SSE4.2.");
+
+            _buffer = (byte*)NativeMemory.AlignedAlloc((nuint)L4.BufferSize, 64);
+            if (_buffer == null)
+                throw new OutOfMemoryException("Could not allocate Swiss disassembly buffers.");
+
+            _table = L4.SwissTable.Create(_buffer);
+            for (int index = 0; index < ResidentCount; index++)
+            {
+                if (!L4.SwissWriterX86.TryAddOrSet(_table.WriteBufferForLockFreeBenchmark,
+                                                   MakeKey(index), (ulong)index + 1))
+                    throw new InvalidOperationException($"Failed to seed Swiss key {index}.");
+            }
+
+            _table.SwapBuffers();
+            _readBuffer = _table.ReadBufferForLockFreeBenchmark;
+            _writeBuffer = _table.WriteBufferForLockFreeBenchmark;
+            for (int index = 0; index < ResidentCount; index++)
+            {
+                if (!L4.SwissWriterX86.TryAddOrSet(_writeBuffer, MakeKey(index), (ulong)index + 1))
+                    throw new InvalidOperationException($"Failed to seed inactive Swiss key {index}.");
+            }
+
+            _hitKey = MakeKey(ResidentCount / 2);
+            _missKey = MakeKey(ResidentCount + 1);
+            _value = 0x1234_5678;
+
+            if (!L4.SwissReaderX86.TryGet(_readBuffer, _hitKey, out _) ||
+                L4.SwissReaderX86.TryGet(_readBuffer, _missKey, out _))
+                throw new InvalidOperationException("Swiss reader setup validation failed.");
+        }
+
+        [GlobalCleanup]
+        public void Cleanup()
+        {
+            _table.Dispose();
+            NativeMemory.AlignedFree(_buffer);
+            _buffer = null;
+        }
+
+        [Benchmark]
+        public bool RawReaderHit()
+        {
+            return L4.SwissReaderX86.TryGet(_readBuffer, _hitKey, out _value);
+        }
+
+        [Benchmark]
+        public bool RawReaderMiss()
+        {
+            return L4.SwissReaderX86.TryGet(_readBuffer, _missKey, out _value);
+        }
+
+        [Benchmark]
+        public bool RawWriterUpsertExisting()
+        {
+            return L4.SwissWriterX86.TryAddOrSet(_writeBuffer, _hitKey, _value);
+        }
+
+        [Benchmark]
+        public bool RawWriterRemoveAndReinsert()
+        {
+            return L4.SwissWriterX86.TryRemove(_writeBuffer, _hitKey, out ulong previousValue) &&
+                   L4.SwissWriterX86.TryAddOrSet(_writeBuffer, _hitKey, previousValue);
+        }
+
+        [Benchmark]
+        public bool TableReaderHit()
+        {
+            return _table.TryGet(_hitKey, out _value);
+        }
+
+        [Benchmark]
+        public bool TableReaderMiss()
+        {
+            return _table.TryGet(_missKey, out _value);
+        }
+
+        [Benchmark]
+        public bool TableWriterUpsertExisting()
+        {
+            return _table.TryAddOrSet(_hitKey, _value);
+        }
+
+        [Benchmark]
+        public bool TableWriterRemoveAndReinsert()
+        {
+            return _table.TryRemove(_hitKey, out ulong previousValue) &&
+                   _table.TryAddOrSet(_hitKey, previousValue);
+        }
+
+        private static L4.AddressSource MakeKey(int index)
+        {
+            return new L4.AddressSource
+            {
+                Address = 0x1000_0000UL + ((ulong)index * 64UL),
+                Description = ((ulong)index * 0x9e37_79b9UL) ^ 0xd1b5_4a32_d192_ed03UL
+            };
+        }
+
+    }
+}

src/Nitload.Common/Collections/SwissTable.X86.cs

@@ -1,130 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="SwissTable.X86"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-using System;
-using System.Numerics;
-using System.Runtime.Intrinsics;
-using System.Runtime.Intrinsics.X86;
-
-namespace Nitload.Common.Collections
-{
-    public partial class SwissTable
-    {
-
-        private unsafe class BucketScannerX86 : IBucketScanner
-        {
-
-            public bool TryFind(
-                        nuint key,
-                        uint hash,
-                        Bucket* bucket,
-                        out nuint value
-            )
-            {
-                byte ctrl = (byte)((hash >> EntryMaskWidth) & 0x7F);
-                Vector128<byte> ctrlVector = Vector128.Create(ctrl);
-                Vector128<byte> bucketCtrlVector = Sse2.LoadVector128((byte*)&bucket->Control);
-                Vector128<byte> cmpResult = Sse2.CompareEqual(ctrlVector, bucketCtrlVector);
-                int mask = Sse2.MoveMask(cmpResult);
-                while (mask != 0)
-                {
-                    int bitPos = BitOperations.TrailingZeroCount(mask);
-                    int index = bitPos;
-                    if (bucket->Keys[index] == key)
-                    {
-                        value = bucket->Values[index];
-                        return true;
-                    }
-                    mask &= mask - 1;
-                }
-                value = default;
-                return false;
-            }
-
-            public bool TryRemove(
-                        nuint key,
-                        uint hash,
-                        Bucket* bucket,
-                        out nuint value
-            )
-            {
-                byte ctrl = (byte)((hash >> EntryMaskWidth) & 0x7F);
-                Vector128<byte> ctrlVector = Vector128.Create(ctrl);
-
-                Vector128<byte> bucketCtrl = Sse2.LoadVector128((byte*)&bucket->Control);
-                Vector128<byte> matchMask = Sse2.CompareEqual(ctrlVector, bucketCtrl);
-                int matches = Sse2.MoveMask(matchMask);
-
-                while (matches != 0)
-                {
-                    int bitPos = BitOperations.TrailingZeroCount(matches);
-                    int index = bitPos;
-                    if (bucket->Keys[index] == key)
-                    {
-                        value = bucket->Values[index];
-                        bucket->Control[index] = 0xFE;  // mark as DELETED
-                        // no need to remove Key/Value
-                        return true;
-                    }
-                    matches &= matches - 1;
-                }
-                value = default;
-                return false;
-            }
-
-            public bool TrySet(
-                        nuint key,
-                        uint hash,
-                        Bucket* bucket,
-                        nuint value,
-                        out bool isNewKey
-            )
-            {
-                byte ctrl = (byte)((hash >> EntryMaskWidth) & 0x7F);         // H2: upper 8 bits (highest bit is naturally 0)
-                Vector128<byte> ctrlVector = Vector128.Create(ctrl);
-
-                Vector128<byte> bucketCtrl = Sse2.LoadVector128(
-                        (byte*)&bucket->Control);
-
-                // === Phase 1: Look up an existing key ===
-                Vector128<byte> matchMask = Sse2.CompareEqual(ctrlVector, bucketCtrl);
-                int matches = Sse2.MoveMask(matchMask);
-
-                while (matches != 0)
-                {
-                    int bitPos = BitOperations.TrailingZeroCount(matches);
-                    int index = bitPos;
-                    if (bucket->Keys[index] == key)
-                    {
-                        // Key already exists -> update value
-                        bucket->Values[index] = value;
-                        isNewKey = false;
-                        return true;
-                    }
-                    matches &= matches - 1;
-                }
-
-                // === Phase 2: Track an available insertion slot ===
-                int emptyOrDeleted = Sse2.MoveMask(bucketCtrl);
-                if (emptyOrDeleted == 0)
-                {
-                    isNewKey = false;
-                    return false;  // bucket full
-                }
-
-                int slot = BitOperations.TrailingZeroCount(emptyOrDeleted);
-                bucket->Control[slot] = ctrl;
-                bucket->Keys[slot] = key;
-                bucket->Values[slot] = value;
-                isNewKey = true;
-                return true;
-            }
-
-        }
-
-    }
-}

src/Nitload.Common/Collections/SwissTable.cs

@@ -1,224 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="SwissTable"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-using System;
-using System.Numerics;
-using System.Runtime.CompilerServices;
-using System.Runtime.InteropServices;
-using System.Runtime.Intrinsics.Arm;
-using System.Runtime.Intrinsics.X86;
-
-namespace Nitload.Common.Collections
-{
-    /// <summary>
-    ///
-    /// </summary>
-    public sealed unsafe partial class SwissTable : IDisposable
-    {
-
-        private const int BucketCount = 1 << EntryMaskWidth;
-        private const int BucketSize = 16;
-        private const uint CrcMagic = 0xffff9961; // Magic number for CRC32C, used in hash computation
-        private const int EntryMaskWidth = 10; // 1024 entries total, 16 per bucket
-        public const int MaxCapacity = BucketCount * BucketSize;   // 256 entries per bucket, 1024 buckets
-
-        public static readonly nuint RequestedNativeMemorySize = (nuint)Unsafe.SizeOf<Entry>();
-
-        private readonly Entry* _entries;
-        private readonly Action<nuint> _freeHandle;
-        private bool _disposed;
-
-        private SwissTable(
-                Entry* buffer,
-                Action<nuint> freeHandle
-        )
-        {
-            _entries = buffer;
-            _freeHandle = freeHandle;
-        }
-
-        public static SwissTable Create()
-        {
-            Entry* buffer = (Entry*)NativeMemory.AlignedAlloc((nuint)Unsafe.SizeOf<Entry>(), 16);
-            for (int i = 0; i < BucketCount; i++)
-            {
-                // Set all control bytes to 0xFF (empty)
-                Unsafe.InitBlock(&(*buffer)[i].Control, 0xFF, BucketSize);
-            }
-            return new SwissTable(buffer, handle => NativeMemory.AlignedFree((void*)handle));
-        }
-
-        public static SwissTable Create(
-                                 Func<nuint, nuint> allocator,
-                                 Action<nuint> freeHandle
-        )
-        {
-            Entry* buffer = (Entry*)allocator(RequestedNativeMemorySize);
-            for (int i = 0; i < BucketCount; i++)
-            {
-                // Set all control bytes to 0xFF (empty)
-                Unsafe.InitBlock(&(*buffer)[i].Control, 0xFF, BucketSize);
-            }
-            return new SwissTable(buffer, freeHandle);
-        }
-
-        public void Dispose()
-        {
-            if (_disposed) {
-                return;
-            }
-            _disposed = true;
-            _freeHandle((nuint)_entries);
-            GC.SuppressFinalize(this);
-        }
-
-        public bool TryAddOrSet(
-                    nuint key,
-                    nuint value,
-                    out bool isNewKey
-        )
-        {
-            uint hash = BitOperations.Crc32C(CrcMagic, (ulong)key);
-            ushort entry = (ushort)(hash & (BucketCount - 1));
-            Bucket* bucket = &(*_entries)[entry];
-            return IBucketScanner.Current.TrySet(key, hash, bucket, value, out isNewKey);
-        }
-
-        public bool TryGet(
-                    nuint key,
-                    out nuint value
-        )
-        {
-            uint hash = BitOperations.Crc32C(CrcMagic, key);
-            ushort entry = (ushort)(hash & (BucketCount - 1));
-            Bucket* bucket = &(*_entries)[entry];
-            return IBucketScanner.Current.TryFind(key, hash, bucket, out value);
-            /*
-            * hash = CRC32 of key
-            * entry = low 8 of hash
-            * ctrl  = 8-15 of hash
-            * index = rest of hash
-            * find value of hash
-            */
-        }
-
-        public bool TryRemove(
-                    nuint key,
-                    out nuint value
-        )
-        {
-            uint hash = BitOperations.Crc32C(CrcMagic, key);
-            ushort entry = (ushort)(hash & (BucketCount - 1));
-            Bucket* bucket = &(*_entries)[entry];
-            return IBucketScanner.Current.TryRemove(key, hash, bucket, out value);
-        }
-
-        internal static SwissTable Create(
-                                   nuint bufferPtr,
-                                   Action<nuint> FreeHandle
-        )
-        {
-            Entry* buffer = (Entry*)bufferPtr;
-            for (int i = 0; i < BucketCount; i++)
-            {
-                // Set all control bytes to 0xFF (empty)
-                Unsafe.InitBlock(&(*buffer)[i].Control, 0xFF, BucketSize);
-            }
-            return new SwissTable(buffer, FreeHandle);
-        }
-
-        ~SwissTable()
-        {
-            Dispose();
-        }
-
-        [InlineArray(BucketCount)]
-        private struct Entry
-        {
-
-            public Bucket Bucket;
-
-        }
-
-        private unsafe struct Bucket
-        {
-
-            public BucketControl Control;
-            public BucketKeyStorage Keys;
-            public BucketValueStorage Values;
-
-        }
-
-        private interface IBucketScanner
-        {
-
-            static IBucketScanner Current { get; } = Create();
-
-            bool TryFind(
-                 nuint key,
-                 uint Hash,
-                 Bucket* bucket,
-                 out nuint value
-            );
-
-            unsafe bool TryRemove(
-                        nuint key,
-                        uint hash,
-                        Bucket* bucket,
-                        out nuint value
-            );
-
-            bool TrySet(
-                 nuint key,
-                 uint hash,
-                 Bucket* bucket,
-                 nuint value,
-                 out bool isNewKey
-            );
-
-            private static IBucketScanner Create()
-            {
-                if (Sse42.IsSupported)
-                {
-                    return new BucketScannerX86();
-                } else if (ArmBase.IsSupported)
-                {
-                    throw new NotSupportedException("ARM architecture is currently not supported for bucket scanning. Please use an x86 platform.");
-                } else
-                {
-                    throw new NotSupportedException("No suitable bucket scanner implementation found for the current platform.");
-                }
-            }
-
-        }
-
-        [InlineArray(BucketSize)]
-        private struct BucketControl
-        {
-
-            public byte Control;
-
-        }
-
-        [InlineArray(BucketSize)]
-        private struct BucketKeyStorage
-        {
-
-            public nuint value;
-
-        }
-
-        [InlineArray(BucketSize)]
-        private struct BucketValueStorage
-        {
-
-            public nuint value;
-
-        }
-
-    }
-}

src/Nitload.Common/Global.cs

@@ -15,4 +15,5 @@ global using System.Threading;
 [assembly: InternalsVisibleTo("Nitload.RegularAnalysis")]
 [assembly: InternalsVisibleTo("Nitload.Graphics")]
 [assembly: InternalsVisibleTo("Nitload.Mathematics")]
+[assembly: InternalsVisibleTo("Nitload.Benchmark")]
 [assembly: InternalsVisibleTo("StgSharpDebug")]

src/Nitload.Common/HighPerformance/Memory/L4.CacheLine.cs

@@ -5,7 +5,6 @@
 // SPDX-License-Identifier: MIT
 // -----------------------------------------------------------------------------
 
-using Nitload.Common.HighPerformance.ProcessorAbstraction;
 using System.Runtime.InteropServices;
 
 namespace Nitload.Common.HighPerformance.Memory
@@ -23,14 +22,12 @@ namespace Nitload.Common.HighPerformance.Memory
         }
 
         [StructLayout(LayoutKind.Explicit, Size = 32, Pack = 32)]
-        private unsafe struct CacheLineMetadata
+        private struct CacheLineMetadata
         {
 
             internal const uint MaxBufferSize = 0xFFFFFFFF - 64U;
 
-            [FieldOffset(0)] private readonly M256 FillingMask;
-
-            [FieldOffset(24)] internal nuint Origin;
+            [FieldOffset(16)] internal AllocationState State;
 
             public static uint SizeOf { get; } = (uint)Unsafe.SizeOf<CacheLineMetadata>();
 
@@ -48,33 +45,25 @@ namespace Nitload.Common.HighPerformance.Memory
             [FieldOffset(8)] public uint PositionMask;
             [FieldOffset(12)] public uint SizeMask;
 
-            #endregion
-
-            #region mask
-
-            [FieldOffset(16)] internal AllocationState State;
-            [FieldOffset(17)] internal byte ReversedProfile;
-            [FieldOffset(18)] internal ushort CustomizeProfile;
-            [FieldOffset(20)] internal int RefCount;
-
         #endregion
         }
 
 #pragma warning disable IDE0032
-        [StructLayout(LayoutKind.Explicit)]
+        [StructLayout(LayoutKind.Explicit, Size = 16)]
         public unsafe struct Handle : IDisposable
         {
 
-            [FieldOffset(8)] private readonly CacheLineMetadata* _head;
             [FieldOffset(0)] private nuint _handle;
 
-            private Handle(
-                    nuint handle,
-                    CacheLineMetadata* cacheRefCount
+            [FieldOffset(8)] private nuint _reserved;
+
+            internal Handle(
+                     nuint handle,
+                     nuint reserved
             )
             {
                 _handle = handle;
-                _head = cacheRefCount;
+                _reserved = reserved;
             }
 
             [Obsolete("You should not create a CacheLineHandle instance outside a L4", true)]
@@ -88,7 +77,7 @@ namespace Nitload.Common.HighPerformance.Memory
                     return;
                 }
                 _handle = 0;
-                _ = Interlocked.Decrement(ref _head->RefCount);
+                _reserved = 0;
             }
 
         }

src/Nitload.Common/HighPerformance/Memory/L4.Debug.cs

@@ -1,92 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="L4.Debug"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
-
-namespace Nitload.Common.HighPerformance.Memory
-{
-    /**/
-    public partial class L4
-    {
-
-        public void DebugAgeAll()
-        {
-            // AgeAll();
-        }
-
-        public bool DebugContains(
-                    nuint origin
-        )
-        {
-            return _map.TryGet(origin, out _);
-        }
-
-        public int DebugEvict(
-                   int count = 1
-        )
-        {
-            return Evict(count);
-        }
-
-        public unsafe DebugSnapshot GetDebugSnapshot()
-        {
-            throw new NotImplementedException();
-            /*
-            int maxId = _maxId;
-            byte[] rrpv = new byte[maxId];
-            byte* p = (byte*)_eviction;
-            for (int i = 0; i < maxId; i++) {
-                rrpv[i] = p[i];
-            }
-            return new DebugSnapshot(_activeCount, _aheadCount, maxId, rrpv);
-            /**/
-        }
-
-        public readonly struct DebugSnapshot
-        {
-
-            /// <summary>
-            ///   RRPV value for each line（0~3）, length == MaxId
-            /// </summary>
-            public readonly byte[] RrpvSnapshot;
-            /// <summary>
-            ///   Count of activated cache line handle
-            /// </summary>
-            public readonly int ActiveCount;
-
-            /// <summary>
-            ///   Count of predictor ahead of current map position（aheadCount）
-            /// </summary>
-            public readonly int AheadCount;
-
-            /// <summary>
-            ///   Max ID of the line being using or once used（maxId）
-            /// </summary>
-            public readonly int MaxId;
-
-            internal DebugSnapshot(
-                     int activeCount,
-                     int aheadCount,
-                     int maxId,
-                     byte[] rrpv
-            )
-            {
-                ActiveCount = activeCount;
-                AheadCount = aheadCount;
-                MaxId = maxId;
-                RrpvSnapshot = rrpv;
-            }
-
-        }
-
-    }
-    /**/
-}

src/Nitload.Common/HighPerformance/Memory/L4.Design.md

@@ -0,0 +1,139 @@
+# L4 运行模型
+
+> 工作稿，2026-10-14。本文替代旧版 L4 设计草案，区分当前代码、已讨论方向和仍待确认的问题。
+
+## 1. 范围与职责
+
+每个 `L4` 实例绑定一个 NUMA 节点，拥有本地 arena，其中放置 TLSF 分配器状态和 L4 Swiss 映射表的双缓冲区。
+
+- **L4** 负责本地分配、映射、缓冲区发布和阶段协调。
+- **Swiss** 保存并查询 L4 使用的映射/预测条目，不解释 source layout。
+- **Predictor** 解释自己的 source spec，生成 packed 数据，并负责格式相关的软件写回或撤销。
+- **PredictorMonitor** 计划负责预测器注册、稳定 ID、执行顺序和生命周期；它与 Swiss 中的预测任务/映射状态是两回事。
+
+本文不假设自动写回。若 packed 数据需要写回，必须能识别其所属预测器并显式调用对应逻辑。
+
+## 2. AddressSource 与缓存行数据
+
+`AddressSource` 是 16 字节 key：
+
+- `Address`：源地址或 source identity。
+- `Description`：64 位 source/layout spec，由所属预测器解释。
+
+当前 Swiss 条目使用该 key 和一个 `ulong` value。源码中的 `CacheLineMetadata` 是 32 字节 TLSF metadata；`L4.Handle` 仍是 16 字节 ABI 占位。引用计数、驱逐保护和写回归属尚未端到端实现。
+
+### 当前与候选 KVP 布局
+
+- 设计讨论中的 `ushort` 是缓存行计数，不是预测器数量或预测器注册表容量。
+- 当前 Swiss bucket 将 key 与 `ulong` value 分开组织；现有的 8-KVP 交叉存储描述的是数据存储布局，不是 H1/hash 探测分组。
+- 一个候选布局是把 value 扩成 16 字节：保留现有 `ulong` cache-line metadata，再增加 8 字节存放预测计数等状态。与 16 字节 `AddressSource` 组成 32 字节 KVP，每条 64 字节 cache line 放两个 KVP。
+- 该方案旨在减少当前 8-KVP 交叉存储造成的 cache-line 分散/冲突。它只调整 KVP 的存储编排，不意味着 H1 探测组从当前 16 槽改成 8 槽。此方案尚未实现，需实测对查找和替换扫描的影响。
+
+## 3. Swiss 映射
+
+当前表有 1024 组，每组 16 个槽位。控制字节扫描使用 SSE2；x64 路径使用 CRC32C 混合两个 64 位 key 字段。两个表缓冲区都分配在 L4 arena 内。
+
+published buffer 地址以 `ulong` 保存：
+
+- `TryGet` 用一次 `Volatile.Read` 捕获 published pointer，并在整个查找中使用该快照。
+- `SwapBuffers` 用 `Interlocked.Exchange` 发布下一缓冲区，返回的旧 published pointer 成为下一轮 inactive write buffer。
+- 原子发布指针不代表旧 buffer 可以立即复用。Map/swap 阶段协议必须先确保读者不再访问旧 buffer，writer 才能清空或覆盖它。
+
+当前只实现 x64/SSE4.2 后端，其他 ISA 后端尚未实现。
+
+## 4. 预测器接口与阶段
+
+当前接口骨架位于 `L4Predictor.cs`：
+
+- `IL4Predictor` 是非泛型管理接口，暴露预测器 ID 和同步的 `PredictMission(in Span<AddressSource>)`。
+- `IL4Predictor<TMission>` 为预测器实现提供强类型 mission API。
+- `PredictMission` 填充调用方提供的 span，并返回有效预测数。span 可以由调用方 `stackalloc`，不得逃逸出本次同步调用。
+- `PredictorMonitor` 目前是空占位；预测器注册和生命周期尚未实现。
+
+当前讨论中的 L4 生命周期分为不同阶段：
+
+1. **注册预测器**：monitor 按稳定顺序保存异构预测器。固定容量数组（讨论过 256）是候选，其容量与缓存行计数无关。
+2. **Prefetch**：预测器按依赖顺序执行。每个 L4 同时只有一个活动 prefetch worker，但 prefetch 可与 Map 重叠，也可能跨 NUMA 节点访问目标数据。
+3. **发布**：完成后的 inactive Swiss buffer 被原子发布。Swiss 保存预测/映射任务状态；预测器注册表不是预测任务队列。
+4. **Map**：调用方查询已发布的 `AddressSource` 并取得 L4 handle。
+5. **撤销/写回**：所属预测器解释 packed 数据，并按需执行软件写回或撤销。
+
+预测器接口本身是同步的。若预测结果需要在 `PredictMission` 返回后或另一线程继续使用，必须先复制到生命周期足够长的自有存储中。异步边界应位于拥有的 batch/work item 周围，而不能让 stack span 逃逸。
+
+## 5. 预测窗口与 Map 同步
+
+两个阈值含义不同：
+
+- `_low_predict = 512`：预测触发/补充阈值。
+- `_predict_slow_path_count = 2 * LogicalCoreCount`：按 L4 绑定 NUMA 节点逻辑处理器数量计算的提前慢路径窗口。
+
+当前 Map 的分流意图如下：
+
+| 剩余预测数 | Map 行为 |
+|---|---|
+| 小于 512 | 尝试成为预测 writer；预测可能完成并发布新 buffer。竞争失败的调用走带读者计数的查找路径。 |
+| 512 到 `512 + _predict_slow_path_count` 之间 | 走带计数的慢查找路径，以便 swap 等待这些读者退出。 |
+| 大于或等于 `512 + _predict_slow_path_count` | 走无计数的直接查找快路径。 |
+
+计数读者协议先等待 swap gate 打开，再增加 reader count 并复查 gate。如果 gate 在两步之间关闭，则撤销计数并重试。swap 方关闭 gate、等待已计数读者归零、交换 buffer、发布新的剩余预测数，最后重新打开 gate。
+
+无计数快路径依赖预测提前量和阶段时序。这是性能启发式，本身不能证明一个被抢占的 reader 不会在旧 buffer 复用时仍继续访问。无计数 reader 与 buffer 生命周期之间的不变量，以及快慢路径边界，都仍需验证。
+
+当前 `Predict()` 返回 `int`，但实现仍是返回 `0` 的空 stub，因此预测数生命周期尚未端到端运行。
+
+## 6. 预测器注册、任务状态与在途缓冲
+
+预测器调度和预测任务执行是两条相关但不同的生命周期，不能把“预测器已预测完”当成“它产生的工作已完成”。
+
+- **待调度预测器（多个）**：保存在 PredictorMonitor 的有序管理数组/队列中，等待轮到自己。固定槽位容量（曾讨论 256）表示预测器注册上限，与缓存行计数无关。
+- **活动预测器（最多一个）**：当前 L4 正在执行其同步 `PredictMission`。预测器之间按依赖顺序切换，不需要多 lane 或 thread-local lane 归属。
+- **在途预测批次（可以多个）**：某预测器已经产出候选，但候选对应的实际任务尚未全部执行。此时要保留稳定的 predictor ID/代次、mission 或写回上下文；该记录属于任务 bag，不等同于预测器注册槽位。`PredictMission` 按预测器依赖顺序串行调用；前一批次的实际任务可以仍在途，是否与后续批次重叠由任务依赖决定。
+- **已完成批次**：对应实际工作全部完成，且所需软件写回或显式丢弃已完成。此时释放在途记录及其引用资源，不再由 L4 保存该批次。预测器本身是否注销是另一项生命周期操作。
+
+Swiss 负责预测任务/映射条目的查找状态；Monitor 负责预测器注册和调度；在途预测器缓冲负责尚未完成的预测工作及其归属。三者不可混为同一个队列或数组。
+
+`PredictMission(in Span<AddressSource>)` 是同步接口，L4 可传入 stackalloc span。若返回后仍需跨线程或跨 NUMA 处理其内容，必须将内容复制到拥有明确生命周期的缓冲区；不得让 stack span 逃逸。由于预测器顺序有依赖，待处理预测必须按既定顺序交接。若采用异步 worker，队列应有界且不阻塞 Map 快路径。
+
+## 7. 驱逐与写回策略
+
+L4 不得推断或解码预测器的 packed 格式。若丢弃一个尚未写回、且对应实际工作仍在途的预测条目会丢失必要状态，就不能静默驱逐它；必须由缓存行保护/引用状态阻止替换，或由 Monitor/预测器先完成写回、撤销或显式释放。相关状态可放在 KVP metadata 或 sidecar，布局尚未定稿。
+
+owner ID 可用于路由显式写回；但若多个预测器能独立声明同一条目，单一 owner 字段不够。引用计数可保护共享条目，而写回路径仍需获得预测器 identity/source spec。
+
+## 8. 当前状态与待决问题
+
+**源码中已实现：**
+
+- NUMA 绑定的 L4 arena 和 TLSF 包装。
+- 双缓冲 Swiss 表及原子 published pointer 交换。
+- x64 CRC32C hash 和 SSE2 控制字节扫描。
+- 固定预测触发阈值，以及按 NUMA 节点逻辑处理器数量计算的提前慢路径窗口。
+- 慢路径的 Map reader gate/counter。
+- 同步的泛型/非泛型预测器接口骨架。
+
+**尚未实现或尚未验证：**
+
+- PredictorMonitor 注册表容量、注册/注销和生命周期状态转换。
+- 实际预测算法与有效预测条目的生成。
+- 端到端撤销/写回归属和缓存行驱逐保护。
+- Prefetch 与 Map 跨 NUMA 重叠时的自有 queue/batch 交接方式。
+- 无计数 Map 快路径不会与 published buffer 复用重叠的证明/测试。
+- 覆盖预测器发布、Map、撤销和 Dispose 的并发压力测试。
+
+## 9. L4 的四个核心操作
+
+### 预测（Prefetch）
+
+Monitor 按注册顺序选择预测器，调用其同步预测接口；预测器解释自己的 source spec，将预测项写入调用方提供的 span。Swiss 管理预测/映射条目。若预测项对应的实际工作尚未完成，则放入在途预测器缓冲，保留后续完成、撤销或写回所需的归属信息。预测期间若没有可用的 cache-line 槽位，替换/保护策略由后续设计决定，不能隐式丢弃仍在途的条目。
+
+### 映射（Map）
+
+计算 worker 按预测器调度获取 `AddressSource`，通过 Swiss 查询 NUMA 本地的 packed 数据并得到 L4 handle。Map 不解释 `Description`，也不负责预测器注册或写回。
+
+### 注册预测器
+
+将预测器放入 `PredictorMonitor` 的管理槽位，分配稳定 ID 和执行顺序，并纳入生命周期监视。注册表槽位与 Swiss 预测条目、在途预测工作是不同资源。
+
+### 移除预测器
+
+先停止向该预测器分派新 mission，再等待其在途预测对应的实际工作完成或被撤销；需要的软件写回完成后，才能释放在途状态并回收注册槽位。具体等待与写回协议尚待设计。

src/Nitload.Common/HighPerformance/Memory/L4.Evict.cs

@@ -1,64 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="L4.Evict"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-namespace Nitload.Common.HighPerformance.Memory
-{
-    public partial class L4
-    {
-
-        /// <summary>
-        ///
-        /// </summary>
-        /// <param name="count">
-        ///
-        /// </param>
-        /// <returns>
-        ///   Count of lines not evicted
-        /// </returns>
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private unsafe int Evict(
-                           int count = 1
-        )
-        {
-            count = (count < 0) ? 0 : count;
-            int* pPtr = _predictCount, mPtr = _mapCount;
-
-
-            int remain = count;
-            for (int i = 0; i < CacheLineCount; i++)
-            {
-                if (pPtr[i] > mPtr[i])
-                {
-                    continue;
-                }
-                remain -= TryEvictAt(i) ? 1 : 0;
-            }
-            return remain;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private unsafe bool TryEvictAt(
-                            int index
-        )
-        {
-            CacheLineMetadata* head = &_head[index];
-            if (Interlocked.CompareExchange(ref head->RefCount, int.MinValue, 0) == 0)
-            {
-                // EvictLine(i + index);
-                _ = _map.TryRemove(head->Origin, out _);
-                IL4Predict predict = CurrentPredict;
-                predict.WriteBack(head->Origin, head->CustomizeProfile, new ReadOnlySpan<byte>((byte*)(ulong)(head->PositionMask + _baseAddress), (int)(ulong)head->SizeMask));
-                _bufferAllocator.Free(index);
-                _mapCount[index] = 0;
-                _predictCount[index] = int.MaxValue;
-                return true;
-            }
-            return false;
-        }
-
-    }
-}

src/Nitload.Common/HighPerformance/Memory/L4.Exceptions.cs

@@ -1,34 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="L4.Exceptions"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-namespace Nitload.Common.HighPerformance.Memory
-{
-#pragma warning disable CA1032 // Implement standard exception constructors
-
-    public sealed class L4PredictUnregisteredException : Exception
-    {
-
-        public L4PredictUnregisteredException(
-               int id
-        )
-            : base($"L4 predictor with id {id} is null. Maybe it has been unregistered.") { }
-
-    }
-
-    public sealed class L4PredictConflictException : Exception
-    {
-
-        public L4PredictConflictException(
-               nuint basePtr,
-               ushort policy,
-               int current
-        )
-            : base($"L4 predictor with id {current} has already registered a cache line with base pointer {basePtr} and policy {policy}.") { }
-
-    }
-#pragma warning restore CA1032 // Implement standard exception constructors
-}

src/Nitload.Common/HighPerformance/Memory/L4.Map.cs

@@ -0,0 +1,111 @@
+// -----------------------------------------------------------------------------
+// file="L4.Map"
+// Project: StgSharp
+// Copyright (c) Nitload.
+// SPDX-License-Identifier: MIT
+// -----------------------------------------------------------------------------
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Nitload.Common.HighPerformance.Memory
+{
+    public unsafe partial class L4
+    {
+
+        private const int _low_predict = 512;
+
+        private int _predict_count;
+        private readonly int _predict_slow_path_count;
+        private int _swiss_reader_counter;
+        private int _swiss_swap_lock;
+        private int _swiss_writer_lock;
+
+        public partial Handle Map(
+                              AddressSource source
+        )
+        {
+            ulong handle;
+            int predictCount = Volatile.Read(ref _predict_count);
+            if (predictCount < _low_predict)
+            {
+                if (Interlocked.CompareExchange(ref _swiss_writer_lock, 1, 0) == 0)
+                {
+                    try
+                    {
+                        int effectivePredictionCount = Predict();
+                        if (effectivePredictionCount > 0)
+                        {
+                            _ = Interlocked.Exchange(ref _swiss_swap_lock, 1);
+                            while (Volatile.Read(ref _swiss_reader_counter) != 0) { }
+
+                            _addressMap.SwapBuffers();
+                            Volatile.Write(ref _predict_count, effectivePredictionCount);
+                            _addressMap.TryRehash();
+                        }
+
+                        if (_addressMap.TryGet(source, out handle)) {
+                            throw new InvalidOperationException($"Unexpected map request: [address source: 0x{source.Address:x16}; layout profile: {source.Description:x16}].");
+                        }
+                    }
+                    finally
+                    {
+                        _ = Interlocked.Exchange(ref _swiss_swap_lock, 0);
+                        _ = Interlocked.Exchange(ref _swiss_writer_lock, 0);
+                    }
+                } else if (!TryGetAddress(source, out handle)) {
+                    throw new InvalidOperationException($"Unexpected map request: [address source: 0x{source.Address:x16}; layout profile: {source.Description:x16}].");
+                }
+            } else if (predictCount < _low_predict + _predict_slow_path_count)
+            {
+                if (!TryGetAddress(source, out handle)) {
+                    throw new InvalidOperationException($"Unexpected map request: [address source: 0x{source.Address:x16}; layout profile: {source.Description:x16}].");
+                }
+            } else if (!_addressMap.TryGet(source, out handle)) {
+                throw new InvalidOperationException($"Unexpected map request: [address source: 0x{source.Address:x16}; layout profile: {source.Description:x16}].");
+            }
+
+            CacheLineMetadata* metadata = (CacheLineMetadata*)handle;
+
+            // process metadata, unfinished
+            uint offset = metadata->PositionMask;
+            nuint address = /*base ptr + */ offset;
+            _ = Interlocked.Decrement(ref _predict_count);
+
+            return new Handle(address, (nuint)handle);
+        }
+
+        private bool TryGetAddress(
+                     AddressSource source,
+                     out ulong handle
+        )
+        {
+            while (true)
+            {
+                while (Volatile.Read(ref _swiss_swap_lock) != 0) { }
+
+                _ = Interlocked.Increment(ref _swiss_reader_counter);
+                if (Volatile.Read(ref _swiss_swap_lock) == 0)
+                {
+                    break;
+                }
+
+                _ = Interlocked.Decrement(ref _swiss_reader_counter);
+            }
+
+            try
+            {
+                return _addressMap.TryGet(source, out handle);
+            }
+            finally
+            {
+                _ = Interlocked.Decrement(ref _swiss_reader_counter);
+            }
+        }
+
+    }
+}

src/Nitload.Common/HighPerformance/Memory/L4.Predict.cs

@@ -5,10 +5,7 @@
 // SPDX-License-Identifier: MIT
 // -----------------------------------------------------------------------------
 
-using Nitload.Common.Collections;
-using Nitload.Common.HighPerformance.Memory;
 using System;
-using System.Collections.Concurrent;
 using System.Collections.Generic;
 using System.Linq;
 using System.Text;
@@ -16,22 +13,12 @@ using System.Threading.Tasks;
 
 namespace Nitload.Common.HighPerformance.Memory
 {
-    public partial class L4
+    public unsafe partial class L4
     {
 
-        private IL4Predict CurrentPredict { get; set; }
-
-        public void ResetPredict(
-                    IL4Predict predict
-        )
+        internal partial int Predict()
         {
-            if (CurrentPredict is null)
-            {
-                CurrentPredict = predict;
-                return;
-            }
-
-            // TODO: write back all and register new predictor
+            throw new NotImplementedException();
         }
 
     }

src/Nitload.Common/HighPerformance/Memory/L4.Predictor.cs

@@ -1,146 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="L4.Predictor"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Runtime.InteropServices;
-using System.Text;
-using System.Threading.Tasks;
-
-namespace Nitload.Common.HighPerformance.Memory
-{
-    [Flags]
-    public enum PredictResult
-    {
-
-        Success = 1,
-        Exhausted = 2,
-
-    }
-
-    public interface IL4Predict
-    {
-
-        PredictResult Predict(
-                      Span<CacheLineDescription> node,
-                      out int count
-        );
-
-        /// <summary>
-        ///   Materializes the cache line identified by <paramref name="origin" /> into <paramref ///  
-        ///   name="cache" />.
-        /// </summary>
-        /// <param name="origin">
-        ///   Source address associated with the cache line.
-        /// </param>
-        /// <param name="policy">
-        ///   Mapping policy associated with the cache line.
-        /// </param>
-        /// <param name="cache">
-        ///   Destination cache line buffer.
-        /// </param>
-        void Prefetch(
-             nuint origin,
-             uint policy,
-             Span<byte> cache
-        );
-
-        /// <summary>
-        ///   Writes the cache line in <paramref name="cache" /> back to <paramref name="origin" />.
-        /// </summary>
-        /// <param name="origin">
-        ///   Source address associated with the cache line.
-        /// </param>
-        /// <param name="policy">
-        ///   Mapping policy associated with the cache line.
-        /// </param>
-        /// <param name="cache">
-        ///   Source cache line buffer.
-        /// </param>
-        void WriteBack(
-             nuint origin,
-             uint policy,
-             ReadOnlySpan<byte> cache
-        );
-
-    }
-
-    [StructLayout(LayoutKind.Explicit)]
-    public struct CacheLineDescription : IEquatable<CacheLineDescription>
-    {
-
-        public override readonly bool Equals(
-                                      object? obj
-        )
-        {
-            return (obj is CacheLineDescription prediction) &&
-                   Address.Equals(prediction.Address) &&
-                   (MapPolicy == prediction.MapPolicy);
-        }
-
-        public readonly bool Equals(
-                             CacheLineDescription other
-        )
-        {
-            return
-            (Address == other.Address) && (MapPolicy == other.MapPolicy);
-        }
-
-        public override readonly int GetHashCode()
-        {
-            return (int)ComposePredictionKey64(Address, MapPolicy);
-        }
-
-        public readonly nuint GetHashCodeLong()
-        {
-            return ComposePredictionKey64(Address, MapPolicy);
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private static nuint ComposePredictionKey64(
-                             nuint address,
-                             ushort mapPolicy
-        )
-        {
-            nuint x = address;
-            nuint y = mapPolicy;
-            unchecked
-            {
-                nuint mixed = x ^ (y * ((nuint)0x9e3779b97f4a7c15UL));
-                mixed ^= mixed >> 30;
-                mixed *= (nuint)0xbf58476d1ce4e5b9UL;
-                mixed ^= mixed >> 27;
-                mixed *= (nuint)0x94d049bb133111ebUL;
-                mixed ^= mixed >> 31;
-                return mixed;
-            }
-        }
-
-        public static bool operator !=(
-                                    CacheLineDescription left,
-                                    CacheLineDescription right
-        )
-        {
-            return !(left == right);
-        }
-        public static bool operator ==(
-                                    CacheLineDescription left,
-                                    CacheLineDescription right
-        )
-        {
-            return left.Equals(right);
-        }
-
-#pragma warning disable CA1051
-        [FieldOffset(0)]public nuint Address;
-        [FieldOffset(8)]public uint Size;
-        [FieldOffset(12)]public ushort MapPolicy;
-        [FieldOffset(14)]internal short Predictor;
-#pragma warning restore CA1051
-    }
-}

src/Nitload.Common/HighPerformance/Memory/L4.PredictorQueue.cs

@@ -0,0 +1,109 @@
+// -----------------------------------------------------------------------------
+// file="L4.PredictorQueue"
+// Project: StgSharp
+// Copyright (c) Nitload.
+// SPDX-License-Identifier: MIT
+// -----------------------------------------------------------------------------
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace Nitload.Common.HighPerformance.Memory
+{
+    public partial class L4
+    {
+
+        private readonly IL4Predictor[] _ring = new IL4Predictor[256];
+        private volatile int _consume;
+        private volatile int _enter;
+        private volatile int _predict;
+
+        private int _queue_sync;
+
+        internal void DropPredictor(
+                      IL4Predictor predictor
+        )
+        {
+            if (predictor is null) {
+                return;
+            }
+            SpinWait sp = new();
+            while (Interlocked.CompareExchange(ref _queue_sync, 1, 0) != 0) {
+                sp.SpinOnce();
+            }
+
+            try
+            {
+                unchecked
+                {
+                    for (int i = _consume; i < _predict; i++)
+                    {
+                        byte idx = (byte)i;
+                        if (ReferenceEquals(predictor, _ring[idx]))
+                        {
+                            int end = _predict;
+                            for (int move = i; move < end - 1; move++)
+                            {
+                                _ring[(byte)move] = _ring[(byte)(move + 1)];
+                            }
+                            _ring[(byte)(end - 1)] = default!;
+                            _predict = end - 1;
+                            return;
+                        }
+                    }
+                }
+            }
+            finally
+            {
+                Interlocked.Exchange(ref _queue_sync, 0);
+            }
+        }
+
+        internal void RegistPredictor(
+                      IL4Predictor predictor
+        )
+        {
+            if (predictor is null) {
+                return;
+            }
+            SpinWait sp = new();
+            while (Interlocked.CompareExchange(ref _queue_sync, 1, 0) != 0) {
+                sp.SpinOnce();
+            }
+
+            WaitForSpare();
+
+            _consume++;
+
+            byte idx = (byte)_consume;
+            _ring[idx] = predictor;
+        }
+
+        private void WaitForSpare()
+        {
+            int spin_count = 0;
+
+            // wait until the queue has space
+            while (_enter - _consume >= 256)
+            {
+                switch (spin_count)
+                {
+                    case < 1024:
+                        spin_count++;
+                        break;
+                    case < 65536:
+                        spin_count++;
+                        Thread.SpinWait(1);
+                        break;
+                    default:
+                        Thread.Sleep(1);
+                        break;
+                }
+            }
+        }
+
+    }
+}

src/Nitload.Common/HighPerformance/Memory/L4.Prefetch.cs

@@ -1,102 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="L4.Prefetch"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-using System.ComponentModel;
-using System.Numerics;
-
-namespace Nitload.Common.HighPerformance.Memory
-{
-    public unsafe partial class L4
-    {
-
-        private partial void Prefetch()
-        {
-            if (CurrentPredict is null) {
-                return;
-            }
-            IL4Predict predict = CurrentPredict;
-            Span<CacheLineDescription> span = new(_prediction, PredictionCount);
-            PredictResult result = predict.Predict(span, out int actualCount);
-            _exhausted = (result & PredictResult.Exhausted) != 0;
-            if (actualCount <= 0)
-            {
-                _exhausted = true;
-                return;
-            }
-            int missIndex = 0;
-            for (int i = 0; i < actualCount; i++)
-            {
-                ref CacheLineDescription handle = ref span[i];
-                nuint address = handle.Address;
-                if (!_map.TryGet(address, out _))
-                {
-                    // miss and record
-                    span[missIndex] = handle;
-                    missIndex++;
-                }
-            }
-
-            // now prefetch the misses
-            for (int i = 0; i < missIndex; i++)
-            {
-                CacheLineMetadata* head;
-                ref CacheLineDescription pHandle = ref span[i];
-                nuint address = pHandle.Address;
-                int index;
-                if (_map.TryGet(address, out nuint handle))
-                {
-                    head = (CacheLineMetadata*)handle;
-                    index = (int)(head - _head);
-                    _predictCount[index] = 0; // reset eviction counter
-
-                    #region update predictor belonging
-
-                    if (_predictCount[index] > short.MaxValue / 2)
-                    {
-                        int predictCount = Volatile.Read(ref _predictCount[index]);
-                        int mapCount = Volatile.Read(ref _mapCount[index]);
-                        int decrement = (int.Min(predictCount, mapCount) + 1) / 2;
-                        _ = Interlocked.Add(ref _predictCount[index], -decrement);
-                        _ = Interlocked.Add(ref _mapCount[index], -decrement);
-                    }
-                    _predictCount[index]++;
-
-                    #endregion
-
-                    continue;
-                }
-
-                int retryCount = 0, remain = missIndex - i;
-                const int maxRetry = 1024;
-                while (!_bufferAllocator.TryAlloc(pHandle.Size, out index))
-                {
-                    remain = Evict(remain);
-                    retryCount++;
-                    if (retryCount > maxRetry) {
-                        throw new OverflowException($"Failed to evict cache line after {maxRetry} retries.");
-                    }
-                    if (retryCount > maxRetry / 2) {
-                        Thread.Sleep(1);
-                    }
-                }
-                head = _head + index;
-                head->Origin = address;
-                head->CustomizeProfile = pHandle.MapPolicy;
-                head->RefCount = 0;
-
-                _predictCount[index] = 1;
-                _mapCount[index] = 1;
-
-                // pre fetch them here
-                predict.Prefetch(head->Origin, head->CustomizeProfile, new Span<byte>((byte*)(head->PositionMask + _baseAddress), (int)head->SizeMask));
-                _ = _map.TryAddOrSet(address, (nuint)head, out _);
-            }
-            _ = Interlocked.Add(ref _aheadCount, actualCount);
-        }
-
-    }
-}

src/Nitload.Common/HighPerformance/Memory/L4.SwissTable.cs

@@ -0,0 +1,289 @@
+// -----------------------------------------------------------------------------
+// file="L4.SwissTable"
+// Project: StgSharp
+// Copyright (c) Nitload.
+// SPDX-License-Identifier: MIT
+// -----------------------------------------------------------------------------
+
+using System.Buffers;
+using System.Numerics;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+using System.Runtime.Intrinsics;
+using System.Runtime.Intrinsics.X86;
+
+namespace Nitload.Common.HighPerformance.Memory
+{
+    public sealed unsafe partial class L4
+    {
+
+        private const int BucketCapacity = 16;
+        private const int GroupCount = 1 << GroupCountLog;
+        private const int GroupCountLog = 10;
+        private const int IdealCount = GroupCount * BucketCapacity;//16384
+        private const int OffsetOfBucket = IdealCount;
+
+        private static readonly int TableBufferSize =
+            IdealCount + (GroupCount * Unsafe.SizeOf<SwissBucket>());
+        internal static readonly int BufferSize = TableBufferSize * 2;
+
+        private enum SwissControl : byte
+        {
+
+            Empty = 0b10000000,
+            Deleted = 0b10000001
+
+        }
+
+        [StructLayout(LayoutKind.Sequential)]
+        public struct AddressSource : IEquatable<AddressSource>
+        {
+
+            public ulong Address;
+            public ulong Description;
+
+            public readonly bool Equals(
+                                 AddressSource other
+            )
+            {
+                return this == other;
+            }
+
+            public override readonly bool Equals(
+                                          object? obj
+            )
+            {
+                return obj is AddressSource source && Equals(source);
+            }
+
+            public override readonly int GetHashCode()
+            {
+                return HashCode.Combine(Address, Description);
+            }
+
+            public static bool operator !=(
+                                        AddressSource left,
+                                        AddressSource right
+            )
+            {
+                return !(left == right);
+            }
+
+            public static bool operator ==(
+                                        AddressSource left,
+                                        AddressSource right
+            )
+            {
+                return left.Address == right.Address && left.Description == right.Description;
+            }
+
+        }
+
+        [InlineArray(BucketCapacity)]
+        internal struct KeyArray
+        {
+
+            private AddressSource _element0;
+
+        }
+
+        internal struct SwissBucket
+        {
+
+            public KeyArray Keys;
+            public fixed ulong Values[BucketCapacity];
+
+        }
+
+        internal unsafe struct SwissEnumerator(
+                               byte* buffer
+        )
+        {
+
+            private readonly SwissBucket* _buckets = (SwissBucket*)(buffer + IdealCount);
+            private readonly Vector128<byte>* _control_bytes = (Vector128<byte>*)buffer;
+            private int _current_group;
+            private int _current_mask;
+            private int _current_offset;
+            private bool _group_loaded;
+
+            public (AddressSource key, ulong value) Current
+            {
+                get
+                {
+                    SwissBucket* bucket = &_buckets[_current_group];
+                    AddressSource key = bucket->Keys[_current_offset];
+                    ulong value = bucket->Values[_current_offset];
+                    return (key, value);
+                }
+            }
+
+            public bool MoveNext()
+            {
+                while (_current_group < GroupCount)
+                {
+                    if (!_group_loaded)
+                    {
+                        if (Sse42.IsSupported)
+                        {
+                            _current_mask = SwissReaderX86.CompareOccupiedMask(*(_control_bytes + _current_group));
+                        } else
+                        {
+                            throw new PlatformNotSupportedException();
+                        }
+                        _group_loaded = true;
+                    }
+
+                    if (_current_mask != 0)
+                    {
+                        _current_offset = BitOperations.TrailingZeroCount(_current_mask);
+                        _current_mask &= _current_mask - 1;
+                        return true;
+                    }
+
+                    _current_group++;
+                    _group_loaded = false;
+                }
+                return false;
+            }
+
+        }
+
+        internal unsafe struct SwissTable : IDisposable
+        {
+
+            private byte* _buffer_write;
+            private int _delete_count;
+            private ulong _published_buffer;
+
+            private SwissTable(
+                    byte* buffers
+            )
+            {
+                _published_buffer = (ulong)buffers;
+                _buffer_write = buffers + TableBufferSize;
+                InitializeBuffer(buffers);
+                InitializeBuffer(_buffer_write);
+            }
+
+            internal byte* ReadBufferForLockFreeBenchmark => (byte*)Volatile.Read(ref _published_buffer);
+
+            internal readonly byte* WriteBufferForLockFreeBenchmark => _buffer_write;
+
+            public void Dispose()
+            {
+                _ = Interlocked.Exchange(ref _published_buffer, 0);
+                _buffer_write = null;
+            }
+
+            /// <summary>
+            ///   Publishes the write buffer. The caller must provide the phase barrier around this
+            ///   operation.
+            /// </summary>
+            public void SwapBuffers()
+            {
+                ulong previousBuffer = Interlocked.Exchange(ref _published_buffer, (ulong)_buffer_write);
+                _buffer_write = (byte*)previousBuffer;
+            }
+
+            /// <summary>
+            ///   Writes to the inactive buffer. The caller must serialize all writes.
+            /// </summary>
+            public bool TryAddOrSet(
+                                 AddressSource key,
+                                 ulong value
+            )
+            {
+                if (Sse42.IsSupported) {
+                    return SwissWriterX86.TryAddOrSet(_buffer_write, key, value, ref _delete_count);
+                }
+
+                throw new NotImplementedException("The Swiss backend is not implemented for this ISA.");
+            }
+
+            /// <summary>
+            ///   Reads the published buffer. The caller must prevent swaps until all reads finish.
+            /// </summary>
+            public bool TryGet(
+                        AddressSource key,
+                        out ulong value
+            )
+            {
+                byte* publishedBuffer = (byte*)Volatile.Read(ref _published_buffer);
+                if (Sse42.IsSupported) {
+                    return SwissReaderX86.TryGet(publishedBuffer, key, out value);
+                }
+
+                throw new NotImplementedException("The Swiss backend is not implemented for this ISA.");
+            }
+
+            public void TryRehash()
+            {
+                if (_delete_count < 2048)
+                {
+                    NativeMemory.Copy(_buffer_write, (byte*)_published_buffer, (nuint)TableBufferSize);
+                    return;
+                }
+                try
+                {
+                    SwissEnumerator e = new((byte*)_published_buffer);
+                    InitializeBuffer(_buffer_write);
+                    if (Sse42.IsSupported)
+                    {
+                        while (e.MoveNext())
+                        {
+                            (AddressSource key, ulong value) = e.Current;
+                            if (!SwissWriterX86.TryAddOrSet(_buffer_write, key, value, ref _delete_count))
+                            {
+                                throw new InvalidOperationException("The Swiss table could not fit all active entries during rehash.");
+                            }
+                        }
+                        _delete_count = 0;
+                    } else
+                    {
+                        throw new PlatformNotSupportedException();
+                    }
+                }
+                catch (Exception)
+                {
+                    NativeMemory.Copy(_buffer_write, (byte*)_published_buffer, (nuint)TableBufferSize);
+                    throw;
+                }
+            }
+
+            /// <summary>
+            ///   Removes from the inactive buffer. The caller must serialize all writes.
+            /// </summary>
+            public bool TryRemove(
+                        AddressSource key,
+                        out ulong value
+            )
+            {
+                if (Sse42.IsSupported)
+                {
+                    return SwissWriterX86.TryRemove(_buffer_write, key, out value, ref _delete_count);
+                } else
+                {
+                    throw new NotImplementedException("The Swiss backend is not implemented for this ISA.");
+                }
+            }
+
+            internal static SwissTable Create(
+                                       byte* buffers
+            )
+            {
+                ArgumentNullException.ThrowIfNull(buffers);
+                return new SwissTable(buffers);
+            }
+
+            private static void InitializeBuffer(
+                                byte* buffer
+            )
+            {
+                Unsafe.InitBlock(buffer, (byte)SwissControl.Empty, IdealCount);
+            }
+
+        }
+
+    }
+}

src/Nitload.Common/HighPerformance/Memory/L4.Swiss_X86.cs

@@ -0,0 +1,240 @@
+// -----------------------------------------------------------------------------
+// file="L4.Swiss_X86"
+// Project: StgSharp
+// Copyright (c) Nitload.
+// SPDX-License-Identifier: MIT
+// -----------------------------------------------------------------------------
+
+using System.Numerics;
+using System.Runtime.CompilerServices;
+using System.Runtime.Intrinsics;
+using System.Runtime.Intrinsics.X86;
+
+namespace Nitload.Common.HighPerformance.Memory
+{
+    public partial class L4
+    {
+
+        private const uint CrcMagic = 0x7f1c9961;
+
+        internal static class SwissHashX64
+        {
+
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            public static uint Compute(
+                               AddressSource key
+            )
+            {
+                ulong hash = CrcMagic;
+                hash = Sse42.X64.Crc32(hash, key.Address);
+                hash = Sse42.X64.Crc32(hash, key.Description);
+                return (uint)hash;
+            }
+
+        }
+
+        internal readonly unsafe struct SwissWriterX86
+        {
+
+            public static bool TryAddOrSet(
+                               byte* buffer,
+                               AddressSource key,
+                               ulong value,
+                               ref int delete_count
+            )
+            {
+                Vector128<byte>* control_bytes = (Vector128<byte>*)buffer;
+                SwissBucket* buckets = (SwissBucket*)(buffer + IdealCount);
+
+                uint hash = SwissHashX64.Compute(key);
+                uint begin = hash % GroupCount;
+
+                uint first_tomb_group = 0;
+                int first_tomb_idx = -1;
+                byte target_hash = (byte)((hash >> GroupCountLog) & ~(1 << 7));
+
+                for (int i = 0; i < GroupCount; i++)
+                {
+                    Vector128<byte>* control_bytes_ptr = control_bytes + begin;
+                    Vector128<byte> control_bytes_v128 = Sse2.LoadAlignedVector128((byte*)control_bytes_ptr);
+
+                    Vector128<byte> target_hash_v128 = Vector128.Create(target_hash);
+                    Vector128<byte> target_empty_v128 = Vector128.Create((byte)SwissControl.Empty);
+                    Vector128<byte> target_tomb_v128 = Vector128.Create((byte)SwissControl.Deleted);
+
+                    Vector128<byte> cmp_hash = Sse2.CompareEqual(control_bytes_v128, target_hash_v128);
+                    Vector128<byte> cmp_empty = Sse2.CompareEqual(control_bytes_v128, target_empty_v128);
+                    Vector128<byte> cmp_tomb = Sse2.CompareEqual(control_bytes_v128, target_tomb_v128);
+
+                    int hash_mask = Sse2.MoveMask(cmp_hash);
+                    int empty_mask = Sse2.MoveMask(cmp_empty);
+                    int tomb_mask = Sse2.MoveMask(cmp_tomb);
+
+                    if (tomb_mask != 0 && first_tomb_idx < 0)
+                    {
+                        int index = BitOperations.TrailingZeroCount(tomb_mask);
+                        first_tomb_group = begin;
+                        first_tomb_idx = index;
+                    }
+                    while (hash_mask != 0)
+                    {
+                        int index = BitOperations.TrailingZeroCount(hash_mask);
+                        SwissBucket* bucket = &buckets[begin];
+                        if (bucket->Keys[index] == key)
+                        {
+                            bucket->Values[index] = value;
+                            return true;
+                        }
+                        hash_mask &= ~(1 << index);
+                    }
+                    while (empty_mask != 0)
+                    {
+                        int index = BitOperations.TrailingZeroCount(empty_mask);
+                        if (first_tomb_idx < 0)
+                        {
+                            SwissBucket* bucket = &buckets[begin];
+                            bucket->Keys[index] = key;
+                            bucket->Values[index] = value;
+                            ((byte*)control_bytes_ptr)[index] = target_hash;
+                        } else
+                        {
+                            SwissBucket* bucket = &buckets[first_tomb_group];
+                            bucket->Keys[first_tomb_idx] = key;
+                            bucket->Values[first_tomb_idx] = value;
+                            ((byte*)(control_bytes + first_tomb_group))[first_tomb_idx] = target_hash;
+                            delete_count--;
+                        }
+                        return true;
+                    }
+
+                    begin = (begin + 1) & (GroupCount - 1);
+                }
+                if (first_tomb_idx >= 0)
+                {
+                    SwissBucket* bucket = &buckets[first_tomb_group];
+                    bucket->Keys[first_tomb_idx] = key;
+                    bucket->Values[first_tomb_idx] = value;
+                    ((byte*)(control_bytes + first_tomb_group))[first_tomb_idx] = target_hash;
+                    delete_count--;
+                    return true;
+                }
+                value = 0;
+                return false;
+            }
+
+            public static bool TryRemove(
+                               byte* buffer,
+                               AddressSource key,
+                               out ulong value,
+                               ref int delete_count
+            )
+            {
+                Vector128<byte>* control_bytes = (Vector128<byte>*)buffer;
+                SwissBucket* buckets = (SwissBucket*)(buffer + IdealCount);
+                uint hash = SwissHashX64.Compute(key);
+                uint begin = hash % GroupCount;
+                byte target_hash = (byte)((hash >> GroupCountLog) & ~(1 << 7));
+
+                for (int i = 0; i < GroupCount; i++)
+                {
+                    Vector128<byte> control_bytes_v128 = Sse2.LoadAlignedVector128((byte*)(control_bytes + begin));
+
+                    Vector128<byte> target_hash_v128 = Vector128.Create(target_hash);
+                    Vector128<byte> cmp_hash = Sse2.CompareEqual(control_bytes_v128, target_hash_v128);
+
+                    int mask = Sse2.MoveMask(cmp_hash);
+
+                    while (mask != 0)
+                    {
+                        int index = BitOperations.TrailingZeroCount(mask);
+                        SwissBucket* bucket = &buckets[begin];
+                        if (bucket->Keys[index] == key)
+                        {
+                            ((byte*)(control_bytes + begin))[index] = (byte)SwissControl.Deleted;
+                            value = bucket->Values[index];
+                            delete_count++;
+                            return true;
+                        }
+                        mask &= ~(1 << index);
+                    }
+
+                    Vector128<byte> target_empty_v128 = Vector128.Create((byte)SwissControl.Empty);
+                    Vector128<byte> cmp_empty = Sse2.CompareEqual(control_bytes_v128, target_empty_v128);
+                    int empty_mask = Sse2.MoveMask(cmp_empty);
+                    if (empty_mask != 0)
+                    {
+                        break;
+                    }
+                    begin = (begin + 1) & (GroupCount - 1);
+                }
+                value = 0;
+                return false;
+            }
+
+        }
+
+        internal readonly unsafe struct SwissReaderX86
+        {
+
+            private static readonly Vector128<byte> _empty_mask = Vector128.Create((byte)SwissControl.Empty);
+            private static readonly Vector128<byte> _tomb_mask = Vector128.Create((byte)SwissControl.Deleted);
+
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            public static int CompareOccupiedMask(
+                              Vector128<byte> control_bytes_v128
+            )
+            {
+                Vector128<byte> cmp_eql = Sse2.CompareEqual(control_bytes_v128, _empty_mask);
+                Vector128<byte> cmp_del = Sse2.CompareEqual(control_bytes_v128, _tomb_mask);
+                int specialMask = Sse2.MoveMask(Sse2.Or(cmp_eql, cmp_del));
+                return (ushort)~(ushort)specialMask;
+            }
+
+            public static bool TryGet(
+                               byte* buffer,
+                               AddressSource key,
+                               out ulong value
+            )
+            {
+                Vector128<byte>* control_bytes = (Vector128<byte>*)buffer;
+                SwissBucket* buckets = (SwissBucket*)(buffer + IdealCount);
+
+                uint hash = SwissHashX64.Compute(key);
+                uint begin = hash % GroupCount;
+                byte target_hash = (byte)((hash >> GroupCountLog) & ~(1 << 7));
+
+                for (int i = 0; i < GroupCount; i++)
+                {
+                    Vector128<byte> control_bytes_v128 = Sse2.LoadAlignedVector128((byte*)(control_bytes + begin));
+                    Vector128<byte> target_hash_v128 = Vector128.Create(target_hash);
+                    Vector128<byte> cmp_hash = Sse2.CompareEqual(control_bytes_v128, target_hash_v128);
+                    int mask = Sse2.MoveMask(cmp_hash);
+                    while (mask != 0)
+                    {
+                        int index = BitOperations.TrailingZeroCount(mask);
+                        SwissBucket* bucket = &buckets[begin];
+                        if (bucket->Keys[index] == key)
+                        {
+                            value = bucket->Values[index];
+                            return true;
+                        }
+                        mask &= ~(1 << index);
+                    }
+
+                    Vector128<byte> target_empty_v128 = Vector128.Create((byte)SwissControl.Empty);
+                    Vector128<byte> cmp_empty = Sse2.CompareEqual(control_bytes_v128, target_empty_v128);
+                    if (Sse2.MoveMask(cmp_empty) != 0)
+                    {
+                        break;
+                    }
+
+                    begin = (begin + 1) & (GroupCount - 1);
+                }
+                value = 0;
+                return false;
+            }
+
+        }
+
+    }
+}

src/Nitload.Common/HighPerformance/Memory/L4.Tlsf.cs

@@ -19,20 +19,21 @@ namespace Nitload.Common.HighPerformance.Memory
     public partial class L4
     {
 
-        private unsafe class TLSF
+        private unsafe struct TLSF
         {
 
             public const int MaxCacheLineCount = 8192;
 
-            public static readonly nuint RequestedAllocation = (nuint)MaxCacheLineCount * CacheLineMetadata.SizeOf;
-
-            private readonly short[] _bucket;
+            public static readonly nuint RequestedAllocation =
+                    ((nuint)MaxCacheLineCount + 1u) * CacheLineMetadata.SizeOf;
             private readonly CacheLineMetadata* _spareMemory;
             private readonly int _align;
             private readonly int _maxLevel;
 
             private int _metadataEnd;
             private readonly Ptr64 _basePtr;
+
+            private fixed short _bucket[64];
             private readonly uint _maxAllocSize;
             private readonly uint _totalSize;
 
@@ -48,7 +49,9 @@ namespace Nitload.Common.HighPerformance.Memory
                 _maxAllocSize = uint.Max(64, (~64U) & (uint.Min(maxBlockSize, CacheLineMetadata.MaxBufferSize) + 63U));
                 _maxLevel = int.MaxValue;
                 _maxLevel = GetLevel(_maxAllocSize);
-                _bucket = new short[GetLevel(_maxAllocSize) + 2];
+
+                // _bucket = new short[GetLevel(_maxAllocSize) + 2];
+                _bucket[63] = (short)(GetLevel(_maxAllocSize) + 2);
                 _spareMemory = (CacheLineMetadata*)(ulong)(_basePtr + _totalSize);
                 _metadataEnd = 0;
 
@@ -268,7 +271,7 @@ namespace Nitload.Common.HighPerformance.Memory
                         idx = candidate->NextLevel;
                     }
                 }
-                for (int i = level + 1; i < _bucket.Length; i++)
+                for (int i = level + 1; i < _bucket[63]; i++)
                 {
                     int idx = _bucket[i];
                     if (idx != 0)

src/Nitload.Common/HighPerformance/Memory/L4.cs

@@ -5,49 +5,20 @@
 // SPDX-License-Identifier: MIT
 // -----------------------------------------------------------------------------
 
-using Nitload.Common.Collections;
-using Nitload.Common.HighPerformance.Memory;
 using Nitload.Common.HighPerformance.ProcessorAbstraction;
-using System.Data;
-using System.Runtime.InteropServices;
 
 namespace Nitload.Common.HighPerformance.Memory
 {
     public sealed unsafe partial class L4 : IDisposable
     {
 
-        private const int CacheLineCount = 8192;
         private const nuint PageSize = 4096;
-        private const int PredictionCount = 2048;
-        private const int PredictionLeastAhead = 1024;
 
-        /// <summary>
-        ///   Array of metadata for each cache line, also used as metadata for tlsf allocator.
-        /// </summary>
-        private readonly CacheLineMetadata* _head;
-        /// <summary>
-        ///   Count of cache lines mapped for each prediction, used for eviction policy.
-        /// </summary>
-        private readonly int* _mapCount;
-        /// <summary>
-        ///   Count of times each cache line is predicted, used for eviction policy.
-        /// </summary>
-        private readonly int* _predictCount;
-        /// <summary>
-        ///   Original memory view for prediction span.
-        /// </summary>
-        private readonly CacheLineDescription* _prediction;
         private bool _disposed;
-        private bool _exhausted;
-
-        private int _aheadCount;
-
         private readonly int _bindedNuma;
-        private volatile int _prefetching;
         private readonly nuint _baseAddress;
-        private readonly SwissTable _map;
-
-        private readonly TLSF _bufferAllocator;
+        private SwissTable _addressMap;
+        private TLSF _bufferAllocator;
 
         public L4(
                int bindedNuma,
@@ -59,130 +30,70 @@ namespace Nitload.Common.HighPerformance.Memory
             ArgumentOutOfRangeException.ThrowIfGreaterThan(bufferSize, CacheLineMetadata.MaxBufferSize);
             ArgumentOutOfRangeException.ThrowIfGreaterThan(maxCacheLineSize, CacheLineMetadata.MaxBufferSize);
             _bindedNuma = bindedNuma;
-
-            // init order is fallow by align requirement of each component.
-            nuint headSize = ((nuint)Unsafe.SizeOf<CacheLineMetadata>()) * CacheLineCount;   // 16 byte align
-            nuint predictionSize = ((nuint)Unsafe.SizeOf<CacheLineDescription>()) * PredictionCount;   //16 byte align
-            nuint mapCountSize = SwissTable.RequestedNativeMemorySize;     // 16 byte align
-            nuint predictionCountSize = sizeof(int) * CacheLineCount;           // 16 byte align
-            nuint normalizedBufferSize = (bufferSize + (PageSize - 1)) & (~(PageSize - 1));    // align to 4096 byte, page size
+            _predict_slow_path_count = GetPredictSlowPathCount(bindedNuma);
+            nuint normalizedBufferSize = (bufferSize + (PageSize - 1)) & (~(PageSize - 1));
             ByteCapacity = normalizedBufferSize;
-
-            AllocSize = headSize + mapCountSize + predictionSize + (predictionCountSize * 2) + normalizedBufferSize;
-
-            // malloc all memory at once, and free at once in Dispose.
-            // This is to avoid fragmentation and improve performance.
+            nuint swissBufferOffset = normalizedBufferSize + TLSF.RequestedAllocation;
+            AllocSize = swissBufferOffset + (nuint)BufferSize;
             _baseAddress = (nuint)Numa.Alloc(bindedNuma, AllocSize);
-            nuint ptr = _baseAddress;
-
-            // init all components with the buffer, and move the buffer pointer forward.
-            nuint _buffer = _baseAddress;
             _bufferAllocator = new TLSF(bufferSize, maxCacheLineSize, (void*)_baseAddress);
-            _buffer += normalizedBufferSize;
-            _head = (CacheLineMetadata*)ptr;
-            ptr += headSize;
-            _prediction = (CacheLineDescription*)ptr;
-            ptr += predictionSize;
-            _map = SwissTable.Create(ptr, _ => { });
-            ptr += mapCountSize;
-            _predictCount = (int*)ptr;
-            ptr += predictionCountSize;
-            _mapCount = (int*)ptr;
-            ptr += predictionCountSize;
-
-            M512* mPtr = (M512*)_head;
-            for (uint i = 1; i < CacheLineCount; i++) {
-                mPtr->BroadCastFrom<ulong>(0);
-            }
+            _addressMap = SwissTable.Create((byte*)(_baseAddress + swissBufferOffset));
         }
 
         public nuint ByteCapacity { get; init; }
 
         public nuint AllocSize { get; init; }
 
-        // public IL4Predict PrefetchPredict { get; set; }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void ContinueOnce(
-                    Handle line
-        )
-        {
-            if (line.Address > 0) {
-                _ = Interlocked.Decrement(ref _aheadCount);
-            }
-        }
-
-        [System.Diagnostics.CodeAnalysis.SuppressMessage(
-                "Design",
-                "CA1063:Implement IDisposable correctly",
-                Justification = """
-                    Only owns native memory via Numa.Free();
-                    no managed IDisposable fields.
-                    Dispose(bool) pattern is unnecessary.
-                    """)]
         public void Dispose()
         {
             if (_disposed) {
                 return;
             }
             _disposed = true;
-            _map.Dispose();
-#pragma warning disable CA1816
-            GC.SuppressFinalize(_bufferAllocator);
-#pragma warning restore CA1816
-
-
-            // init order is fallow by align requirement of each component.
+            _addressMap.Dispose();
             Numa.Free((void*)_baseAddress, _bindedNuma, AllocSize);
             GC.SuppressFinalize(this);
         }
 
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public Handle Map(
-                      ref CacheLineDescription prediction
-        )
+        public partial Handle Map(
+                              AddressSource source
+        );
+
+        internal void Collect()
         {
-            if ((_aheadCount < PredictionLeastAhead) && !_exhausted)
-            {
-                if (Interlocked.CompareExchange(ref _prefetching, 1, 0) == 0)
-                {
-                    try
-                    {
-                        if (_aheadCount < PredictionLeastAhead)
-                        {
-                            // do prefetch in work load now, sync
-                            Prefetch();
-                        }
-                    }
-                    finally
-                    {
-                        _prefetching = 0;
-                    }
-                }
-            }
-            while (true)
-            {
-                if (_map.TryGet(prediction.GetHashCodeLong(), out nuint entryHandle))
-                {
-                    // cache hit
-                    CacheLineMetadata* entry = (CacheLineMetadata*)entryHandle;
-                    if (Interlocked.Increment(ref entry->RefCount) > 0)
-                    {
-                        _predictCount[entry - _head] = 0;
-                        _ = Interlocked.Decrement(ref _aheadCount);
-                        _ = Interlocked.Decrement(ref _mapCount[entry - _head]);
-                        nuint* hPtr = stackalloc nuint[2] { entry->PositionMask + _baseAddress, (nuint)entry };
-                        return *(Handle*)hPtr;
-                    } else
-                    {
-                        _ = Interlocked.Decrement(ref entry->RefCount);
-                    }
-                }
-                Thread.Sleep(0);
-            }
+            ObjectDisposedException.ThrowIf(_disposed, this);
+            _bufferAllocator.Collect();
         }
 
-        private partial void Prefetch();
+        internal void Free(
+                      int handle
+        )
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+            _bufferAllocator.Free(handle);
+        }
+
+        internal bool TryAllocate(
+                      uint size,
+                      out int handle
+        )
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+            return _bufferAllocator.TryAlloc(size, out handle);
+        }
+
+        internal partial int Predict();
+
+        private static int GetPredictSlowPathCount(int bindedNuma)
+        {
+            foreach (NumaNode node in Numa.AllNumaNode)
+            {
+                if (node.NumaNodeId == (uint)bindedNuma)
+                    return checked(node.LogicalCoreCount * 2);
+            }
+
+            throw new ArgumentOutOfRangeException(nameof(bindedNuma), "No topology information exists for the bound NUMA node.");
+        }
 
     }
 }

src/Nitload.Common/HighPerformance/Memory/L4Predictor.cs

@@ -0,0 +1,37 @@
+// -----------------------------------------------------------------------------
+// file="L4Predictor"
+// Project: StgSharp
+// Copyright (c) Nitload.
+// SPDX-License-Identifier: MIT
+// -----------------------------------------------------------------------------
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace Nitload.Common.HighPerformance.Memory
+{
+    public interface IL4Predictor
+    {
+
+        int Id { get; set; }
+
+        int PredictMission(
+            in Span<L4.AddressSource> RequiredBuffer
+        );
+
+    }
+
+    public interface IL4Predictor<TMission> : IL4Predictor
+    {
+
+        bool TryGetNextMission(
+             out TMission mission
+        );
+
+    }
+
+    internal class PredictorMonitor { }
+}

src/Nitload.Common/HighPerformance/ProcessorAbstraction/LogicalCore.cs

@@ -16,22 +16,21 @@ namespace Nitload.Common.HighPerformance.ProcessorAbstraction
     public readonly struct LogicalCore
     {
 
-        public readonly uint GlobalCpuId;
-        public readonly uint NumaGroupId;
-
-        /// <summary>
-        ///   Stays 0 on linux.
-        /// </summary>
+        public readonly uint ProcessorGroupId;
+        public readonly uint SocketId;
+        public readonly uint CpuIndex;
         public readonly uint NumaNodeId;
 
         internal LogicalCore(
-                 uint globalCpuId,
-                 uint numaGroupId,
+                 uint processorGroupId,
+                 uint socketId,
+                 uint cpuIndex,
                  uint numaNodeId
         )
         {
-            GlobalCpuId = globalCpuId;
-            NumaGroupId = numaGroupId;
+            ProcessorGroupId = processorGroupId;
+            SocketId = socketId;
+            CpuIndex = cpuIndex;
             NumaNodeId = numaNodeId;
         }
 

src/Nitload.Common/HighPerformance/ProcessorAbstraction/Numa.cs

@@ -33,7 +33,7 @@ namespace Nitload.Common.HighPerformance.ProcessorAbstraction
             if (_numaNodes.Length == 0) {
                 throw new InvalidOperationException("Numa info has not been loaded.");
             }
-            if ((numaId < 0) || (numaId >= _numaNodes.Length)) {
+            if ((numaId < 0) || !ContainsNode((uint)numaId)) {
                 throw new ArgumentOutOfRangeException(nameof(numaId), "Invalid NUMA node ID.");
             }
             return NumaAllocNative(size, numaId);
@@ -69,22 +69,24 @@ namespace Nitload.Common.HighPerformance.ProcessorAbstraction
             if (_numaNodes.Length == 0) {
                 throw new InvalidOperationException("Numa info has not been loaded.");
             }
-            if ((numaId < 0) || (numaId >= _numaNodes.Length)) {
+            if ((numaId < 0) || !ContainsNode((uint)numaId)) {
                 throw new ArgumentOutOfRangeException(nameof(numaId), "Invalid NUMA node ID.");
             }
             NumaFreeNative(address, size, numaId);
         }
 
-        [LibraryImport(Native.LibName, EntryPoint = "nif_get_numa_each")]
+        [LibraryImport(Native.LibName, EntryPoint = "nfn_get_numa_each")]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         [DefaultDllImportSearchPaths(DllImportSearchPath.AssemblyDirectory)]
         public static partial int GetNumaEach(
                                   uint numaId,
-                                  Span<ulong> CpuIndexInNuma,
-                                  Span<uint> globalCpuIdInNuma
+                                  Span<uint> processorGroupIds,
+                                  Span<uint> socketIds,
+                                  Span<uint> cpuIndices,
+                                  Span<uint> numaNodeIds
         );
 
-        [LibraryImport(Native.LibName, EntryPoint = "nif_get_numa_overall")]
+        [LibraryImport(Native.LibName, EntryPoint = "nfn_get_numa_overall")]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         [DefaultDllImportSearchPaths(DllImportSearchPath.AssemblyDirectory)]
         public static partial int GetNumaOverall(
@@ -97,10 +99,10 @@ namespace Nitload.Common.HighPerformance.ProcessorAbstraction
             if (_numaNodes.Length == 0) {
                 throw new InvalidOperationException("Numa info has not been loaded.");
             }
-            L4[] buffers = new L4[NumaNodeCount];
-            for (int i = 0; i < NumaNodeCount; i++)
+            L4[] buffers = new L4[_numaNodes.Length];
+            for (int i = 0; i < _numaNodes.Length; i++)
             {
-                L4 buffer = new L4(i);
+                L4 buffer = new L4((int)_numaNodes[i].NumaNodeId);
                 buffers[i] = buffer;
             }
             return buffers;
@@ -108,23 +110,38 @@ namespace Nitload.Common.HighPerformance.ProcessorAbstraction
 
         internal static void Initialize()
         {
-            Span<int> coreCountInNuma = stackalloc int[(Environment.ProcessorCount / 32) + 1];
             int numaNodeCount = 0;
-            if (0 == GetNumaOverall(ref numaNodeCount, coreCountInNuma)) {
+            if (0 == GetNumaOverall(ref numaNodeCount, default)) {
                 throw new InvalidOperationException("Failed to get NUMA overall information.");
             }
-            _numaNodes = new NumaNode[numaNodeCount];
-            for (uint i = 0; i < numaNodeCount; i++) {
-                _numaNodes[i] = InitNumaNode(i, coreCountInNuma[(int)i]);
+            int[] coreCountInNuma = new int[numaNodeCount];
+            if (0 == GetNumaOverall(ref numaNodeCount, coreCountInNuma)) {
+                throw new InvalidOperationException("Failed to get NUMA node processor counts.");
+            }
+            int activeNodeCount = 0;
+            for (int i = 0; i < coreCountInNuma.Length; i++) {
+                if (coreCountInNuma[i] > 0) {
+                    activeNodeCount++;
+                }
+            }
+            NumaNodeCount = activeNodeCount;
+            _numaNodes = new NumaNode[activeNodeCount];
+            int nodeIndex = 0;
+            for (uint numaId = 0; numaId < numaNodeCount; numaId++) {
+                int coreCount = coreCountInNuma[(int)numaId];
+                if (coreCount == 0) {
+                    continue;
+                }
+                _numaNodes[nodeIndex++] = InitNumaNode(numaId, coreCount);
             }
         }
 
-        [LibraryImport(Native.LibName, EntryPoint = "nif_set_thread_affinity")]
+        [LibraryImport(Native.LibName, EntryPoint = "nfn_set_thread_affinity")]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         [DefaultDllImportSearchPaths(DllImportSearchPath.AssemblyDirectory)]
         internal static partial void SetThreadAffinity(
-                                     int coreId,
-                                     int numaId
+                                     int cpuIndex,
+                                     int processorGroupId
         );
 
         [MethodImpl(MethodImplOptions.NoInlining)]
@@ -133,12 +150,27 @@ namespace Nitload.Common.HighPerformance.ProcessorAbstraction
                                 int count
         )
         {
-            Span<uint> globalIndex = stackalloc uint[count];
-            _ = GetNumaEach(numaId, null, globalIndex);
-            return new(numaId, count, globalIndex);
+            Span<uint> processorGroupIds = stackalloc uint[count];
+            Span<uint> socketIds = stackalloc uint[count];
+            Span<uint> cpuIndices = stackalloc uint[count];
+            Span<uint> numaNodeIds = stackalloc uint[count];
+            if (0 == GetNumaEach(numaId, processorGroupIds, socketIds, cpuIndices, numaNodeIds)) {
+                throw new InvalidOperationException($"Failed to enumerate processors for NUMA node {numaId}.");
+            }
+            return new(numaId, count, processorGroupIds, socketIds, cpuIndices, numaNodeIds);
         }
 
-        [LibraryImport(Native.LibName, EntryPoint = "nif_numa_alloc")]
+        private static bool ContainsNode(uint numaId)
+        {
+            foreach (NumaNode node in _numaNodes) {
+                if (node.NumaNodeId == numaId) {
+                    return true;
+                }
+            }
+            return false;
+        }
+
+        [LibraryImport(Native.LibName, EntryPoint = "nfn_numa_alloc")]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         [DefaultDllImportSearchPaths(DllImportSearchPath.AssemblyDirectory)]
         private static unsafe partial void* NumaAllocNative(
@@ -146,7 +178,7 @@ namespace Nitload.Common.HighPerformance.ProcessorAbstraction
                                             int numaId
         );
 
-        [LibraryImport(Native.LibName, EntryPoint = "nif_numa_free")]
+        [LibraryImport(Native.LibName, EntryPoint = "nfn_numa_free")]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         [DefaultDllImportSearchPaths(DllImportSearchPath.AssemblyDirectory)]
         private static unsafe partial void NumaFreeNative(

src/Nitload.Common/HighPerformance/ProcessorAbstraction/NumaNode.cs

@@ -22,16 +22,26 @@ namespace Nitload.Common.HighPerformance.ProcessorAbstraction
         internal NumaNode(
                  uint numaId,
                  int count,
-                 Span<uint> logicalCoreIds
+                 Span<uint> processorGroupIds,
+                 Span<uint> socketIds,
+                 Span<uint> cpuIndices,
+                 Span<uint> numaNodeIds
 
         )
         {
+            NumaNodeId = numaId;
             _logicalCores = new LogicalCore[count];
             for (int i = 0; i < count; i++) {
-                _logicalCores[i] = new LogicalCore(1, numaId, logicalCoreIds[i]);
+                _logicalCores[i] = new LogicalCore(
+                    processorGroupIds[i],
+                    socketIds[i],
+                    cpuIndices[i],
+                    numaNodeIds[i]);
             }
         }
 
+        public uint NumaNodeId { get; }
+
         public int LogicalCoreCount => _logicalCores.Length;
 
         public ReadOnlySpan<LogicalCore> LogicalCores => _logicalCores;

src/Nitload.Common/Threading/ThreadHelper.cs

@@ -37,7 +37,7 @@ namespace Nitload.Threading
                            LogicalCore core
         )
         {
-            SetThreadAffinity(core.GlobalCpuId, core.NumaNodeId);
+            SetThreadAffinity(core.CpuIndex, core.ProcessorGroupId);
         }
 
         [Conditional("DEBUG")]
@@ -51,12 +51,12 @@ namespace Nitload.Threading
 
 #pragma warning disable CA5393
 
-        [LibraryImport(Native.LibName, EntryPoint = "nif_set_thread_affinity")]
+        [LibraryImport(Native.LibName, EntryPoint = "nfn_set_thread_affinity")]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         [DefaultDllImportSearchPaths(DllImportSearchPath.AssemblyDirectory)]
         private static partial void SetThreadAffinity(
-                                    uint globalCoreId,
-                                    uint numaNodeId
+                                    uint cpuIndex,
+                                    uint processorGroupId
         );
 
 #pragma warning restore CA5393

src/Nitload.Common/Timing/StgSharpTime.cs

@@ -97,7 +97,7 @@ namespace Nitload
             }
 
             Thread.Sleep(10);
-            Numa.SetThreadAffinity((int)threadConfig.BindedCoreIndex, (int)threadConfig.BindedNumaNode);
+            Numa.SetThreadAffinity((int)threadConfig.CpuIndex, (int)threadConfig.ProcessorGroupId);
             while (mainProvider.IsRunning)
             {
                 long elapsedTicks;

src/Nitload.Common/Timing/TimeSourceProvider.cs

@@ -14,15 +14,15 @@ using System.Threading;
 namespace Nitload.Common.Timing
 {
     public class TimeSourceStartupConfiguration(
-                 nuint bindedNumaNode = 0,
-                 nuint bindedCoreIndex = 0,
+                 nuint processorGroupId = 0,
+                 nuint cpuIndex = 0,
                  ThreadPriority threadPriority = ThreadPriority.Highest
     )
     {
 
-        public nuint BindedNumaNode { get; } = bindedNumaNode;
+        public nuint ProcessorGroupId { get; } = processorGroupId;
 
-        public nuint BindedCoreIndex { get; } = bindedCoreIndex;
+        public nuint CpuIndex { get; } = cpuIndex;
 
         public ThreadPriority Priority { get; } = threadPriority;
 

src/Nitload.Graphics/Camera.cs

@@ -15,11 +15,11 @@ namespace Nitload.Mathematics.Numeric.Graphics
     {
 
         private bool _isLookAtAvailable;
-        internal GraphicsMatrix _lookAt;
-        internal GraphicsMatrix _projection;
-        internal GraphicsMatrix cameraAtt;
-        internal GraphicsMatrix rotation;
-        internal GraphicsMatrix rotationAtt;
+        internal GMatrix44<float> _lookAt;
+        internal GMatrix44<float> _projection;
+        internal GMatrix44<float> cameraAtt;
+        internal GMatrix44<float> rotation;
+        internal GMatrix44<float> rotationAtt;
         internal Radius _pitch;
         internal Radius _row;
         internal Radius _yaw;
@@ -27,13 +27,13 @@ namespace Nitload.Mathematics.Numeric.Graphics
 
         public Camera()
         {
-            cameraAtt = GraphicsMatrix.Unit;
+            cameraAtt = GMatrix44<float>.Unit;
             _target = Vec3<float>.Zero;
             up = Vec3<float>.Zero;
             _isLookAtAvailable = false;
-            _lookAt = GraphicsMatrix.Unit;
-            rotationAtt = GraphicsMatrix.Unit;
-            _projection = new GraphicsMatrix();
+            _lookAt = GMatrix44<float>.Unit;
+            rotationAtt = GMatrix44<float>.Unit;
+            _projection = new GMatrix44<float>();
         }
 
         public Camera(
@@ -43,32 +43,32 @@ namespace Nitload.Mathematics.Numeric.Graphics
         )
             : this()
         {
-            rotationAtt = GraphicsMatrix.Unit;
-            cameraAtt = new GraphicsMatrix();
+            rotationAtt = GMatrix44<float>.Unit;
+            cameraAtt = new GMatrix44<float>();
             SetViewDirection(position, target, up);
             _pitch = Radius.Zero;
             _row = Radius.Zero;
             _yaw = Radius.Zero;
         }
 
-        public GraphicsMatrix Projection => _projection;
+        public GMatrix44<float> Projection => _projection;
 
-        public GraphicsMatrix View
+        public GMatrix44<float> View
         {
             get
             {
                 if (_isLookAtAvailable) {
                     return _lookAt;
                 }
-                GraphicsMatrix move = GraphicsMatrix.Unit;
-                move.column[3] -= cameraAtt.column[3];
+                GMatrix44<float> move = GMatrix44<float>.Unit;
+                move[3] = move[3] - cameraAtt[3];
                 _lookAt = rotationAtt.Transpose * move;
                 _isLookAtAvailable = true;
                 return _lookAt;
             }
         }
 
-        public GraphicsMatrix CameraMatrix()
+        public GMatrix44<float> CameraMatrix()
         {
             return Projection * View;
         }
@@ -77,7 +77,7 @@ namespace Nitload.Mathematics.Numeric.Graphics
                     float distance
         )
         {
-            cameraAtt.column[3].Z -= distance;
+            cameraAtt[3, 2] -= distance;
             _isLookAtAvailable = false;
         }
 
@@ -85,7 +85,7 @@ namespace Nitload.Mathematics.Numeric.Graphics
                     float distance
         )
         {
-            cameraAtt.column[3].X -= distance;
+            cameraAtt[3, 0] -= distance;
             _isLookAtAvailable = false;
         }
 
@@ -93,7 +93,7 @@ namespace Nitload.Mathematics.Numeric.Graphics
                     float distance
         )
         {
-            cameraAtt.column[3].Y -= distance;
+            cameraAtt[3, 1] -= distance;
             _isLookAtAvailable = false;
         }
 
@@ -104,9 +104,9 @@ namespace Nitload.Mathematics.Numeric.Graphics
         )
         {
             Vec3<float> direction = position - target;
-            if ((position == cameraAtt.column[3].XYZ) &&
+            if ((position == new Vec3<float>(cameraAtt[3, 0], cameraAtt[3, 1], cameraAtt[3, 2])) &&
                 (this.up == up) &&
-                (cameraAtt.column[3].XYZ == direction)) {
+                (new Vec3<float>(cameraAtt[3, 0], cameraAtt[3, 1], cameraAtt[3, 2]) == direction)) {
                 return;
             }
             if (direction.GetLength() == 0)
@@ -126,10 +126,10 @@ namespace Nitload.Mathematics.Numeric.Graphics
 
             Vec3<float> right = Linear.Orthogonalize(Vec3.Cross(up, direction));
 
-            cameraAtt.column[0].XYZ = right;
-            cameraAtt.column[1].XYZ = up;
-            cameraAtt.column[2].XYZ = direction;
-            cameraAtt.column[3].XYZ = position;
+            cameraAtt[0] = new Vec4<float>(right, 0);
+            cameraAtt[1] = new Vec4<float>(up, 0);
+            cameraAtt[2] = new Vec4<float>(direction, 0);
+            cameraAtt[3] = new Vec4<float>(position, 1);
 
             InternalPitch();
             InternalRow();
@@ -152,13 +152,13 @@ namespace Nitload.Mathematics.Numeric.Graphics
                 width = MathF.Abs(GeometryScaler.Tan(fovRadius / 2) * near * 2),
                 height = (width * size.Y) / size.X;
 
-            _projection.column[0].X = (2 * near) / width;
-            _projection.column[1].Y = (2 * near) / height;
-            _projection.column[2].X = (2 * offsetX) / width;
-            _projection.column[2].Y = (2 * offsetY) / height;
-            _projection.column[2].Z = (far + near) / (near - far);
-            _projection.column[2].W = -1;
-            _projection.column[3].Z = (2 * near * far) / (near - far);
+            _projection[0].X = (2 * near) / width;
+            _projection[1].Y = (2 * near) / height;
+            _projection[2].X = (2 * offsetX) / width;
+            _projection[2].Y = (2 * offsetY) / height;
+            _projection[2].Z = (far + near) / (near - far);
+            _projection[2].W = -1;
+            _projection[3].Z = (2 * near * far) / (near - far);
         }
 
         public void Test(

src/Nitload.Graphics/OpenGL/Buffer/EBO.cs

@@ -1,21 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="EBO"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-namespace Nitload.Graphics.OpenGL
-{
-    /// <summary>A set of OpenGL element-buffer handles.</summary>
-    public sealed record class ElementBuffer(
-        GlHandle[] Handles
-    )
-    {
-
-        public int Count => Handles.Length;
-
-        public GlHandle this[int index] => Handles[index];
-
-    }
-}

src/Nitload.Graphics/OpenGL/Buffer/FBO.cs

@@ -1,21 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="FBO"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-namespace Nitload.Graphics.OpenGL
-{
-    /// <summary>A set of OpenGL framebuffer handles.</summary>
-    public sealed record class FrameBuffer(
-        GlHandle[] Handles
-    )
-    {
-
-        public int Count => Handles.Length;
-
-        public GlHandle this[int index] => Handles[index];
-
-    }
-}

src/Nitload.Graphics/OpenGL/Buffer/RBO.cs

@@ -1,21 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="RBO"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-namespace Nitload.Graphics.OpenGL
-{
-    /// <summary>A set of OpenGL renderbuffer handles.</summary>
-    public sealed record class RenderBuffer(
-        GlHandle[] Handles
-    )
-    {
-
-        public int Count => Handles.Length;
-
-        public GlHandle this[int index] => Handles[index];
-
-    }
-}

src/Nitload.Graphics/OpenGL/Buffer/TextureGL.cs

@@ -1,54 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="TextureGL"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-namespace Nitload.Graphics.OpenGL
-{
-    /// <summary>A set of OpenGL texture handles.</summary>
-    public sealed record class TextureGL(
-        GlHandle[] Handles
-    )
-    {
-
-        public int Count => Handles.Length;
-
-        public GlHandle this[int index] => Handles[index];
-
-    }
-
-    public readonly record struct TextureProperty(
-        TextureFilter FilterOnMagnify,
-        TextureFilter FilterOnMinify,
-        TextureWrap WrapOnHorizontal,
-        TextureWrap WrapOnVertical
-    );
-
-    #pragma warning disable CA1008
-    public enum TextureFilter
-    #pragma warning restore CA1008
-    {
-
-        Nearest = glConst.NEAREST,
-        Linear = glConst.LINEAR,
-        NearestLinearMipmap = glConst.NEAREST_MIPMAP_LINEAR,
-        LinearLinearMipmap = glConst.LINEAR_MIPMAP_LINEAR,
-        NearestNearestMipmap = glConst.NEAREST_MIPMAP_NEAREST,
-        LinearNearestMipmap = glConst.LINEAR_MIPMAP_NEAREST,
-
-    }
-
-    #pragma warning disable CA1008
-    public enum TextureWrap
-    #pragma warning restore CA1008
-    {
-
-        Repeat = glConst.REPEAT,
-        MirroredRepeat = glConst.MIRRORED_REPEAT,
-        ClampToEdge = glConst.CLAMP_TO_EDGE,
-        ClampToBorder = glConst.CLAMP_TO_BORDER,
-
-    }
-}

src/Nitload.Graphics/OpenGL/Buffer/VAO.cs

@@ -1,21 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="VAO"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-namespace Nitload.Graphics.OpenGL
-{
-    /// <summary>A set of OpenGL vertex-array handles.</summary>
-    public sealed record class VertexArray(
-        GlHandle[] Handles
-    )
-    {
-
-        public int Count => Handles.Length;
-
-        public GlHandle this[int index] => Handles[index];
-
-    }
-}

src/Nitload.Graphics/OpenGL/Buffer/VBO.cs

@@ -1,21 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="VBO"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-namespace Nitload.Graphics.OpenGL
-{
-    /// <summary>A set of OpenGL vertex-buffer handles.</summary>
-    public sealed record class VertexBuffer(
-        GlHandle[] Handles
-    )
-    {
-
-        public int Count => Handles.Length;
-
-        public GlHandle this[int index] => Handles[index];
-
-    }
-}

src/Nitload.Graphics/OpenGL/Generated/OpenGLFunction.Base.g.cs

@@ -1783,10 +1783,11 @@ namespace Nitload.Graphics.OpenGL
         /// <para>See <see href="https://docs.gl/gl4/glUniform">docs.gl</see>.</para>
         /// </summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Uniform(int location, bool transpose, GraphicsMatrix value)
+        public void Uniform(int location, bool transpose, GMatrix44<float> value)
         {
-            __context->glUniformMatrix4fv(location, 1, transpose ? (byte)1 : (byte)0, (float*)&value);
+                __context->glUniformMatrix4fv(location, 1, transpose ? (byte)1 : (byte)0, (float*)&value);
         }
+        
 
         /// <summary>
         /// <para>Forwards to the native OpenGL entry point.</para>
@@ -1794,9 +1795,9 @@ namespace Nitload.Graphics.OpenGL
         /// <para>See <see href="https://docs.gl/gl4/glUniform">docs.gl</see>.</para>
         /// </summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Uniform(int location, bool transpose, ReadOnlySpan<GraphicsMatrix> values)
+        public void Uniform(int location, bool transpose, ReadOnlySpan<GMatrix44<float>> values)
         {
-            fixed (GraphicsMatrix* __value = values)
+            fixed (GMatrix44<float>* __value = values)
             {
                 __context->glUniformMatrix4fv(location, values.Length, transpose ? (byte)1 : (byte)0, (float*)__value);
             }

src/Nitload.Graphics/OpenGL/Generated/OpenGLFunction.v4_1.g.cs

@@ -631,10 +631,11 @@ namespace Nitload.Graphics.OpenGL
         /// <para>See <see href="https://docs.gl/gl4/glProgramUniform">docs.gl</see>.</para>
         /// </summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void ProgramUniform(GlHandle program, int location, bool transpose, GraphicsMatrix value)
+        public void ProgramUniform(GlHandle program, int location, bool transpose, GMatrix44<float> value)
         {
-            __context->glProgramUniformMatrix4fv(program.Value, location, 1, transpose ? (byte)1 : (byte)0, (float*)&value);
-        }
+                __context->glProgramUniformMatrix4fv(program.Value, location, 1, transpose ? (byte)1 : (byte)0, (float*)&value);
+            }
+        
 
         /// <summary>
         /// <para>Forwards to the native OpenGL entry point.</para>
@@ -642,9 +643,9 @@ namespace Nitload.Graphics.OpenGL
         /// <para>See <see href="https://docs.gl/gl4/glProgramUniform">docs.gl</see>.</para>
         /// </summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void ProgramUniform(GlHandle program, int location, bool transpose, ReadOnlySpan<GraphicsMatrix> values)
+        public void ProgramUniform(GlHandle program, int location, bool transpose, ReadOnlySpan<GMatrix44<float>> values)
         {
-            fixed (GraphicsMatrix* __value = values)
+            fixed (GMatrix44<float>* __value = values)
             {
                 __context->glProgramUniformMatrix4fv(program.Value, location, values.Length, transpose ? (byte)1 : (byte)0, (float*)__value);
             }

src/Nitload.Graphics/OpenGL/glRenderStream.cs

@@ -42,10 +42,11 @@ namespace Nitload.Graphics.OpenGL
             {
                 ContextHandle = Marshal.AllocHGlobal(Marshal.SizeOf<OpenglContext>());
                 OpenglContext* contextID = (OpenglContext*)ContextHandle;
-                contextID->glGetString = (delegate*<uint,byte*>)IntPtr.Zero;
+                contextID->glGetString = (delegate* unmanaged[Cdecl]<uint,byte*>)IntPtr.Zero;
             }
-            if (GL == null) {
-                _context = OpenGLFunction.BuildGlFunctionPackage(ContextHandle);
+            if (GL == null)
+            {
+                // _context = OpenGLFunction.BuildGlFunctionPackage(ContextHandle);
             }
         }
 
@@ -60,7 +61,8 @@ namespace Nitload.Graphics.OpenGL
         public unsafe void MakeAsCurrentContext()
         {
             GraphicFramework.glfwMakeContextCurrent(CanvasHandle);
-            OpenGLFunction.CurrentGL = this.GL;
+
+            // OpenGLFunction.CurrentGL = this.GL;
         }
 
         /// <inheritdoc />
@@ -73,7 +75,8 @@ namespace Nitload.Graphics.OpenGL
             SwapBuffers();
             renderToThread[this] = ThreadHelper.EmptyThread;
             GraphicFramework.glfwMakeContextCurrent(IntPtr.Zero);
-            OpenGLFunction.CurrentGL = null;
+
+            // OpenGLFunction.CurrentGL = null;
         }
 
         /// <inheritdoc />
@@ -121,7 +124,7 @@ namespace Nitload.Graphics.OpenGL
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         protected sealed override void NativeCameraViewRange(
                                        Radius fieldOfRange,
-                                       Vec2 offset,
+                                       Vec2<float> offset,
                                        (float frontDepth, float backDepth) viewDepth
         )
         {
@@ -130,9 +133,9 @@ namespace Nitload.Graphics.OpenGL
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         protected sealed override void NativeCameraViewTarget(
-                                       Vec3 position,
-                                       Vec3 direction,
-                                       Vec3 up
+                                       Vec3<float> position,
+                                       Vec3<float> direction,
+                                       Vec3<float> up
         )
         {
             NativeCamera.SetViewDirection(position, direction, up);

src/Nitload.Graphics/PlainGeometryMesh.cs

@@ -16,14 +16,15 @@ namespace Nitload.Graphics
     public class PlainGeometryMesh
     {
 
-        private readonly PlainGeometry _shape;
-        private readonly Vec2[] _textureCoordinates;
+        private readonly Vec2<float>[] _textureCoordinates;
         private readonly Image<Rgba8> _textureImage;
 
+        private readonly PlainGeometry _shape;
+
         public PlainGeometryMesh(
                PlainGeometry shape,
                Image<Rgba8> texture,
-               Vec2[] texCoord
+               Vec2<float>[] texCoord
         )
         {
             ArgumentNullException.ThrowIfNull(shape);
@@ -40,14 +41,13 @@ namespace Nitload.Graphics
             _textureCoordinates = texCoord;
         }
 
-        public Vec4[] VertexArray => _shape.VertexStream;
+        public Vec3<float>[] VertexArray => _shape.VertexStream;
 
         public Image<Rgba8> TextureImage => _textureImage;
 
         public ReadOnlySpan<int> MeshIndices => _shape.VertexIndices;
 
-        public ReadOnlySpan<Vec4> TextureCoord => MemoryMarshal.Cast<Vec2, Vec4>(
-            _textureCoordinates);
+        public ReadOnlySpan<Vec2<float>> TextureCoord => _textureCoordinates;
 
         public PlainGeometryMesh Resize(
                                  PlainGeometry newShape

src/Nitload.Graphics/RenderStream.cs

@@ -5,10 +5,10 @@
 // SPDX-License-Identifier: MIT
 // -----------------------------------------------------------------------------
 
+using Nitload.Common.Timing;
 using Nitload.Mathematics;
 using Nitload.Mathematics.Numeric.Graphics;
 using Nitload.Mathematics.Numeric.Graphics;
-using Nitload.Common.Timing;
 
 using System;
 using System.Collections.Generic;
@@ -123,14 +123,14 @@ namespace Nitload.Graphics
 
         protected abstract void NativeCameraViewRange(
                                 Radius fieldOfRange,
-                                Vec2 offset,
+                                Vec2<float> offset,
                                 (float frontDepth, float backDepth) viewDepth
         );
 
         protected abstract void NativeCameraViewTarget(
-                                Vec3 position,
-                                Vec3 direction,
-                                Vec3 up
+                                Vec3<float> position,
+                                Vec3<float> direction,
+                                Vec3<float> up
         );
 
         #endregion

src/Nitload.Graphics/glfw.cs

@@ -43,7 +43,7 @@ namespace Nitload.Graphics
 
         public static GLFWFunction glfwContext => _glfw;
 
-        [LibraryImport(Native.LibName, EntryPoint = "nif_load_glfw_functions")]
+        [LibraryImport(Native.LibName, EntryPoint = "nfn_load_glfw_functions")]
         internal static unsafe partial void glfwLoadLibrary(
                                             GLFWFunction* context
         );

src/Nitload.Mathematics/Geometries/Coordination/CoordinationBase.cs

@@ -16,41 +16,61 @@ namespace Nitload.Geometries
 
         private bool globalCoordAvailable;
         private CoordinationBase localCoordination;
-        private GraphicsMatrix coordMat;
+        private GMatrix44<float> coordMat;
 
         public CoordinationBase(
                CoordinationBase localCoordination
         )
         {
             this.localCoordination = localCoordination;
-            coordMat = new GraphicsMatrix();
+            coordMat = new GMatrix44<float>();
         }
 
         public virtual Point LocalOrigin
         {
-            get => new Point(coordMat.column[3].XYZ);
-            internal set => coordMat.column[3].XYZ = value.Coord;
+            get => new Point(new Vec3<float>(coordMat[3, 0], coordMat[3, 1], coordMat[3, 2]));
+            internal set
+            {
+                coordMat[3, 0] = value.Coord.X;
+                coordMat[3, 1] = value.Coord.Y;
+                coordMat[3, 2] = value.Coord.Z;
+            }
         }
 
-        public virtual Vec3 LocalX
+        public virtual Vec3<float> LocalX
         {
-            get => coordMat.column[3].XYZ;
-            internal set => coordMat.column[3].XYZ = value;
+            get => new Vec3<float>(coordMat[3, 0], coordMat[3, 1], coordMat[3, 2]);
+            internal set
+            {
+                coordMat[3, 0] = value.X;
+                coordMat[3, 1] = value.Y;
+                coordMat[3, 2] = value.Z;
+            }
         }
 
-        public virtual Vec3 LocalY
+        public virtual Vec3<float> LocalY
         {
-            get => coordMat.column[3].XYZ;
-            internal set => coordMat.column[3].XYZ = value;
+            get => new Vec3<float>(coordMat[3, 0], coordMat[3, 1], coordMat[3, 2]);
+            internal set
+            {
+                coordMat[3, 0] = value.X;
+                coordMat[3, 1] = value.Y;
+                coordMat[3, 2] = value.Z;
+            }
         }
 
-        public virtual Vec3 LocalZ
+        public virtual Vec3<float> LocalZ
         {
-            get => coordMat.column[3].XYZ;
-            set => coordMat.column[3].XYZ = value;
+            get => new Vec3<float>(coordMat[3, 0], coordMat[3, 1], coordMat[3, 2]);
+            set
+            {
+                coordMat[3, 0] = value.X;
+                coordMat[3, 1] = value.Y;
+                coordMat[3, 2] = value.Z;
+            }
         }
 
-        protected ref GraphicsMatrix CoordMat => ref coordMat;
+        protected ref GMatrix44<float> CoordMat => ref coordMat;
 
     }
 }

src/Nitload.Mathematics/Geometries/Coordination/PlainCoordinate.cs

@@ -21,24 +21,24 @@ namespace Nitload.Geometries
         public PlainCoordinate(
                CoordinationBase local,
                Point origin,
-               Vec3 xAxis,
-               Vec3 yAxis
+               Vec3<float> xAxis,
+               Vec3<float> yAxis
         )
             : base(local)
         {
-            CoordMat = GraphicsMatrix.Unit;
+            CoordMat = GMatrix44<float>.Unit;
 
-            CoordMat.column[0] = new Vec4(xAxis, 0);
-            CoordMat.column[1] = new Vec4(yAxis, 0);
-            CoordMat.column[2] = new Vec4(Linear.Normalize(Vec3.Cross(xAxis, yAxis)), 0);
+            CoordMat[0] = new Vec4<float>(xAxis, 0);
+            CoordMat[1] = new Vec4<float>(yAxis, 0);
+            CoordMat[2] = new Vec4<float>(Linear.Normalize(Vec3.Cross(xAxis, yAxis)), 0);
 
             LocalOrigin = origin;
         }
 
-        public static PlainCoordinate StandardPlainCoordination { get; } = new(null,
+        public static PlainCoordinate StandardPlainCoordination { get; } = new(default,
                                                                                new Point(0, 0, 0),
-                                                                               new Vec3(1, 0, 0),
-                                                                               new Vec3(0, 1, 0));
+                                                                               new Vec3<float>(1, 0, 0),
+                                                                               new Vec3<float>(0, 1, 0));
 
     }
 }

src/Nitload.Mathematics/Geometries/Coordination/SpaceCoordinate.cs

@@ -20,9 +20,9 @@ namespace Nitload.Geometries
         public SpaceCoordinate(
                CoordinationBase localCoordination,
                Point origin,
-               Vec3 xAxis,
-               Vec3 yAxis,
-               Vec3 zAxis
+               Vec3<float> xAxis,
+               Vec3<float> yAxis,
+               Vec3<float> zAxis
         )
             : base(localCoordination) { }
 

src/Nitload.Mathematics/Geometries/IGeometry.cs

@@ -25,7 +25,7 @@ namespace Nitload.Geometries
         ] { get; set; }
 
         #pragma warning disable CA1819 
-        public Vec4[] VertexStream { get; }
+        public Vec3<float>[] VertexStream { get; }
  #pragma warning restore CA1819 
 
         public CoordinationBase Coordination { get; }

src/Nitload.Mathematics/Geometries/IInstancing.cs

@@ -41,8 +41,11 @@ namespace Nitload.Geometries
 
         public Vec3<float> CenterPositionGlobal { get; internal set; }
 
-        public Vec3<float> Coord { get => GlobalBuffer.CoordAndRotationList[BufferId].XYZ; set => GlobalBuffer.CoordAndRotationList[BufferId] =
-                                                                                                  new Vec4<float>(value.reg); }
+        public Vec3<float> Coord { get => GlobalBuffer.CoordAndRotationList[BufferId].XYZ; set
+                                                                                           {
+                                                                                               Vec4<float> v = new(value, 0);
+                                                                                               GlobalBuffer.CoordAndRotationList[BufferId] = v;
+                                                                                           } }
 
         public void Move()
         {

src/Nitload.Mathematics/Geometries/PlainGeometry/Define/GeometryOperation.cs

@@ -16,11 +16,11 @@ namespace Nitload.Geometries
     {
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec3 DefaultMotion(
-                           int tick
+        public static Vec3<float> DefaultMotion(
+                                  int tick
         )
         {
-            return default(Vec3);
+            return Vec3<float>.Zero;
         }
 
     }

src/Nitload.Mathematics/Geometries/PlainGeometry/Define/IPlainEntity.cs

@@ -18,7 +18,7 @@ namespace Nitload.Geometries
     public interface IPlainEntity
     {
 
-        public Vec2 CenterPosition { get; set; }
+        public Vec2<float> CenterPosition { get; set; }
 
         public bool CollideWith(
                     IPlainEntity entity
@@ -45,7 +45,7 @@ namespace Nitload.Geometries
             throw new NotImplementedException();
         }
 
-        Vec2 IPlainEntity.CenterPosition
+        Vec2<float> IPlainEntity.CenterPosition
         {
             get => _shape.Coordination.LocalOrigin.Coord.XY;
             set => throw new InvalidOperationException();

src/Nitload.Mathematics/Geometries/PlainGeometry/Define/ParticleOnPlain.cs

@@ -39,7 +39,7 @@ namespace Nitload.Geometries
 
         public int BufferId { get; set; }
 
-        Vec3 IInstancing.CenterPositionGlobal { get; set; }
+        Vec3<float> IInstancing.CenterPositionGlobal { get; set; }
 
         bool IPlainEntity.CollideWith(
                           IPlainEntity entity
@@ -48,7 +48,7 @@ namespace Nitload.Geometries
             throw new NotImplementedException();
         }
 
-        Vec2 IPlainEntity.CenterPosition
+        Vec2<float> IPlainEntity.CenterPosition
         {
             get => GlobalBuffer.CoordAndRotationList[BufferId].XY;
             set => throw new NotImplementedException();

src/Nitload.Mathematics/Geometries/PlainGeometry/Define/PlainGeometry.cs

@@ -20,7 +20,7 @@ namespace Nitload.Geometries
     public abstract class PlainGeometry : IGeometry
     {
 
-        protected Vec4[] vertexMat;
+        protected Vec3<float>[] vertexMat;
         internal CoordinationBase coordinate;
 
         internal PlainGeometry(
@@ -34,8 +34,8 @@ namespace Nitload.Geometries
                      int index
         ]
         {
-            get => new Point(vertexMat[index]);
-            set => vertexMat[index].vec = value.coordVec;
+            get => new(vertexMat[index]);
+            set => vertexMat[index] = value.Coord;
         }
 
         public int VertexCount => this.vertexMat.Length;
@@ -43,9 +43,9 @@ namespace Nitload.Geometries
         public abstract ReadOnlySpan<int> VertexIndices { get; }
 
         #pragma warning disable CA1819 
-        public Vec4[] VertexStream => vertexMat;
+        public Vec3<float>[] VertexStream => vertexMat;
 
         public CoordinationBase Coordination => this.coordinate;
 #pragma warning restore CA1819
     }
-}
+}

src/Nitload.Mathematics/Geometries/PlainGeometry/Define/PlainInstancingBuffer.cs

@@ -31,28 +31,28 @@ namespace Nitload.Geometries
         private bool disposedValue;
 
         private CoordinatePlain globalCoordinate;
-        private List<Vec4> coordList;
+        private List<Vec4<float>> coordList;
         private List<IInstancing> instanceList;
         private List<float> scalingList;
         private Mutex mutex;
 
         public PlainInstancingBuffer()
         {
-            coordList = new List<Vec4>(capacity:100);
+            coordList = new List<Vec4<float>>(capacity:100);
             instanceList = new List<IInstancing>(capacity:100);
             scalingList = new List<float>(capacity:100);
-            coordArray = Array.Empty<Vec4>();
+            coordArray = Array.Empty<Vec4<float>>();
             scaleArray = Array.Empty<float>();
             mutex = new Mutex();
         }
 
         public List<IInstancing> InstanceList => instanceList;
 
-        public List<Vec4> CoordAndRotationList => coordList;
+        public List<Vec4<float>> CoordAndRotationList => coordList;
 
         public List<float> ScalingList => scalingList;
 
-        public Span<Vec4> CoordAndRotationSpan => CollectionsMarshal.AsSpan(coordList);
+        public Span<Vec4<float>> CoordAndRotationSpan => CollectionsMarshal.AsSpan(coordList);
 
         public Span<float> ScalingSpan => CollectionsMarshal.AsSpan(scalingList);
 
@@ -60,7 +60,7 @@ namespace Nitload.Geometries
         {
             mutex.WaitOne();
             int ret = instanceList.Count;
-            coordList.Add(new Vec4());
+            coordList.Add(new Vec4<float>());
             scalingList.Add(0);
             mutex.ReleaseMutex();
             return ret;
@@ -143,7 +143,7 @@ namespace Nitload.Geometries
 
         #region field of mem opt
 
-        private Vec4[] coordArray;
+        private Vec4<float>[] coordArray;
         private float[] scaleArray;
 
     #endregion

src/Nitload.Mathematics/Geometries/PlainGeometry/Parallelogram.cs

@@ -15,7 +15,7 @@ namespace Nitload.Geometries
     public class Parallelogram : Polygon4
     {
 
-        internal readonly Func<int, Vec3> movCenterOperation = GeometryOperation.DefaultMotion;
+        internal readonly Func<int, Vec3<float>> movCenterOperation = GeometryOperation.DefaultMotion;
 
         internal Point center;
 

src/Nitload.Mathematics/Geometries/PlainGeometry/Plain.cs

@@ -16,16 +16,16 @@ namespace Nitload.Geometries
     {
 
         internal readonly float d = -1;
-        internal Vec3 _origin;
+        internal Vec3<float> _origin;
 
-        internal Vec3 plainParameter;
-        internal Vec3 vec1;
-        internal Vec3 vec2;
+        internal Vec3<float> plainParameter;
+        internal Vec3<float> vec1;
+        internal Vec3<float> vec2;
 
         public Plain(
-               Vec3 o,
-               Vec3 v1,
-               Vec3 v2
+               Vec3<float> o,
+               Vec3<float> v1,
+               Vec3<float> v2
         )
         {
             this._origin = o;
@@ -50,9 +50,9 @@ namespace Nitload.Geometries
                Point p3
         )
         {
-            Vec3 origin = p1.Coord;
-            Vec3 v1 = p2.Coord - origin;
-            Vec3 v2 = p3.Coord - origin;
+            Vec3<float> origin = p1.Coord;
+            Vec3<float> v1 = p2.Coord - origin;
+            Vec3<float> v2 = p3.Coord - origin;
 
 
             vec1 = v1 - (v2 * (v1.Y / v2.Y));   //xz

src/Nitload.Mathematics/Geometries/PlainGeometry/Polygon4.cs

@@ -28,11 +28,11 @@ namespace Nitload.Geometries
         internal Polygon4()
             : base(PlainCoordinate.StandardPlainCoordination)
         {
-            vertexMat = new Vec4[4];
+            vertexMat = new Vec3<float>[4];
         }
 
         internal Polygon4(
-                 Vec4[] rawCoord
+                 Vec3<float>[] rawCoord
         )
             : base(PlainCoordinate.StandardPlainCoordination)
         {
@@ -84,7 +84,7 @@ namespace Nitload.Geometries
         )
             : base(PlainCoordinate.StandardPlainCoordination)
         {
-            vertexMat = new Vec4[4];
+            vertexMat = new Vec3<float>[4];
 
             this[0] = new Point(v0x, v0y, 0);
             this[1] = new Point(v1x, v1y, 0);
@@ -105,7 +105,7 @@ namespace Nitload.Geometries
         )
             : base(coordination)
         {
-            vertexMat = new Vec4[4];
+            vertexMat = new Vec3<float>[4];
 
             this[0] = new Point(v0x, v0y, 0);
             this[1] = new Point(v1x, v1y, 0);

src/Nitload.Mathematics/Geometries/PlainGeometry/Polygon5.cs

@@ -31,7 +31,7 @@ namespace Nitload.Geometries
         public unsafe Polygon5()
             : base(PlainCoordinate.StandardPlainCoordination)
         {
-            vertexMat = new Vec4[5];
+            vertexMat = new Vec3<float>[5];
         }
 
         public Polygon5(
@@ -48,7 +48,7 @@ namespace Nitload.Geometries
         )
             : base(PlainCoordinate.StandardPlainCoordination)
         {
-            vertexMat = new Vec4[5];
+            vertexMat = new Vec3<float>[5];
             this[0] = new Point(v0x, v0y, 0);
             this[1] = new Point(v1x, v1y, 0);
             this[2] = new Point(v2x, v2y, 0);
@@ -71,7 +71,7 @@ namespace Nitload.Geometries
         )
             : base(coordination)
         {
-            vertexMat = new Vec4[5];
+            vertexMat = new Vec3<float>[5];
             this[0] = new Point(v0x, v0y, 0);
             this[1] = new Point(v1x, v1y, 0);
             this[2] = new Point(v2x, v2y, 0);

src/Nitload.Mathematics/Geometries/PlainGeometry/Polygon6.cs

@@ -34,32 +34,32 @@ namespace Nitload.Geometries
         public Polygon6()
             : base(PlainCoordinate.StandardPlainCoordination)
         {
-            vertexMat = new Vec4[6];
+            vertexMat = new Vec3<float>[6];
         }
 
         public Polygon6(
                PlainCoordinate coordination,
-               Vec2 vert0,
-               Vec2 vert1,
-               Vec2 vert2,
-               Vec2 vert3,
-               Vec2 vert4,
-               Vec2 vert5,
-               Vec2 vert6
+               Vec2<float> vert0,
+               Vec2<float> vert1,
+               Vec2<float> vert2,
+               Vec2<float> vert3,
+               Vec2<float> vert4,
+               Vec2<float> vert5,
+               Vec2<float> vert6
         )
             : base(coordination)
         {
-            vertexMat = new Vec4[6];
-            vertexMat[0].reg = vert0.reg;
-            vertexMat[1].reg = vert1.reg;
-            vertexMat[2].reg = vert2.reg;
-            vertexMat[3].reg = vert3.reg;
-            vertexMat[4].reg = vert4.reg;
-            vertexMat[5].reg = vert5.reg;
-            vertexMat[6].reg = vert6.reg;
+            vertexMat = new Vec3<float>[6];
+            vertexMat[0].XY = vert0;
+            vertexMat[1].XY = vert1;
+            vertexMat[2].XY = vert2;
+            vertexMat[3].XY = vert3;
+            vertexMat[4].XY = vert4;
+            vertexMat[5].XY = vert5;
+            vertexMat[6].XY = vert6;
         }
 
         public override ReadOnlySpan<int> VertexIndices => Indices;
 
     }
-}
+}

src/Nitload.Mathematics/Geometries/PlainGeometry/Rectangle.cs

@@ -29,8 +29,8 @@ namespace Nitload.Geometries
             : base(v0x, v0y, v1x, v1y, v2x, v2y, v3x, v3y)
         {
             #if DEBUG
-            Vec2 side0 = (this[0].Coord - this[1].Coord).XY;
-            Vec2 side1 = (this[2].Coord - this[1].Coord).XY;
+            Vec2<float> side0 = (this[0].Coord - this[1].Coord).XY;
+            Vec2<float> side1 = (this[2].Coord - this[1].Coord).XY;
             if (side0.Cross(side1) == 0) {
                 throw new ArgumentException();
             }
@@ -51,8 +51,8 @@ namespace Nitload.Geometries
             : base(coordination, v0x, v0y, v1x, v1y, v2x, v2y, v3x, v3y)
         {
             #if DEBUG
-            Vec2 side0 = (this[0].Coord - this[1].Coord).XY;
-            Vec2 side1 = (this[2].Coord - this[1].Coord).XY;
+            Vec2<float> side0 = (this[0].Coord - this[1].Coord).XY;
+            Vec2<float> side1 = (this[2].Coord - this[1].Coord).XY;
             if (side0.Cross(side1) == 0) {
                 throw new ArgumentException();
             }
@@ -68,11 +68,11 @@ namespace Nitload.Geometries
         /// <returns>
         ///
         /// </returns>
-        public virtual Vec3 MovCenter(
-                            uint tick
+        public virtual Vec3<float> MovCenter(
+                                   uint tick
         )
         {
-            return default(Vec3);
+            return Vec3<float>.Zero;
         }
 
     }

src/Nitload.Mathematics/Geometries/PlainGeometry/Triangle.cs

@@ -25,7 +25,7 @@ namespace Nitload.Geometries
         public Triangle()
             : base(PlainCoordinate.StandardPlainCoordination)
         {
-            vertexMat = new Vec4[3];
+            vertexMat = new Vec3<float>[3];
         }
 
         public Triangle(

src/Nitload.Mathematics/Geometries/Point.cs

@@ -19,23 +19,13 @@ namespace Nitload.Geometries
     public struct Point
     {
 
-        [FieldOffset(0)] private Vec3 coord;
-        [FieldOffset(0)] internal Vector4 coordVec;
-
-        internal Point(
-                 Vec4 vector
-        )
-        {
-            coordVec = vector.vec;
-            coordVec.W = 1;
-        }
+        [FieldOffset(0)] private Vec3<float> coord;
 
         public Point(
-               Vec3 coord
+               Vec3<float> vector
         )
         {
-            Coord = coord;
-            coordVec.W = 1;
+            coord = vector;
         }
 
         public Point(
@@ -44,12 +34,12 @@ namespace Nitload.Geometries
                float z
         )
         {
-            coordVec = new Vector4(x, y, z, 1);
+            coord = new Vec3<float>(x, y, z);
         }
 
-        public Vec3 Coord
+        public Vec3<float> Coord
         {
-            get => coord;
+            readonly get => coord;
             set => coord = value;
         }
 

src/Nitload.Mathematics/Geometries/SpaceGeometry/TriangulatedSurface.cs

@@ -26,18 +26,18 @@ namespace Nitload.Geometries
 
         private List<List<int>> _sideIndices;
         private List<int> _triangleIndices;
-        private List<Vec3> _vertices;
+        private List<Vec3<float>> _vertices;
 
         public TriangulatedSurface()
         {
-            _triangleIndices = new List<int>();
-            _vertices = new List<Vec3>();
-            _sides = new HashSet<(int,int)>();
-            _sideIndices = new List<List<int>>();
+            _triangleIndices = [];
+            _vertices = [];
+            _sides = [];
+            _sideIndices = [];
         }
 
         /**/
-        public IEnumerable<List<int>> SideIndicesEnumeratble => _sideIndices;
+        public IEnumerable<List<int>> SideIndicesEnumerable => _sideIndices;
 
         /*
         public Triangle GetTriangle( int index )
@@ -51,7 +51,7 @@ namespace Nitload.Geometries
         }
         /**/
 
-        public Span<Vec3> VertexSpan => CollectionsMarshal.AsSpan(_vertices);
+        public Span<Vec3<float>> VertexSpan => CollectionsMarshal.AsSpan(_vertices);
 
         public Span<int> TriangleIndicesSpan => CollectionsMarshal.AsSpan(_triangleIndices);
 
@@ -77,7 +77,7 @@ namespace Nitload.Geometries
         }
 
         public void AddVertexByOrder(
-                    Vec3 vertex
+                    Vec3<float> vertex
         )
         {
             _vertices.Add(vertex);

src/Nitload.Mathematics/Numeric/Graphics/GMatrix44_T.cs

@@ -0,0 +1,258 @@
+// -----------------------------------------------------------------------------
+// file="GMatrix44_T"
+// Project: StgSharp
+// Copyright (c) Nitload.
+// SPDX-License-Identifier: MIT
+// -----------------------------------------------------------------------------
+
+using Nitload.Mathematics;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Numerics;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+using System.Runtime.Intrinsics;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace Nitload.Mathematics.Numeric.Graphics
+{
+    [StructLayout(LayoutKind.Sequential, Pack = 16)]
+    public struct GMatrix44<T> where T : unmanaged, INumber<T>
+    {
+
+        private Buffer _buffer;
+
+        internal unsafe ref Vec4<T> this[
+                                    int x
+        ]
+        {
+            get => ref Unsafe.Add(ref Unsafe.As<GMatrix44<T>, Vec4<T>>(ref this), x);
+        }
+
+        public T this[
+                 int x,
+                 int y
+        ]
+        {
+            readonly get => _buffer[x][y];
+            set => _buffer[x][y] = value;
+        }
+
+        public static GMatrix44<T> Unit
+        {
+            get
+            {
+                GMatrix44<T> result = new();
+                result[0] = new Vec4<T>(T.One, T.Zero, T.Zero, T.Zero);
+                result[1] = new Vec4<T>(T.Zero, T.One, T.Zero, T.Zero);
+                result[2] = new Vec4<T>(T.Zero, T.Zero, T.One, T.Zero);
+                result[3] = new Vec4<T>(T.Zero, T.Zero, T.Zero, T.One);
+                return result;
+            }
+        }
+
+        public GMatrix44<T> Transpose
+        {
+            get
+            {
+                GMatrix44<T> transpose = new();
+
+                // Native SK transpose is intentionally deferred until the module
+                // startup path can guarantee that GlobalContext has been initialized.
+
+                if (Unsafe.SizeOf<T>() == 4)
+                {
+                    Vector128<T> row0Source = _buffer[0].AsVector128Unsafe();
+                    Vector128<T> row1Source = _buffer[1].AsVector128Unsafe();
+                    Vector128<T> row2Source = _buffer[2].AsVector128Unsafe();
+                    Vector128<T> row3Source = _buffer[3].AsVector128Unsafe();
+                    Vector128<int> row0 = Unsafe.As<Vector128<T>, Vector128<int>>(ref row0Source);
+                    Vector128<int> row1 = Unsafe.As<Vector128<T>, Vector128<int>>(ref row1Source);
+                    Vector128<int> row2 = Unsafe.As<Vector128<T>, Vector128<int>>(ref row2Source);
+                    Vector128<int> row3 = Unsafe.As<Vector128<T>, Vector128<int>>(ref row3Source);
+
+                    Vector128<int> pairMask = Vector128.Create(-1, 0, -1, 0);
+                    Vector128<int> firstPairMask = Vector128.Create(-1, -1, 0, 0);
+                    Vector128<int> lowShuffle = Vector128.Create(0, 0, 1, 1);
+                    Vector128<int> highShuffle = Vector128.Create(2, 2, 3, 3);
+                    Vector128<int> secondLaneShuffle = Vector128.Create(2, 3, 2, 3);
+
+                    Vector128<int> pair01Low = Vector128.ConditionalSelect(
+                        pairMask,
+                        Vector128.Shuffle(row0, lowShuffle),
+                        Vector128.Shuffle(row1, lowShuffle));
+                    Vector128<int> pair23Low = Vector128.ConditionalSelect(
+                        pairMask,
+                        Vector128.Shuffle(row2, lowShuffle),
+                        Vector128.Shuffle(row3, lowShuffle));
+                    Vector128<int> pair01High = Vector128.ConditionalSelect(
+                        pairMask,
+                        Vector128.Shuffle(row0, highShuffle),
+                        Vector128.Shuffle(row1, highShuffle));
+                    Vector128<int> pair23High = Vector128.ConditionalSelect(
+                        pairMask,
+                        Vector128.Shuffle(row2, highShuffle),
+                        Vector128.Shuffle(row3, highShuffle));
+
+                    Vector128<int> result0 = Vector128.ConditionalSelect(
+                        firstPairMask, pair01Low, pair23Low);
+                    Vector128<int> result1 = Vector128.ConditionalSelect(
+                        firstPairMask,
+                        Vector128.Shuffle(pair01Low, secondLaneShuffle),
+                        Vector128.Shuffle(pair23Low, secondLaneShuffle));
+                    Vector128<int> result2 = Vector128.ConditionalSelect(
+                        firstPairMask, pair01High, pair23High);
+                    Vector128<int> result3 = Vector128.ConditionalSelect(
+                        firstPairMask,
+                        Vector128.Shuffle(pair01High, secondLaneShuffle),
+                        Vector128.Shuffle(pair23High, secondLaneShuffle));
+                    transpose._buffer[0] = Vec4.FromVector128Unsafe(
+                        Unsafe.As<Vector128<int>, Vector128<T>>(ref result0));
+                    transpose._buffer[1] = Vec4.FromVector128Unsafe(
+                        Unsafe.As<Vector128<int>, Vector128<T>>(ref result1));
+                    transpose._buffer[2] = Vec4.FromVector128Unsafe(
+                        Unsafe.As<Vector128<int>, Vector128<T>>(ref result2));
+                    transpose._buffer[3] = Vec4.FromVector128Unsafe(
+                        Unsafe.As<Vector128<int>, Vector128<T>>(ref result3));
+                    return transpose;
+                }
+
+                if (Unsafe.SizeOf<T>() == 8)
+                {
+                    Vector256<T> row0Source = _buffer[0].AsVector256Unsafe();
+                    Vector256<T> row1Source = _buffer[1].AsVector256Unsafe();
+                    Vector256<T> row2Source = _buffer[2].AsVector256Unsafe();
+                    Vector256<T> row3Source = _buffer[3].AsVector256Unsafe();
+                    Vector256<long> row0 = Unsafe.As<Vector256<T>, Vector256<long>>(ref row0Source);
+                    Vector256<long> row1 = Unsafe.As<Vector256<T>, Vector256<long>>(ref row1Source);
+                    Vector256<long> row2 = Unsafe.As<Vector256<T>, Vector256<long>>(ref row2Source);
+                    Vector256<long> row3 = Unsafe.As<Vector256<T>, Vector256<long>>(ref row3Source);
+
+                    Vector256<long> pairMask = Vector256.Create(-1L, 0L, -1L, 0L);
+                    Vector256<long> firstPairMask = Vector256.Create(-1L, -1L, 0L, 0L);
+                    Vector256<long> firstShuffle = Vector256.Create(0L, 0L, 1L, 1L);
+                    Vector256<long> secondShuffle = Vector256.Create(2L, 2L, 3L, 3L);
+                    Vector256<long> pair01First = Vector256.ConditionalSelect(
+                        pairMask,
+                        Vector256.Shuffle(row0, firstShuffle),
+                        Vector256.Shuffle(row1, firstShuffle));
+                    Vector256<long> pair23First = Vector256.ConditionalSelect(
+                        pairMask,
+                        Vector256.Shuffle(row2, firstShuffle),
+                        Vector256.Shuffle(row3, firstShuffle));
+                    Vector256<long> pair01Second = Vector256.ConditionalSelect(
+                        pairMask,
+                        Vector256.Shuffle(row0, secondShuffle),
+                        Vector256.Shuffle(row1, secondShuffle));
+                    Vector256<long> pair23Second = Vector256.ConditionalSelect(
+                        pairMask,
+                        Vector256.Shuffle(row2, secondShuffle),
+                        Vector256.Shuffle(row3, secondShuffle));
+                    Vector256<long> result0 = Vector256.ConditionalSelect(
+                        firstPairMask, pair01First, pair23First);
+                    Vector256<long> result1 = Vector256.ConditionalSelect(
+                        firstPairMask,
+                        Vector256.Shuffle(pair01First, secondShuffle),
+                        Vector256.Shuffle(pair23First, secondShuffle));
+                    Vector256<long> result2 = Vector256.ConditionalSelect(
+                        firstPairMask, pair01Second, pair23Second);
+                    Vector256<long> result3 = Vector256.ConditionalSelect(
+                        firstPairMask,
+                        Vector256.Shuffle(pair01Second, secondShuffle),
+                        Vector256.Shuffle(pair23Second, secondShuffle));
+                    transpose._buffer[0] = Vec4.FromVector256Unsafe(
+                        Unsafe.As<Vector256<long>, Vector256<T>>(ref result0));
+                    transpose._buffer[1] = Vec4.FromVector256Unsafe(
+                        Unsafe.As<Vector256<long>, Vector256<T>>(ref result1));
+                    transpose._buffer[2] = Vec4.FromVector256Unsafe(
+                        Unsafe.As<Vector256<long>, Vector256<T>>(ref result2));
+                    transpose._buffer[3] = Vec4.FromVector256Unsafe(
+                        Unsafe.As<Vector256<long>, Vector256<T>>(ref result3));
+                    return transpose;
+                }
+
+                throw GraphicVector.ThrowUnsupportedTypeException<T>();
+            }
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static GMatrix44<T> operator -(
+                                            GMatrix44<T> left,
+                                            GMatrix44<T> right
+        )
+        {
+            Unsafe.SkipInit(out GMatrix44<T> result);
+            result._buffer[0] = left._buffer[0] - right._buffer[0];
+            result._buffer[1] = left._buffer[1] - right._buffer[1];
+            result._buffer[2] = left._buffer[2] - right._buffer[2];
+            result._buffer[3] = left._buffer[3] - right._buffer[3];
+
+            return result;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static GMatrix44<T> operator *(
+                                            GMatrix44<T> left,
+                                            T right
+        )
+        {
+            Unsafe.SkipInit(out GMatrix44<T> result);
+            result._buffer[0] = left._buffer[0] * right;
+            result._buffer[1] = left._buffer[1] * right;
+            result._buffer[2] = left._buffer[2] * right;
+            result._buffer[3] = left._buffer[3] * right;
+
+            return result;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static GMatrix44<T> operator *(
+                                            T left,
+                                            GMatrix44<T> right
+        )
+        {
+            return right * left;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static GMatrix44<T> operator *(
+                                            GMatrix44<T> left,
+                                            GMatrix44<T> right
+        )
+        {
+            Unsafe.SkipInit(out GMatrix44<T> result);
+            result._buffer[0] = left._buffer[0] + right._buffer[0];
+            result._buffer[1] = left._buffer[1] + right._buffer[1];
+            result._buffer[2] = left._buffer[2] + right._buffer[2];
+            result._buffer[3] = left._buffer[3] + right._buffer[3];
+
+            return result;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static GMatrix44<T> operator +(
+                                            GMatrix44<T> left,
+                                            GMatrix44<T> right
+        )
+        {
+            Unsafe.SkipInit(out GMatrix44<T> result);
+            result._buffer[0] = left._buffer[0] + right._buffer[0];
+            result._buffer[1] = left._buffer[1] + right._buffer[1];
+            result._buffer[2] = left._buffer[2] + right._buffer[2];
+            result._buffer[3] = left._buffer[3] + right._buffer[3];
+
+            return result;
+        }
+
+        [InlineArray(4)]
+        private struct Buffer
+        {
+
+            public Vec4<T> _column;
+
+        }
+
+    }
+}

src/Nitload.Mathematics/Numeric/Graphics/GraphicsMatrix.cs

@@ -1,261 +0,0 @@
-// -----------------------------------------------------------------------------
-// file="GraphicsMatrix"
-// Project: StgSharp
-// Copyright (c) Nitload.
-// SPDX-License-Identifier: MIT
-// -----------------------------------------------------------------------------
-
-using Nitload.Mathematics;
-using Nitload.Mathematics.Internal;
-using Nitload.Mathematics.Numeric;
-using System;
-using System.Collections;
-using System.Collections.Generic;
-using System.Numerics;
-using System.Runtime.CompilerServices;
-using System.Runtime.InteropServices;
-using System.Runtime.Intrinsics.X86;
-
-namespace Nitload.Mathematics.Numeric.Graphics
-{
-    [StructLayout(LayoutKind.Explicit, Size = 16 * sizeof(float), Pack = 16)]
-    public unsafe struct GraphicsMatrix : IEquatable<GraphicsMatrix>
-    {
-
-        [FieldOffset(0 * sizeof(float))] internal Column column;
-
-        [FieldOffset(0)] internal ColumnSet4 mat;
-        [FieldOffset(0)] internal MatrixKernel<float> kernel;
-
-        internal GraphicsMatrix(
-                 ColumnSet4 mat
-        )
-        {
-            Unsafe.SkipInit(out this);
-            this.mat = mat;
-        }
-
-        internal GraphicsMatrix(
-                 Vector4 vec0,
-                 Vector4 vec1,
-                 Vector4 vec2,
-                 Vector4 vec3
-        )
-        {
-            Unsafe.SkipInit(out this);
-            mat.colum0 = vec0;
-            mat.colum1 = vec1;
-            mat.colum2 = vec2;
-            mat.colum3 = vec3;
-        }
-
-        public GraphicsMatrix()
-        {
-            Unsafe.SkipInit(out this);
-        }
-
-        public unsafe GraphicsMatrix(
-                      float a00,
-                      float a01,
-                      float a02,
-                      float a03,
-                      float a10,
-                      float a11,
-                      float a12,
-                      float a13,
-                      float a20,
-                      float a21,
-                      float a22,
-                      float a23,
-                      float a30,
-                      float a31,
-                      float a32,
-                      float a33
-        )
-        {
-            Unsafe.SkipInit(out this);
-            mat.colum0 = new Vector4(a00, a10, a20, a30);
-            mat.colum1 = new Vector4(a01, a11, a21, a31);
-            mat.colum2 = new Vector4(a02, a12, a22, a32);
-            mat.colum3 = new Vector4(a03, a13, a23, a33);
-        }
-
-        public unsafe float this[
-                            int rowNum,
-                            int columNum
-        ]
-        {
-            get
-            {
-#if DEBUG
-                if (rowNum is > 3 or < 0)
-                {
-                    throw new ArgumentOutOfRangeException(nameof(columNum));
-                }
-                if (columNum is > 3 or < 0) {
-                    throw new ArgumentOutOfRangeException(nameof(columNum));
-                }
-#endif
-                return kernel[rowNum + (4 * columNum)];
-            }
-            set
-            {
-#if DEBUG
-                if (rowNum is > 3 or < 0)
-                {
-                    throw new ArgumentOutOfRangeException(nameof(columNum));
-                }
-                if (columNum is > 3 or < 0) {
-                    throw new ArgumentOutOfRangeException(nameof(columNum));
-                }
-#endif
-                kernel[rowNum + (4 * columNum)] = value;
-            }
-        }
-
-        public GraphicsMatrix Transpose
-        {
-            get
-            {
-                GraphicsMatrix transpose = new();
-                InternalTranspose(ref transpose);
-                return transpose;
-            }
-        }
-
-        public static GraphicsMatrix Unit => new GraphicsMatrix(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0,
-                                                                0, 0, 0, 1);
-
-        public static GraphicsMatrix WNegativeUnit => new GraphicsMatrix(1, 0, 0, 0, 0, 1, 0, 0, 0,
-                                                                         0, 1, 0, 0, 0, 0, -1);
-
-        public static GraphicsMatrix XNegativeUnit => new GraphicsMatrix(-1, 0, 0, 0, 0, 1, 0, 0, 0,
-                                                                         0, 1, 0, 0, 0, 0, 1);
-
-        public static GraphicsMatrix YNegativeUnit => new GraphicsMatrix(1, 0, 0, 0, 0, -1, 0, 0, 0,
-                                                                         0, 1, 0, 0, 0, 0, 1);
-
-        public static GraphicsMatrix ZNegativeUnit => new GraphicsMatrix(1, 0, 0, 0, 0, 1, 0, 0, 0,
-                                                                         0, -1, 0, 0, 0, 0, 1);
-
-        public ReadOnlySpan<float> AsSpan()
-        {
-            return MemoryMarshal.CreateReadOnlySpan(ref Unsafe.As<ColumnSet4, float>(ref mat), 16);
-        }
-
-        public override bool Equals(
-                             object? obj
-        )
-        {
-            return (obj is GraphicsMatrix x) && Equals(x);
-        }
-
-        public bool Equals(
-                    GraphicsMatrix other
-        )
-        {
-            return mat.Equals(other.mat);
-        }
-
-        public override int GetHashCode()
-        {
-            return HashCode.Combine(mat.colum0.GetHashCode(), mat.colum1.GetHashCode(),
-                                    mat.colum2.GetHashCode(), mat.colum3.GetHashCode());
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal unsafe void InternalTranspose(
-                             ref GraphicsMatrix transpose
-        )
-        {
-            const int f32 = 0;
-            fixed (MatrixKernel<float>* source = &this.kernel, target = &transpose.kernel) {
-                NumericalModule.GlobalContext.mat_sk[f32].Call(MatrixIntrinsicHandle.Transpose,
-                                                               null, (MatrixKernel*)source,
-                                                               (MatrixKernel*)target, 0);
-            }
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static unsafe GraphicsMatrix operator -(
-                                                     GraphicsMatrix left,
-                                                     GraphicsMatrix right
-        )
-        {
-            GraphicsMatrix ret = new();
-            int f32 = MatrixElementType.F32.IntrinsicNode;
-            NumericalModule.GlobalContext.mat_sk[f32].Call(MatrixIntrinsicHandle.Sub,
-                                                           (MatrixKernel*)&left.kernel,
-                                                           (MatrixKernel*)&right.kernel,
-                                                           (MatrixKernel*)&ret.kernel, 1);
-            return ret;
-        }
-
-        public static bool operator !=(
-                                    GraphicsMatrix left,
-                                    GraphicsMatrix right
-        )
-        {
-            return !(left == right);
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static unsafe GraphicsMatrix operator *(
-                                                     GraphicsMatrix mat,
-                                                     float value
-        )
-        {
-            int f32 = MatrixElementType.F32.IntrinsicNode;
-            return new GraphicsMatrix(mat.mat.colum0 * value, mat.mat.colum1 * value,
-                                      mat.mat.colum2 * value, mat.mat.colum3 * value);
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static GraphicsMatrix operator *(
-                                              GraphicsMatrix left,
-                                              GraphicsMatrix right
-        )
-        {
-            GraphicsMatrix ret = new();
-            int f32 = MatrixElementType.F32.IntrinsicNode;
-            NumericalModule.GlobalContext.mat_sk[f32].Call(MatrixIntrinsicHandle.Fma,
-                                                           (MatrixKernel*)&left,
-                                                           (MatrixKernel*)&right,
-                                                           (MatrixKernel*)&ret, 0);
-            return ret;
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static unsafe GraphicsMatrix operator +(
-                                                     GraphicsMatrix left,
-                                                     GraphicsMatrix right
-        )
-        {
-            GraphicsMatrix ret = new();
-            int f32 = MatrixElementType.F32.IntrinsicNode;
-            NumericalModule.GlobalContext.mat_sk[f32].Call(MatrixIntrinsicHandle.Add,
-                                                           (MatrixKernel*)&left,
-                                                           (MatrixKernel*)&right,
-                                                           (MatrixKernel*)&ret, 1);
-            return ret;
-        }
-
-        public static bool operator ==(
-                                    GraphicsMatrix left,
-                                    GraphicsMatrix right
-        )
-        {
-            return left.Equals(right);
-        }
-
-        [InlineArray(4)]
-        internal struct Column
-        {
-
-            private Vec4<float> value;
-
-        }
-
-    }
-}
-

src/Nitload.Mathematics/Numeric/Graphics/Vec3.cs

@@ -15,13 +15,61 @@ namespace Nitload.Mathematics.Numeric.Graphics
     public static class Vec3
     {
 
-        public static bool IsParallel<T>(Vec3<T> left, Vec3<T> right) where T: unmanaged,INumber<T>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static Vec3<double> ConvertToDouble(
+                                   Vec3<long> source
+        )
+        {
+            return FromVector256Unsafe(Vector256.ConvertToDouble(source.AsVector256Safe()));
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static Vec3<double> ConvertToDouble(
+                                   Vec3<ulong> source
+        )
+        {
+            return FromVector256Unsafe(Vector256.ConvertToDouble(source.AsVector256Safe()));
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static Vec3<float> ConvertToSingle(
+                                  Vec3<int> source
+        )
+        {
+            return FromVector128Unsafe(Vector128.ConvertToSingle(source.AsVector128Safe()));
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static Vec3<float> ConvertToSingle(
+                                  Vec3<uint> source
+        )
+        {
+            return FromVector128Unsafe(Vector128.ConvertToSingle(source.AsVector128Safe()));
+        }
+
+        public static Vec3<T> FromSpan<T>(
+                              ReadOnlySpan<T> span
+        ) where T : unmanaged, INumber<T>
+        {
+            if (span.Length < 3) {
+                throw new ArgumentException("Span length must be at least 3.", nameof(span));
+            }
+
+            return new(span[0], span[1], span[2]);
+        }
+
+        public static bool IsParallel<T>(
+                           Vec3<T> left,
+                           Vec3<T> right
+        ) where T : unmanaged,INumber<T>
         {
             return Cross(left, right).Equals(T.Zero);
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal static Vector128<T> AsVector128Safe<T>(this Vec3<T> source) where T: unmanaged, INumber<T>
+        internal static Vector128<T> AsVector128Safe<T>(
+                                     this Vec3<T> source
+        ) where T : unmanaged, INumber<T>
         {
             Vector128<T> result = Vector128<T>.Zero;
             Unsafe.WriteUnaligned(ref Unsafe.As<Vector128<T>, byte>(ref result), source);
@@ -29,7 +77,9 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal static Vector128<T> AsVector128Unsafe<T>(this Vec3<T> source) where T: unmanaged, INumber<T>
+        internal static Vector128<T> AsVector128Unsafe<T>(
+                                     this Vec3<T> source
+        ) where T : unmanaged, INumber<T>
         {
             Unsafe.SkipInit(out Vector128<T> result);
             Unsafe.WriteUnaligned(ref Unsafe.As<Vector128<T>, byte>(ref result), source);
@@ -37,7 +87,9 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal static Vector256<T> AsVector256Safe<T>(this Vec3<T> source) where T: unmanaged, INumber<T>
+        internal static Vector256<T> AsVector256Safe<T>(
+                                     this Vec3<T> source
+        ) where T : unmanaged, INumber<T>
         {
             Vector256<T> result = Vector256<T>.Zero;
             Unsafe.WriteUnaligned(ref Unsafe.As<Vector256<T>, byte>(ref result), source);
@@ -45,7 +97,9 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal static Vector256<T> AsVector256Unsafe<T>(this Vec3<T> source) where T: unmanaged, INumber<T>
+        internal static Vector256<T> AsVector256Unsafe<T>(
+                                     this Vec3<T> source
+        ) where T : unmanaged, INumber<T>
         {
             Unsafe.SkipInit(out Vector256<T> result);
             Unsafe.WriteUnaligned(ref Unsafe.As<Vector256<T>, byte>(ref result), source);
@@ -53,45 +107,28 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal static Vec3<T> FromVector128Unsafe<T>(Vector128<T> source) where T: unmanaged, INumber<T>
+        internal static Vec3<T> FromVector128Unsafe<T>(
+                                Vector128<T> source
+        ) where T : unmanaged, INumber<T>
         {
             return Unsafe.As<Vector128<T>, Vec3<T>>(ref source);
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal static Vec3<T> FromVector256Unsafe<T>(Vector256<T> source) where T: unmanaged, INumber<T>
+        internal static Vec3<T> FromVector256Unsafe<T>(
+                                Vector256<T> source
+        ) where T : unmanaged, INumber<T>
         {
             return Unsafe.As<Vector256<T>, Vec3<T>>(ref source);
         }
 
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec3<float> ConvertToSingle(Vec3<int> source)
-        {
-            return FromVector128Unsafe(Vector128.ConvertToSingle(source.AsVector128Safe()));
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec3<float> ConvertToSingle(Vec3<uint> source)
-        {
-            return FromVector128Unsafe(Vector128.ConvertToSingle(source.AsVector128Safe()));
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec3<double> ConvertToDouble(Vec3<long> source)
-        {
-            return FromVector256Unsafe(Vector256.ConvertToDouble(source.AsVector256Safe()));
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec3<double> ConvertToDouble(Vec3<ulong> source)
-        {
-            return FromVector256Unsafe(Vector256.ConvertToDouble(source.AsVector256Safe()));
-        }
-
         #region cross
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec3<T> Cross<T>(Vec3<T> left, Vec3<T> right) where T: unmanaged, INumber<T>
+        public static Vec3<T> Cross<T>(
+                              Vec3<T> left,
+                              Vec3<T> right
+        ) where T : unmanaged, INumber<T>
         {
             if (typeof(T) == typeof(float))
             {
@@ -140,7 +177,10 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private static Vec3<double> CrossDouble(Vec3<double> left, Vec3<double> right)
+        private static Vec3<double> CrossDouble(
+                                    Vec3<double> left,
+                                    Vec3<double> right
+        )
         {
             Vector256<double> l = left.AsVector256Safe();
             Vector256<double> r = right.AsVector256Safe();
@@ -151,7 +191,10 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private static Vec3<int> CrossInt32(Vec3<int> left, Vec3<int> right)
+        private static Vec3<int> CrossInt32(
+                                 Vec3<int> left,
+                                 Vec3<int> right
+        )
         {
             Vector128<int> l = left.AsVector128Safe();
             Vector128<int> r = right.AsVector128Safe();
@@ -162,7 +205,10 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private static Vec3<float> CrossSingle(Vec3<float> left, Vec3<float> right)
+        private static Vec3<float> CrossSingle(
+                                   Vec3<float> left,
+                                   Vec3<float> right
+        )
         {
             Vector128<float> l = left.AsVector128Safe();
             Vector128<float> r = right.AsVector128Safe();
@@ -173,7 +219,10 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private static Vec3<uint> CrossUInt32(Vec3<uint> left, Vec3<uint> right)
+        private static Vec3<uint> CrossUInt32(
+                                  Vec3<uint> left,
+                                  Vec3<uint> right
+        )
         {
             Vector128<uint> l = left.AsVector128Safe();
             Vector128<uint> r = right.AsVector128Safe();
@@ -184,7 +233,10 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private static Vec3<ulong> CrossUInt64(Vec3<ulong> left, Vec3<ulong> right)
+        private static Vec3<ulong> CrossUInt64(
+                                   Vec3<ulong> left,
+                                   Vec3<ulong> right
+        )
         {
             Vector256<ulong> l = left.AsVector256Safe();
             Vector256<ulong> r = right.AsVector256Safe();
@@ -195,7 +247,10 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private static Vec3<long> CrossInt64(Vec3<long> left, Vec3<long> right)
+        private static Vec3<long> CrossInt64(
+                                  Vec3<long> left,
+                                  Vec3<long> right
+        )
         {
             Vector256<long> l = left.AsVector256Safe();
             Vector256<long> r = right.AsVector256Safe();

src/Nitload.Mathematics/Numeric/Graphics/Vec3_T.cs

@@ -21,21 +21,28 @@ namespace Nitload.Mathematics.Numeric.Graphics
     /// </summary>
     [StructLayout(LayoutKind.Sequential, Pack = 16)]
     public struct Vec3<T> : IUnmanagedVector<Vec3<T>>, IEquatable<Vec3<T>>, IEnumerable<T>
-        where T: unmanaged, INumber<T>
+        where T : unmanaged, INumber<T>
     {
 
         public T X;
         public T Y;
         public T Z;
 
-        public Vec3(Vec2<T> xy, T z)
+        public Vec3(
+               Vec2<T> xy,
+               T z
+        )
         {
             X = xy.X;
             Y = xy.Y;
             Z = z;
         }
 
-        public Vec3(T x, T y, T z)
+        public Vec3(
+               T x,
+               T y,
+               T z
+        )
         {
             X = x;
             Y = y;
@@ -73,7 +80,9 @@ namespace Nitload.Mathematics.Numeric.Graphics
         public static Vec3<T> UnitZ => new(T.Zero, T.Zero, T.One);
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public readonly T Dot(Vec3<T> right)
+        public readonly T Dot(
+                          Vec3<T> right
+        )
         {
             if (Unsafe.SizeOf<T>() == 8)
             {
@@ -89,31 +98,28 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public readonly bool Equals(Vec3<T> other)
+        public readonly bool Equals(
+                             Vec3<T> other
+        )
         {
-            if (Unsafe.SizeOf<T>() == 4) {
+            if (Unsafe.SizeOf<T>() == 4)
+            {
                 return this.AsVector128Safe() == other.AsVector128Safe();
-            }
-            if (Unsafe.SizeOf<T>() == 8) {
+            } else if (Unsafe.SizeOf<T>() == 8) {
                 return this.AsVector256Safe() == other.AsVector256Safe();
             }
+#pragma warning disable CA1065
             throw GraphicVector.ThrowUnsupportedTypeException<T>();
+#pragma warning restore CA1065
         }
 
-        public override readonly bool Equals(object? obj)
+        public override readonly bool Equals(
+                                      object? obj
+        )
         {
             return obj is Vec3<T> other && Equals(other);
         }
 
-        public static Vec3<T> FromSpan(ReadOnlySpan<T> span)
-        {
-            if (span.Length < 3) {
-                throw new ArgumentException("Span length must be at least 3.", nameof(span));
-            }
-
-            return new(span[0], span[1], span[2]);
-        }
-
         public readonly IEnumerator<T> GetEnumerator()
         {
             yield return X;
@@ -132,33 +138,40 @@ namespace Nitload.Mathematics.Numeric.Graphics
             return T.Max(X, T.Max(Y, Z));
         }
 
-        public static bool IsParallel(Vec3<T> left, Vec3<T> right)
+        public static bool IsParallel(
+                           Vec3<T> left,
+                           Vec3<T> right
+        )
         {
             return Vec3.Cross(left, right) == Zero;
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec3<T> operator -(Vec3<T> value)
+        public static Vec3<T> operator -(
+                                       Vec3<T> value
+        )
         {
-            if (Unsafe.SizeOf<T>() == 4) {
+            if (Unsafe.SizeOf<T>() == 4)
+            {
                 return Vec3.FromVector128Unsafe(Vector128<T>.Zero - value.AsVector128Unsafe());
-            }
-            if (Unsafe.SizeOf<T>() == 8) {
+            } else if (Unsafe.SizeOf<T>() == 8) {
                 return Vec3.FromVector256Unsafe(Vector256<T>.Zero - value.AsVector256Unsafe());
             }
             throw GraphicVector.ThrowUnsupportedTypeException<T>();
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec3<T> operator -(Vec3<T> left, Vec3<T> right)
+        public static Vec3<T> operator -(
+                                       Vec3<T> left,
+                                       Vec3<T> right
+        )
         {
             if (Unsafe.SizeOf<T>() == 4)
             {
                 Vector128<T> left_v128 = left.AsVector128Unsafe();
                 Vector128<T> right_v128 = right.AsVector128Unsafe();
                 return Vec3.FromVector128Unsafe(left_v128 - right_v128);
-            }
-            if (Unsafe.SizeOf<T>() == 8)
+            } else if (Unsafe.SizeOf<T>() == 8)
             {
                 Vector256<T> left_v256 = left.AsVector256Unsafe();
                 Vector256<T> right_v256 = right.AsVector256Unsafe();
@@ -168,21 +181,26 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static bool operator !=(Vec3<T> left, Vec3<T> right)
+        public static bool operator !=(
+                                    Vec3<T> left,
+                                    Vec3<T> right
+        )
         {
             return !left.Equals(right);
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec3<T> operator *(Vec3<T> vector, T scalar)
+        public static Vec3<T> operator *(
+                                       Vec3<T> vector,
+                                       T scalar
+        )
         {
             if (Unsafe.SizeOf<T>() == 4)
             {
                 Vector128<T> vector_v128 = vector.AsVector128Unsafe();
                 Vector128<T> scalar_v128 = Vector128.Create(scalar);
                 return Vec3.FromVector128Unsafe(vector_v128 * scalar_v128);
-            }
-            if (Unsafe.SizeOf<T>() == 8)
+            } else if (Unsafe.SizeOf<T>() == 8)
             {
                 Vector256<T> vector_v256 = vector.AsVector256Unsafe();
                 Vector256<T> scalar_v256 = Vector256.Create(scalar);
@@ -192,27 +210,35 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec3<T> operator *(T scalar, Vec3<T> vector)
+        public static Vec3<T> operator *(
+                                       T scalar,
+                                       Vec3<T> vector
+        )
         {
             return vector * scalar;
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static T operator *(Vec3<T> left, Vec3<T> right)
+        public static T operator *(
+                                 Vec3<T> left,
+                                 Vec3<T> right
+        )
         {
             return left.Dot(right);
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec3<T> operator /(Vec3<T> vector, T scalar)
+        public static Vec3<T> operator /(
+                                       Vec3<T> vector,
+                                       T scalar
+        )
         {
             if (Unsafe.SizeOf<T>() == 4)
             {
                 Vector128<T> vector_v128 = vector.AsVector128Unsafe();
                 Vector128<T> scalar_v128 = Vector128.Create(scalar);
                 return Vec3.FromVector128Unsafe(vector_v128 / scalar_v128);
-            }
-            if (Unsafe.SizeOf<T>() == 8)
+            } else if (Unsafe.SizeOf<T>() == 8)
             {
                 Vector256<T> vector_v256 = vector.AsVector256Unsafe();
                 Vector256<T> scalar_v256 = Vector256.Create(scalar);
@@ -222,15 +248,17 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec3<T> operator +(Vec3<T> left, Vec3<T> right)
+        public static Vec3<T> operator +(
+                                       Vec3<T> left,
+                                       Vec3<T> right
+        )
         {
             if (Unsafe.SizeOf<T>() == 4)
             {
                 Vector128<T> left_v128 = left.AsVector128Unsafe();
                 Vector128<T> right_v128 = right.AsVector128Unsafe();
                 return Vec3.FromVector128Unsafe(left_v128 + right_v128);
-            }
-            if (Unsafe.SizeOf<T>() == 8)
+            } else if (Unsafe.SizeOf<T>() == 8)
             {
                 Vector256<T> left_v256 = left.AsVector256Unsafe();
                 Vector256<T> right_v256 = right.AsVector256Unsafe();
@@ -240,13 +268,18 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static bool operator ==(Vec3<T> left, Vec3<T> right)
+        public static bool operator ==(
+                                    Vec3<T> left,
+                                    Vec3<T> right
+        )
         {
             return left.Equals(right);
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static implicit operator Vec3<T>((T X, T Y, T Z) tuple)
+        public static implicit operator Vec3<T>(
+                                        (T X, T Y, T Z) tuple
+        )
         {
             return new(tuple.X, tuple.Y, tuple.Z);
         }
@@ -256,5 +289,13 @@ namespace Nitload.Mathematics.Numeric.Graphics
             return GetEnumerator();
         }
 
+        [InlineArray(3)]
+        private struct Buffer
+        {
+
+            internal T _element;
+
+        }
+
     }
 }

src/Nitload.Mathematics/Numeric/Graphics/Vec4.cs

@@ -7,6 +7,7 @@
 
 using System.Numerics;
 using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
 using System.Runtime.Intrinsics;
 
 namespace Nitload.Mathematics.Numeric.Graphics
@@ -15,7 +16,55 @@ namespace Nitload.Mathematics.Numeric.Graphics
     {
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal static Vector128<T> AsVector128Unsafe<T>(this Vec4<T> source) where T: unmanaged, INumber<T>
+        public static Vec4<double> ConvertToDouble(
+                                   Vec4<long> source
+        )
+        {
+            return FromVector256Unsafe(Vector256.ConvertToDouble(source.AsVector256Unsafe()));
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static Vec4<double> ConvertToDouble(
+                                   Vec4<ulong> source
+        )
+        {
+            return FromVector256Unsafe(Vector256.ConvertToDouble(source.AsVector256Unsafe()));
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static Vec4<float> ConvertToSingle(
+                                  Vec4<int> source
+        )
+        {
+            return FromVector128Unsafe(Vector128.ConvertToSingle(source.AsVector128Unsafe()));
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static Vec4<float> ConvertToSingle(
+                                  Vec4<uint> source
+        )
+        {
+            return FromVector128Unsafe(Vector128.ConvertToSingle(source.AsVector128Unsafe()));
+        }
+
+        public static Vec4<T> FromSpan<T>(
+                              ReadOnlySpan<T> span
+        ) where T : unmanaged, INumber<T>
+        {
+            if (span.Length < 4) {
+                throw new ArgumentException("Span length must be at least 4.", nameof(span));
+            }
+
+            Unsafe.SkipInit(out Vec4<T> result);
+            Span<T> target = MemoryMarshal.CreateSpan(ref Unsafe.As<Vec4<T>, T>(ref result), 4);
+            span[..4].CopyTo(target);
+            return result;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal static Vector128<T> AsVector128Unsafe<T>(
+                                     this Vec4<T> source
+        ) where T : unmanaged, INumber<T>
         {
             Unsafe.SkipInit(out Vector128<T> result);
             Unsafe.WriteUnaligned(ref Unsafe.As<Vector128<T>, byte>(ref result), source);
@@ -23,7 +72,9 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal static Vector256<T> AsVector256Unsafe<T>(this Vec4<T> source) where T: unmanaged, INumber<T>
+        internal static Vector256<T> AsVector256Unsafe<T>(
+                                     this Vec4<T> source
+        ) where T : unmanaged, INumber<T>
         {
             Unsafe.SkipInit(out Vector256<T> result);
             Unsafe.WriteUnaligned(ref Unsafe.As<Vector256<T>, byte>(ref result), source);
@@ -31,40 +82,20 @@ namespace Nitload.Mathematics.Numeric.Graphics
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal static Vec4<T> FromVector128Unsafe<T>(Vector128<T> source) where T: unmanaged, INumber<T>
+        internal static Vec4<T> FromVector128Unsafe<T>(
+                                Vector128<T> source
+        ) where T : unmanaged, INumber<T>
         {
             return Unsafe.As<Vector128<T>, Vec4<T>>(ref source);
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal static Vec4<T> FromVector256Unsafe<T>(Vector256<T> source) where T: unmanaged, INumber<T>
+        internal static Vec4<T> FromVector256Unsafe<T>(
+                                Vector256<T> source
+        ) where T : unmanaged, INumber<T>
         {
             return Unsafe.As<Vector256<T>, Vec4<T>>(ref source);
         }
 
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec4<float> ConvertToSingle(Vec4<int> source)
-        {
-            return FromVector128Unsafe(Vector128.ConvertToSingle(source.AsVector128Unsafe()));
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec4<float> ConvertToSingle(Vec4<uint> source)
-        {
-            return FromVector128Unsafe(Vector128.ConvertToSingle(source.AsVector128Unsafe()));
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec4<double> ConvertToDouble(Vec4<long> source)
-        {
-            return FromVector256Unsafe(Vector256.ConvertToDouble(source.AsVector256Unsafe()));
-        }
-
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static Vec4<double> ConvertToDouble(Vec4<ulong> source)
-        {
-            return FromVector256Unsafe(Vector256.ConvertToDouble(source.AsVector256Unsafe()));
-        }
-
     }
 }

src/Nitload.Mathematics/Numeric/Graphics/Vec4_T.cs

@@ -20,11 +20,7 @@ namespace Nitload.Mathematics.Numeric.Graphics
     public struct Vec4<T> : IUnmanagedVector<Vec4<T>> where T : unmanaged, INumber<T>
     {
 
-        public T W;
-
-        public T X;
-        public T Y;
-        public T Z;
+        private Buffer _buffer;
 
         public Vec4(
                Vec3<T> v3,
@@ -50,9 +46,41 @@ namespace Nitload.Mathematics.Numeric.Graphics
             W = w;
         }
 
+        public T this[
+                 int index
+        ]
+        {
+            get => _buffer[index];
+            set => _buffer[index] = value;
+        }
+
+        public T X
+        {
+            get => _buffer[0];
+            set => _buffer[0] = value;
+        }
+
+        public T Y
+        {
+            get => _buffer[1];
+            set => _buffer[1] = value;
+        }
+
+        public T Z
+        {
+            get => _buffer[2];
+            set => _buffer[2] = value;
+        }
+
+        public T W
+        {
+            get => _buffer[3];
+            set => _buffer[3] = value;
+        }
+
         public Vec2<T> XY
         {
-            get => Unsafe.As<T, Vec2<T>>(ref X);
+            get => Unsafe.As<T, Vec2<T>>(ref _buffer[0]);
             set
             {
                 X = value.X;
@@ -62,11 +90,60 @@ namespace Nitload.Mathematics.Numeric.Graphics
 
         public Vec3<T> XYZ
         {
-            get => Unsafe.As<T, Vec3<T>>(ref X);
+            get => Unsafe.As<T, Vec3<T>>(ref _buffer[0]);
             set
             {
                 T w = W;
-                Unsafe.As<T, Vec3<T>>(ref X) = value;
+                Unsafe.As<T, Vec3<T>>(ref _buffer[0]) = value;
+                W = w;
+            }
+        }
+
+        public Vec3<T> ZXY
+        {
+            readonly get
+            {
+                if (Unsafe.SizeOf<T>() == 4)
+                {
+                    Vector128<T> source = this.AsVector128Unsafe();
+                    Vector128<int> bits = Unsafe.As<Vector128<T>, Vector128<int>>(ref source);
+                    Vector128<int> result = Vector128.Shuffle(bits, Vector128.Create(2, 0, 1, 3));
+                    Vector128<T> shuffled = Unsafe.As<Vector128<int>, Vector128<T>>(ref result);
+                    return Vec3.FromVector128Unsafe(shuffled);
+                }
+                if (Unsafe.SizeOf<T>() == 8)
+                {
+                    Vector256<T> source = this.AsVector256Unsafe();
+                    Vector256<long> bits = Unsafe.As<Vector256<T>, Vector256<long>>(ref source);
+                    Vector256<long> result = Vector256.Shuffle(bits, Vector256.Create(2L, 0L, 1L,
+                                                                                      3L));
+                    Vector256<T> shuffled = Unsafe.As<Vector256<long>, Vector256<T>>(ref result);
+                    return Vec3.FromVector256Unsafe(shuffled);
+                }
+                throw GraphicVector.ThrowUnsupportedTypeException<T>();
+            }
+            set
+            {
+                T w = W;
+                if (Unsafe.SizeOf<T>() == 4)
+                {
+                    Vector128<T> source = value.AsVector128Unsafe();
+                    Vector128<int> bits = Unsafe.As<Vector128<T>, Vector128<int>>(ref source);
+                    Vector128<int> result = Vector128.Shuffle(bits, Vector128.Create(1, 2, 0, 3));
+                    Vector128<T> shuffled = Unsafe.As<Vector128<int>, Vector128<T>>(ref result);
+                    Unsafe.As<T, Vec3<T>>(ref _buffer[0]) = Vec3.FromVector128Unsafe(shuffled);
+                } else if (Unsafe.SizeOf<T>() == 8)
+                {
+                    Vector256<T> source = value.AsVector256Unsafe();
+                    Vector256<long> bits = Unsafe.As<Vector256<T>, Vector256<long>>(ref source);
+                    Vector256<long> result = Vector256.Shuffle(bits, Vector256.Create(1L, 2L, 0L,
+                                                                                      3L));
+                    Vector256<T> shuffled = Unsafe.As<Vector256<long>, Vector256<T>>(ref result);
+                    Unsafe.As<T, Vec3<T>>(ref _buffer[0]) = Vec3.FromVector256Unsafe(shuffled);
+                } else
+                {
+                    throw GraphicVector.ThrowUnsupportedTypeException<T>();
+                }
                 W = w;
             }
         }
@@ -86,7 +163,7 @@ namespace Nitload.Mathematics.Numeric.Graphics
 
         public ReadOnlySpan<T> AsSpan()
         {
-            return MemoryMarshal.CreateReadOnlySpan(ref X, 4);
+            return MemoryMarshal.CreateReadOnlySpan(ref _buffer[0], 4);
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -98,8 +175,7 @@ namespace Nitload.Mathematics.Numeric.Graphics
             {
                 Vec4<T> product = Vec4.FromVector128Unsafe(this.AsVector128Unsafe() * right.AsVector128Unsafe());
                 return product.X + product.Y + product.Z + product.W;
-            }
-            if (Unsafe.SizeOf<T>() == 8)
+            } else if (Unsafe.SizeOf<T>() == 8)
             {
                 Vec4<T> product = Vec4.FromVector256Unsafe(this.AsVector256Unsafe() * right.AsVector256Unsafe());
                 return product.X + product.Y + product.Z + product.W;
@@ -114,20 +190,6 @@ namespace Nitload.Mathematics.Numeric.Graphics
             return (obj is Vec4<T> v) && (v == this);
         }
 
-        public static Vec4<T> FromSpan(
-                              ReadOnlySpan<T> span
-        )
-        {
-            if (span.Length < 4) {
-                throw new ArgumentException("Span length must be at least 4.", nameof(span));
-            }
-
-            Unsafe.SkipInit(out Vec4<T> result);
-            Span<T> target = MemoryMarshal.CreateSpan(ref result.X, 4);
-            span[..4].CopyTo(target);
-            return result;
-        }
-
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public ReadOnlySpan<T>.Enumerator GetEnumerator()
         {
@@ -139,16 +201,41 @@ namespace Nitload.Mathematics.Numeric.Graphics
             return HashCode.Combine(X, Y, Z, W);
         }
 
+        public Vec4<T> Shuffle(
+                       int t0,
+                       int t1,
+                       int t2,
+                       int t3
+        )
+        {
+            if (Unsafe.SizeOf<T>() == 4)
+            {
+                Vector128<T> v = this.AsVector128Unsafe();
+                Vector128<int> bits = Unsafe.As<Vector128<T>, Vector128<int>>(ref v);
+                Vector128<int> result = Vector128.Shuffle(bits, Vector128.Create(t0, t1, t2, t3));
+                return Vec4.FromVector128Unsafe(Unsafe.As<Vector128<int>, Vector128<T>>(ref result));
+            } else if (Unsafe.SizeOf<T>() == 8)
+            {
+                Vector256<T> v = this.AsVector256Unsafe();
+                Vector256<long> bits = Unsafe.As<Vector256<T>, Vector256<long>>(ref v);
+                Vector256<long> result = Vector256.Shuffle(bits, Vector256.Create(t0, t1, t2, t3));
+                return Vec4.FromVector256Unsafe(Unsafe.As<Vector256<long>, Vector256<T>>(ref result));
+            } else
+            {
+                throw GraphicVector.ThrowUnsupportedTypeException<T>();
+            }
+        }
+
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static Vec4<T> operator -(
                                        Vec4<T> left,
                                        Vec4<T> right
         )
         {
-            if (Unsafe.SizeOf<T>() == 4) {
+            if (Unsafe.SizeOf<T>() == 4)
+            {
                 return Vec4.FromVector128Unsafe(left.AsVector128Unsafe() - right.AsVector128Unsafe());
-            }
-            if (Unsafe.SizeOf<T>() == 8) {
+            } else if (Unsafe.SizeOf<T>() == 8) {
                 return Vec4.FromVector256Unsafe(left.AsVector256Unsafe() - right.AsVector256Unsafe());
             }
             throw GraphicVector.ThrowUnsupportedTypeException<T>();
@@ -168,10 +255,10 @@ namespace Nitload.Mathematics.Numeric.Graphics
                                        T scalar
         )
         {
-            if (Unsafe.SizeOf<T>() == 4) {
+            if (Unsafe.SizeOf<T>() == 4)
+            {
                 return Vec4.FromVector128Unsafe(vector.AsVector128Unsafe() * Vector128.Create(scalar));
-            }
-            if (Unsafe.SizeOf<T>() == 8) {
+            } else if (Unsafe.SizeOf<T>() == 8) {
                 return Vec4.FromVector256Unsafe(vector.AsVector256Unsafe() * Vector256.Create(scalar));
             }
             throw GraphicVector.ThrowUnsupportedTypeException<T>();
@@ -186,6 +273,14 @@ namespace Nitload.Mathematics.Numeric.Graphics
             return vector * scalar;
         }
 
+        public static Vec4<T> operator *(
+                                       GMatrix44<T> mat,
+                                       Vec4<T> vec
+        )
+        {
+            return (mat[0] * vec.X) + (mat[1] * vec.Y) + (mat[2] * vec.Z) + (mat[3] * vec.W);
+        }
+
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static T operator *(
                                  Vec4<T> left,
@@ -201,10 +296,10 @@ namespace Nitload.Mathematics.Numeric.Graphics
                                        T scalar
         )
         {
-            if (Unsafe.SizeOf<T>() == 4) {
+            if (Unsafe.SizeOf<T>() == 4)
+            {
                 return Vec4.FromVector128Unsafe(vector.AsVector128Unsafe() / Vector128.Create(scalar));
-            }
-            if (Unsafe.SizeOf<T>() == 8) {
+            } else if (Unsafe.SizeOf<T>() == 8) {
                 return Vec4.FromVector256Unsafe(vector.AsVector256Unsafe() / Vector256.Create(scalar));
             }
             throw GraphicVector.ThrowUnsupportedTypeException<T>();
@@ -216,10 +311,10 @@ namespace Nitload.Mathematics.Numeric.Graphics
                                        Vec4<T> right
         )
         {
-            if (Unsafe.SizeOf<T>() == 4) {
+            if (Unsafe.SizeOf<T>() == 4)
+            {
                 return Vec4.FromVector128Unsafe(left.AsVector128Unsafe() + right.AsVector128Unsafe());
-            }
-            if (Unsafe.SizeOf<T>() == 8) {
+            } else if (Unsafe.SizeOf<T>() == 8) {
                 return Vec4.FromVector256Unsafe(left.AsVector256Unsafe() + right.AsVector256Unsafe());
             }
             throw GraphicVector.ThrowUnsupportedTypeException<T>();
@@ -230,10 +325,10 @@ namespace Nitload.Mathematics.Numeric.Graphics
                                     Vec4<T> right
         )
         {
-            if (Unsafe.SizeOf<T>() == 4) {
+            if (Unsafe.SizeOf<T>() == 4)
+            {
                 return left.AsVector128Unsafe() == right.AsVector128Unsafe();
-            }
-            if (Unsafe.SizeOf<T>() == 8) {
+            } else if (Unsafe.SizeOf<T>() == 8) {
                 return left.AsVector256Unsafe() == right.AsVector256Unsafe();
             }
 #pragma warning disable CA1065
@@ -241,5 +336,13 @@ namespace Nitload.Mathematics.Numeric.Graphics
 #pragma warning restore CA1065
         }
 
+        [InlineArray(4)]
+        private struct Buffer
+        {
+
+            private T _element;
+
+        }
+
     }
 }

src/Nitload.Mathematics/Numeric/Runtime/MatrixParallel.cs

@@ -170,7 +170,7 @@ namespace Nitload.Mathematics.Numeric
 
         #region C invoke
 
-        [LibraryImport(Native.LibName, EntryPoint = "nif_compare_simd")]
+        [LibraryImport(Native.LibName, EntryPoint = "nfn_compare_simd")]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         [DefaultDllImportSearchPaths(DllImportSearchPath.AssemblyDirectory)]
         private static partial int CompareSIMDID(
@@ -178,7 +178,7 @@ namespace Nitload.Mathematics.Numeric
                                    SIMDID right
         );
 
-        [LibraryImport(Native.LibName, EntryPoint = "nif_load_intrinsic_function")]
+        [LibraryImport(Native.LibName, EntryPoint = "nfn_load_intrinsic_function")]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         [DefaultDllImportSearchPaths(DllImportSearchPath.AssemblyDirectory)]
         private static partial void LoadIntrinsicFunction(
@@ -186,7 +186,7 @@ namespace Nitload.Mathematics.Numeric
                                     ulong id
         );
 
-        [LibraryImport(Native.LibName, EntryPoint = "nif_get_unite_simd")]
+        [LibraryImport(Native.LibName, EntryPoint = "nfn_get_unite_simd")]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         [DefaultDllImportSearchPaths(DllImportSearchPath.AssemblyDirectory)]
         private static partial SIMDID UniteSIMDID(

src/Nitload.Mathematics/Numeric/Runtime/MatrixParallelThread.cs

@@ -155,12 +155,12 @@ namespace Nitload.Mathematics.Numeric
         }
 
 #pragma warning disable CA5393
-        [LibraryImport(Native.LibName, EntryPoint = "nif_get_simd_level_local")]
+        [LibraryImport(Native.LibName, EntryPoint = "nfn_get_simd_level_local")]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         [DefaultDllImportSearchPaths(DllImportSearchPath.AssemblyDirectory)]
         internal static partial ulong GetSimdId();
 
-        [LibraryImport(Native.LibName, EntryPoint = "nif_load_intrinsic_function")]
+        [LibraryImport(Native.LibName, EntryPoint = "nfn_load_intrinsic_function")]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         [DefaultDllImportSearchPaths(DllImportSearchPath.AssemblyDirectory)]
         private static unsafe partial void LoadIntrinsicFunction(

src/Nitload.Native/.clangd

@@ -1,2 +1,2 @@
 CompileFlags:
-  CompilationDatabase: ../..
+  CompilationDatabase: .

src/Nitload.Native/CMakeLists.txt

@@ -3,112 +3,107 @@ project(Nitload.Native LANGUAGES C)
 
 include(${CMAKE_CURRENT_LIST_DIR}/ExternalLibs.cmake OPTIONAL)
 
-set(NIF_TARGET_OS "auto" CACHE STRING "Target OS identifier: auto, windows, linux, macos, ios, android, unknown")
-set_property(CACHE NIF_TARGET_OS PROPERTY STRINGS auto windows linux macos ios android unknown)
+set(NFN_TARGET_OS "auto" CACHE STRING "Target OS identifier: auto, windows, linux, macos, ios, android, unknown")
+set_property(CACHE NFN_TARGET_OS PROPERTY STRINGS auto windows linux macos ios android unknown)
 
-set(NIF_TARGET_ARCH "auto" CACHE STRING "Target ISA identifier: auto, x86_64, arm64, riscv64, ppc64le")
-set_property(CACHE NIF_TARGET_ARCH PROPERTY STRINGS auto x86_64 arm64 riscv64 ppc64le)
+set(NFN_TARGET_ARCH "auto" CACHE STRING "Target ISA identifier: auto, x86_64, arm64, riscv64, ppc64le")
+set_property(CACHE NFN_TARGET_ARCH PROPERTY STRINGS auto x86_64 arm64 riscv64 ppc64le)
 
-nif_resolve_target_identifiers(
-  "${NIF_TARGET_OS}"
-  "${NIF_TARGET_ARCH}"
-  NIF_RESOLVED_OS_NAME
-  NIF_RESOLVED_OS_DEFINE
-  NIF_RESOLVED_ARCH_NAME
-  NIF_RESOLVED_ARCH_DEFINE)
+nfn_resolve_target_identifiers(
+  "${NFN_TARGET_OS}"
+  "${NFN_TARGET_ARCH}"
+  NFN_RESOLVED_OS_NAME
+  NFN_RESOLVED_OS_DEFINE
+  NFN_RESOLVED_ARCH_NAME
+  NFN_RESOLVED_ARCH_DEFINE)
 
-set(NIF_NATIVE_SOURCES
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/dllmain.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/load_glfw.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/load_intrinsic.x86.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/m.bufop.x86.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/m.solve.x86.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/m.transpose.x86.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/mk.fma.pack.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/mk.fma.x86.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/mk.p_scan.x86.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/s.factorial.x86.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/s.hash.x86.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/simdid_compare.x86.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/simdid.x86.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/sk.fma.x86.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/thread.linux.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/thread.windows.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/vector.c
-  ${CMAKE_CURRENT_LIST_DIR}/nif-src/vector_dot.c)
+# CONFIGURE_DEPENDS makes CMake reconfigure when files are added or removed,
+# so native sources, headers, and templates need no per-file CMake edits.
+file(GLOB_RECURSE NFN_NATIVE_SOURCES CONFIGURE_DEPENDS
+  ${CMAKE_CURRENT_LIST_DIR}/nfn-src/*.c)
 
-set(NIF_NATIVE_HEADERS
-  ${CMAKE_CURRENT_LIST_DIR}/nif-head/glfw_function.h
-  ${CMAKE_CURRENT_LIST_DIR}/nif-head/nif_internal.h
-  ${CMAKE_CURRENT_LIST_DIR}/nif-head/nif_intrinsic.context.base.h
-  ${CMAKE_CURRENT_LIST_DIR}/nif-head/nif_intrinsic.context.x86.h
-  ${CMAKE_CURRENT_LIST_DIR}/nif-head/nif_intrinsic.h
-  ${CMAKE_CURRENT_LIST_DIR}/nif-head/nif_intrinsic.matkernel.h
-  ${CMAKE_CURRENT_LIST_DIR}/nif-head/nif_intrinsic.std.h
-  ${CMAKE_CURRENT_LIST_DIR}/nif-head/nif_target.h
-  ${CMAKE_CURRENT_LIST_DIR}/nif-head/NitloadFrameWork.h)
+file(GLOB_RECURSE NFN_NATIVE_HEADERS CONFIGURE_DEPENDS
+  ${CMAKE_CURRENT_LIST_DIR}/nfn-head/*.h)
 
-set(NIF_NATIVE_TEMPLATES
-  ${CMAKE_CURRENT_LIST_DIR}/nif-template/nif_template.fma.x86.h)
+file(GLOB_RECURSE NFN_NATIVE_TEMPLATES CONFIGURE_DEPENDS
+  ${CMAKE_CURRENT_LIST_DIR}/nfn-template/*.h)
 
 # Nitload.Native now lives under <root>/src/Nitload.Native, so walk up two
 # levels (project dir -> src -> solution root) to reach the solution root.
-get_filename_component(NIF_NATIVE_SRC_ROOT ${CMAKE_CURRENT_LIST_DIR} DIRECTORY)
-get_filename_component(NIF_SOLUTION_ROOT ${NIF_NATIVE_SRC_ROOT} DIRECTORY)
+get_filename_component(NFN_NATIVE_SRC_ROOT ${CMAKE_CURRENT_LIST_DIR} DIRECTORY)
+get_filename_component(NFN_SOLUTION_ROOT ${NFN_NATIVE_SRC_ROOT} DIRECTORY)
 
-if(NIF_RESOLVED_OS_NAME STREQUAL "windows")
-  set(NIF_OS_TAG win)
-elseif(NIF_RESOLVED_OS_NAME STREQUAL "linux")
-  set(NIF_OS_TAG linux)
+if(NFN_RESOLVED_OS_NAME STREQUAL "windows")
+  set(NFN_OS_TAG win)
+elseif(NFN_RESOLVED_OS_NAME STREQUAL "linux")
+  set(NFN_OS_TAG linux)
 else()
-  set(NIF_OS_TAG unknown)
+  set(NFN_OS_TAG unknown)
 endif()
 
-if(NIF_RESOLVED_ARCH_NAME STREQUAL "x86_64")
-  set(NIF_ARCH_TAG x64)
+if(NFN_RESOLVED_ARCH_NAME STREQUAL "x86_64")
+  set(NFN_ARCH_TAG x64)
 else()
-  set(NIF_ARCH_TAG ${NIF_RESOLVED_ARCH_NAME})
+  set(NFN_ARCH_TAG ${NFN_RESOLVED_ARCH_NAME})
 endif()
 
-set(NIF_BUILD_OUTPUT_DIR ${NIF_SOLUTION_ROOT}/bin/${NIF_OS_TAG}-${NIF_ARCH_TAG})
+set(NFN_EXPECTED_RID "" CACHE STRING "Optional managed target RID to validate before deployment")
+if(NFN_EXPECTED_RID AND NOT NFN_EXPECTED_RID STREQUAL "${NFN_OS_TAG}-${NFN_ARCH_TAG}")
+  message(FATAL_ERROR "Native target ${NFN_OS_TAG}-${NFN_ARCH_TAG} does not match managed target ${NFN_EXPECTED_RID}. Use a matching compiler/toolchain and a separate build directory.")
+endif()
+
+set(NFN_BUILD_OUTPUT_DIR "${NFN_SOLUTION_ROOT}/bin/${NFN_OS_TAG}-${NFN_ARCH_TAG}"
+    CACHE PATH "Native artifact directory shared with managed build deployment")
 # Compile-time intermediates (native PDB / .obj side files) live inside the CMake
 # build tree (cmake_build/<preset>) so they get cleaned up with it.
-set(NIF_OBJECT_ROOT_DIR ${CMAKE_CURRENT_BINARY_DIR}/obj/${PROJECT_NAME})
-set(NIF_NATIVE_PROJECT_FILES
-  ${NIF_NATIVE_SOURCES}
-  ${NIF_NATIVE_HEADERS}
-  ${NIF_NATIVE_TEMPLATES})
+set(NFN_OBJECT_ROOT_DIR ${CMAKE_CURRENT_BINARY_DIR}/obj/${PROJECT_NAME})
+set(NFN_NATIVE_PROJECT_FILES
+  ${NFN_NATIVE_SOURCES}
+  ${NFN_NATIVE_HEADERS}
+  ${NFN_NATIVE_TEMPLATES})
 
-add_library(${PROJECT_NAME} SHARED ${NIF_NATIVE_PROJECT_FILES})
+add_library(${PROJECT_NAME} SHARED ${NFN_NATIVE_PROJECT_FILES})
 
-source_group(TREE ${CMAKE_CURRENT_LIST_DIR} FILES ${NIF_NATIVE_PROJECT_FILES})
+source_group(TREE ${CMAKE_CURRENT_LIST_DIR} FILES ${NFN_NATIVE_PROJECT_FILES})
 
 set_target_properties(${PROJECT_NAME} PROPERTIES
   C_STANDARD 11
   C_STANDARD_REQUIRED ON
-  RUNTIME_OUTPUT_DIRECTORY ${NIF_BUILD_OUTPUT_DIR}
-  LIBRARY_OUTPUT_DIRECTORY ${NIF_BUILD_OUTPUT_DIR}
-  ARCHIVE_OUTPUT_DIRECTORY ${NIF_BUILD_OUTPUT_DIR})
+  OUTPUT_NAME "Nitload.Native"
+  PDB_NAME "Nitload.Native"
+  DEBUG_POSTFIX ""
+  RELEASE_POSTFIX ""
+  RELWITHDEBINFO_POSTFIX ""
+  MINSIZEREL_POSTFIX ""
+  RUNTIME_OUTPUT_DIRECTORY "${NFN_BUILD_OUTPUT_DIR}"
+  LIBRARY_OUTPUT_DIRECTORY "${NFN_BUILD_OUTPUT_DIR}"
+  ARCHIVE_OUTPUT_DIRECTORY "${NFN_BUILD_OUTPUT_DIR}"
+  PDB_OUTPUT_DIRECTORY "${NFN_BUILD_OUTPUT_DIR}")
+
+# P/Invoke loads Nitload.Native.dll on Windows, including GNU-style Clang toolchains.
+if(WIN32)
+  set_target_properties(${PROJECT_NAME} PROPERTIES PREFIX "")
+endif()
 
 foreach(_config Debug Release RelWithDebInfo MinSizeRel)
   string(TOUPPER ${_config} _config_upper)
   set_target_properties(${PROJECT_NAME} PROPERTIES
-    RUNTIME_OUTPUT_DIRECTORY_${_config_upper} ${NIF_BUILD_OUTPUT_DIR}
-    LIBRARY_OUTPUT_DIRECTORY_${_config_upper} ${NIF_BUILD_OUTPUT_DIR}
-    ARCHIVE_OUTPUT_DIRECTORY_${_config_upper} ${NIF_BUILD_OUTPUT_DIR}
-    PDB_OUTPUT_DIRECTORY_${_config_upper} ${NIF_BUILD_OUTPUT_DIR}
-    COMPILE_PDB_OUTPUT_DIRECTORY_${_config_upper} ${NIF_OBJECT_ROOT_DIR}/${_config}/${NIF_ARCH_TAG})
+    RUNTIME_OUTPUT_DIRECTORY_${_config_upper} ${NFN_BUILD_OUTPUT_DIR}
+    LIBRARY_OUTPUT_DIRECTORY_${_config_upper} ${NFN_BUILD_OUTPUT_DIR}
+    ARCHIVE_OUTPUT_DIRECTORY_${_config_upper} ${NFN_BUILD_OUTPUT_DIR}
+    PDB_OUTPUT_DIRECTORY_${_config_upper} ${NFN_BUILD_OUTPUT_DIR}
+    COMPILE_PDB_OUTPUT_DIRECTORY_${_config_upper} ${NFN_OBJECT_ROOT_DIR}/${_config}/${NFN_ARCH_TAG})
 endforeach()
 
 set_target_properties(${PROJECT_NAME} PROPERTIES
-  COMPILE_PDB_OUTPUT_DIRECTORY ${NIF_OBJECT_ROOT_DIR}/$<CONFIG>/${NIF_ARCH_TAG})
+  COMPILE_PDB_OUTPUT_DIRECTORY ${NFN_OBJECT_ROOT_DIR}/$<CONFIG>/${NFN_ARCH_TAG})
 
 if(MSVC OR (CMAKE_C_COMPILER_ID STREQUAL "Clang" AND CMAKE_C_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC"))
   target_compile_options(${PROJECT_NAME} PRIVATE
-    /Fd${NIF_OBJECT_ROOT_DIR}/$<CONFIG>/${NIF_ARCH_TAG}/)
+    /Fd${NFN_OBJECT_ROOT_DIR}/$<CONFIG>/${NFN_ARCH_TAG}/)
 endif()
 
-if(CMAKE_C_COMPILER_ID STREQUAL "Clang" AND NIF_RESOLVED_ARCH_NAME STREQUAL "x86_64")
+if(CMAKE_C_COMPILER_ID STREQUAL "Clang" AND NFN_RESOLVED_ARCH_NAME STREQUAL "x86_64")
   # Keep the intrinsic type system and builtin declarations visible to all TUs.
   # The runtime dispatch contract still follows T_arch/T_feature at the function level.
   if(CMAKE_C_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC")
@@ -138,19 +133,19 @@ endif()
 
 target_include_directories(${PROJECT_NAME}
   PRIVATE
-    ${CMAKE_CURRENT_LIST_DIR}/nif-head
-    ${CMAKE_CURRENT_LIST_DIR}/nif-template
+    ${CMAKE_CURRENT_LIST_DIR}/nfn-head
+    ${CMAKE_CURRENT_LIST_DIR}/nfn-template
     ${CMAKE_CURRENT_LIST_DIR}/lib)
 
 target_compile_definitions(${PROJECT_NAME}
   PRIVATE
-    NIF_EXTERN_TARGET
-    NIF_OS_TARGET=${NIF_RESOLVED_OS_DEFINE}
-    NIF_ARCH_TARGET=${NIF_RESOLVED_ARCH_DEFINE})
+    NFN_EXTERN_TARGET
+    NFN_OS_TARGET=${NFN_RESOLVED_OS_DEFINE}
+    NFN_ARCH_TARGET=${NFN_RESOLVED_ARCH_DEFINE})
 
-set(NIF_NATIVE_EXTERNAL_TARGET ${PROJECT_NAME})
+set(NFN_NATIVE_EXTERNAL_TARGET ${PROJECT_NAME})
 add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/lib)
 
-message(STATUS "Nitload.Native target OS: ${NIF_RESOLVED_OS_NAME} (${NIF_RESOLVED_OS_DEFINE})")
-message(STATUS "Nitload.Native target ISA: ${NIF_RESOLVED_ARCH_NAME} (${NIF_RESOLVED_ARCH_DEFINE})")
-message(STATUS "Nitload.Native output dir: ${NIF_BUILD_OUTPUT_DIR}")
+message(STATUS "Nitload.Native target OS: ${NFN_RESOLVED_OS_NAME} (${NFN_RESOLVED_OS_DEFINE})")
+message(STATUS "Nitload.Native target ISA: ${NFN_RESOLVED_ARCH_NAME} (${NFN_RESOLVED_ARCH_DEFINE})")
+message(STATUS "Nitload.Native output dir: ${NFN_BUILD_OUTPUT_DIR}")

src/Nitload.Native/CMakePresets.json

@@ -9,8 +9,7 @@
             "cacheVariables": {
                 "CMAKE_BUILD_TYPE": "Debug",
                 "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
-                "CMAKE_C_COMPILER": "clang",
-                "CMAKE_CXX_COMPILER": "clang++"
+                "CMAKE_C_COMPILER": "clang"
             }
         },
         {
@@ -21,8 +20,7 @@
             "cacheVariables": {
                 "CMAKE_BUILD_TYPE": "Release",
                 "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
-                "CMAKE_C_COMPILER": "clang",
-                "CMAKE_CXX_COMPILER": "clang++"
+                "CMAKE_C_COMPILER": "clang"
             }
         }
     ],

src/Nitload.Native/ExternalLibs.cmake

@@ -1,74 +1,74 @@
-function(nif_normalize_os_identifier INPUT_VALUE OUTPUT_NAME OUTPUT_DEFINE)
-    string(TOLOWER "${INPUT_VALUE}" _nif_os)
+function(nfn_normalize_os_identifier INPUT_VALUE OUTPUT_NAME OUTPUT_DEFINE)
+    string(TOLOWER "${INPUT_VALUE}" _nfn_os)
 
-    if(_nif_os STREQUAL "auto")
-        string(TOLOWER "${CMAKE_SYSTEM_NAME}" _nif_system_name)
-        if(_nif_system_name STREQUAL "windows")
-            set(_nif_os "windows")
-        elseif(_nif_system_name STREQUAL "linux")
-            set(_nif_os "linux")
+    if(_nfn_os STREQUAL "auto")
+        string(TOLOWER "${CMAKE_SYSTEM_NAME}" _nfn_system_name)
+        if(_nfn_system_name STREQUAL "windows")
+            set(_nfn_os "windows")
+        elseif(_nfn_system_name STREQUAL "linux")
+            set(_nfn_os "linux")
         endif()
     endif()
 
-    if(_nif_os STREQUAL "windows")
-        set(_nif_define NIF_OS_WINDOWS)
-    elseif(_nif_os STREQUAL "linux")
-        set(_nif_define NIF_OS_LINUX)
+    if(_nfn_os STREQUAL "windows")
+        set(_nfn_define NFN_OS_WINDOWS)
+    elseif(_nfn_os STREQUAL "linux")
+        set(_nfn_define NFN_OS_LINUX)
     else()
-        message(FATAL_ERROR "Unsupported NIF_TARGET_OS='${INPUT_VALUE}'.")
+        message(FATAL_ERROR "Unsupported NFN_TARGET_OS='${INPUT_VALUE}'.")
     endif()
 
-    set(${OUTPUT_NAME} "${_nif_os}" PARENT_SCOPE)
-    set(${OUTPUT_DEFINE} "${_nif_define}" PARENT_SCOPE)
+    set(${OUTPUT_NAME} "${_nfn_os}" PARENT_SCOPE)
+    set(${OUTPUT_DEFINE} "${_nfn_define}" PARENT_SCOPE)
 endfunction()
 
-function(nif_normalize_arch_identifier INPUT_VALUE OUTPUT_NAME OUTPUT_DEFINE)
-    string(TOLOWER "${INPUT_VALUE}" _nif_arch)
+function(nfn_normalize_arch_identifier INPUT_VALUE OUTPUT_NAME OUTPUT_DEFINE)
+    string(TOLOWER "${INPUT_VALUE}" _nfn_arch)
 
-    if(_nif_arch STREQUAL "auto")
-        string(TOLOWER "${CMAKE_SYSTEM_PROCESSOR}" _nif_processor)
-        if(_nif_processor MATCHES "^(amd64|x86_64|x64)$")
-            set(_nif_arch "x86_64")
-        elseif(_nif_processor MATCHES "^(arm64|aarch64)$")
-            set(_nif_arch "arm64")
-        elseif(_nif_processor STREQUAL "riscv64")
-            set(_nif_arch "riscv64")
-        elseif(_nif_processor MATCHES "^(ppc64le|powerpc64le)$")
-            set(_nif_arch "ppc64le")
+    if(_nfn_arch STREQUAL "auto")
+        string(TOLOWER "${CMAKE_SYSTEM_PROCESSOR}" _nfn_processor)
+        if(_nfn_processor MATCHES "^(amd64|x86_64|x64)$")
+            set(_nfn_arch "x86_64")
+        elseif(_nfn_processor MATCHES "^(arm64|aarch64)$")
+            set(_nfn_arch "arm64")
+        elseif(_nfn_processor STREQUAL "riscv64")
+            set(_nfn_arch "riscv64")
+        elseif(_nfn_processor MATCHES "^(ppc64le|powerpc64le)$")
+            set(_nfn_arch "ppc64le")
         else()
-            message(FATAL_ERROR "Unable to infer ISA from CMAKE_SYSTEM_PROCESSOR='${CMAKE_SYSTEM_PROCESSOR}'. Set NIF_TARGET_ARCH explicitly.")
+            message(FATAL_ERROR "Unable to infer ISA from CMAKE_SYSTEM_PROCESSOR='${CMAKE_SYSTEM_PROCESSOR}'. Set NFN_TARGET_ARCH explicitly.")
         endif()
     endif()
 
-    if(_nif_arch STREQUAL "x86_64")
-        set(_nif_define NIF_ARCH_X86_64)
-    elseif(_nif_arch STREQUAL "arm64")
-        set(_nif_define NIF_ARCH_ARM64)
-    elseif(_nif_arch STREQUAL "riscv64")
-        set(_nif_define NIF_ARCH_RISCV64)
-    elseif(_nif_arch STREQUAL "ppc64le")
-        set(_nif_define NIF_ARCH_PPC64le)
+    if(_nfn_arch STREQUAL "x86_64")
+        set(_nfn_define NFN_ARCH_X86_64)
+    elseif(_nfn_arch STREQUAL "arm64")
+        set(_nfn_define NFN_ARCH_ARM64)
+    elseif(_nfn_arch STREQUAL "riscv64")
+        set(_nfn_define NFN_ARCH_RISCV64)
+    elseif(_nfn_arch STREQUAL "ppc64le")
+        set(_nfn_define NFN_ARCH_PPC64le)
     else()
-        message(FATAL_ERROR "Unsupported NIF_TARGET_ARCH='${INPUT_VALUE}'.")
+        message(FATAL_ERROR "Unsupported NFN_TARGET_ARCH='${INPUT_VALUE}'.")
     endif()
 
-    set(${OUTPUT_NAME} "${_nif_arch}" PARENT_SCOPE)
-    set(${OUTPUT_DEFINE} "${_nif_define}" PARENT_SCOPE)
+    set(${OUTPUT_NAME} "${_nfn_arch}" PARENT_SCOPE)
+    set(${OUTPUT_DEFINE} "${_nfn_define}" PARENT_SCOPE)
 endfunction()
 
-function(nif_resolve_target_identifiers INPUT_OS INPUT_ARCH OUTPUT_OS_NAME OUTPUT_OS_DEFINE OUTPUT_ARCH_NAME OUTPUT_ARCH_DEFINE)
-    nif_normalize_os_identifier("${INPUT_OS}" _nif_os_name _nif_os_define)
-    nif_normalize_arch_identifier("${INPUT_ARCH}" _nif_arch_name _nif_arch_define)
+function(nfn_resolve_target_identifiers INPUT_OS INPUT_ARCH OUTPUT_OS_NAME OUTPUT_OS_DEFINE OUTPUT_ARCH_NAME OUTPUT_ARCH_DEFINE)
+    nfn_normalize_os_identifier("${INPUT_OS}" _nfn_os_name _nfn_os_define)
+    nfn_normalize_arch_identifier("${INPUT_ARCH}" _nfn_arch_name _nfn_arch_define)
 
-    set(${OUTPUT_OS_NAME} "${_nif_os_name}" PARENT_SCOPE)
-    set(${OUTPUT_OS_DEFINE} "${_nif_os_define}" PARENT_SCOPE)
-    set(${OUTPUT_ARCH_NAME} "${_nif_arch_name}" PARENT_SCOPE)
-    set(${OUTPUT_ARCH_DEFINE} "${_nif_arch_define}" PARENT_SCOPE)
+    set(${OUTPUT_OS_NAME} "${_nfn_os_name}" PARENT_SCOPE)
+    set(${OUTPUT_OS_DEFINE} "${_nfn_os_define}" PARENT_SCOPE)
+    set(${OUTPUT_ARCH_NAME} "${_nfn_arch_name}" PARENT_SCOPE)
+    set(${OUTPUT_ARCH_DEFINE} "${_nfn_arch_define}" PARENT_SCOPE)
 endfunction()
 
-function(nif_register_external_package TARGET PACKAGE_NAME PACKAGE_DIR)
+function(nfn_register_external_package TARGET PACKAGE_NAME PACKAGE_DIR)
     if(NOT TARGET ${TARGET})
-        message(FATAL_ERROR "nif_register_external_package: target '${TARGET}' does not exist.")
+        message(FATAL_ERROR "nfn_register_external_package: target '${TARGET}' does not exist.")
     endif()
 
     if(EXISTS "${PACKAGE_DIR}")
@@ -79,7 +79,7 @@ function(nif_register_external_package TARGET PACKAGE_NAME PACKAGE_DIR)
     endif()
 endfunction()
 
-function(nif_link_external_binary_if_exists TARGET LIBRARY_PATH)
+function(nfn_link_external_binary_if_exists TARGET LIBRARY_PATH)
     if(EXISTS "${LIBRARY_PATH}")
         target_link_libraries(${TARGET} PRIVATE "${LIBRARY_PATH}")
         message(STATUS "Linked external binary: ${LIBRARY_PATH}")

src/Nitload.Native/Nitload.Native.vcxproj

@@ -85,9 +85,10 @@
     <!-- 把 ARM64 → arm64，x64 保持 x64 -->
     <_ArchTag Condition="'$(Platform)'=='x64'">x64</_ArchTag>
     <_ArchTag Condition="'$(Platform)'=='ARM64'">arm64</_ArchTag>
-    <!-- 输出到 cmake_build/win_<arch>/，与 CMake 目录约定保持一致 -->
-    <OutDir>$(SolutionDir)cmake_build\win_$(_ArchTag)\</OutDir>
-    <IntDir>$(SolutionDir)obj\$(ProjectName)\$(Configuration)\$(Platform)\</IntDir>
+    <!-- Keep the navigation project's artifact paths aligned with CMake and managed deployment. -->
+    <TargetName>Nitload.Native</TargetName>
+    <OutDir>$(NativeBuildDir)</OutDir>
+    <IntDir>$(SolutionRoot)obj\$(ProjectName)\$(Configuration)\$(Platform)\</IntDir>
   </PropertyGroup>
   <PropertyGroup Condition="'$(Configuration)'=='Debug'">
     <RunCodeAnalysis>true</RunCodeAnalysis>
@@ -110,7 +111,7 @@
       <LanguageStandard_C>stdc11</LanguageStandard_C>
       <MultiProcessorCompilation>true</MultiProcessorCompilation>
       <FavorSizeOrSpeed>Speed</FavorSizeOrSpeed>
-      <AdditionalIncludeDirectories>$(ProjectDir)lib;$(ProjectDir)nif-head;$(ProjectDir)nif-template;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+      <AdditionalIncludeDirectories>$(ProjectDir)lib;$(ProjectDir)nfn-head;$(ProjectDir)nfn-template;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
     </ClCompile>
     <Link>
       <!-- DLL 应该用 Windows，不是 Console -->
@@ -172,23 +173,23 @@
   <!--  source files                                            -->
   <!-- ════════════════════════════════════════════════════════ -->
   <ItemGroup>
-    <ClCompile Include="nif-src\dllmain.c" />
-    <ClCompile Include="nif-src\m.bufop.x86.c" />
-    <ClCompile Include="nif-src\m.solve.x86.c" />
-    <ClCompile Include="nif-src\m.transpose.x86.c" />
-    <ClCompile Include="nif-src\mk.fma.x86.c" />
-    <ClCompile Include="nif-src\mk.p_scan.x86.c" />
-    <ClCompile Include="nif-src\s.factorial.x86.c" />
-    <ClCompile Include="nif-src\sk.fma.x86.c" />
-    <ClCompile Include="nif-src\s.hash.x86.c" />
-    <ClCompile Include="nif-src\load_intrinsic.x86.c" />
-    <ClCompile Include="nif-src\load_glfw.c" />
-    <ClCompile Include="nif-src\simdid.x86.c" />
-    <ClCompile Include="nif-src\simdid_compare.x86.c" />
-    <ClCompile Include="nif-src\thread.linux.c" />
-    <ClCompile Include="nif-src\thread.windows.c" />
-    <ClCompile Include="nif-src\vector.c" />
-    <ClCompile Include="nif-src\vector_dot.c" />
+    <ClCompile Include="nfn-src\dllmain.c" />
+    <ClCompile Include="nfn-src\m.bufop.x86.c" />
+    <ClCompile Include="nfn-src\m.solve.x86.c" />
+    <ClCompile Include="nfn-src\m.transpose.x86.c" />
+    <ClCompile Include="nfn-src\mk.fma.x86.c" />
+    <ClCompile Include="nfn-src\mk.p_scan.x86.c" />
+    <ClCompile Include="nfn-src\s.factorial.x86.c" />
+    <ClCompile Include="nfn-src\sk.fma.x86.c" />
+    <ClCompile Include="nfn-src\s.hash.x86.c" />
+    <ClCompile Include="nfn-src\load_intrinsic.x86.c" />
+    <ClCompile Include="nfn-src\load_glfw.c" />
+    <ClCompile Include="nfn-src\simdid.x86.c" />
+    <ClCompile Include="nfn-src\simdid_compare.x86.c" />
+    <ClCompile Include="nfn-src\thread.linux.c" />
+    <ClCompile Include="nfn-src\thread.windows.c" />
+    <ClCompile Include="nfn-src\vector.c" />
+    <ClCompile Include="nfn-src\vector_dot.c" />
   </ItemGroup>
   <!-- ════════════════════════════════════════════════════════ -->
   <!--  header files                                            -->
@@ -197,15 +198,15 @@
     <ClInclude Include="lib\glfw\glfw3.h" />
     <ClInclude Include="lib\glfw\glfw3native.h" />
     <ClInclude Include="lib\stbi\stb_image.h" />
-    <ClInclude Include="nif-head\glfw_function.h" />
-    <ClInclude Include="nif-head\nif_internal.h" />
-    <ClInclude Include="nif-head\nif_intrinsic.context.x86.h" />
-    <ClInclude Include="nif-head\nif_intrinsic.std.h" />
-    <ClInclude Include="nif-head\nif_intrinsic.h" />
-    <ClInclude Include="nif-head\nif_intrinsic.matkernel.h" />
-    <ClInclude Include="nif-head\nif_target.h" />
-    <ClInclude Include="nif-head\NitloadFrameWork.h" />
-    <ClInclude Include="nif-template\nif_template.fma.x86.h" />
+    <ClInclude Include="nfn-head\glfw_function.h" />
+    <ClInclude Include="nfn-head\nfn_internal.h" />
+    <ClInclude Include="nfn-head\nfn_intrinsic.context.x86.h" />
+    <ClInclude Include="nfn-head\nfn_intrinsic.std.h" />
+    <ClInclude Include="nfn-head\nfn_intrinsic.h" />
+    <ClInclude Include="nfn-head\nfn_intrinsic.matkernel.h" />
+    <ClInclude Include="nfn-head\nfn_target.h" />
+    <ClInclude Include="nfn-head\NitloadFrameWork.h" />
+    <ClInclude Include="nfn-template\nfn_template.fma.x86.h" />
   </ItemGroup>
   <ItemGroup>
     <None Include="naming.md" />

src/Nitload.Native/Nitload.Native.vcxproj.filters

@@ -21,69 +21,69 @@
     </Filter>
   </ItemGroup>
   <ItemGroup>
-    <ClCompile Include="nif-src\dllmain.c">
+    <ClCompile Include="nfn-src\dllmain.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\s.factorial.x86.c">
+    <ClCompile Include="nfn-src\s.factorial.x86.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\s.hash.x86.c">
+    <ClCompile Include="nfn-src\s.hash.x86.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\vector.c">
+    <ClCompile Include="nfn-src\vector.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\vector_dot.c">
+    <ClCompile Include="nfn-src\vector_dot.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\load_glfw.c">
+    <ClCompile Include="nfn-src\load_glfw.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\sk.fma.x86.c">
+    <ClCompile Include="nfn-src\sk.fma.x86.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\load_intrinsic.x86.c">
+    <ClCompile Include="nfn-src\load_intrinsic.x86.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\m.bufop.x86.c">
+    <ClCompile Include="nfn-src\m.bufop.x86.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\m.solve.x86.c">
+    <ClCompile Include="nfn-src\m.solve.x86.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\simdid.x86.c">
+    <ClCompile Include="nfn-src\simdid.x86.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\mk.fma.x86.c">
+    <ClCompile Include="nfn-src\mk.fma.x86.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\simdid_compare.x86.c">
+    <ClCompile Include="nfn-src\simdid_compare.x86.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\thread.linux.c">
+    <ClCompile Include="nfn-src\thread.linux.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\thread.windows.c">
+    <ClCompile Include="nfn-src\thread.windows.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\m.transpose.x86.c">
+    <ClCompile Include="nfn-src\m.transpose.x86.c">
       <Filter>源文件</Filter>
     </ClCompile>
-    <ClCompile Include="nif-src\mk.p_scan.x86.c">
+    <ClCompile Include="nfn-src\mk.p_scan.x86.c">
       <Filter>源文件</Filter>
     </ClCompile>
   </ItemGroup>
   <ItemGroup>
-    <ClInclude Include="nif-head\nif_internal.h">
+    <ClInclude Include="nfn-head\nfn_internal.h">
       <Filter>头文件</Filter>
     </ClInclude>
-    <ClInclude Include="nif-head\NitloadFrameWork.h">
+    <ClInclude Include="nfn-head\NitloadFrameWork.h">
       <Filter>头文件</Filter>
     </ClInclude>
-    <ClInclude Include="nif-head\glfw_function.h">
+    <ClInclude Include="nfn-head\glfw_function.h">
       <Filter>头文件</Filter>
     </ClInclude>
-    <ClInclude Include="nif-head\nif_intrinsic.matkernel.h">
+    <ClInclude Include="nfn-head\nfn_intrinsic.matkernel.h">
       <Filter>头文件</Filter>
     </ClInclude>
     <ClInclude Include="lib\glfw\glfw3.h">
@@ -95,19 +95,19 @@
     <ClInclude Include="lib\stbi\stb_image.h">
       <Filter>头文件</Filter>
     </ClInclude>
-    <ClInclude Include="nif-head\nif_target.h">
+    <ClInclude Include="nfn-head\nfn_target.h">
       <Filter>头文件</Filter>
     </ClInclude>
-    <ClInclude Include="nif-head\nif_intrinsic.context.x86.h">
+    <ClInclude Include="nfn-head\nfn_intrinsic.context.x86.h">
       <Filter>头文件</Filter>
     </ClInclude>
-    <ClInclude Include="nif-head\nif_intrinsic.h">
+    <ClInclude Include="nfn-head\nfn_intrinsic.h">
       <Filter>头文件</Filter>
     </ClInclude>
-    <ClInclude Include="nif-head\nif_intrinsic.std.h">
+    <ClInclude Include="nfn-head\nfn_intrinsic.std.h">
       <Filter>头文件</Filter>
     </ClInclude>
-    <ClInclude Include="nif-template\nif_template.fma.x86.h">
+    <ClInclude Include="nfn-template\nfn_template.fma.x86.h">
       <Filter>模板文件</Filter>
     </ClInclude>
   </ItemGroup>

src/Nitload.Native/README.md

@@ -1,4 +1,17 @@
-# StgSharp.Native 
+# Nitload.Native
+
+## Naming convention
+
+The C implementation uses `nfn` for Nitload Framework Native: exported functions use
+`nfn_`, macros and CMake cache options use `NFN_`, and native source folders and
+headers use `nfn-` and `nfn_`. The shared library remains named `Nitload.Native`.
+The longer prefix also distinguishes these names from Linux Netfilter's `nf_` names.
+
+This migration renames the exported C symbols from `nif_*` to `nfn_*`. Native
+binaries and managed assemblies must therefore be rebuilt and deployed together;
+pre-migration P/Invoke entry points are not compatible with a newly built library.
+The old `NIF_*` CMake cache options are no longer used. Reconfigure an existing
+build tree with the corresponding `NFN_*` options, or use a fresh build tree.
 
 ## COMPILE
 
@@ -6,6 +19,47 @@ Though this project do has a .vcxproj file,
 you can only edit but not compile in visul studio.  
 Currently you can only compile this lib via Clang and cmake.
 
+## Build output and managed deployment
+
+From the repository root:
+
+```powershell
+# On Windows, add your LLVM bin directory if clang is not already on PATH.
+$env:PATH = 'C:\Program Files\LLVM\bin;' + $env:PATH
+cmake --preset clang-debug -S src/Nitload.Native
+cmake --build cmake_build/clang-debug --target Nitload.Native
+```
+
+The presets require `clang` on `PATH`. If an existing CMake cache was configured
+with an absolute compiler path, make `clang` available on `PATH` before running
+the preset again. The `NFN_*` options replace the former `NIF_*` options.
+
+CMake writes `Nitload.Native.dll` and its linker PDB to `bin/win-x64` on Windows x64
+(Linux uses `bin/linux-x64/libNitload.Native.so`). Debug and release presets currently
+share this platform directory; the most recent native build is the deployed version.
+`NFN_BUILD_OUTPUT_DIR` can override the destination. Managed builds pass their expected
+RID as `NFN_EXPECTED_RID` so an incompatible native target is rejected before deployment.
+
+`StgSharpDebug.csproj` enables `BuildNativeBeforeManaged` and `RequireNativeLibrary`.
+Its build runs the incremental CMake build (`clang-debug` for Debug, `clang-release`
+otherwise), then deploys the native library to the executable's actual `TargetDir`.
+Other managed projects copy an existing native artifact without invoking CMake.
+Managed-output staging never copies deployed native files back over the CMake artifact.
+
+To use a prebuilt native artifact, pass `-p:BuildNativeBeforeManaged=false`. A matching
+Clang/Ninja environment and the local GLFW static library are required for native builds.
+Cross-target builds require a matching toolchain/preset; changing a managed platform alone
+does not cross-compile the C library.
+
+## clangd in VS Code
+
+The `.clangd` file searches for `compile_commands.json` in `src/Nitload.Native`.
+When using CMake Tools, set `cmake.copyCompileCommands` to
+`${workspaceFolder}/src/Nitload.Native/compile_commands.json` so the active Debug or Release preset
+updates that file after configuration. For command-line configuration, copy
+`cmake_build/<preset>/compile_commands.json` to `src/Nitload.Native`. Restart
+clangd after changing the database or renaming headers.
+
 ## Code Layout
 
 Conventions:

src/Nitload.Native/SIMDID.x86.md

@@ -217,7 +217,7 @@ Detection:
 - **Unknown hybrid** (flag set but core type unrecognised): leave topology at 00.
 - **SIMD_DUAL**: set when any of the following: `AVX Feature DUAL=1` (glued YMM), or `AVX512_IMPL=DUAL`.
 
-`nif_get_unite_simd` computes topology bits [1..0] with bitwise **AND** (conservative intersection — weaker topology wins) and SIMD_DUAL with bitwise **OR** (dual if either core is dual). `nif_compare_simd` compares topology value numerically as step 6 and SIMD_DUAL as the final (step 7) tie-break.
+`nfn_get_unite_simd` computes topology bits [1..0] with bitwise **AND** (conservative intersection — weaker topology wins) and SIMD_DUAL with bitwise **OR** (dual if either core is dual). `nfn_compare_simd` compares topology value numerically as step 6 and SIMD_DUAL as the final (step 7) tie-break.
 
 ---
 

src/Nitload.Native/lib/CMakeLists.txt

@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.16)
 
-if(NOT DEFINED NIF_NATIVE_EXTERNAL_TARGET)
-  message(FATAL_ERROR "NIF_NATIVE_EXTERNAL_TARGET must be set before adding lib/.")
+if(NOT DEFINED NFN_NATIVE_EXTERNAL_TARGET)
+  message(FATAL_ERROR "NFN_NATIVE_EXTERNAL_TARGET must be set before adding lib/.")
 endif()
 
 include(${CMAKE_CURRENT_LIST_DIR}/../ExternalLibs.cmake OPTIONAL)
@@ -17,6 +17,6 @@ foreach(_pkg ${LIB_PACKAGE_DIRS})
   if(EXISTS ${_pkg_dir}/CMakeLists.txt)
     add_subdirectory(${_pkg_dir})
   else()
-    nif_register_external_package(${NIF_NATIVE_EXTERNAL_TARGET} ${_pkg} ${_pkg_dir})
+    nfn_register_external_package(${NFN_NATIVE_EXTERNAL_TARGET} ${_pkg} ${_pkg_dir})
   endif()
 endforeach()

src/Nitload.Native/lib/glfw/CMakeLists.txt

@@ -1,11 +1,11 @@
 cmake_minimum_required(VERSION 3.16)
 
-nif_register_external_package(${NIF_NATIVE_EXTERNAL_TARGET} glfw ${CMAKE_CURRENT_LIST_DIR})
+nfn_register_external_package(${NFN_NATIVE_EXTERNAL_TARGET} glfw ${CMAKE_CURRENT_LIST_DIR})
 
 if(WIN32)
   if(NOT EXISTS ${CMAKE_CURRENT_LIST_DIR}/glfw3_mt.lib)
     message(FATAL_ERROR "Required GLFW static library not found: ${CMAKE_CURRENT_LIST_DIR}/glfw3_mt.lib")
   endif()
 
-  nif_link_external_binary_if_exists(${NIF_NATIVE_EXTERNAL_TARGET} ${CMAKE_CURRENT_LIST_DIR}/glfw3_mt.lib)
+  nfn_link_external_binary_if_exists(${NFN_NATIVE_EXTERNAL_TARGET} ${CMAKE_CURRENT_LIST_DIR}/glfw3_mt.lib)
 endif()

src/Nitload.Native/lib/glfw/glfw3native.h

@@ -207,7 +207,7 @@ GLFWAPI const char *glfwGetWin32Monitor(GLFWmonitor *monitor);
  *  GLFW_PLATFORM_UNAVAILABLE.
  *
  *  @remark The `HDC` associated with the window can be queried with the
- *  [GetDC](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getdc)
+ *  [GetDC](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nfn-winuser-getdc)
  *  function.
  *  @code
  *  HDC dc = GetDC(glfwGetWin32Window(window));
@@ -234,7 +234,7 @@ GLFWAPI HWND glfwGetWin32Window(GLFWwindow *window);
  *  GLFW_PLATFORM_UNAVAILABLE and @ref GLFW_NO_WINDOW_CONTEXT.
  *
  *  @remark The `HDC` associated with the window can be queried with the
- *  [GetDC](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getdc)
+ *  [GetDC](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nfn-winuser-getdc)
  *  function.
  *  @code
  *  HDC dc = GetDC(glfwGetWin32Window(window));

src/Nitload.Native/lib/stbi/CMakeLists.txt

@@ -1,3 +1,3 @@
 cmake_minimum_required(VERSION 3.16)
 
-nif_register_external_package(${NIF_NATIVE_EXTERNAL_TARGET} stbi ${CMAKE_CURRENT_LIST_DIR})
+nfn_register_external_package(${NFN_NATIVE_EXTERNAL_TARGET} stbi ${CMAKE_CURRENT_LIST_DIR})

src/Nitload.Native/nfn-head/NitloadFrameWork.h

@@ -0,0 +1,37 @@
+#ifndef NFN_NATIVE_H
+#define NFN_NATIVE_H
+
+#ifdef __cplusplus
+#error "This header is not meant to be included in C++ code. Nitload.Native is a C library and should be used with C linkage."
+#endif
+
+#include "nfn_internal.h"
+#include "nfn_target.h"
+
+#include <immintrin.h>
+#include <assert.h>
+#include <glfw_function.h>
+
+#define byte char
+#define cs_char uint16_t
+#define nfn_null_assert(ptr) assert(ptr != NULL)
+
+#ifndef NFN_
+#endif
+
+NFN_API void NFN_DECL   nfn_load_glfw_functions(GLFWFunctionTable *table);
+NFN_API void NFN_DECL   nfn_load_intrinsic_function(void *intrinsic_context, uint64_t id);
+NFN_API SIMDID NFN_DECL nfn_get_simd_level_global();
+/* Per-core variant: always re-executes CPUID, never caches.
+ * Must be called on the target core (after affinity is set). */
+NFN_API SIMDID NFN_DECL nfn_get_simd_level_local();
+NFN_API SIMDID NFN_DECL nfn_get_unite_simd(SIMDID left, SIMDID right);
+NFN_API int NFN_DECL    nfn_compare_simd(SIMDID left, SIMDID right);
+NFN_API void NFN_DECL   nfn_set_thread_affinity(int cpu_index, int processor_group_id);
+NFN_API void *NFN_DECL  nfn_numa_alloc(size_t size, int numa_id);
+NFN_API void NFN_DECL   nfn_numa_free(void *ptr, size_t size, int numa_id);
+NFN_API int NFN_DECL    nfn_get_numa_each(int numa_id, uint32_t *processor_group_ids,
+                                          uint32_t *socket_ids, uint32_t *cpu_indices,
+                                          uint32_t *numa_node_ids);
+NFN_API int NFN_DECL    nfn_get_numa_overall(int *out_numa_count, int *count_of_each_numa);
+#endif

src/Nitload.Native/nfn-head/nfn_internal.h

@@ -1,6 +1,6 @@
 
-#ifndef NIF_INTERNAL
-#define NIF_INTERNAL
+#ifndef NFN_INTERNAL
+#define NFN_INTERNAL
 
 #include <xmmintrin.h>
 
@@ -9,33 +9,33 @@
 #ifdef _MSC_VER
 #define _CRT_SECURE_NO_WARNINGS 1
 #define WIN32_LEAN_AND_MEAN
-#define NIF_DECL __cdecl
-#define NIF_MAT_DECL __cdecl __forceinline
-#define NIF_API __declspec(dllexport)
+#define NFN_DECL __cdecl
+#define NFN_MAT_DECL __cdecl __forceinline
+#define NFN_API __declspec(dllexport)
 #define FORCEINLINE __forceinline
 #define NOINLINE __declspec(noinline)
 #include <windows.h>
 #elif defined(__clang__) || defined(__GNUC__)
-#define NIF_DECL __attribute__((cdecl))
-#define NIF_MAT_DECL __attribute__((cdecl)) __attribute__((always_inline))
-#define NIF_API __attribute__((dllexport))
+#define NFN_DECL __attribute__((cdecl))
+#define NFN_MAT_DECL __attribute__((cdecl)) __attribute__((always_inline))
+#define NFN_API __attribute__((dllexport))
 #define FORCEINLINE __attribute__((always_inline))
 #define NOINLINE __attribute__((noinline))
 #else
-#define NIF_API
-#define NIF_DECL
-#define NIF_MAT_DECL
+#define NFN_API
+#define NFN_DECL
+#define NFN_MAT_DECL
 #define FORCEINLINE
 #define NOINLINE
 #endif
 
 #if defined(_MSC_VER)
-#define NIF_ALIGNAS(n) __declspec(align(n))
+#define NFN_ALIGNAS(n) __declspec(align(n))
 #else
-#define NIF_ALIGNAS(n) __attribute__((aligned(n)))
+#define NFN_ALIGNAS(n) __attribute__((aligned(n)))
 #endif
 
-#define NIF_APIDEF
+#define NFN_APIDEF
 
 #define PRIVATE static
 #define INTERNAL extern

src/Nitload.Native/nfn-head/nfn_intrinsic.context.base.h

@@ -1,5 +1,5 @@
-#ifndef NIF_INTRINSIC_CONTEXT_BASE
-#define NIF_INTRINSIC_CONTEXT_BASE
+#ifndef NFN_INTRINSIC_CONTEXT_BASE
+#define NFN_INTRINSIC_CONTEXT_BASE
 
 
 // -----------------------------------------------------------------------------