In my experience researching complex topics, such as extending and embedding Perl, it is inevitable that the range of examples available will be large. Unfortunately, the examples that I have found regarding extending Perl fall into two categories. The first category of examples are far too simplistic. These range from the ubiquitous 'hello world' example written in XS, to tutorial examples on how SWIG might wrap the libgd graphics library. These are all very straight forward examples, and should suffice for most real world tasks. Not mine, however.

The other category of example code is mind blowingly complex. This camp includes most well known examples of Perl extension -- I've searched through the multi-language SWIG bindings for Subversion, and the Perl specific bindings to Tk. Both are stunning examples of how to do extension correctly. Unfortunately, there is a huge overhead to wrapping your mind around projects of this scale. Multi-module, multi-library projects are far far too complex for what I need to do.

I was really unable to find a happy medium -- I need to expose a number of C structures as Perl objects, reserving the option to expose them to other languages (e.g. python, java, guile). For this, some of the aspects of Subversion bindings are easy to understand. However, I also need to be able to pass callbacks to C from Perl code references to allow the C libraries to pass information to Perl. In Subversion, callbacks are provided by a language specific runtime library which implements a thunk editor. The subversion thunk editor manages manipulation of the stack such that calling back and forth between Perl and C works according to the Perl stack protocol. Just hearing the word 'thunk' makes me shudder, with horrible visions of Win32 dancing in my head. At any rate, the Subversion method seemed to me to be just a bit more abstraction than I wanted to deal with for my (relatively) simple case.

As I was dreaming about how to get my extension project off the ground, I found a massively useful book at my local Barnes & Noble book store. The book, Extending and Embedding Perl by Tim Jenness and Simon Cozens. In my opinion, this book is the most complete and coherent source of Perl extension and embedding knowledge available. It's not terse like the documentation which comes with Perl -- although that continues to be an authoratative source of this info. Instead, it's a well written, easy to read coverage of all the details needed to get the job done. It includes fully documented code samples -- which cover a broad range of projects. Want to find out how to create a new Perl scalar value in C and pass it back to Perl? There is simple example code to demonstrate the technique, along with detailed breakdowns of the output of tools such as Devel::Peek.

Suffice to say that I love this book. I've nearly read it front to back in about a week, which says a lot considering the dry nature of the subject material. However, I'm motivated to learn, as I want to complete my extension project. Over the coming days, I'll outline where I am with the project, and offer up a description of how to solve extension and embedding problems that aren't covered by 99% of available examples. Stay tuned.