view release on metacpan or  search on metacpan

lib/Affix.pod  view on Meta::CPAN

    free($ptr);

=head3 C<own( $pin )>

Returns true if the given pin is an owned C<Affix::Memory> object (i.e., memory allocated via C<malloc> or C<calloc>
that Perl manages directly). Returns false for unmanaged pins or raw scalars.

    if (own($ptr)) {
        say "Perl owns this memory; it will be freed automatically.";
    }

=head3 C<is_pin( $var )>

Returns true if the variable is currently bound to C memory via C<pin>, C<cast>, or pointer dereferencing. Returns
false for ordinary Perl scalars.

    my $x = 42;
    say is_pin($x); # false

    pin $x, libc(), 'errno', Int;
    say is_pin($x); # true

=head2 Lifecycle & Ownership

=head3 C<attach_destructor( $pin, $func_ptr, [$lib] )>

Attaches a custom C function to be called when the Pin is destroyed. This is incredibly useful for C libraries that
require specific cleanup routines (e.g., C<SDL_DestroyWindow>, C<sqlite3_free>).

    # Find the address of the library's custom free function
    my $free_func = find_symbol($my_lib, 'custom_free');

    # When $ptr goes out of scope, Affix will call custom_free($ptr)
    attach_destructor($ptr, $free_func, $my_lib);

=head3 C<readonly( $pin, [$bool] )>

Gets or sets the "const" status of a memory pin. If set to true, any attempt to write to that memory from Perl will
throw an exception.

    readonly($point, 1);
    $point->{x} = 20; # CRASH: Modification of a read-only C value

=head2 Type Casting

=head3 C<cast( $ptr, $type )>

The most powerful tool in the memory kit. It "overlays" a C type definition onto a raw memory address.

    my $mem = malloc(16);
    my $point = cast($mem, Struct[ x => Int, y => Int ]);
    $point->{x} = 10;

=head1 POINTER UTILITIES

Navigate and inspect raw pointers with helper functions for address arithmetic, null checks, and more.

=head3 C<address( $ptr )>

Returns the virtual memory address of the pointer as a Perl Unsigned Integer (C<UInt64>). Useful for passing addresses
to other FFI libraries or debugging.

    say sprintf("Address: 0x%X", address($ptr));

=head3 C<ptr_add( $ptr, $offset_bytes )>

Returns a new B<unmanaged alias Pin> offset by C<$offset_bytes>.

    my $int_arr   = calloc(10, Int);
    my $next_elem = ptr_add($int_arr, sizeof(Int));

I<Note: If C<$ptr> is an Array type, C<ptr_add> correctly decays the returned pin into a Pointer to the element type.>

=head3 C<ptr_diff( $ptr1, $ptr2 )>

Returns the byte difference (C<$ptr1 - $ptr2>) between two pointers as an integer.

=head3 C<is_null( $ptr )>

Returns true if the address is C<NULL> (C<0x0>).

=head3 C<strnlen( $ptr, $max )>

Safe string length calculation. Checks the pointer for a C<NULL> terminator, scanning at most C<$max> bytes.

=head3 C<raw( $ptr, $length_in_bytes )>

Returns a Perl string containing the raw, un-decoded binary data extracted directly from the memory address. This is
the programmatic, binary equivalent of C<dump()>.

=head3 C<snapshot( $pin )>

Deeply reads the C memory backing a Pin and returns a pure, non-magical native Perl data structure (ArrayRef, HashRef,
or Scalar). Because it does not apply VTable magic to the returned values, reading elements from the returned structure
in a bulk operation (like summing a 10,000 element array) is exceptionally fast.

=head1 Raw Memory Operations

Classic C memory functions (memcpy, memset, etc.) available directly from Perl for high-performance byte manipulation.
These functions accept either Pins or raw integer addresses.

=over

=item * C<memcpy( $dest, $src, $bytes )>: Copies exactly C<$bytes> from C<$src> to C<$dest>.

=item * C<memmove( $dest, $src, $bytes )>: Copies C<$bytes> from C<$src> to C<$dest>. Safe to use if the memory regions overlap.

=item * C<memset( $ptr, $byte_val, $bytes )>: Fills the first C<$bytes> of the memory block with the value C<$byte_val>.

=item * C<memcmp( $ptr1, $ptr2, $bytes )>: Compares the first C<$bytes> of two memory blocks. Returns an integer less than, equal to, or greater than zero.

=item * C<memchr( $ptr, $byte_val, $bytes )>: Locates the first occurrence of C<$byte_val> within the first C<$bytes> of the memory block. Returns a new Pin pointing to the match, or C<undef>.

=back

=head1 C<Const> & Readonly Memory

Enforce C's const contract at the Perl level. Affix intercepts writes to read-only memory and throws a fatal exception:
C<Modification of a read-only C value attempted>.

=head2 Declarative Const: C<Const[ $type ]>