Documentation

Compiling & Running

perla has four main modes of invocation:

All command-line flags

Optimization levels

Defaults to -O0 — optimized for compile speed during dev. For release builds, use -O2 or -O3.

On a medium-sized web app, the gcc phase goes from ~15s at -O0 to ~100s at -O2. Worth it for release; not worth it during iteration.

__C__ Blocks

__C__ { ... } drops raw C into the generated output. perla doesn't parse or rewrite the block — it's emitted verbatim. Three valid positions:

File scope

Place outside any sub. Use for #includes, static state, and helper functions that you'll call from multiple __C__ blocks.

__C__ {
    #include <sys/time.h>
    #include <unistd.h>
    static int call_counter = 0;
}

Inside a sub

Emitted as a { ... } block inside the generated C function body.

sub add {
    my ($a, $b) = @_;
    my $sum = 0;
    __C__ {
        int64_t __a = strada_to_int(v_a);
        int64_t __b = strada_to_int(v_b);
        strada_decref(v_sum);
        v_sum = strada_new_int(__a + __b);
    }
    return $sum;
}

Expression context (GCC statement-expression)

my $pid = __C__ {
    ({ StradaValue *__r = strada_new_int((int64_t)getpid()); __r; })
};

Variable name mapping

Runtime helpers available

All strada_* and perla_* functions are in scope. The most useful:

Memory rules

1. Tagged-int guard. Integers in range -2^62..2^62-1 are encoded directly in pointers. Any code that reads sv->type/sv->value/sv->meta/sv->refcount must check STRADA_IS_TAGGED_INT(sv) first. The high-level helpers handle this for you.
2. strada_to_str allocates. Always free() the result. For no-alloc, use strada_to_str_buf with a stack buffer.
3. Decref before reassign. strada_decref(v_result); v_result = strada_new_int(42); — forgetting leaks; double-free is worse.
4. _take vs plain for container inserts. strada_hv_store_take(hv, "k", strada_new_str("v")) keeps refcount at 1; strada_hv_store increfs. Use _take for freshly-allocated values, plain store for existing variables.

Complete worked example

use strict;

__C__ {
    #include <sys/resource.h>
}

sub rss_bytes {
    my $r = 0;
    __C__ {
        struct rusage __u;
        if (getrusage(RUSAGE_SELF, &__u) == 0) {
            /* ru_maxrss is KB on Linux, bytes on macOS */
            strada_decref(v_r);
            v_r = strada_new_int((int64_t)__u.ru_maxrss * 1024);
        }
    }
    return $r;
}

printf "RSS: %d MB\n", int(rss_bytes() / 1024 / 1024);

For the complete __C__ reference including FFI examples, see the Markdown version on GitHub.

Module Search Paths

perla has two separate search paths for use and require.

Compile-time path (consulted when parsing use X)

Built by _build_lib_paths, in search order:

1. Directory of the input file
2. Current directory (.)
3. $PERLA5LIB env var
4. $PERL5LIB (Perl compatibility)
5. $HOME/perla/lib (if it exists)
6. -I path CLI flags (prepended)
7. use lib "..." statements during parse

Not included by default: /opt/bzperl/... or any large CPAN tree. Including it would trigger transitive source parsing of every module in the tree, blowing compile time. Add it via use lib "..." in your script if you need it.

Runtime path (consulted for require and lazy-loads)

Baked into the executable at compile time. Plus at startup: $PERLA_LIB, ~/.perla.conf, /etc/perla.conf. Also probes archlib subdirs (x86_64-linux/) for each path.

Dedup

Two layers prevent re-parsing:

• Name-keyed: use Foo::Bar twice gets caught by matching the Perl module name.
• Path-keyed: two different use statements resolving to the same file (lib-path collisions) get caught by matching the resolved path.

The precompile cache

perla -M Foo/Bar.pm writes:

• Foo/Bar.pm.o — object file for static linking
• Foo/Bar.pm.deps — transitive dependency list
• Foo/Bar.pm.so — shared library (if PERLA_BUILD_PM_SO=1 or --shared)

Subsequent compiles that use this module pick up the cached .pm.o instead of re-parsing. Useful for warming a module tree:

$ perla -M lib/          # recursively precompile every .pm under lib/

Auto-build heuristic

