### ----------------------------------------------------
### -- NativeHelpers::Blob
### -- Licenses: Artistic-2.0
### -- Authors: Salvador Ortiz <sortiz@cpan.com>
### -- File: README.md
### ----------------------------------------------------
# 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

Copyright © 2016 by Salvador Ortiz


