NAME

Wasm::Memory - Interface to WebAssembly Memory

VERSION

version 0.23

SYNOPSIS

Use WebAssembly memory from plain Perl:

 use PeekPoke::FFI qw( peek poke );
 use Wasm
   -api => 0,
   -wat => q{
     (module
       (memory (export "memory") 3 9)
     )
   }
 ;
 
 # $memory isa Wasm::Memory
 poke($memory->address + 10, 42);                # store the byte 42 at offset
                                                 # 10 inside the data region
 
 my($current, $min, $max) = $memory->limits;
 printf "size    = %x\n", $memory->size;         # 30000
 printf "current = %d\n", $current;              # 3
 printf "min     = %d\n", $min;                  # 3
 printf "max     = %d\n", $max;                  # 9
 
 $memory->grow(4);                               # increase data region by 4 pages
 
 ($current, $min, $max) = $memory->limits;
 printf "size    = %x\n", $memory->size;         # 70000
 printf "current = %d\n", $current;              # 7
 printf "min     = %d\n", $min;                  # 3
 printf "max     = %d\n", $max;                  # 9

Use WebAssembly memory from Perl in callback from WebAssembly:

 use Wasm::Memory qw( wasm_caller_memory );
 
 {
   # this just uses Platypus to create a utility function
   # to convert a pointer to a C string into a Perl string.
   use FFI::Platypus 1.00;
   my $ffi = FFI::Platypus->new( api => 1 );
   $ffi->attach_cast( 'cstring' => 'opaque' => 'string' );
 }
 
 sub print_wasm_string
 {
   my $ptr = shift;
   my $memory = wasm_caller_memory;
   print cstring($ptr + $memory->address);
 }
 
 use Wasm
   -api => 0,
   -wat => q{
     (module
       (import "main" "print_wasm_string" (func $print_wasm_string (param i32)))
       (func (export "run")
         i32.const 0
         call $print_wasm_string
       )
       (memory (export "memory") 1)
       (data (i32.const 0) "Hello, world!\n\00")
     )
   },
 ;
 
 run();

DESCRIPTION

WARNING: WebAssembly and Wasmtime are a moving target and the interface for these modules is under active development. Use with caution.

This class represents a region of memory exported from a WebAssembly module. A Wasm::Memory instance is automatically imported into Perl space for each WebAssembly memory region with the same name.

FUNCTIONS

wasm_caller_memory

 my $memory = wasm_caller_memory;

Returns the memory region of the WebAssembly caller, if Perl has been called by Wasm, otherwise it returns undef.

This function can be exported by request via Exporter.

METHODS

address

 my $pointer = $memory->address;

Returns an opaque pointer to the start of memory.

size

 my $size = $memory->size;

Returns the size of the memory in bytes.

limits

 my($current, $min, $max) = $memory->limits;

Returns the current memory limit, the minimum and maximum. All sizes are in pages.

grow

 $memory->grow($count);

Grown the memory region by $count pages.

SEE ALSO

Wasm

AUTHOR

Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020-2022 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.