[Summary view] [Print] [Text view]

   1  =head1 NAME
   2  
   3  perlembed - how to embed perl in your C program
   4  
   5  =head1 DESCRIPTION
   6  
   7  =head2 PREAMBLE
   8  
   9  Do you want to:
  10  
  11  =over 5
  12  
  13  =item B<Use C from Perl?>
  14  
  15  Read L<perlxstut>, L<perlxs>, L<h2xs>, L<perlguts>, and L<perlapi>.
  16  
  17  =item B<Use a Unix program from Perl?>
  18  
  19  Read about back-quotes and about C<system> and C<exec> in L<perlfunc>.
  20  
  21  =item B<Use Perl from Perl?>
  22  
  23  Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlfunc/require> 
  24  and L<perlfunc/use>.
  25  
  26  =item B<Use C from C?>
  27  
  28  Rethink your design.
  29  
  30  =item B<Use Perl from C?>
  31  
  32  Read on...
  33  
  34  =back
  35  
  36  =head2 ROADMAP
  37  
  38  =over 5
  39  
  40  =item *
  41  
  42  Compiling your C program
  43  
  44  =item *
  45  
  46  Adding a Perl interpreter to your C program
  47  
  48  =item *
  49  
  50  Calling a Perl subroutine from your C program
  51  
  52  =item *
  53  
  54  Evaluating a Perl statement from your C program
  55  
  56  =item *
  57  
  58  Performing Perl pattern matches and substitutions from your C program
  59  
  60  =item *
  61  
  62  Fiddling with the Perl stack from your C program
  63  
  64  =item *
  65  
  66  Maintaining a persistent interpreter
  67  
  68  =item *
  69  
  70  Maintaining multiple interpreter instances
  71  
  72  =item *
  73  
  74  Using Perl modules, which themselves use C libraries, from your C program
  75  
  76  =item *
  77  
  78  Embedding Perl under Win32
  79  
  80  =back 
  81  
  82  =head2 Compiling your C program
  83  
  84  If you have trouble compiling the scripts in this documentation,
  85  you're not alone.  The cardinal rule: COMPILE THE PROGRAMS IN EXACTLY
  86  THE SAME WAY THAT YOUR PERL WAS COMPILED.  (Sorry for yelling.)
  87  
  88  Also, every C program that uses Perl must link in the I<perl library>.
  89  What's that, you ask?  Perl is itself written in C; the perl library
  90  is the collection of compiled C programs that were used to create your
  91  perl executable (I</usr/bin/perl> or equivalent).  (Corollary: you
  92  can't use Perl from your C program unless Perl has been compiled on
  93  your machine, or installed properly--that's why you shouldn't blithely
  94  copy Perl executables from machine to machine without also copying the
  95  I<lib> directory.)
  96  
  97  When you use Perl from C, your C program will--usually--allocate,
  98  "run", and deallocate a I<PerlInterpreter> object, which is defined by
  99  the perl library.
 100  
 101  If your copy of Perl is recent enough to contain this documentation
 102  (version 5.002 or later), then the perl library (and I<EXTERN.h> and
 103  I<perl.h>, which you'll also need) will reside in a directory
 104  that looks like this:
 105  
 106      /usr/local/lib/perl5/your_architecture_here/CORE
 107  
 108  or perhaps just
 109  
 110      /usr/local/lib/perl5/CORE
 111  
 112  or maybe something like
 113  
 114      /usr/opt/perl5/CORE
 115  
 116  Execute this statement for a hint about where to find CORE:
 117  
 118      perl -MConfig -e 'print $Config{archlib}'
 119  
 120  Here's how you'd compile the example in the next section,
 121  L<Adding a Perl interpreter to your C program>, on my Linux box:
 122  
 123      % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
 124      -I/usr/local/lib/perl5/i586-linux/5.003/CORE
 125      -L/usr/local/lib/perl5/i586-linux/5.003/CORE
 126      -o interp interp.c -lperl -lm
 127  
 128  (That's all one line.)  On my DEC Alpha running old 5.003_05, the 
 129  incantation is a bit different:
 130  
 131      % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include
 132      -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
 133      -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib
 134      -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm
 135  
 136  How can you figure out what to add?  Assuming your Perl is post-5.001,
 137  execute a C<perl -V> command and pay special attention to the "cc" and
 138  "ccflags" information.
 139  
 140  You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) for
 141  your machine: C<perl -MConfig -e 'print $Config{cc}'> will tell you what
 142  to use.
 143  
 144  You'll also have to choose the appropriate library directory
 145  (I</usr/local/lib/...>) for your machine.  If your compiler complains
 146  that certain functions are undefined, or that it can't locate
 147  I<-lperl>, then you need to change the path following the C<-L>.  If it
 148  complains that it can't find I<EXTERN.h> and I<perl.h>, you need to
 149  change the path following the C<-I>.
 150  
 151  You may have to add extra libraries as well.  Which ones?
 152  Perhaps those printed by
 153  
 154     perl -MConfig -e 'print $Config{libs}'
 155  
 156  Provided your perl binary was properly configured and installed the
 157  B<ExtUtils::Embed> module will determine all of this information for
 158  you:
 159  
 160     % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
 161  
 162  If the B<ExtUtils::Embed> module isn't part of your Perl distribution,
 163  you can retrieve it from
 164  http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/
 165  (If this documentation came from your Perl distribution, then you're
 166  running 5.004 or better and you already have it.)
 167  
 168  The B<ExtUtils::Embed> kit on CPAN also contains all source code for
 169  the examples in this document, tests, additional examples and other
 170  information you may find useful.
 171  
 172  =head2 Adding a Perl interpreter to your C program
 173  
 174  In a sense, perl (the C program) is a good example of embedding Perl
 175  (the language), so I'll demonstrate embedding with I<miniperlmain.c>,
 176  included in the source distribution.  Here's a bastardized, non-portable
 177  version of I<miniperlmain.c> containing the essentials of embedding:
 178  
 179      #include <EXTERN.h>               /* from the Perl distribution     */
 180      #include <perl.h>                 /* from the Perl distribution     */
 181  
 182      static PerlInterpreter *my_perl;  /***    The Perl interpreter    ***/
 183  
 184      int main(int argc, char **argv, char **env)
 185      {
 186      PERL_SYS_INIT3(&argc,&argv,&env);
 187          my_perl = perl_alloc();
 188          perl_construct(my_perl);
 189      PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
 190          perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
 191          perl_run(my_perl);
 192          perl_destruct(my_perl);
 193          perl_free(my_perl);
 194      PERL_SYS_TERM();
 195      }
 196  
 197  Notice that we don't use the C<env> pointer.  Normally handed to
 198  C<perl_parse> as its final argument, C<env> here is replaced by
 199  C<NULL>, which means that the current environment will be used.  The macros
 200  PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific tune up 
 201  of the C runtime environment necessary to run Perl interpreters; since
 202  PERL_SYS_INIT3() may change C<env>, it may be more appropriate to provide
 203  C<env> as an argument to perl_parse().
 204  
 205  Now compile this program (I'll call it I<interp.c>) into an executable:
 206  
 207      % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
 208  
 209  After a successful compilation, you'll be able to use I<interp> just
 210  like perl itself:
 211  
 212      % interp
 213      print "Pretty Good Perl \n";
 214      print "10890 - 9801 is ", 10890 - 9801;
 215      <CTRL-D>
 216      Pretty Good Perl
 217      10890 - 9801 is 1089
 218  
 219  or
 220  
 221      % interp -e 'printf("%x", 3735928559)'
 222      deadbeef
 223  
 224  You can also read and execute Perl statements from a file while in the
 225  midst of your C program, by placing the filename in I<argv[1]> before
 226  calling I<perl_run>.
 227  
 228  =head2 Calling a Perl subroutine from your C program
 229  
 230  To call individual Perl subroutines, you can use any of the B<call_*>
 231  functions documented in L<perlcall>.
 232  In this example we'll use C<call_argv>.
 233  
 234  That's shown below, in a program I'll call I<showtime.c>.
 235  
 236      #include <EXTERN.h>
 237      #include <perl.h>
 238  
 239      static PerlInterpreter *my_perl;
 240  
 241      int main(int argc, char **argv, char **env)
 242      {
 243          char *args[] = { NULL };
 244      PERL_SYS_INIT3(&argc,&argv,&env);
 245          my_perl = perl_alloc();
 246          perl_construct(my_perl);
 247  
 248          perl_parse(my_perl, NULL, argc, argv, NULL);
 249      PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
 250  
 251          /*** skipping perl_run() ***/
 252  
 253          call_argv("showtime", G_DISCARD | G_NOARGS, args);
 254  
 255          perl_destruct(my_perl);
 256          perl_free(my_perl);
 257      PERL_SYS_TERM();
 258      }
 259  
 260  where I<showtime> is a Perl subroutine that takes no arguments (that's the
 261  I<G_NOARGS>) and for which I'll ignore the return value (that's the
 262  I<G_DISCARD>).  Those flags, and others, are discussed in L<perlcall>.
 263  
 264  I'll define the I<showtime> subroutine in a file called I<showtime.pl>:
 265  
 266      print "I shan't be printed.";
 267  
 268      sub showtime {
 269          print time;
 270      }
 271  
 272  Simple enough.  Now compile and run:
 273  
 274      % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
 275  
 276      % showtime showtime.pl
 277      818284590
 278  
 279  yielding the number of seconds that elapsed between January 1, 1970
 280  (the beginning of the Unix epoch), and the moment I began writing this
 281  sentence.
 282  
 283  In this particular case we don't have to call I<perl_run>, as we set 
 284  the PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
 285  perl_destruct.
 286  
 287  If you want to pass arguments to the Perl subroutine, you can add
 288  strings to the C<NULL>-terminated C<args> list passed to
 289  I<call_argv>.  For other data types, or to examine return values,
 290  you'll need to manipulate the Perl stack.  That's demonstrated in
 291  L<Fiddling with the Perl stack from your C program>.
 292  
 293  =head2 Evaluating a Perl statement from your C program
 294  
 295  Perl provides two API functions to evaluate pieces of Perl code.
 296  These are L<perlapi/eval_sv> and L<perlapi/eval_pv>.
 297  
 298  Arguably, these are the only routines you'll ever need to execute
 299  snippets of Perl code from within your C program.  Your code can be as
 300  long as you wish; it can contain multiple statements; it can employ
 301  L<perlfunc/use>, L<perlfunc/require>, and L<perlfunc/do> to
 302  include external Perl files.
 303  
 304  I<eval_pv> lets us evaluate individual Perl strings, and then
 305  extract variables for coercion into C types.  The following program,
 306  I<string.c>, executes three Perl strings, extracting an C<int> from
 307  the first, a C<float> from the second, and a C<char *> from the third.
 308  
 309     #include <EXTERN.h>
 310     #include <perl.h>
 311  
 312     static PerlInterpreter *my_perl;
 313  
 314     main (int argc, char **argv, char **env)
 315     {
 316         STRLEN n_a;
 317         char *embedding[] = { "", "-e", "0" };
 318  
 319         PERL_SYS_INIT3(&argc,&argv,&env);
 320         my_perl = perl_alloc();
 321         perl_construct( my_perl );
 322  
 323         perl_parse(my_perl, NULL, 3, embedding, NULL);
 324         PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
 325         perl_run(my_perl);
 326  
 327         /** Treat $a as an integer **/
 328         eval_pv("$a = 3; $a **= 2", TRUE);
 329         printf("a = %d\n", SvIV(get_sv("a", FALSE)));
 330  
 331         /** Treat $a as a float **/
 332         eval_pv("$a = 3.14; $a **= 2", TRUE);
 333         printf("a = %f\n", SvNV(get_sv("a", FALSE)));
 334  
 335         /** Treat $a as a string **/
 336         eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
 337         printf("a = %s\n", SvPV(get_sv("a", FALSE), n_a));
 338  
 339         perl_destruct(my_perl);
 340         perl_free(my_perl);
 341         PERL_SYS_TERM();
 342     }
 343  
 344  All of those strange functions with I<sv> in their names help convert Perl scalars to C types.  They're described in L<perlguts> and L<perlapi>.
 345  
 346  If you compile and run I<string.c>, you'll see the results of using
 347  I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
 348  I<SvPV()> to create a string:
 349  
 350     a = 9
 351     a = 9.859600
 352     a = Just Another Perl Hacker
 353  
 354  In the example above, we've created a global variable to temporarily
 355  store the computed value of our eval'ed expression.  It is also
 356  possible and in most cases a better strategy to fetch the return value
 357  from I<eval_pv()> instead.  Example:
 358  
 359     ...
 360     STRLEN n_a;
 361     SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
 362     printf("%s\n", SvPV(val,n_a));
 363     ...
 364  
 365  This way, we avoid namespace pollution by not creating global
 366  variables and we've simplified our code as well.
 367  
 368  =head2 Performing Perl pattern matches and substitutions from your C program
 369  
 370  The I<eval_sv()> function lets us evaluate strings of Perl code, so we can
 371  define some functions that use it to "specialize" in matches and
 372  substitutions: I<match()>, I<substitute()>, and I<matches()>.
 373  
 374     I32 match(SV *string, char *pattern);
 375  
 376  Given a string and a pattern (e.g., C<m/clasp/> or C</\b\w*\b/>, which
 377  in your C program might appear as "/\\b\\w*\\b/"), match()
 378  returns 1 if the string matches the pattern and 0 otherwise.
 379  
 380     int substitute(SV **string, char *pattern);
 381  
 382  Given a pointer to an C<SV> and an C<=~> operation (e.g.,
 383  C<s/bob/robert/g> or C<tr[A-Z][a-z]>), substitute() modifies the string
 384  within the C<SV> as according to the operation, returning the number of substitutions
 385  made.
 386  
 387     int matches(SV *string, char *pattern, AV **matches);
 388  
 389  Given an C<SV>, a pattern, and a pointer to an empty C<AV>,
 390  matches() evaluates C<$string =~ $pattern> in a list context, and
 391  fills in I<matches> with the array elements, returning the number of matches found.
 392  
 393  Here's a sample program, I<match.c>, that uses all three (long lines have
 394  been wrapped here):
 395  
 396   #include <EXTERN.h>
 397   #include <perl.h>
 398  
 399   static PerlInterpreter *my_perl;
 400  
 401   /** my_eval_sv(code, error_check)
 402   ** kinda like eval_sv(), 
 403   ** but we pop the return value off the stack 
 404   **/
 405   SV* my_eval_sv(SV *sv, I32 croak_on_error)
 406   {
 407       dSP;
 408       SV* retval;
 409       STRLEN n_a;
 410  
 411       PUSHMARK(SP);
 412       eval_sv(sv, G_SCALAR);
 413  
 414       SPAGAIN;
 415       retval = POPs;
 416       PUTBACK;
 417  
 418       if (croak_on_error && SvTRUE(ERRSV))
 419       croak(SvPVx(ERRSV, n_a));
 420  
 421       return retval;
 422   }
 423  
 424   /** match(string, pattern)
 425   **
 426   ** Used for matches in a scalar context.
 427   **
 428   ** Returns 1 if the match was successful; 0 otherwise.
 429   **/
 430  
 431   I32 match(SV *string, char *pattern)
 432   {
 433       SV *command = newSV(0), *retval;
 434       STRLEN n_a;
 435  
 436       sv_setpvf(command, "my $string = '%s'; $string =~ %s",
 437             SvPV(string,n_a), pattern);
 438  
 439       retval = my_eval_sv(command, TRUE);
 440       SvREFCNT_dec(command);
 441  
 442       return SvIV(retval);
 443   }
 444  
 445   /** substitute(string, pattern)
 446   **
 447   ** Used for =~ operations that modify their left-hand side (s/// and tr///)
 448   **
 449   ** Returns the number of successful matches, and
 450   ** modifies the input string if there were any.
 451   **/
 452  
 453   I32 substitute(SV **string, char *pattern)
 454   {
 455       SV *command = newSV(0), *retval;
 456       STRLEN n_a;
 457  
 458       sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
 459             SvPV(*string,n_a), pattern);
 460  
 461       retval = my_eval_sv(command, TRUE);
 462       SvREFCNT_dec(command);
 463  
 464       *string = get_sv("string", FALSE);
 465       return SvIV(retval);
 466   }
 467  
 468   /** matches(string, pattern, matches)
 469   **
 470   ** Used for matches in a list context.
 471   **
 472   ** Returns the number of matches,
 473   ** and fills in **matches with the matching substrings
 474   **/
 475  
 476   I32 matches(SV *string, char *pattern, AV **match_list)
 477   {
 478       SV *command = newSV(0);
 479       I32 num_matches;
 480       STRLEN n_a;
 481  
 482       sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
 483             SvPV(string,n_a), pattern);
 484  
 485       my_eval_sv(command, TRUE);
 486       SvREFCNT_dec(command);
 487  
 488       *match_list = get_av("array", FALSE);
 489       num_matches = av_len(*match_list) + 1; /** assume $[ is 0 **/
 490  
 491       return num_matches;
 492   }
 493  
 494   main (int argc, char **argv, char **env)
 495   {
 496       char *embedding[] = { "", "-e", "0" };
 497       AV *match_list;
 498       I32 num_matches, i;
 499       SV *text;
 500       STRLEN n_a;
 501  
 502       PERL_SYS_INIT3(&argc,&argv,&env);
 503       my_perl = perl_alloc();
 504       perl_construct(my_perl);
 505       perl_parse(my_perl, NULL, 3, embedding, NULL);
 506       PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
 507  
 508       text = newSV(0);
 509       sv_setpv(text, "When he is at a convenience store and the "
 510      "bill comes to some amount like 76 cents, Maynard is "
 511      "aware that there is something he *should* do, something "
 512      "that will enable him to get back a quarter, but he has "
 513      "no idea *what*.  He fumbles through his red squeezey "
 514      "changepurse and gives the boy three extra pennies with "
 515      "his dollar, hoping that he might luck into the correct "
 516      "amount.  The boy gives him back two of his own pennies "
 517      "and then the big shiny quarter that is his prize. "
 518      "-RICHH");
 519  
 520       if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
 521       printf("match: Text contains the word 'quarter'.\n\n");
 522       else
 523       printf("match: Text doesn't contain the word 'quarter'.\n\n");
 524  
 525       if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
 526       printf("match: Text contains the word 'eighth'.\n\n");
 527       else
 528       printf("match: Text doesn't contain the word 'eighth'.\n\n");
 529  
 530       /** Match all occurrences of /wi../ **/
 531       num_matches = matches(text, "m/(wi..)/g", &match_list);
 532       printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
 533  
 534       for (i = 0; i < num_matches; i++)
 535       printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),n_a));
 536       printf("\n");
 537  
 538       /** Remove all vowels from text **/
 539       num_matches = substitute(&text, "s/[aeiou]//gi");
 540       if (num_matches) {
 541       printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
 542              num_matches);
 543       printf("Now text is: %s\n\n", SvPV(text,n_a));
 544       }
 545  
 546       /** Attempt a substitution **/
 547       if (!substitute(&text, "s/Perl/C/")) {
 548       printf("substitute: s/Perl/C...No substitution made.\n\n");
 549       }
 550  
 551       SvREFCNT_dec(text);
 552       PL_perl_destruct_level = 1;
 553       perl_destruct(my_perl);
 554       perl_free(my_perl);
 555       PERL_SYS_TERM();
 556   }
 557  
 558  which produces the output (again, long lines have been wrapped here)
 559  
 560     match: Text contains the word 'quarter'.
 561  
 562     match: Text doesn't contain the word 'eighth'.
 563  
 564     matches: m/(wi..)/g found 2 matches...
 565     match: will
 566     match: with
 567  
 568     substitute: s/[aeiou]//gi...139 substitutions made.
 569     Now text is: Whn h s t  cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
 570     Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck
 571     qrtr, bt h hs n d *wht*.  H fmbls thrgh hs rd sqzy chngprs nd gvs th by
 572     thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt.  Th by gvs
 573     hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH
 574  
 575     substitute: s/Perl/C...No substitution made.
 576  
 577  =head2 Fiddling with the Perl stack from your C program
 578  
 579  When trying to explain stacks, most computer science textbooks mumble
 580  something about spring-loaded columns of cafeteria plates: the last
 581  thing you pushed on the stack is the first thing you pop off.  That'll
 582  do for our purposes: your C program will push some arguments onto "the Perl
 583  stack", shut its eyes while some magic happens, and then pop the
 584  results--the return value of your Perl subroutine--off the stack.
 585  
 586  First you'll need to know how to convert between C types and Perl
 587  types, with newSViv() and sv_setnv() and newAV() and all their
 588  friends.  They're described in L<perlguts> and L<perlapi>.
 589  
 590  Then you'll need to know how to manipulate the Perl stack.  That's
 591  described in L<perlcall>.
 592  
 593  Once you've understood those, embedding Perl in C is easy.
 594  
 595  Because C has no builtin function for integer exponentiation, let's
 596  make Perl's ** operator available to it (this is less useful than it
 597  sounds, because Perl implements ** with C's I<pow()> function).  First
 598  I'll create a stub exponentiation function in I<power.pl>:
 599  
 600      sub expo {
 601          my ($a, $b) = @_;
 602          return $a ** $b;
 603      }
 604  
 605  Now I'll create a C program, I<power.c>, with a function
 606  I<PerlPower()> that contains all the perlguts necessary to push the
 607  two arguments into I<expo()> and to pop the return value out.  Take a
 608  deep breath...
 609  
 610      #include <EXTERN.h>
 611      #include <perl.h>
 612  
 613      static PerlInterpreter *my_perl;
 614  
 615      static void
 616      PerlPower(int a, int b)
 617      {
 618        dSP;                            /* initialize stack pointer      */
 619        ENTER;                          /* everything created after here */
 620        SAVETMPS;                       /* ...is a temporary variable.   */
 621        PUSHMARK(SP);                   /* remember the stack pointer    */
 622        XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack  */
 623        XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack  */
 624        PUTBACK;                      /* make local stack pointer global */
 625        call_pv("expo", G_SCALAR);      /* call the function             */
 626        SPAGAIN;                        /* refresh stack pointer         */
 627                                      /* pop the return value from stack */
 628        printf ("%d to the %dth power is %d.\n", a, b, POPi);
 629        PUTBACK;
 630        FREETMPS;                       /* free that return value        */
 631        LEAVE;                       /* ...and the XPUSHed "mortal" args.*/
 632      }
 633  
 634      int main (int argc, char **argv, char **env)
 635      {
 636        char *my_argv[] = { "", "power.pl" };
 637  
 638        PERL_SYS_INIT3(&argc,&argv,&env);
 639        my_perl = perl_alloc();
 640        perl_construct( my_perl );
 641  
 642        perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
 643        PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
 644        perl_run(my_perl);
 645  
 646        PerlPower(3, 4);                      /*** Compute 3 ** 4 ***/
 647  
 648        perl_destruct(my_perl);
 649        perl_free(my_perl);
 650        PERL_SYS_TERM();
 651      }
 652  
 653  
 654  
 655  Compile and run:
 656  
 657      % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
 658  
 659      % power
 660      3 to the 4th power is 81.
 661  
 662  =head2 Maintaining a persistent interpreter
 663  
 664  When developing interactive and/or potentially long-running
 665  applications, it's a good idea to maintain a persistent interpreter
 666  rather than allocating and constructing a new interpreter multiple
 667  times.  The major reason is speed: since Perl will only be loaded into
 668  memory once.
 669  
 670  However, you have to be more cautious with namespace and variable
 671  scoping when using a persistent interpreter.  In previous examples
 672  we've been using global variables in the default package C<main>.  We
 673  knew exactly what code would be run, and assumed we could avoid
 674  variable collisions and outrageous symbol table growth.
 675  
 676  Let's say your application is a server that will occasionally run Perl
 677  code from some arbitrary file.  Your server has no way of knowing what
 678  code it's going to run.  Very dangerous.
 679  
 680  If the file is pulled in by C<perl_parse()>, compiled into a newly
 681  constructed interpreter, and subsequently cleaned out with
 682  C<perl_destruct()> afterwards, you're shielded from most namespace
 683  troubles.
 684  
 685  One way to avoid namespace collisions in this scenario is to translate
 686  the filename into a guaranteed-unique package name, and then compile
 687  the code into that package using L<perlfunc/eval>.  In the example
 688  below, each file will only be compiled once.  Or, the application
 689  might choose to clean out the symbol table associated with the file
 690  after it's no longer needed.  Using L<perlapi/call_argv>, We'll
 691  call the subroutine C<Embed::Persistent::eval_file> which lives in the
 692  file C<persistent.pl> and pass the filename and boolean cleanup/cache
 693  flag as arguments.
 694  
 695  Note that the process will continue to grow for each file that it
 696  uses.  In addition, there might be C<AUTOLOAD>ed subroutines and other
 697  conditions that cause Perl's symbol table to grow.  You might want to
 698  add some logic that keeps track of the process size, or restarts
 699  itself after a certain number of requests, to ensure that memory
 700  consumption is minimized.  You'll also want to scope your variables
 701  with L<perlfunc/my> whenever possible.
 702  
 703  
 704   package Embed::Persistent;
 705   #persistent.pl
 706  
 707   use strict;
 708   our %Cache;
 709   use Symbol qw(delete_package);
 710  
 711   sub valid_package_name {
 712       my($string) = @_;
 713       $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
 714       # second pass only for words starting with a digit
 715       $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;
 716  
 717       # Dress it up as a real package name
 718       $string =~ s|/|::|g;
 719       return "Embed" . $string;
 720   }
 721  
 722   sub eval_file {
 723       my($filename, $delete) = @_;
 724       my $package = valid_package_name($filename);
 725       my $mtime = -M $filename;
 726       if(defined $Cache{$package}{mtime}
 727          &&
 728          $Cache{$package}{mtime} <= $mtime)
 729       {
 730          # we have compiled this subroutine already,
 731          # it has not been updated on disk, nothing left to do
 732          print STDERR "already compiled $package->handler\n";
 733       }
 734       else {
 735          local *FH;
 736          open FH, $filename or die "open '$filename' $!";
 737          local($/) = undef;
 738          my $sub = <FH>;
 739          close FH;
 740  
 741          #wrap the code into a subroutine inside our unique package
 742          my $eval = qq{package $package; sub handler { $sub; }};
 743          {
 744              # hide our variables within this block
 745              my($filename,$mtime,$package,$sub);
 746              eval $eval;
 747          }
 748          die $@ if $@;
 749  
 750          #cache it unless we're cleaning out each time
 751          $Cache{$package}{mtime} = $mtime unless $delete;
 752       }
 753  
 754       eval {$package->handler;};
 755       die $@ if $@;
 756  
 757       delete_package($package) if $delete;
 758  
 759       #take a look if you want
 760       #print Devel::Symdump->rnew($package)->as_string, $/;
 761   }
 762  
 763   1;
 764  
 765   __END__
 766  
 767   /* persistent.c */
 768   #include <EXTERN.h>
 769   #include <perl.h>
 770  
 771   /* 1 = clean out filename's symbol table after each request, 0 = don't */
 772   #ifndef DO_CLEAN
 773   #define DO_CLEAN 0
 774   #endif
 775  
 776   #define BUFFER_SIZE 1024
 777  
 778   static PerlInterpreter *my_perl = NULL;
 779  
 780   int
 781   main(int argc, char **argv, char **env)
 782   {
 783       char *embedding[] = { "", "persistent.pl" };
 784       char *args[] = { "", DO_CLEAN, NULL };
 785       char filename[BUFFER_SIZE];
 786       int exitstatus = 0;
 787       STRLEN n_a;
 788  
 789       PERL_SYS_INIT3(&argc,&argv,&env);
 790       if((my_perl = perl_alloc()) == NULL) {
 791          fprintf(stderr, "no memory!");
 792          exit(1);
 793       }
 794       perl_construct(my_perl);
 795  
 796       PL_origalen = 1; /* don't let $0 assignment update the proctitle or embedding[0] */
 797       exitstatus = perl_parse(my_perl, NULL, 2, embedding, NULL);
 798       PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
 799       if(!exitstatus) {
 800          exitstatus = perl_run(my_perl);
 801  
 802          while(printf("Enter file name: ") &&
 803                fgets(filename, BUFFER_SIZE, stdin)) {
 804  
 805              filename[strlen(filename)-1] = '\0'; /* strip \n */
 806              /* call the subroutine, passing it the filename as an argument */
 807              args[0] = filename;
 808              call_argv("Embed::Persistent::eval_file",
 809                             G_DISCARD | G_EVAL, args);
 810  
 811              /* check $@ */
 812              if(SvTRUE(ERRSV))
 813                  fprintf(stderr, "eval error: %s\n", SvPV(ERRSV,n_a));
 814          }
 815       }
 816  
 817       PL_perl_destruct_level = 0;
 818       perl_destruct(my_perl);
 819       perl_free(my_perl);
 820       PERL_SYS_TERM();
 821       exit(exitstatus);
 822   }
 823  
 824  Now compile:
 825  
 826   % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
 827  
 828  Here's an example script file:
 829  
 830   #test.pl
 831   my $string = "hello";
 832   foo($string);
 833  
 834   sub foo {
 835       print "foo says: @_\n";
 836   }
 837  
 838  Now run:
 839  
 840   % persistent
 841   Enter file name: test.pl
 842   foo says: hello
 843   Enter file name: test.pl
 844   already compiled Embed::test_2epl->handler
 845   foo says: hello
 846   Enter file name: ^C
 847  
 848  =head2 Execution of END blocks
 849  
 850  Traditionally END blocks have been executed at the end of the perl_run.
 851  This causes problems for applications that never call perl_run. Since
 852  perl 5.7.2 you can specify C<PL_exit_flags |= PERL_EXIT_DESTRUCT_END>
 853  to get the new behaviour. This also enables the running of END blocks if
 854  the perl_parse fails and C<perl_destruct> will return the exit value.
 855  
 856  =head2 $0 assignments
 857  
 858  When a perl script assigns a value to $0 then the perl runtime will
 859  try to make this value show up as the program name reported by "ps" by
 860  updating the memory pointed to by the argv passed to perl_parse() and
 861  also calling API functions like setproctitle() where available.  This
 862  behaviour might not be appropriate when embedding perl and can be
 863  disabled by assigning the value C<1> to the variable C<PL_origalen>
 864  before perl_parse() is called.
 865  
 866  The F<persistent.c> example above is for instance likely to segfault
 867  when $0 is assigned to if the C<PL_origalen = 1;> assignment is
 868  removed.  This because perl will try to write to the read only memory
 869  of the C<embedding[]> strings.
 870  
 871  =head2 Maintaining multiple interpreter instances
 872  
 873  Some rare applications will need to create more than one interpreter
 874  during a session.  Such an application might sporadically decide to
 875  release any resources associated with the interpreter.
 876  
 877  The program must take care to ensure that this takes place I<before>
 878  the next interpreter is constructed.  By default, when perl is not
 879  built with any special options, the global variable
 880  C<PL_perl_destruct_level> is set to C<0>, since extra cleaning isn't
 881  usually needed when a program only ever creates a single interpreter
 882  in its entire lifetime.
 883  
 884  Setting C<PL_perl_destruct_level> to C<1> makes everything squeaky clean:
 885  
 886   while(1) {
 887       ...
 888       /* reset global variables here with PL_perl_destruct_level = 1 */
 889       PL_perl_destruct_level = 1;
 890       perl_construct(my_perl);
 891       ...
 892       /* clean and reset _everything_ during perl_destruct */
 893       PL_perl_destruct_level = 1;
 894       perl_destruct(my_perl);
 895       perl_free(my_perl);
 896       ...
 897       /* let's go do it again! */
 898   }
 899  
 900  When I<perl_destruct()> is called, the interpreter's syntax parse tree
 901  and symbol tables are cleaned up, and global variables are reset.  The
 902  second assignment to C<PL_perl_destruct_level> is needed because
 903  perl_construct resets it to C<0>.
 904  
 905  Now suppose we have more than one interpreter instance running at the
 906  same time.  This is feasible, but only if you used the Configure option
 907  C<-Dusemultiplicity> or the options C<-Dusethreads -Duseithreads> when
 908  building perl.  By default, enabling one of these Configure options
 909  sets the per-interpreter global variable C<PL_perl_destruct_level> to
 910  C<1>, so that thorough cleaning is automatic and interpreter variables
 911  are initialized correctly.  Even if you don't intend to run two or
 912  more interpreters at the same time, but to run them sequentially, like
 913  in the above example, it is recommended to build perl with the
 914  C<-Dusemultiplicity> option otherwise some interpreter variables may
 915  not be initialized correctly between consecutive runs and your
 916  application may crash.
 917  
 918  See also L<perlxs/Thread-aware system interfaces>.
 919  
 920  Using C<-Dusethreads -Duseithreads> rather than C<-Dusemultiplicity>
 921  is more appropriate if you intend to run multiple interpreters
 922  concurrently in different threads, because it enables support for
 923  linking in the thread libraries of your system with the interpreter.
 924  
 925  Let's give it a try:
 926  
 927  
 928   #include <EXTERN.h>
 929   #include <perl.h>
 930  
 931   /* we're going to embed two interpreters */
 932   /* we're going to embed two interpreters */
 933  
 934   #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"
 935  
 936   int main(int argc, char **argv, char **env)
 937   {
 938       PerlInterpreter *one_perl, *two_perl;
 939       char *one_args[] = { "one_perl", SAY_HELLO };
 940       char *two_args[] = { "two_perl", SAY_HELLO };
 941  
 942       PERL_SYS_INIT3(&argc,&argv,&env);
 943       one_perl = perl_alloc();
 944       two_perl = perl_alloc();
 945  
 946       PERL_SET_CONTEXT(one_perl);
 947       perl_construct(one_perl);
 948       PERL_SET_CONTEXT(two_perl);
 949       perl_construct(two_perl);
 950  
 951       PERL_SET_CONTEXT(one_perl);
 952       perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
 953       PERL_SET_CONTEXT(two_perl);
 954       perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
 955  
 956       PERL_SET_CONTEXT(one_perl);
 957       perl_run(one_perl);
 958       PERL_SET_CONTEXT(two_perl);
 959       perl_run(two_perl);
 960  
 961       PERL_SET_CONTEXT(one_perl);
 962       perl_destruct(one_perl);
 963       PERL_SET_CONTEXT(two_perl);
 964       perl_destruct(two_perl);
 965  
 966       PERL_SET_CONTEXT(one_perl);
 967       perl_free(one_perl);
 968       PERL_SET_CONTEXT(two_perl);
 969       perl_free(two_perl);
 970       PERL_SYS_TERM();
 971   }
 972  
 973  Note the calls to PERL_SET_CONTEXT().  These are necessary to initialize
 974  the global state that tracks which interpreter is the "current" one on
 975  the particular process or thread that may be running it.  It should
 976  always be used if you have more than one interpreter and are making
 977  perl API calls on both interpreters in an interleaved fashion.
 978  
 979  PERL_SET_CONTEXT(interp) should also be called whenever C<interp> is
 980  used by a thread that did not create it (using either perl_alloc(), or
 981  the more esoteric perl_clone()).
 982  
 983  Compile as usual:
 984  
 985   % cc -o multiplicity multiplicity.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
 986  
 987  Run it, Run it:
 988  
 989   % multiplicity
 990   Hi, I'm one_perl
 991   Hi, I'm two_perl
 992  
 993  =head2 Using Perl modules, which themselves use C libraries, from your C program
 994  
 995  If you've played with the examples above and tried to embed a script
 996  that I<use()>s a Perl module (such as I<Socket>) which itself uses a C or C++ library,
 997  this probably happened:
 998  
 999  