By default, a module used in your program is only auto-precompiled if its source matches an import-installing pattern (sub import, our @EXPORT, *{$M.import}). Everything else is left for runtime require. This prevents runaway cascade compiles.

To precompile every dependency, use --precompile-deps.

Installing CPAN Modules

perla ships native implementations of the most-used modules (JSON, DBI, Carp, Data::Dumper, List::Util, Scalar::Util, Storable, Encode, File::Temp, Digest::*, MIME::Base64, Time::HiRes, and more). For everything else — pure-Perl and XS — there's perla-cpan.

Quick start

# One-time: point perla at an install prefix
$ export PERLA_LIB=$HOME/.perla/local/lib/perla5
$ export PERLA5LIB=$PERLA_LIB

# Install what your program needs — dependencies resolved automatically
$ perla-cpan Try::Tiny Path::Tiny JSON::MaybeXS

# Compile and run as usual
$ perla myprog.pl

Sources

perla-cpan accepts a module name (fetched from MetaCPAN), a pre-unpacked directory, or a local tarball:

$ perla-cpan Try::Tiny                   # by name, with transitive deps
$ perla-cpan ~/build/My-Dist-1.0/         # pre-unpacked directory
$ perla-cpan --deps ~/dl/Foo-Bar.tar.gz   # local tarball, recurse deps

Useful flags

Debugging & Diagnostics

--debug output vocabulary

Common failure modes

sh: 1: foo: not found after compile

The compiled binary wasn't on $PATH. Recent perla prefixes ./ automatically; if you see this, rebuild perla.

redefinition of 'perla_sub_Foo_bar' at link

