19.2 Embedding Overview

Strange as it may seem, there are no tools to automate the task of embedding Perl as there are for extending Perl. Why is that? After all, extensions also have to account for translating data from Perl to C and back (input and output parameters). The reason is that when Perl drives C code, it specifies precisely how and when a C extension is loaded. As an extension writer, you have the job of simply writing XSUBs in a callback style, providing some initializations; the XSUBs will be called when the script invokes the appropriate corresponding functions. In contrast, since there is no standard way to write a C application, you have to decide when to initialize an embedded Perl interpreter and how to give control over to a Perl script.

To simplify embedding, this chapter shows you an easy-to-use veneer over Perl's internal API. These routines have been developed for this book to save you the bother of assimilating over 50 pages of internal documentation. But if you are the type who thrives on such details, Chapter 20, Perl Internals , should provide the needed fix. It also explains the code for these convenience routines.

It so happens that the Perl executable is made up of two parts: a library of core Perl routines[ 2 ] ( libperl.a on Unix systems and perl.lib on Microsoft Windows systems, or dynamically loadable equivalents of the same) and a simple driver file, perlmain.c , containing main() , which, shorn of all its portability aspects, looks like this:

 #include <EXTERN.h>   #include <perl.h>   static PerlInterpreter *my_perl;    int main(int argc, char **argv, char **env)  {      my_perl = perl_alloc();                        #      perl_construct(my_perl);                       # Initialize       perl_parse(my_perl, xs_init, argc, argv, env); #      perl_run(my_perl);                             # Run       perl_destruct(my_perl);                        # Shut down      perl_free(my_perl);  }

[2] Not to be confused with the lib directory in a Perl distribution.

perl_alloc and perl_construct create an interpreter object. perl_parse does some more initializations, parses the command-line parameters provided to it via argc and argv , calls an initialization routine, xs_init , to load other extensions (or to at least initialize the dynamic loader), and finally parses the script provided as part of the command line. perl_run executes the script. Finally, perl_destruct and perl_free shut down and deallocate the interpreter.

To take advantage of the power of Perl, all you need to do is link the Perl library to your application and essentially clone the code in perlmain.c . We will talk about xs_init in the section "Adding Extensions " later in this chapter; until then, we will assume that we don't need any extensions and pass NULL to perl_parse instead of xs_init . The interpreter is fully primed once perl_parse is done, after which you can call all functions exported by the Perl library. In this chapter, however, we will restrict ourselves to a few high-level calls, listed in Table 19.1 .

perl_call_argv(     char *sub,     I32  flags,     char **argv);

perl_call_va (     char *sub,     [char *type, arg,]*     ["OUT",]     [char *type, arg,]*     NULL );

int 

perl_eval_va(       char *str,       [char *type,             *arg],       NULL);

set_int(char *var,         int  value); int get_int(         char *var,         int *pvalue);

set_double(char *var,            double             value); int get_double(           char *var,            double           *pvalue);

set_str(char *var,         char *value); int get_str(char *var,         char **value);

The get_* and set_* functions can be used only to manipulate a scalar at a time. The reason I allowed this limitation is that Perl already provides a nice chunk of functions that can slice, dice, and iterate through arrays and hashes; we'll take a detailed look at them in Chapter 20 . These functions, while faster and more fine-grained, are tied to internals-related details (memory management, temporary variables, and so on); hence any discussion of them necessitates discussing these other aspects too. The get_* and set_* functions are simpler.