1000   Can't load module Socket, dynamic loading not available in this perl.
1001    (You may need to build a new perl executable which either supports
1002    dynamic loading or has the Socket module statically linked into it.)
1003  
1004  
1005  What's wrong?
1006  
1007  Your interpreter doesn't know how to communicate with these extensions
1008  on its own.  A little glue will help.  Up until now you've been
1009  calling I<perl_parse()>, handing it NULL for the second argument:
1010  
1011   perl_parse(my_perl, NULL, argc, my_argv, NULL);
1012  
1013  That's where the glue code can be inserted to create the initial contact between
1014  Perl and linked C/C++ routines.  Let's take a look some pieces of I<perlmain.c>
1015  to see how Perl does this:
1016  
1017   static void xs_init (pTHX);
1018  
1019   EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
1020   EXTERN_C void boot_Socket (pTHX_ CV* cv);
1021  
1022  
1023   EXTERN_C void
1024   xs_init(pTHX)
1025   {
1026          char *file = __FILE__;
1027          /* DynaLoader is a special case */
1028          newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
1029          newXS("Socket::bootstrap", boot_Socket, file);
1030   }
1031  
1032  Simply put: for each extension linked with your Perl executable
1033  (determined during its initial configuration on your
1034  computer or when adding a new extension),
1035  a Perl subroutine is created to incorporate the extension's
1036  routines.  Normally, that subroutine is named
1037  I<Module::bootstrap()> and is invoked when you say I<use Module>.  In
1038  turn, this hooks into an XSUB, I<boot_Module>, which creates a Perl
1039  counterpart for each of the extension's XSUBs.  Don't worry about this
1040  part; leave that to the I<xsubpp> and extension authors.  If your
1041  extension is dynamically loaded, DynaLoader creates I<Module::bootstrap()>
1042  for you on the fly.  In fact, if you have a working DynaLoader then there
1043  is rarely any need to link in any other extensions statically.
1044  
1045  
1046  Once you have this code, slap it into the second argument of I<perl_parse()>:
1047  
1048  
1049   perl_parse(my_perl, xs_init, argc, my_argv, NULL);
1050  
1051  
1052  Then compile:
1053  
1054   % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
1055  
1056   % interp
1057     use Socket;
1058     use SomeDynamicallyLoadedModule;
1059  
1060     print "Now I can use extensions!\n"'
1061  
1062  B<ExtUtils::Embed> can also automate writing the I<xs_init> glue code.
1063  
1064   % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c
1065   % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
1066   % cc -c interp.c  `perl -MExtUtils::Embed -e ccopts`
1067   % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
1068  
1069  Consult L<perlxs>, L<perlguts>, and L<perlapi> for more details.
1070  
1071  =head1 Embedding Perl under Win32
1072  
1073  In general, all of the source code shown here should work unmodified under
1074  Windows.
1075  
1076  However, there are some caveats about the command-line examples shown.
1077  For starters, backticks won't work under the Win32 native command shell.
1078  The ExtUtils::Embed kit on CPAN ships with a script called
1079  B<genmake>, which generates a simple makefile to build a program from
1080  a single C source file.  It can be used like this:
1081  
1082   C:\ExtUtils-Embed\eg> perl genmake interp.c
1083   C:\ExtUtils-Embed\eg> nmake
1084   C:\ExtUtils-Embed\eg> interp -e "print qq{I'm embedded in Win32!\n}"
1085  
1086  You may wish to use a more robust environment such as the Microsoft
1087  Developer Studio.  In this case, run this to generate perlxsi.c:
1088  
1089   perl -MExtUtils::Embed -e xsinit
1090  
1091  Create a new project and Insert -> Files into Project: perlxsi.c,
1092  perl.lib, and your own source files, e.g. interp.c.  Typically you'll
1093  find perl.lib in B<C:\perl\lib\CORE>, if not, you should see the
1094  B<CORE> directory relative to C<perl -V:archlib>.  The studio will
1095  also need this path so it knows where to find Perl include files.
1096  This path can be added via the Tools -> Options -> Directories menu.
1097  Finally, select Build -> Build interp.exe and you're ready to go.
1098  
1099  =head1 Hiding Perl_
1100  
1101  If you completely hide the short forms forms of the Perl public API,
1102  add -DPERL_NO_SHORT_NAMES to the compilation flags.  This means that
1103  for example instead of writing
1104  
1105      warn("%d bottles of beer on the wall", bottlecount);
1106  
1107  you will have to write the explicit full form
1108  
1109      Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);
1110  
1111  (See L<perlguts/Background and PERL_IMPLICIT_CONTEXT for the explanation
1112  of the C<aTHX_>.> )  Hiding the short forms is very useful for avoiding
1113  all sorts of nasty (C preprocessor or otherwise) conflicts with other
1114  software packages (Perl defines about 2400 APIs with these short names,
1115  take or leave few hundred, so there certainly is room for conflict.)
1116  
1117  =head1 MORAL
1118  
1119  You can sometimes I<write faster code> in C, but
1120  you can always I<write code faster> in Perl.  Because you can use
1121  each from the other, combine them as you wish.
1122  
1123  
1124  =head1 AUTHOR
1125  
1126  Jon Orwant <F<orwant@media.mit.edu>> and Doug MacEachern
1127  <F<dougm@covalent.net>>, with small contributions from Tim Bunce, Tom
1128  Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
1129  Zakharevich.
1130  
1131  Doug MacEachern has an article on embedding in Volume 1, Issue 4 of
1132  The Perl Journal ( http://www.tpj.com/ ).  Doug is also the developer of the
1133  most widely-used Perl embedding: the mod_perl system
1134  (perl.apache.org), which embeds Perl in the Apache web server.
1135  Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl
1136  have used this model for Oracle, Netscape and Internet Information
1137  Server Perl plugins.
1138  
1139  =head1 COPYRIGHT
1140  
1141  Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant.  All
1142  Rights Reserved.
1143  
1144  Permission is granted to make and distribute verbatim copies of this
1145  documentation provided the copyright notice and this permission notice are
1146  preserved on all copies.
1147  
1148  Permission is granted to copy and distribute modified versions of this
1149  documentation under the conditions for verbatim copying, provided also
1150  that they are marked clearly as modified versions, that the authors'
1151  names and title are unchanged (though subtitles and additional
1152  authors' names may be added), and that the entire resulting derived
1153  work is distributed under the terms of a permission notice identical
1154  to this one.
1155  
1156  Permission is granted to copy and distribute translations of this
1157  documentation into another language, under the above conditions for
1158  modified versions.