CArray A perl5 module for space-efficient typed external C Arrays Alpha - Interface might change, not fully tested yet Reini Urban rurban@x-ray.at INTRODUCTION Several XS classes and methods to deal with typed, space-efficient C arrays are provided. For the three basic C-types array of INT, DOUBLE and STRING and some sequential aggregate types int[2][], int[3][], int[4][], double[2][], double[3][] hand-optimized, fast XS versions are provided. This roughly reflects to: CArray CIntArray int[] CInt2Array int[][2] CInt3Array int[][3] CInt4Array int[][4] CDoubleArray double[] CDouble2Array double[][2] CDouble3Array double[][3] CStringArray *char[] External C arrays limit communication overhead with large simple data structures, where size or time constraints become serious, optionally manipulated by external XS modules. Such as various computional geometry modules dealing with 10.000 - 200.000 double[3]. Modification is done in-place and preferably in bulk. It might also be easier to write XSUBs by converting the data to CArray's before, pass this pointer to the C func, and handle the results in Perl then instead of writing wrappers just for C arrays. Not all perl array methods are provided since perl tie doesn't support the full range yet (i.e. no push, pop, shift, unshift, ...). But there are efficient methods for grow, init, copy, delete, C++ style slice, indirect sort, destructive reverse and conversions between the raw and supported sequential types. Displaced arrays (mappings with arbitary offsets) and more attributes (fill-pointer, read-only, gslice, ...) are not yet supported. See the file Changes for user-visible changes. See CArray.pm for usage. See Geometry::Points, Geometry::Delaunay for samples. Copyright (c) 1999 Reini Urban. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. INSTALLATION or No prerequisites needed, besides a C compiler. CArray installs as a standard Perl module, perl Makefile.pl make test clean install (resp. nmake, dmake) Tested Platforms: CArray was developed under Win32 - MSVC6 - perl5.00558 w/wo threads/debugging and additionally tested with cygwin - gcc 2.95. Please report other platforms to the author. I see no difficulty for gcc supported platforms, no special platform-specific headers or libraries are used. SEE ALSO perlxs(1), the "tie" entry in the perlfunc manpage, Geometry::Points, C::Dynalib::Poke, Tie::MmapArray. WARNING These classes may be easily abused and may lead to system crashes or worse. Bad malloc'ed perls or systems might also lead to destruction. (such as perl5.00558 on Win32 with PERL_MALLOC) The author makes NO WARRANTY, implied or otherwise, about the suitability of this software for safety or security purposes. The author shall not in any case be liable for special, incidental, consequential, indirect or other similar damages arising from the use of this software. Your mileage will vary. If in any doubt DO NOT USE IT. You've been warned. FUTURE, BUGS The next version 0.12 will go into the Tie:: namespace, renamed to Tie::CArray 0.12 will also support arbitrary perl pack-style structures (hashes and arrays) and change the new arguments: new new and tie syntax: 2nd arg for template, 3rd for init-values There are certainly some bugs. Not fully tested yet. Tests for copy, grow, delete, tie are pending. Also some more conversion tests, esp. with double and degenerate (grow, cut) cases. 1 realloc() in string_set() with DEBUGGING perl fails sometimes. 2 An implicit DESTROY invocation sometimes asserts a DEBUGGING perl, regardless if PERL_MALLOC or the WinNT msvcrt.dll malloc is used. (5.00502 - 5.00558) Esp. on perl shutdown, when freeing the extra objects at the second GC. This became much better in 0.08 than in previous versions. This is alpha: Interface syntax for arbitrary structures by pack-style templates might change. Method names and arguments may change. Not fully tested yet! Last Changed 2000/01/02