Book macro

Examples

quick.rs

#![allow(unused)]
fn main() {
// SPDX-License-Identifier: AGPL-3.0
// Copyright (C) 2026 SAP2B

#![no_std]
#![no_main]

use kyaaa::*;

// Define cache-aligned memory layouts (64-byte alignment to prevent false sharing across cores)
page!(
    align(64) struct Game {
        id: Str<32>,
        name: Str<32>,
    }

    align(64) struct User {
        id: Str<32>,
        name: Str<32>,
    }
);

// Global compile-time static book instance mapped directly in the data segment
book!(
    pub static HLIST;
    zelda => Game {
        id: Str::from_str("323456789012345678901234"),
        name: Str::from_str("LOL"),
    },
    re9 => Game {
        id: Str::from_str("523456789012345678901234"),
        name: Str::from_str("Requiem"),
    },
    player => User {
        id: Str::from_str("623456789012345678901234"),
        name: Str::from_str("Player"),
    },
    admin => User {
        id: Str::from_str("423456789012345678901234"),
        name: Str::from_str("admin"),
    },
);

// Entry-point generation macro with 64-byte stack alignment
kmain!(
    align(64);

    fn kmain(_sp: *const usize) -> i32 {
        // Local expression-based book instance allocated on the stack
        let hlist = book!(
            nier => Game {
                id: Str::from_str("023456789012345678901234"),
                name: Str::from_str("LOL"),
            },
            mario => Game {
                id: Str::from_str("023456789012345678901234"),
                name: Str::from_str("Mario"),
            },
            sap => User {
                id: Str::from_str("223456789012345678901234"),
                name: Str::from_str("SAP2B"),
            },
            admin => User {
                id: Str::from_str("423456789012345678901234"),
                name: Str::from_str("admin"),
            },
        );

        // Zero-cost field mutation via generated reference wrappers
        hlist.nier().set().name("NieR Automata");
        hlist.sap().set().name("SAP2B HFT");
        HLIST.zelda().set().name("Zelda");
        HLIST.admin().set().name("Admin HFT");

        // Type-safe dynamic element retrieval using ID lookups
        if let Some(nier) = hlist.get::<Game>(hlist.nier().id()) {
            black_box(nier);
        }
        if let Some(zelda) = HLIST.get::<Game>(HLIST.zelda().id()) {
            black_box(zelda);
        }

        // Type mismatch check: returns None safely because `hlist.sap().id()` belongs to a User, not a Game
        let mismatch = hlist.get::<Game>(hlist.sap().id());
        black_box(mismatch);

        // Zero-overhead filtered iterations over specific concrete types
        hlist.list::<User>().for_each(|user| {
            black_box(user);
        });

        HLIST.list::<User>().for_each(|user| {
            black_box(user);
        });

        0
    }
);

// Inline helper to prevent dead-code elimination by compiler optimizations
#[inline(always)]
fn black_box<T>(dummy: T) -> T {
    core::hint::black_box(dummy)
}
}

gameasm.rs

#![allow(unused)]
fn main() {
// SPDX-License-Identifier: AGPL-3.0
// Copyright (C) 2026 SAP2B

#![no_main]
#![no_std]

use kyaaa::*;

page!(
    align(64) struct Game {
        id: Str<32>,
        name: Str<32>,
    }

    align(64) struct User {
        id: Str<32>,
        name: Str<32>,
    }
);

book!(
    pub static HLIST;
    zelda => Game {
        id: Str::from_str("323456789012345678901234"),
        name: Str::from_str("LOL"),
    },
    admin => User {
        id: Str::from_str("423456789012345678901234"),
        name: Str::from_str("admin"),
    },
);

kmain!(
    align(64);

    fn kmain(_sp: *const usize) -> i32 {
        let hlist = book!(
            nier => Game {
                id: Str::from_str("023456789012345678901234"),
                name: Str::from_str("LOL"),
            },
            sap => User {
                id: Str::from_str("223456789012345678901234"),
                name: Str::from_str("SAP2B"),
            },
        );

        hlist.nier().set().name("NieR Automata");
        hlist.sap().set().name("SAP2B HFT");
        HLIST.zelda().set().name("Zelda");
        HLIST.admin().set().name("Admin HFT");

        black_box(hlist.nier().get());
        black_box(hlist.sap().get());
        black_box(HLIST.admin().get());
        black_box(HLIST.zelda().get());

        0
    }
);

#[inline(always)]
fn black_box<T>(dummy: T) -> T {
    core::hint::black_box(dummy)
}
}

assembly proof

cargo asm --example gameasm --release k_main

[build]
target = "x86_64-unknown-none"

[target.x86_64-unknown-none]
rustflags = [
    "-C", "target-cpu=native",
    "-C", "code-model=kernel",
    "-C", "relocation-model=static",
    "-C", "default-linker-libraries=no",
    "-C", "llvm-args=-inline-threshold=1000",
    "-C", "force-frame-pointers=off",
    "-C", "target-feature=+sse,+sse2,+avx,+avx2"
]

[package]
name = "kyaaa"
version = "0.2.3"
edition = "2024"
description="Zero heap. Zero vtables. A static no_std heterogeneous list (HList) that murders dynamic dispatch and melts straight into raw ASM... kyaaa!"
keywords = ["hlist", "no_std", "zero-cost", "macro", "data-structures"]
categories = ["data-structures", "no-std", "embedded", "memory-management"]
license = "AGPL-3.0-only"
repository = "https://github.com/SAP2B/kyaaa"
readme = "README.md"

[dependencies]

[dev-dependencies]

[profile.dev]
panic = "abort"

[profile.release]
opt-level = 3        
lto = "fat"          
codegen-units = 1    
panic = "abort"      
strip = true         
debug = false

output