Peta::XS#

📦 std

Peta::XS - the interpreter’s capability layer for pure Perl.

Design: docs/internal/design/peta-xs.md; rationale and tier model: docs/internal/analysis/xs.md. Unlike every other module in src/native/ this is NOT a CPAN phenotype - there is no upstream .xs to mirror. It is pperl’s own versioned, semantic API that lets third-party pure Perl do what internals-XS modules do on perl5.

CONTRACT (v1.0)#

Capabilities: facts, magic. Evolution is additive within a major version; a capability is never silently redefined.

  1. Facts and verbs, never layout. Every exposed datum is defined by observable semantics (never flag bits, offsets, addresses or struct names) and survives any internal refactor.

  2. Opaque handles. Anything referring to an interpreter entity (a wizard, a magic attachment) is a runtime-owned opaque value - no arithmetic, no raw pointers as IVs.

  3. The boundary speaks Perl. Callbacks are coderefs; data crosses as ordinary Perl values. Consumers are pure Perl and cannot be binary-broken by any pperl release. The loudest possible failure is a compile-time version/capability refusal in import.

JIT interaction (contract text): a variable carrying Peta::XS magic is never JIT-compiled - the p5jit entry guards decline magical SVs, so compiled-loop exactness holds by construction.

The implementation attaches PERL_MAGIC_ext (‘~’) magic through the pperl core (sv.c Perl_sv_magicext, mg.c call discipline), so callback timing is exactly perl5’s tied-variable timing. No Rust-side registry exists: all state rides on the magic attachment’s mg_obj, the way XS magic modules own state.

Functions#

Other Functions#

refcount#

Reference count of the thing $ref points at.

value_slots#

Which value representations the runtime currently considers valid for the scalar $ref points at.

magic#

Inventory of the magic attached to the variable $ref points at.

wizard#

Create a wizard: an opaque bundle of magic callbacks.

cast#

Attach a wizard to the variable $ref points at.

dispell#

Detach a wizard from the variable $ref points at.

getdata#

Retrieve the private data this wizard’s attachment carries.