NAME

Tie::Array::Pointer - ties a perl array to a C pointer

SYNOPSIS

Tie to @buffer; allocate 256 * 4 bytes for me:

use Tie::Array::Pointer;
my @buffer;
tie @buffer, 'Tie::Array::Pointer', {
  length => 256,
  type   => 'L',
};

Tie to @buffer; use memory address I've provided:

tie @buffer, 'Tie::Array::Pointer', {
  length  => 320 * 200,
  type    => 'c',
  address => 0x000a0000,
};

Get the memory address of the C array.

my $addr = tied(@buffer)->address();

DESCRIPTION

Tie::Array::Pointer ties a Perl array to a C pointer. This makes it possible for Perl code and C code to share simple integer arrays.

Options

When you tie an array to Tie::Array::Pointer, you need to pass it a hashref that tells it how big the array is and what the simple integer type each of its elements is.

length

(required) :: The number of elements in the array.

type

(required) :: This is a very small subset of pack types, which defines whether the array contains 8 bit, 16 bit, or 32 bit integers. The valid values for this option are:

c   signed char      8 bit
C   unsigned char    8 bit
s   signed short    16 bit
S   unsigned short  16 bit
l   signed long     32 bit
L   unsigned long   32 bit

address

(optional) :: If you specify a memory address using this option, the act of tie'ing (tying?) will not allocate any memory. Instead, we'll trust that you know what you're doing and that the system will allow reads and writes to happen to this address.

Limitations

Don't treat arrays that are tied to this package as normal Perl arrays. When you tie arrays to this package, they really take on the characteristics of a C array. They should therefore be treated with the same carefulness that a C array would.

In future versions of this module, some of these limitations may be lifted, but don't hold your breath.

Typical perl array ops are unavailable.

You cannot push, pop, shift, or unshift on these arrays.

You can't access indices beyond what you have allocated.

You cannot access indices beyond the memory you have allocated. For example, consider the following code:

tie my @buffer, 'Tie::Array::Pointer', {
  length => 32,
  type   => 's',
};
$buffer[235355] = 5;

Here we allocated a 32 element array, but then we tried to assign something into the 235355th element of this array. THIS WILL SEGFAULT.

Only integer values are allowed.

Please don't try to assign anything besides an integer to an element. That means no strings and no references and no floats.

METHODS

address

This method returns the address of the beginning of the C array that the tied array represents.

Example:

my $addr = tied(@buffer)->address;

DIAGNOSTICS

"not allowed (yet)"

This means that you tried to do something that we haven't implemented. For example, you might've tried to unshift a value into an array. I don't even want to think about how I'd implement that, so it'll die on you if you try.

TO DO

More error checking in TIEARRAY

At least allow resizing of arrays?

I'll do this if someone asks.

shift unshift push pop

I don't really want to implement them, but....

AUTHOR

John BEPPU <beppu@cpan.org>

SEE ALSO

Term::Caca

cpanm Tie::Array::Pointer

perl -MCPAN -e shell
install Tie::Array::Pointer