# Native Modules

PetaPerl does not support XS (C extensions). Instead, performance-critical
CPAN modules are reimplemented natively in Rust. These "native modules"
provide the same Perl-level API as their XS counterparts but integrate
directly with PetaPerl's runtime — enabling JIT compilation, auto-parallelization,
and zero FFI overhead.

## How It Works

When you write `use List::Util qw(sum min max)`, PetaPerl's module loader
detects that `List::Util` has a native implementation and registers Rust
function pointers directly. There is no compilation step, no `.so` loading,
and no XS glue code.

Native functions are dispatched via `NativeFn` — a direct function pointer
with O(1) call overhead, identical to built-in operators.

## Available Native Modules

### Core Utilities

| Module | Functions | Notes |
|--------|-----------|-------|
| Scalar::Util | blessed, reftype, refaddr, weaken, isweak, looks_like_number, ... | Full API |
| List::Util | sum, min, max, first, any, all, none, reduce, ... | MULTICALL optimized |
| Sub::Util | subname, set_subname | |
| Hash::Util | lock_keys, lock_hash, ... | |

### Digest / Crypto

| Module | Functions | Notes |
|--------|-----------|-------|
| Digest::MD5 | md5, md5_hex, md5_base64, OO interface | Full API |
| Digest::SHA | sha1, sha256, sha512, OO interface | Full API |
| MIME::Base64 | encode_base64, decode_base64 | |
| MIME::QuotedPrint | encode_qp, decode_qp | |

### File / System

| Module | Functions | Notes |
|--------|-----------|-------|
| File::Basename | basename, dirname, fileparse | |
| File::Copy | copy, move | |
| File::Find | find, finddepth | |
| File::Glob | bsd_glob | |
| File::Path | make_path, remove_tree | |
| File::Spec | catdir, catfile, rel2abs, ... | |
| File::Temp | tempfile, tempdir | OO + functional |
| File::stat | stat (OO) | |
| Cwd | cwd, getcwd, abs_path | |
| Sys::Hostname | hostname | |

### I/O

| Module | Functions | Notes |
|--------|-----------|-------|
| IO::File | OO file handle | |
| IO::Handle | OO handle base | |
| IO::Dir | OO directory handle | |
| IO::Pipe | OO pipe handle | |
| IO::Select | select wrapper | |
| IO::Socket | OO socket handle | |
| IO::Seekable | seek/tell mixin | |
| FileHandle | Legacy OO handle | |
| Socket | socket primitives | |

### Data / Encoding

| Module | Functions | Notes |
|--------|-----------|-------|
| Data::Dumper | Dumper | |
| Storable | freeze, thaw, nstore, retrieve | |
| Encode | encode, decode, find_encoding | |
| JSON::PP | encode_json, decode_json | Via Pure Perl |

### Numeric / Math

| Module | Functions | Notes |
|--------|-----------|-------|
| POSIX | floor, ceil, fmod, strtod, strftime, ... | Subset |
| Math::GMP | Arbitrary precision integers | Via Peta::FFI::GMP |

### Build / Config

| Module | Functions | Notes |
|--------|-----------|-------|
| Config | %Config hash | Build configuration |
| Fcntl | O_RDONLY, O_WRONLY, ... | Constants auto-loaded |
| Errno | ENOENT, EACCES, ... | Constants auto-loaded |

### Introspection

| Module | Functions | Notes |
|--------|-----------|-------|
| B | Compiler backend introspection | Minimal |
| PadWalker | peek_my, peek_our | |
| mro | get_linear_isa, set_mro | |
| version | Version object handling | Full OO API |

## Performance

Native modules run at the same speed as built-in operators since they share
the same dispatch mechanism. For block-taking functions (first, any, all,
reduce), PetaPerl uses MULTICALL optimization to avoid per-element subroutine
call overhead.

Benchmarks (vs perl5 with XS):

| Function | PetaPerl native | perl5 XS | Ratio |
|----------|----------------|----------|-------|
| List::Util::sum | 1.7x faster | baseline | |
| List::Util::min/max | 2.9x faster | baseline | |
| List::Util::first | ~1x | baseline | MULTICALL parity |

## Adding Native Modules

Native module documentation is extracted from the module's Rust
source (`//!` module docs and `///` function docs) by
`docs/sphinx/bin/02-reference` during the docs build.