NAME

P5NCI - Perl extension for loading shared libraries and their functions

SYNOPSIS

  use P5NCI;

  # find and load a shared library in a cross-platform fashion
  my $library_path = P5NCI::find_lib( 'nci_test' );
  my $library      = P5NCI::load_lib( $library_path );

  # load a function from the shared library
  my $double_func  = P5NCI::load_func( $library, 'double_double', 'dd' );

  # now use it
  my $two_dot_oh   = $double_func->( 1.0 );

DESCRIPTION

P5NCI provides a bare-bones, stripped down, procedural interface to shared libraries installed on your system. It allows you to call functions in them without writing or compiling any glue code.

I recommend using P5NCI::Library as it has a nicer interface, but you can do everything through here if you really want.

FUNCTIONS

find_lib( $library_name )

Finds and returns the full path to a library on your particular platform given its short name. For example, on Unix, passing a $library_name of nci_test will give you the full path to libnci_test.so, if it's installed. On Windows and Mac OS X this should do the right thing as well.

load_lib( $library_full_path )

Given the full path to a library (as returned from find_lib() or specified on your own if you really don't care about cross-platform coding), loads the library, if possible, and returns it in an opaque scalar that you really oughtn't examine.

load_func( $library, $function_name, $signature )

Given an opaque library from load_lib() in $library, the name of a function within that library in $function_name, and the signature of that function in $signature, loads and returns a subroutine reference that allows you to pass values to and return values from the function.

This function itself will throw an exception if you fail to provide both a function name and its signature. It will also throw an exception if it does not understand the signature. That might not be an error -- it doesn't understand a lot of valid signatures yet.

Signatures are simple strings representing the types of the arguments the function takes in their simplest forms. For example, a function that takes two ints and returns an int would have a signature of iii. A function that takes two ints and returns nothing (or void) has a signature of vii. The currently working signature items are:

d, a double

f, a float

i, an integer

p, a pointer (read-only for now, so be careful)

s, a short

t, a string

v, void (nothing), valid only as an output type, not an input type

Note: The signature list will definitely expand and may change in the future.

SEE ALSO

DynaLoader, Inline::C, perlxs.

AUTHOR

chromatic, <chromatic at wgz dot org>.

Based on Parrot's NCI by Dan Sugalski, Leo Toetsch, and a host of other people including me (a little bit, here and there).

Thanks to Bill Ricker for documentation fixes and other suggestions.

Thanks to Norman Nunley for pair programming to help fix the generation code.

BUGS

No known bugs, though the signature list is currently pretty small in what it supports and what it can support. Right now, you can only bind to C functions that take zero to four arguments. The XS code takes a long time to compile as it is.

Hopefully this approach uses much less memory than the naive implementation, though it depends on how well your platform manages shared libraries.

COPYRIGHT AND LICENSE

Copyright (c) 2004, 2006 - 2007, chromatic.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl 5.8.x.