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