README

NAME
    Task::MemManager - A memory allocated and manager for low level code in
    Perl.

VERSION
    version 0.02

SYNOPSIS
      use Task::MemManager;

      my $mem_manager = Task::MemManager->new(10, 1, { allocator => 'PerlAlloc' });

      my $buffer = $mem_manager->get_buffer();
      my $buffer_size = $mem_manager->get_buffer_size();
      my $element_size = $mem_manager->get_element_size();
      my $num_of_elements = $mem_manager->get_num_of_elements();

      my $region = $mem_manager->extract_buffer_region($pos_start, $pos_end);

      my $delayed_gc_objects = $mem_manager->get_delayed_gc_objects();

DESCRIPTION
    Task::MemManager is a memory allocator and manager designed for low
    level code in Perl. It provides functionalities to allocate, manage, and
    manipulate memory buffers.

METHODS
  new
      Purpose     : Allocates a buffer using a specified allocator.
      Returns     : A reference to the buffer.
      Parameters  : 
        - $num_of_items: Number of items in the buffer.
        - $size_of_each_item: Size of each item in the buffer.
        - \%opts: Reference to a hash of options. These are:
          - allocator: Name of the allocator to use.
          - delayed_gc: Should garbage collection be delayed?
          - init_value: Value to initialize the buffer with (byte, non UTF!).
          - death_stub: Function to call upon object destruction (if any).
      Throws      : Croaks if the buffer allocation fails.
      Comments    : Default allocator is PerlAlloc, which uses Perl's string functions.
                    Default init_value is undef ('zero' zeroes out memory, 
                    any other byte value will initialize memory with that value).
                    Default delayed_gc is 0 (garbage collection is immediate).

  extract_buffer_region
      Usage       : my $region = Task::MemManager->extract_buffer_region($pos_start, $pos_end);
      Purpose     : Extracts a region of the buffer.
      Returns     : A Perl string (null terminated) containing the region.
      Parameters  : 
        - $pos_start: The starting position of the region.
        - $pos_end: The ending position of the region.
      Throws      : n/a
      Comments    : Returns undef if attempt to overrun buffer, or if $pos_start > $pos_end.

  get_buffer
      Usage       : my $buffer = Task::MemManager->get_buffer();
      Purpose     : Returns the memory address of the buffer.
      Returns     : The memory address of the buffer as an unsigned integer.
      Parameters  : n/a
      Throws      : n/a
      Comments    : None.

  get_buffer_size
      Usage       : my $buffer_size = Task::MemManager->get_buffer_size();
      Purpose     : Returns the size of the buffer.
      Returns     : The size of the buffer in bytes.
      Parameters  : n/a
      Throws      : n/a
      Comments    : None.

  get_element_size
      Usage       : my $element_size = Task::MemManager->get_element_size();
      Purpose     : Returns the size of each element in the buffer.
      Returns     : The size of each element in bytes.
      Parameters  : n/a
      Throws      : n/a
      Comments    : None.

  get_num_of_elements
      Usage       : my $num_of_elements = Task::MemManager->get_num_of_elements();
      Purpose     : Returns the number of elements in the buffer.
      Returns     : The number of elements in the buffer.
      Parameters  : n/a
      Throws      : n/a
      Comments    : None.

  get_delayed_gc_objects
      Usage       : my $delayed_gc_objects = Task::MemManager->get_delayed_gc_objects();
      Purpose     : Obtains a list of objects that have delayed garbage collection.
      Returns     : A reference to an array of objects with delayed GC.
      Parameters  : n/a
      Throws      : n/a
      Comments    : None.

