native-code

Domain knowledge for building native extensions for the BEAM VM. Covers the NIF boundary (C and Rust), SIMD via Zig, and the cross-cutting concerns that apply regardless of implementation language.

For general language patterns (C, Zig, Rust), see droo-stack.

What You Get

• NIF boundary patterns (C erl_nif.h, Rust Rustler, Zig SIMD)
• Scheduler contract and memory model rules
• Elixir-side module structure for NIF wrappers
• Common crash/leak patterns and fixes
• Two-level testing strategy (native unit + ExUnit boundary)

When to use

• Writing or reviewing NIF code (C erl_nif.h or Rust Rustler)
• Integrating Zig SIMD routines into BEAM via C ABI
• Designing the Elixir-side module for a NIF
• Debugging scheduler issues, memory leaks, or crashes at the native boundary
• Building tree-sitter grammar parsers as NIFs
• Setting up precompiled NIF releases

When NOT to use

• General C, Zig, or Rust coding -- use droo-stack
• General Elixir patterns -- use droo-stack
• Raxol TUI framework -- use raxol skill

Reading guide

Working on	Read
Scheduler contract, memory model, deployment	references/boundary-patterns
Elixir-side NIF module structure	references/nif-elixir
C NIFs (erl_nif.h, resources, tree-sitter)	references/nif-c
Rust NIFs (Rustler, ResourceArc, safety)	references/nif-rust
Zig SIMD (@Vector, reductions, NIF integration)	references/simd-zig

Key principles

1. Never block the BEAM scheduler -- NIFs must return within 1ms or use dirty schedulers
2. The BEAM owns terms, you own native memory -- never store ERL_NIF_TERM across NIF calls
3. Crash in NIF = crash the entire VM -- no panics (Rust), no segfaults, no undefined behavior
4. Test at two levels -- native unit tests (cargo test, zig test) AND ExUnit boundary tests
5. Zero-copy where possible -- use BEAM binaries for large data transfer

Common pitfalls

Mistake	Impact	Fix
NIF takes >1ms without dirty scheduler	Scheduler starvation, latency spikes	Add ERL_NIF_DIRTY_JOB_CPU_BOUND or schedule = "DirtyCpu"
Storing ERL_NIF_TERM in native struct	Use-after-free, undefined behavior	Copy data out of terms, or use enif_make_copy with a process-independent env
Rust panic! / unwrap() inside NIF	Entire BEAM VM crashes	Use Result, catch panics at boundary with std::panic::catch_unwind
Missing NIF stub in Elixir module	Silent nil return or confusing error	Stub must raise "NIF not loaded"
Not freeing native resources	Memory leak proportional to call rate	Register destructors via resource types

See also

• droo-stack -- C, Zig, Rust language patterns
• raxol -- Elixir TUI framework (potential NIF consumer)
• nix -- packaging native deps with Nix (buildRustPackage, mkDerivation)