Either the source defines the same sub twice (perla now matches Perl's last-wins semantic — rebuild perla), or a dependency cycle re-parses the file (caught by path-keyed dedup).

undefined reference to perla_mod_init_Xxx at link

A precompiled .pm.o was built with the wrong module name. Re-run perla -M /full/path/to/module.pm or set PERLA_MODULE_NAME=Foo::Bar explicitly.

Can't locate object method X via package "REF(0x0x...)"

A blessed ref was stringified for use as a class name. perla_bless should unwrap this via perla_class_name — rebuild perla if you see this today.

Compile works but program behaves weirdly

Run with --keep, grep the generated .c for the affected sub. Usually a codegen issue with a specific Perl idiom.

Environment variables

Perl Compatibility

What works

• Core syntax: sigils, arrays, hashes, regex (=~, s///, m// with /i, /s, /x, /g, /e), foreach/map/grep/sort, push/pop/shift/unshift, slice syntax, string interpolation, heredoc, qw//.
• OO: bless, @ISA, SUPER::, AUTOLOAD, multiple inheritance with Perl's method resolution order, overload ("", ==, arithmetic, etc.).
• Moose-ish: has, extends, with, before/after/around, isa, meta, auto-accessors — native C runtime implementation (not Class::MOP).
• Exception handling: eval { }, die, $@, Try::Tiny, typed catch.
• Text & symbol-table features: format/write reports (incl. $~/$^/$=/$%/$^A, formline), tie/untie/tied on scalars, hashes, arrays, and filehandles, typeglobs and aliasing (*A = *B, *A = \$x), goto LABEL, state variables, local on slices.
• Full Unicode: UTF-8 string semantics (the SVf_UTF8 flag), Unicode::Normalize / utf8:: NFC/NFD/NFKC/NFKD, and Encode transcoding (Latin-1, CP1252, ASCII). Plus unsigned 64-bit (UV) integer arithmetic.
• Core modules: strict, warnings, Carp, Data::Dumper, JSON, YAML, URI::Escape, File::Spec, File::Temp, File::Find, List::Util, Scalar::Util, Time::HiRes, Encode, Digest::MD5/SHA, MIME::Base64, HTTP::Date, Storable::dclone.
• DBI: connection, prepare, execute, bind, fetchrow_hashref/array, selectrow_array, transactions (begin_work/commit/rollback), etc. SQLite, MySQL/MariaDB, and PostgreSQL drivers via native implementation.
• CPAN modules: install pure-Perl and XS distributions with perla-cpan — it fetches from MetaCPAN, resolves transitive deps, and compiles XS against perla's perl.h shim.
• DBIx::Class: a minimal stub in your lib/DBIx/Class/ provides has_one/has_many/belongs_to, ResultSet::search/first/all, Bootstrap::Simple. Not the real DBIC — it's a re-implementation of its public API.
• Drogo (web framework): works, including Drogo::Server::Cannoli.

What doesn't work (yet)

• eval STRING at runtime. Has an opt-in path via core::full_eval_on() but it shells out to a child perla compile — slow and not ergonomic. eval BLOCK works normally for exception handling.
• Runtime DynaLoader/XSLoader bootstrap of arbitrary .sos. XS is compiled ahead of time by perla-cpan against perla's perl.h shim and linked in — there's no perl-style runtime loader. Most distributions build cleanly; a complex one may surface a missing macro in the shim (usually a one-line addition).
• CPAN version constraints & Makefile.PL configure logic. perla-cpan installs the current release and reads lib/ directly; it doesn't run a dist's configure-time code or satisfy >=1.0, <2.0 ranges.
• Threads (Perl's threads module). perla is single-threaded per process; use fork for concurrency (async::* helpers work).
• Source filters. Parse happens before any runtime, so source filters that modify the source at use-time don't apply.
• Some corner-case Perl idioms. Deep symbol-table trickery, local on some magical vars, baroque overload dispatch. Most work; a fraction don't. Report them.

Memory Management

perla links Strada's shared runtime, which means Perl programs compiled with perla get two opt-in memory features that mainline Perl does not have. Both are compiled in by default and are no-ops in source if the runtime was built --without-cycle-gc or --without-arena.

Automatic cycle collection

A Bacon–Rajan synchronous cycle collector reclaims indirect reference cycles (array/hash/ref graphs) without Scalar::Util::weaken. It runs at a candidate-root threshold and once more at exit. Acyclic data is still freed deterministically via refcounting; only genuine cycles wait for the collector.

# Indirect cycle -- normal Perl leaks this; perla collects it automatically.
my $a = { name => "a" };
my $b = { name => "b" };
$a->{peer} = $b;
$b->{peer} = $a;        # no weaken needed

Scalar::Util::weaken still works as before and is the right choice when you need deterministic teardown or are targeting a runtime built --without-cycle-gc. Cycles that close only through a closure capture or a tied container fall back to weaken; those aren't handled by the collector. Cyclic blessed objects reclaimed by the collector skip DESTROY — this matches Perl's own global-destruction behaviour for unreachable cycles.

Explicit controls are exposed under Strada:::

Request arena

For request-scoped work (most obviously Cannoli’s preforking workers), the arena bump-allocates StradaValue structs into a region freed wholesale at arena_end — skipping per-object allocation and refcount teardown for the request's churn. Dormant until Strada::arena_begin() is called; safe to ship enabled.

Strada::arena_begin();
handle_request($req);     # allocate freely; nothing freed individually
Strada::arena_end();        # reclaims everything allocated since begin

See the Strada memory documentation for the deeper design notes (side-table cycle collector, ARENA_OWNS skip in strada_free_value, the cycle collector's cc_free_shell).

Cannoli Integration

Cannoli is the Strada-native preforking HTTP server. perla-compiled apps load into it via the cannoli_perla.so bridge.

$ cd /path/to/cannoli/lib/perla
$ make                            # builds cannoli_perla.so
$ make demo                       # builds Demo.pm.so
$ /path/to/cannoli/cannoli \
    --library "./cannoli_perla.so:\
        so=$(pwd)/Demo.pm.so;\
        init=perla_mod_init_Demo;\
        handler=perla_sub_Demo_hello" \
    --dev -p 8080

$ curl http://127.0.0.1:8080/
Hello from a perla-compiled handler!

The bridge parses three config options:

• so= — path to the perla-compiled .pm.so (handler module)
• init= — module init function to call once at startup (usually perla_mod_init_Foo)
• handler= — per-request handler function (usually perla_sub_Foo_handle)

See the cannoli_perla source for full detail. Cannoli ships with a parallel cannoli_perl.so for running real Perl (via libperl) if you'd rather stay in that world.

Tip: wrap each request in Strada::arena_begin() / Strada::arena_end() (see Memory Management) for one-shot wholesale reclamation of the request's allocations. Cannoli's preforking model (single-threaded per worker) is the intended use case; nothing in the bridge prevents it from working out of the box.

More