EXAMPLES
    We will illustrate the use of these methods with multiple examples.
    These will cover issues like the allocation of memory, the extraction of
    regions from the buffer, constant (to the eyes of Perl) memory
    allocation, delayed garbage collection, and the use of a death stub,
    which is a function that is called upon object destruction and may be
    used to perform e.g. logging or cleanup , operations other than freeing
    the memory buffer itself. The examples are best run sequentially in a
    single Perl script.

  Example 1: Allocating buffers and killing them
      use Task::MemManager;
      ## uses the default allocator PerlAlloc
      my $memdeath = Task::MemManager->new(
          40, 1,
          {
              init_value => 'zero',
              death_stub => sub {
                  my ($obj_ref) = @_;
                  printf "Killing 0x%8x \n", $obj_ref->{identifier};
              },
          }
      );

      my $mem = Task::MemManager->new(
          20, 1,
          {
              init_value => 'A',
              death_stub => sub {
                  my ($obj_ref) = @_;
                  printf "Killing 0x%8x \n", $obj_ref->{identifier};
              },
              allocator => 'CMalloc',
          }
      );
      printf( "%10s object is %s\n", ' mem', $mem );
      $mem = Task::MemManager->new(
        20, 1,
        {
            init_value => 'A',
            death_stub => sub {
                my ($obj_ref) = @_;
                printf "Killing 0x%8x \n", $obj_ref->{identifier};
            },
            allocator => 'CMalloc',
        }
      );

    Print the buffer objects

      printf( "%10s object is %s\n", ' memdeath', $memdeath );
      printf( "%10s object is %s\n", ' mem', $mem );

    If you would like to kill a buffer immediately, you can undefine it:

      undef $memdeath;

    Attempting to under (or in general modify a constant or a Readonly)
    memory buffer will kill the script. Note that these buffers can be
    modified outside of Perl (including the Perl API) but not inside the
    main Perl script. Such buffers are useful for keeping a constant (in
    space) buffer throughout the lifetime of the script. Attempt to modify
    them from within Perl, will kill the script at *runtime* uncovering the
    modification attempt.

      use Const::Fast; ## may also use Readonly mutatis mutandis
      const my $mem_cp2 => Task::MemManager->new(
          20, 1,
          {
              init_value => 'D',
              death_stub => sub {
                  my ($obj_ref) = @_;
                  printf "Killing 0x%8x \n", $obj_ref->{identifier};
              },
              allocator => 'CMalloc',
          }
      );
      undef $mem_cp2;  # This will kill the script

  Example 2: Extracting and inspecting a region from the buffer
    First we will define a subroutine that will print the extracted region
    in a nicely formated hexadecimal format.

      sub print_hex_values {
          my ( $string, $bytes_per_line ) = @_;
          $bytes_per_line //= 8;    # Default to 8 bytes per line if not provided

          my @bytes = unpack( 'C*', $string );    # Unpack the string into a list of bytes

          for ( my $i = 0 ; $i < @bytes ; $i++ ) {
              printf( "%02X ", $bytes[$i] );   # Print each byte in hexadecimal format
              print "\n" 
                if ( ( $i + 1 ) % $bytes_per_line == 0 )
                ;    # Print a newline after every $bytes_per_line bytes
          }
          print "\n" 
            if ( @bytes % $bytes_per_line != 0 )
            ;        # Print a final newline if the last line wasn't complete
      }

    Now let's extract the region and print it

      my $region = $mem->extract_buffer_region(5, 10);
      print_hex_values( $region, 8 );

  Example 3: Shallow copying defers buffer deallocation
    Making a shallow copy of the buffer:

      my $mem_cp = $mem;
      printf( "%10s object is %s\n", ' mem_cp', $mem_cp );
      printf "Buffer %10s with buffer address %s\n", 
        'Alpha', $mem->get_buffer();
      printf "Buffer %10s with buffer address %s\n", 
        'Alpha_copy', $mem_cp->get_buffer();

    Killing the original buffer in Perl. Trying to access it after death
    will lead to an error (but we intercept it in the code below)

      undef $mem;
      say "mem : ", ( $mem ? $mem->get_buffer() : "does not exist anymore" );

    The shallow copy continues to exist, and so does the buffer region:

      printf "Buffer %10s with buffer address %s\n", 
        'Alpha_copy', $mem_cp->get_buffer();
      print_hex_values( $mem_cp->extract_buffer_region, 10 );

  Example 4: Object modification and object destruction
    Attempting to modify an existing buffer object, e.g. by reassiging it to
    a new buffer object, will instantly free the old memory buffer, and
    allocate a new buffer with new contents (this Example continues at the
    end of Example 3)

      $mem_cp = Task::MemManager->new(
          20, 1,
          {
              init_value => 'D',
              death_stub => sub {
                  my ($obj_ref) = @_;
                  printf "Killing 0x%8x \n", $obj_ref->{identifier};
              },
              allocator => 'CMalloc',
          }
      );
      printf( "%10s object is %s\n", ' mem_cp', $mem_cp );
      printf "Buffer %10s with buffer address %s\n", 
        'Alpha_copy after modification', $mem_cp->get_buffer();
      print_hex_values( $mem_cp->extract_buffer_region, 10 );

  Example 5: Fine control over garbage collection
    Delayed garbage collection is useful when you want to keep a buffer
    alive for a while after it goes out of scope. This is useful when you
    want to transfer ownership of the memory space to an interfacing code
    (e.g. C code), and don't want Perl to free the memory buffer (e.g when a
    lexical variable is reassigned to a new buffer object in a loop). In
    this example we will create two buffers, one without and one with
    delayed garbage collection and will track when they die relative to the
    end of the script. This example is entirely self-contained.

      use Task::MemManager;
      use strict;
      use warnings;

      $mem_cp = Task::MemManager->new(
          20, 1,
          {
              init_value => 'D',
              death_stub => sub {
                  my ($obj_ref) = @_;
                  printf "Killing 0x%8x \n", $obj_ref->{identifier};
              },
              allocator => 'PerlAlloc',
          }
      );
      $mem_cp2 = Task::MemManager->new(
          20, 1,
          {
              init_value => 'D',
              death_stub => sub {
                  my ($obj_ref) = @_;
                  printf "Killing 0x%8x \n", $obj_ref->{identifier};
              },
              delayed_gc => 1,
              allocator => 'CMalloc',
          }
      );

    List the objects with delayed garbage collection

      my $delayed_gc_objects = Task::MemManager->get_delayed_gc_objects();
      printf "Objects with delayed GC : " 
        . ("0x%8x " x @$delayed_gc_objects) 
        . "\n", @$delayed_gc_objects;

    Time the precise moment of death:

      say "Undefining an object with delayed GC does not kill it!";
      undef $mem_cp2;
      say "End of the program - see how Perl's destroying all "
        . "delayed GC objects along with the rest of the objects";

