DESCRIPTION

This module implements the machinery necessary to easily call C functions from Perl with arbitrarily many arguments. The types of the arguments are a bit restricted at the moment, but it nonetheless works for a fairly broad variety of things. In particular, it handles pointers just fine.

Like all other C::TinyCompiler packages, you make this module available as a package to your compiler state either by indicating it as an argument to your state's constructor or by applying the package later:

The primary operation of this package is to scan through your code, identify functions for which you want to build Perl functions, and build the necessary C and Perl code. You indicate which of your functions should have Perl interfaces by preceding them "immediately" with the package name:

The extraction parser does not care about whitespace, and is smart enough to consider classic C-style comments (i.e. /* comment */ but not // comment) as whitespace. This is true even within the function's arguments (i.e. get_height_and_temp) and between the Callable declaration and the function declaration (i.e. third_func).

Just before your code is run through the preprocessor, each function marked as callable will be examined and a new C-level invocation function with a standard argument layout will be added to the Foot section. Also, the text for a Perl function that knows the name of the C-level invocation function and knows how to invoke it will be generated.

After you have compiled your code, you can obtain a Perl subref that invokes your code by calling the get_callable_subref method, supplying the function's name. You can then invoke this method with your Perl arguments.

Basic Usage

The basic usage was already demonstrated in the Synopsis. If you use basic C types, you should be able to just put C::TinyCompiler::Callable before the function declaration and you will be able to invoke your code from Perl in the obvious way.

Working with pointers and C-level arrays

There are many ways that your Perl code might refer to arbitrary C data. One is to have a Perl scalar whose integer value is the pointer address. Another is to have the actual binary data stored in a Perl's PV slot, which is ordinarily reserved for the string portion of the scalar. Since there is no clean way to ascertain your scalar's provenance, C::TinyCompiler::Callable introduces the following convention: if your scalar is a reference, it assumes that the PV slot of the referent is a binary blob, and uses the address of that PV slot as the argument for a pointer. If your scalar is not a reference, it assumes that the IV slot of your scalar is a pointer address.

How does this work in practice? If you need to pass a string to your C code, pass a reference to the actual variable holding the data instead of passing the variable itself:

Working with Perl-level objects

If you have Perl objects with data that you want to pass to a Callable function, you can add the pack_as method to your class to make life easier. When your function gets an object, it will ask it if it can pack as the needed type, such as int or double *. This way your object can present meaningful data when used as an argument.

Assuming the ficticious object mentioned in the previous section holds an array of doubles, one could implement a pack_as method for tha class like so:

Then the user could invoke the my_sum function from the synopsis like so:

my $sum = $my_sum_subref->($obj, $obj);

Caveats about Speed

This is an interface to C::TinyCompiler, and the resulting code compiles down to C code. However, the code generated this way still has to jump through a lot of hoops.

I have tried to optimize the generated code as much as possible, but the path from your Perl invocation of the generated subref to your actual C code involves: (1) invoking the subref with your arguments, which goes on to (2) unpack those arguments from @_, (3) ask those arguments if they are objects and know how to cast themselves to the required C type, and if not use a default casting mechanism, (4) pack all of the arguments into a single C binary buffer, (5) build a return binary buffer, (6) call an XS "trampoline" that calls the C wrapper with the input and output binary buffers, which (7) unpacks the binary input buffer into C variables, (8) invokes the original function with the unpacked C variables, (9) packs the return value into the supplied binary return buffer and returns (it's actually a void function), bringing us back to the subref which (10) unpacks the binary return buffer and returns the value.

Contrast those steps with the steps needed for calling a simple xsub wrapper. The steps involve (1) invoking the xsub with your arguments in Perl which (2) unpacks the stack in your XS/C code, (3) invokes the original function with the unpacked C variables, and (4) packs the return value(s) into SVs and places them on the return stack.

In short, don't use this sort of functionality to add two integers. If you need to perform complicated time stepping on a mesh, though, the extra overhead of the function invocation will be relatively innocuous.

SEE ALSO

There are a number of modules or tools that do something similar to what C::TinyCompiler::Callable does. All of these modules use another compiler to generate the object code in use, so they will present tradeoffs in compile time and execution time compared with C::TinyCompiler::Callable.

C::TinyCompiler::Perl pulls in all of the Perl headers, which in principle would allow you to write your own Perl-callable C functions that manipulate the stack and everything. Of course, that is not documented and it's likely to be quite verbose, so it's not for the faint of heart. But in principle, that mechanism provides another way to generate hooks so you can call C functions from Perl.

For a runtime foreign function interface, see FFI::Raw, which mostly supersedes FFI (though the latter might be worth looking into). This module uses assembly to build a C stack and then directly fire your C function. Building the stack takes a little more effort on your part, but those details can easily be encapsulated in a Perl-side wrapper. The only reason I didn't use that module as this module's C function caller is that it is not (yet) as general as I would like and I didn't want to introduce another nontrivial dependency.

A more powerful means for building C functions and calling them from Perl is Inline::C. This has the full power of XS, and the full optimization of your local compiler, but is not designed to quickly compile. Generally, I find that Inline::C is a great means for prototyping my XS code, but the assumption is that eventually the codebase will reach a stable state. If you need to dynamically generate lots of different C functions throughout your code's execution, the compiler invocation overhead of Inline::C will likely not pay off compared to the speed of tcc's compilation.

If your goal is to write a stable set of C functions that can be called from Perl, you should ultimately look into Perl's C interface layer, perlxs. XS is generally meant to be used in the context of a module or suite of modules, and it is nicely wrapped by Inline::C (and more basically by Inline::XS). If you do not need to generate C code on the fly, this is the best means for writing code that quickly invokes and executes. The Perl hooks into your code will be the most direct of all of these options, and the generated object code will be optimized by your compiler in ways that tcc likely will not be.