Peta::XS#

📦 std

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

Unlike pperl’s other native modules, this is not a CPAN module reimplemented: it is pperl’s own versioned, semantic API that lets third-party pure Perl do what internals-XS modules do on perl5.

use Peta::XS qw(:facts :magic);

my $x = 1;
print "refcount ", refcount(\$x), "\n";          # 2: $x, and the reference passed
my $reads = 0;
my $w = wizard(
    get  => sub { $reads++ },
    set  => sub { my ($ref, $data) = @_; $data->{sets}++ },
    data => sub { return { sets => 0 } },
);
cast(\$x, $w);                                   # attach the hooks to $x
my $y = $x + $x;                                 # two reads
$x = 5;                                          # one write
print "reads $reads, sets ", getdata(\$x, $w)->{sets}, "\n";   # reads 2, sets 1
print join(",", map { $_->{type} } magic(\$x)), "\n";          # ~
dispell(\$x, $w);                                # detach

Capabilities are imported by tag: :facts (refcount, value_slots, magic) and :magic (wizard, cast, dispell, getdata). use Peta::XS; alone imports nothing.

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.

A variable carrying Peta::XS magic is never JIT-compiled, so its callbacks fire on every access, exactly as the interpreter would fire them. Callbacks run with exactly the timing of perl’s tied variables.

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.