view release on metacpan or  search on metacpan

lib/Affix.pod  view on Meta::CPAN

=item * B<Constants:> C<typedef> installs constants (e.g., C<OK() == 0>) into your package.

=item * B<Dualvars:> Values returned from C act as dualvars. They print as strings (C<"OK">) but evaluate mathematically as integers (C<0>).

=item * B<String Marshalling:> You can pass the string name of an element (C<"OK">) directly to functions that expect
that enum type.

=item * B<Aliases:> You can also use C<IntEnum[ ... ]>, C<CharEnum[ ... ]>, and C<UIntEnum[ ... ]> to force the underlying integer size.

=back

=head2 SIMD Vectors

Vectors are first-class types. You can interact with them using standard B<ArrayRefs> (convenient) or B<Packed Strings>
(high-performance, zero-overhead).

=over

=item * B<C<Vector[ $size, $type ]>>: Create a custom vector (e.g., C<Vector[ 4, Float ]>).

=item * B<Aliases>: C<M256>, C<M256d>, C<M512>, C<M512d>, C<M512i>.

=back

    # C: __m256 add_vecs(__m256 a, __m256 b);
    affix $lib, 'add_vecs', [ M256, M256 ] => M256;
    my $v1 = pack('f8', 1..8);
    my $v2 = pack('f8', 10, 20, 30, 40, 50, 60, 70, 80);
    my $packed_res = add_vecs( $v1, $v2 );

=head1 MEMORY MANAGEMENT

When bridging Perl and C, handling raw memory safely is critical. Affix uses B<Pins> to manage this boundary.

A Pin (an C<Affix::Pointer> object) is a magical scalar reference that holds a C memory address, its associated type
information, and an ownership flag. If a Pin is "managed", Perl will automatically free the underlying memory when the
variable goes out of scope.

=head2 Allocation & Deallocation

These functions allocate memory on the C heap. Memory allocated via these functions is B<managed by Perl> by default.

=head3 C<malloc( $size )>

Allocates C<$size> bytes of uninitialized memory. Returns a managed C<Pointer[Void]> pin.

    my $ptr = malloc(1024); # Allocates 1KB
    # $ptr is automatically freed when it goes out of scope

=head3 C<calloc( $count, $type )>

Allocates memory for an array of C<$count> elements of the given C<$type>, and zero-initializes the memory. Returns a
managed pin typed as an Array.

    my $arr = calloc( 10, Int );
    $arr->[0] = 42; # Write directly to the first element

=head3 C<realloc( $ptr, $new_size )>

Resizes the memory area pointed to by C<$ptr> to C<$new_size> bytes. The original pin is updated automatically
in-place.

    $ptr = realloc( $ptr, 2048 );

=head3 C<strdup( $string )>

Allocates managed memory and copies the Perl string (along with a C<NULL> terminator) into it. Returns a managed
C<Pointer[Char]> pin.

    my $str_ptr = strdup("Hello C!");

=head3 C<free( $ptr )>

Manually releases memory.

B<Warning:> Only use this on memory that you exclusively own (e.g., allocated via C<malloc>). Do not call C<free> on
unmanaged pointers returned by C libraries unless the library explicitly transfers ownership to you, or you will cause
a segmentation fault.

    free($ptr);

=head2 Lifecycle & Ownership

=head3 C<own( $ptr, [$bool] )>

Gets or sets the lifecycle management status of a pointer.

=over

=item * C<own($ptr, 1)>: Perl takes ownership. C<free()> will be called automatically when C<$ptr> is garbage collected.

=item * C<own($ptr, 0)>: Perl releases ownership. You (or the C library) are now responsible for freeing the memory.

=back

    # Take ownership of a pointer returned from C
    my $c_string = get_string_from_c();
    own($c_string, 1);

=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);

=head2 Type Casting

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

Reinterprets a memory address as a new type. The behavior depends on the requested C<$type>:

=over

=item * B<Casting to a Value (Primitives/Strings):> Reads the memory immediately and returns a Perl scalar copy.