Rand Stats

NativeHelpers::Blob

github:salortiz

NativeHelpers::Blob

Introduction

Right now the support for Blob/Buf in Perl 6's NativeCall is incomplete. You can use these as arguments for native functions, but not as attributes for CStruct or CUnion, for example.

In a CStruct class, you can use a Pointer or a CArray, but those don't have the flexibility of a Blob or Buf, moving data between them is slow, and with big buffers the memory required increases dramatically.

At some point, these problems will be addressed in core, but in the meantime...

Usage

use NativeHelpers::Blob;

Run benchmarks

Use

zef install Bench

to install that module, and then you can run the benchmarks in the root directory:

perl6 -Ilib bench.pl6
perl6 -Ilib bench-slurpy.pl6

Exported functions

multi sub pointer-to(Blob:D, :$typed -> Pointer)

Returns a Pointer to the contents of the Blob.

The type of the returned Pointer will be the same of the Blob if :typed was used or void if not.

Should be noted that the memory is owned by Rakudo, so you must not attempt to free it.

multi sub pointer-to(array:D, :$typed -> Pointer)

Returns a Pointer to the contents of the native array.

The type of the returned Pointer will be the same of the array if :typed was used or void if not.

Should be noted that the memory is owned by Rakudo, so you must not attempt to free it.

multi sub pointer-to(CArray:D, :$typed -> Pointer)

Returns a Pointer to the contents of the native CArray.

The type of the returned Pointer will be the same of the CAarray if :typed was used or void if not.

Should be noted that the memory is owned by Rakudo, so you must not attempt to free it.

sub carray-from-blob(Blob:D, :$managed)

Returns a CArray constructed from de contents of the Blob.

If :managed was given, the returned CArray contains a copy of the original content of the Blob and will be managed, otherwise the CArray holds a reference to the Blob content.

sub blob-allocate(Blob:U \blob, $elems)

Rakudo 2016.03+ provides Blob.allocate to create a Blob/Buf with a pre-allocated initial size.

For older ones you can use this subroutine for the same effect. It create a blob with $elems zeroed elements.

sub blob-from-pointer(Pointer:D, Int :$elems!, Blob:U :$type = Buf)

Returns a Blob of type :type constructed from the memory pointed by the given Pointer and the following :elems elements.

The type of the Pointer should be compatible with the type of the Blob,

Please note that the amount of memory copied depends of $elems and :type´s native size.

sub blob-from-carray(CArray:D, Int :$size)

Returns a Blob constructed from the contents of the CArray.

When the CArray is unmanaged, for example as returned by a native call function, you should include de :size argument.

The type of the Blob is determined by the type of the CArray.

WARNING

This module depends on internal details of the REPRs of the involved types in MoarVM, so it can stop working without notice.

In the same way as when handling pointers in C, you should known what are you doing.

This is an early release to allow the interested people the testing and discussion of the module: there is some missing features and you should be aware that the API isn't in stone yet.

Copyright © 2016 by Salvador Ortiz