A type for storing a caller allocated Buffer
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib/NativeHelpers Version 0.0.3, API changed Jul 3, 2018
t Free the right pointer Sep 10, 2017
.gitignore First version of the code Sep 9, 2017
.travis.yml
LICENSE
META6.json
README.md Version 0.0.3, API changed Jul 3, 2018

README.md

Build Status

NAME

NativeHelpers::CBuffer - A type for storing a caller allocated Buffer

SYNOPSIS

    use NativeHelpers::CBuffer;

   class CBuffer is repr('CPointer') is export

The CBuffer object, is repr("CPointer"), as such, it can be directly used in NativeCall signatures in the place of a Pointer.

DESCRIPTION

NativeHelpers::CBuffer is a convinent way to store buffers and C NULL terminated strings

EXAMPLE

    use NativeHelpers::CBuffer;

    my CBuffer $buf = CBuffer.new(100); # Allocates a buffer of 100 bytes

    sub strncpy(CBuffer, Str, size_t) is native { };
    strncpy($buf, "Uella!", 100);

    say $buf; # Uella!

METHODS

multi new (Int)

    multi method new(Int $size, :$with, :$of-type where { $of-type  $types } = uint8)

Allocates a buffer of size $size elements, of type $of-type and with content a copy of $with. Where $with can be either a Str or a Blob, and $of-type can be any of:

    my $types = (uint8, int8, uint16, int16, uint32, int32, uint64, int64, size_t, long, ulong, longlong, ulonglong);

multi new (Blob)

    multi method new(Blob $init)

Allocates a buffer and store the content of the $init parameter.

multi new (Str)

    multi method new(Str $init)

Allocates a buffer and store the content of the $init parameter as a NULL-terminated ASCII string.

elems

    method elems(--> Int:D)

Return the number of elements stored

bytes

    method bytes(--> Int:D)

Return the number of bytes stored

type

    method type()

Return the type of the elements stored

Blob

    method Blob(--> Blob:D)

Return a copy of the content as a Blob

Pointer

    method Pointer(--> Pointer)

Return the pointer to the allocated buffer of type Pointer[self.type]

Str

    method Str(--> Str:D)

Return a Str with the content decoded as null-terminated ASCII

gist

same as method Str

free

     method free()

Calls free the allocated buffer

BUGS, TODOS and WARNINGS

At the moment, the CBuffer is immutable on the perl side, once created and initialized, it's content can be modified only by C functions. At the moment, the CBuffer is not resizable.

The CBuffer uses NativeCall to allocate memory, beware of not using CBuffer in modules to allocate runtime memory during compilation. In other words, do not use CBuffer.new in BEGIN blocks or constant declarations, any abuse will result in Segmentation faults and/or memory corruption!

In order to declare C-stile #define constants in modules, use perl sub (or macro) instead:

   # the following, is equivalent to
     #define STRING_CONST     "The string"

   sub STRING_CONST is export { CBuffer.new("The string") };

AUTHOR

Vittore F. Scolari vittore.scolari@pasteur.fr

COPYRIGHT AND LICENSE

Copyright 2017 Institut Pasteur

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.