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