DIAGNOSTICS
    There are no diagnostics that one can use. The module will croak if the
    allocation fails, so you don't have to worry about error handling.

DEPENDENCIES
    The module depends on the "Inline::C" module to access the memory buffer
    of the Perl scalar using the PerlAPI. In addition it depends implicitly
    on all the dependencies of the memory allocators it uses

TODO
    Open to suggestions. A few foolish ideas of my own include: adding
    further allocators and providing facilities that will *trigger* the
    delayed garbage collection for a specific object, at specific time
    points in a script (emulating for example Go's garbage collector).

SEE ALSO
    *   <https://metacpan.org/pod/Inline::C>

        Inline::C is a module that allows you to write Perl subroutines in
        C.

    *   <https://perldoc.perl.org/perlguts>

        Introduction to the Perl API.

    *   <https://perldoc.perl.org/perlapi>

        Autogenerated documentation for the perl public API.

AUTHOR
    Christos Argyropoulos, "<chrisarg at cpan.org>"

COPYRIGHT AND LICENSE
    This software is copyright (c) 2024 by Christos Argyropoulos.

    This is free software; you can redistribute it and/or modify it under
    the MIT license. The full text of the license can be found in the
    LICENSE file See <https://en.wikipedia.org/wiki/MIT_License> for more
    information.