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 -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 exit(EXIT_SUCCESS);
163 }
164 Notice that we don't use the "env" pointer. Normally handed to
166 "perl_parse" as its final argument, "env" here is replaced by "NULL",
167 which means that the current environment will be used.
168 The macros PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific
170 tune up of the C runtime environment necessary to run Perl
171 interpreters; they should only be called once regardless of how many
172 interpreters you create or destroy. Call PERL_SYS_INIT3() before you
173 create your first interpreter, and PERL_SYS_TERM() after you free your
174 last interpreter.
175 Since PERL_SYS_INIT3() may change "env", it may be more appropriate to
177 provide "env" as an argument to perl_parse().
178 Also notice that no matter what arguments you pass to perl_parse(),
180 PERL_SYS_INIT3() must be invoked on the C main() argc, argv and env and
181 only once.
182 Mind that argv[argc] must be NULL, same as those passed to a main
184 function in C.
185 Now compile this program (I'll call it interp.c) into an executable:
187 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
189 After a successful compilation, you'll be able to use interp just like
191 perl itself:
192 % interp
194 print "Pretty Good Perl \n";
195 print "10890 - 9801 is ", 10890 - 9801;
196 <CTRL-D>
197 Pretty Good Perl
198 10890 - 9801 is 1089
199 or
201 % interp -e 'printf("%x", 3735928559)'
203 deadbeef
204 You can also read and execute Perl statements from a file while in the
206 midst of your C program, by placing the filename in argv[1] before
207 calling perl_run.
208 Calling a Perl subroutine from your C program
210 To call individual Perl subroutines, you can use any of the call_*
211 functions documented in perlcall. In this example we'll use
212 "call_argv".
213 That's shown below, in a program I'll call showtime.c.
215 #include <EXTERN.h>
217 #include <perl.h>
218 static PerlInterpreter *my_perl;
220 int main(int argc, char **argv, char **env)
222 {
223 char *args[] = { NULL };
224 PERL_SYS_INIT3(&argc,&argv,&env);
225 my_perl = perl_alloc();
226 perl_construct(my_perl);
227 perl_parse(my_perl, NULL, argc, argv, NULL);
229 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
230 /*** skipping perl_run() ***/
232 call_argv("showtime", G_DISCARD | G_NOARGS, args);
234 perl_destruct(my_perl);
236 perl_free(my_perl);
237 PERL_SYS_TERM();
238 exit(EXIT_SUCCESS);
239 }
240 where showtime is a Perl subroutine that takes no arguments (that's the
242 G_NOARGS) and for which I'll ignore the return value (that's the
243 G_DISCARD). Those flags, and others, are discussed in perlcall.
244 I'll define the showtime subroutine in a file called showtime.pl:
246 print "I shan't be printed.";
248 sub showtime {
250 print time;
251 }
252 Simple enough. Now compile and run:
254 % cc -o showtime showtime.c \
256 `perl -MExtUtils::Embed -e ccopts -e ldopts`
257 % showtime showtime.pl
258 818284590
259 yielding the number of seconds that elapsed between January 1, 1970
261 (the beginning of the Unix epoch), and the moment I began writing this
262 sentence.
263 In this particular case we don't have to call perl_run, as we set the
265 PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
266 perl_destruct.
267 If you want to pass arguments to the Perl subroutine, you can add
269 strings to the "NULL"-terminated "args" list passed to call_argv. For
270 other data types, or to examine return values, you'll need to
271 manipulate the Perl stack. That's demonstrated in "Fiddling with the
272 Perl stack from your C program".
273 Evaluating a Perl statement from your C program
275 Perl provides two API functions to evaluate pieces of Perl code. These
276 are "eval_sv" in perlapi and "eval_pv" in perlapi.
277 Arguably, these are the only routines you'll ever need to execute
279 snippets of Perl code from within your C program. Your code can be as
280 long as you wish; it can contain multiple statements; it can employ
281 "use" in perlfunc, "require" in perlfunc, and "do" in perlfunc to
282 include external Perl files.
283 eval_pv lets us evaluate individual Perl strings, and then extract
285 variables for coercion into C types. The following program, string.c,
286 executes three Perl strings, extracting an "int" from the first, a
287 "float" from the second, and a "char *" from the third.
288 #include <EXTERN.h>
290 #include <perl.h>
291 static PerlInterpreter *my_perl;
293 main (int argc, char **argv, char **env)
295 {
296 char *embedding[] = { "", "-e", "0", NULL };
297 PERL_SYS_INIT3(&argc,&argv,&env);
299 my_perl = perl_alloc();
300 perl_construct( my_perl );
301 perl_parse(my_perl, NULL, 3, embedding, NULL);
303 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
304 perl_run(my_perl);
305 /** Treat $a as an integer **/
307 eval_pv("$a = 3; $a **= 2", TRUE);
308 printf("a = %d\n", SvIV(get_sv("a", 0)));
309 /** Treat $a as a float **/
311 eval_pv("$a = 3.14; $a **= 2", TRUE);
312 printf("a = %f\n", SvNV(get_sv("a", 0)));
313 /** Treat $a as a string **/
315 eval_pv(
316 "$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
317 printf("a = %s\n", SvPV_nolen(get_sv("a", 0)));
318 perl_destruct(my_perl);
320 perl_free(my_perl);
321 PERL_SYS_TERM();
322 }
323 All of those strange functions with sv in their names help convert Perl
325 scalars to C types. They're described in perlguts and perlapi.
326 If you compile and run string.c, you'll see the results of using SvIV()
328 to create an "int", SvNV() to create a "float", and SvPV() to create a
329 string:
330 a = 9
332 a = 9.859600
333 a = Just Another Perl Hacker
334 In the example above, we've created a global variable to temporarily
336 store the computed value of our eval'ed expression. It is also
337 possible and in most cases a better strategy to fetch the return value
338 from eval_pv() instead. Example:
339 ...
341 SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
342 printf("%s\n", SvPV_nolen(val));
343 ...
344 This way, we avoid namespace pollution by not creating global variables
346 and we've simplified our code as well.
347 Performing Perl pattern matches and substitutions from your C program
349 The eval_sv() function lets us evaluate strings of Perl code, so we can
350 define some functions that use it to "specialize" in matches and
351 substitutions: match(), substitute(), and matches().
352 I32 match(SV *string, char *pattern);
354 Given a string and a pattern (e.g., "m/clasp/" or "/\b\w*\b/", which in
356 your C program might appear as "/\\b\\w*\\b/"), match() returns 1 if
357 the string matches the pattern and 0 otherwise.
358 int substitute(SV **string, char *pattern);
360 Given a pointer to an "SV" and an "=~" operation (e.g.,
362 "s/bob/robert/g" or "tr[A-Z][a-z]"), substitute() modifies the string
363 within the "SV" as according to the operation, returning the number of
364 substitutions made.
365 SSize_t matches(SV *string, char *pattern, AV **matches);
367 Given an "SV", a pattern, and a pointer to an empty "AV", matches()
369 evaluates "$string =~ $pattern" in a list context, and fills in matches
370 with the array elements, returning the number of matches found.
371 Here's a sample program, match.c, that uses all three (long lines have
373 been wrapped here):
374 #include <EXTERN.h>
376 #include <perl.h>
377 static PerlInterpreter *my_perl;
379 /** my_eval_sv(code, error_check)
381 ** kinda like eval_sv(),
382 ** but we pop the return value off the stack
383 **/
384 SV* my_eval_sv(SV *sv, I32 croak_on_error)
385 {
386 dSP;
387 SV* retval;
388 PUSHMARK(SP);
391 eval_sv(sv, G_SCALAR);
392 SPAGAIN;
394 retval = POPs;
395 PUTBACK;
396 if (croak_on_error && SvTRUE(ERRSV))
398 croak_sv(ERRSV);
399 return retval;
401 }
402 /** match(string, pattern)
404 **
405 ** Used for matches in a scalar context.
406 **
407 ** Returns 1 if the match was successful; 0 otherwise.
408 **/
409 I32 match(SV *string, char *pattern)
411 {
412 SV *command = newSV(0), *retval;
413 sv_setpvf(command, "my $string = '%s'; $string =~ %s",
415 SvPV_nolen(string), pattern);
416 retval = my_eval_sv(command, TRUE);
418 SvREFCNT_dec(command);
419 return SvIV(retval);
421 }
422 /** substitute(string, pattern)
424 **
425 ** Used for =~ operations that
426 ** modify their left-hand side (s/// and tr///)
427 **
428 ** Returns the number of successful matches, and
429 ** modifies the input string if there were any.
430 **/
431 I32 substitute(SV **string, char *pattern)
433 {
434 SV *command = newSV(0), *retval;
435 sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
437 SvPV_nolen(*string), pattern);
438 retval = my_eval_sv(command, TRUE);
440 SvREFCNT_dec(command);
441 *string = get_sv("string", 0);
443 return SvIV(retval);
444 }
445 /** matches(string, pattern, matches)
447 **
448 ** Used for matches in a list context.
449 **
450 ** Returns the number of matches,
451 ** and fills in **matches with the matching substrings
452 **/
453 SSize_t matches(SV *string, char *pattern, AV **match_list)
455 {
456 SV *command = newSV(0);
457 SSize_t num_matches;
458 sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
460 SvPV_nolen(string), pattern);
461 my_eval_sv(command, TRUE);
463 SvREFCNT_dec(command);
464 *match_list = get_av("array", 0);
466 num_matches = av_top_index(*match_list) + 1;
467 return num_matches;
469 }
470 main (int argc, char **argv, char **env)
472 {
473 char *embedding[] = { "", "-e", "0", NULL };
474 AV *match_list;
475 I32 num_matches, i;
476 SV *text;
477 PERL_SYS_INIT3(&argc,&argv,&env);
479 my_perl = perl_alloc();
480 perl_construct(my_perl);
481 perl_parse(my_perl, NULL, 3, embedding, NULL);
482 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
483 text = newSV(0);
485 sv_setpv(text, "When he is at a convenience store and the "
486 "bill comes to some amount like 76 cents, Maynard is "
487 "aware that there is something he *should* do, something "
488 "that will enable him to get back a quarter, but he has "
489 "no idea *what*. He fumbles through his red squeezey "
490 "changepurse and gives the boy three extra pennies with "
491 "his dollar, hoping that he might luck into the correct "
492 "amount. The boy gives him back two of his own pennies "
493 "and then the big shiny quarter that is his prize. "
494 "-RICHH");
495 if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
497 printf("match: Text contains the word 'quarter'.\n\n");
498 else
499 printf("match: Text doesn't contain the word 'quarter'.\n\n");
500 if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
502 printf("match: Text contains the word 'eighth'.\n\n");
503 else
504 printf("match: Text doesn't contain the word 'eighth'.\n\n");
505 /** Match all occurrences of /wi../ **/
507 num_matches = matches(text, "m/(wi..)/g", &match_list);
508 printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
509 for (i = 0; i < num_matches; i++)
511 printf("match: %s\n",
512 SvPV_nolen(*av_fetch(match_list, i, FALSE)));
513 printf("\n");
514 /** Remove all vowels from text **/
516 num_matches = substitute(&text, "s/[aeiou]//gi");
517 if (num_matches) {
518 printf("substitute: s/[aeiou]//gi...%lu substitutions made.\n",
519 (unsigned long)num_matches);
520 printf("Now text is: %s\n\n", SvPV_nolen(text));
521 }
522 /** Attempt a substitution **/
524 if (!substitute(&text, "s/Perl/C/")) {
525 printf("substitute: s/Perl/C...No substitution made.\n\n");
526 }
527 SvREFCNT_dec(text);
529 PL_perl_destruct_level = 1;
530 perl_destruct(my_perl);
531 perl_free(my_perl);
532 PERL_SYS_TERM();
533 }
534 which produces the output (again, long lines have been wrapped here)
536 match: Text contains the word 'quarter'.
538 match: Text doesn't contain the word 'eighth'.
540 matches: m/(wi..)/g found 2 matches...
542 match: will
543 match: with
544 substitute: s/[aeiou]//gi...139 substitutions made.
546 Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
547 Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt
548 bck qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd
549 gvs th by thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct
550 mnt. Th by gvs hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s
551 hs prz. -RCHH
552 substitute: s/Perl/C...No substitution made.
554 Fiddling with the Perl stack from your C program
556 When trying to explain stacks, most computer science textbooks mumble
557 something about spring-loaded columns of cafeteria plates: the last
558 thing you pushed on the stack is the first thing you pop off. That'll
559 do for our purposes: your C program will push some arguments onto "the
560 Perl stack", shut its eyes while some magic happens, and then pop the
561 results--the return value of your Perl subroutine--off the stack.
562 First you'll need to know how to convert between C types and Perl
564 types, with newSViv() and sv_setnv() and newAV() and all their friends.
565 They're described in perlguts and perlapi.
566 Then you'll need to know how to manipulate the Perl stack. That's
568 described in perlcall.
569 Once you've understood those, embedding Perl in C is easy.
571 Because C has no builtin function for integer exponentiation, let's
573 make Perl's ** operator available to it (this is less useful than it
574 sounds, because Perl implements ** with C's pow() function). First
575 I'll create a stub exponentiation function in power.pl:
576 sub expo {
578 my ($a, $b) = @_;
579 return $a ** $b;
580 }
581 Now I'll create a C program, power.c, with a function PerlPower() that
583 contains all the perlguts necessary to push the two arguments into
584 expo() and to pop the return value out. Take a deep breath...
585 #include <EXTERN.h>
587 #include <perl.h>
588 static PerlInterpreter *my_perl;
590 static void
592 PerlPower(int a, int b)
593 {
594 dSP; /* initialize stack pointer */
595 ENTER; /* everything created after here */
596 SAVETMPS; /* ...is a temporary variable. */
597 PUSHMARK(SP); /* remember the stack pointer */
598 XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
599 XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
600 PUTBACK; /* make local stack pointer global */
601 call_pv("expo", G_SCALAR); /* call the function */
602 SPAGAIN; /* refresh stack pointer */
603 /* pop the return value from stack */
604 printf ("%d to the %dth power is %d.\n", a, b, POPi);
605 PUTBACK;
606 FREETMPS; /* free that return value */
607 LEAVE; /* ...and the XPUSHed "mortal" args.*/
608 }
609 int main (int argc, char **argv, char **env)
611 {
612 char *my_argv[] = { "", "power.pl", NULL };
613 PERL_SYS_INIT3(&argc,&argv,&env);
615 my_perl = perl_alloc();
616 perl_construct( my_perl );
617 perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
619 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
620 perl_run(my_perl);
621 PerlPower(3, 4); /*** Compute 3 ** 4 ***/
623 perl_destruct(my_perl);
625 perl_free(my_perl);
626 PERL_SYS_TERM();
627 exit(EXIT_SUCCESS);
628 }
629 Compile and run:
631 % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
633 % power
635 3 to the 4th power is 81.
636 Maintaining a persistent interpreter
638 When developing interactive and/or potentially long-running
639 applications, it's a good idea to maintain a persistent interpreter
640 rather than allocating and constructing a new interpreter multiple
641 times. The major reason is speed: since Perl will only be loaded into
642 memory once.
643 However, you have to be more cautious with namespace and variable
645 scoping when using a persistent interpreter. In previous examples
646 we've been using global variables in the default package "main". We
647 knew exactly what code would be run, and assumed we could avoid
648 variable collisions and outrageous symbol table growth.
649 Let's say your application is a server that will occasionally run Perl
651 code from some arbitrary file. Your server has no way of knowing what
652 code it's going to run. Very dangerous.
653 If the file is pulled in by "perl_parse()", compiled into a newly
655 constructed interpreter, and subsequently cleaned out with
656 "perl_destruct()" afterwards, you're shielded from most namespace
657 troubles.
658 One way to avoid namespace collisions in this scenario is to translate
660 the filename into a guaranteed-unique package name, and then compile
661 the code into that package using "eval" in perlfunc. In the example
662 below, each file will only be compiled once. Or, the application might
663 choose to clean out the symbol table associated with the file after
664 it's no longer needed. Using "call_argv" in perlapi, We'll call the
665 subroutine "Embed::Persistent::eval_file" which lives in the file
666 "persistent.pl" and pass the filename and boolean cleanup/cache flag as
667 arguments.
668 Note that the process will continue to grow for each file that it uses.
670 In addition, there might be "AUTOLOAD"ed subroutines and other
671 conditions that cause Perl's symbol table to grow. You might want to
672 add some logic that keeps track of the process size, or restarts itself
673 after a certain number of requests, to ensure that memory consumption
674 is minimized. You'll also want to scope your variables with "my" in
675 perlfunc whenever possible.
676 package Embed::Persistent;
678 #persistent.pl
679 use strict;
681 our %Cache;
682 use Symbol qw(delete_package);
683 sub valid_package_name {
685 my($string) = @_;
686 $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
687 # second pass only for words starting with a digit
688 $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;
689 # Dress it up as a real package name
691 $string =~ s|/|::|g;
692 return "Embed" . $string;
693 }
694 sub eval_file {
696 my($filename, $delete) = @_;
697 my $package = valid_package_name($filename);
698 my $mtime = -M $filename;
699 if(defined $Cache{$package}{mtime}
700 &&
701 $Cache{$package}{mtime} <= $mtime)
702 {
703 # we have compiled this subroutine already,
704 # it has not been updated on disk, nothing left to do
705 print STDERR "already compiled $package->handler\n";
706 }
707 else {
708 local *FH;
709 open FH, $filename or die "open '$filename' $!";
710 local($/) = undef;
711 my $sub = <FH>;
712 close FH;
713 #wrap the code into a subroutine inside our unique package
715 my $eval = qq{package $package; sub handler { $sub; }};
716 {
717 # hide our variables within this block
718 my($filename,$mtime,$package,$sub);
719 eval $eval;
720 }
721 die $@ if $@;
722 #cache it unless we're cleaning out each time
724 $Cache{$package}{mtime} = $mtime unless $delete;
725 }
726 eval {$package->handler;};
728 die $@ if $@;
729 delete_package($package) if $delete;
731 #take a look if you want
733 #print Devel::Symdump->rnew($package)->as_string, $/;
734 }
735 1;
737 __END__
739 /* persistent.c */
741 #include <EXTERN.h>
742 #include <perl.h>
743 /* 1 = clean out filename's symbol table after each request,
745 0 = don't
746 */
747 #ifndef DO_CLEAN
748 #define DO_CLEAN 0
749 #endif
750 #define BUFFER_SIZE 1024
752 static PerlInterpreter *my_perl = NULL;
754 int
756 main(int argc, char **argv, char **env)
757 {
758 char *embedding[] = { "", "persistent.pl", NULL };
759 char *args[] = { "", DO_CLEAN, NULL };
760 char filename[BUFFER_SIZE];
761 int failing, exitstatus;
762 PERL_SYS_INIT3(&argc,&argv,&env);
764 if((my_perl = perl_alloc()) == NULL) {
765 fprintf(stderr, "no memory!");
766 exit(EXIT_FAILURE);
767 }
768 perl_construct(my_perl);
769 PL_origalen = 1; /* don't let $0 assignment update the
771 proctitle or embedding[0] */
772 failing = perl_parse(my_perl, NULL, 2, embedding, NULL);
773 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
774 if(!failing)
775 failing = perl_run(my_perl);
776 if(!failing) {
777 while(printf("Enter file name: ") &&
778 fgets(filename, BUFFER_SIZE, stdin)) {
779 filename[strlen(filename)-1] = '\0'; /* strip \n */
781 /* call the subroutine,
782 passing it the filename as an argument */
783 args[0] = filename;
784 call_argv("Embed::Persistent::eval_file",
785 G_DISCARD | G_EVAL, args);
786 /* check $@ */
788 if(SvTRUE(ERRSV))
789 fprintf(stderr, "eval error: %s\n", SvPV_nolen(ERRSV));
790 }
791 }
792 PL_perl_destruct_level = 0;
794 exitstatus = perl_destruct(my_perl);
795 perl_free(my_perl);
796 PERL_SYS_TERM();
797 exit(exitstatus);
798 }
799 Now compile:
801 % cc -o persistent persistent.c \
803 `perl -MExtUtils::Embed -e ccopts -e ldopts`
804 Here's an example script file:
806 #test.pl
808 my $string = "hello";
809 foo($string);
810 sub foo {
812 print "foo says: @_\n";
813 }
814 Now run:
816 % persistent
818 Enter file name: test.pl
819 foo says: hello
820 Enter file name: test.pl
821 already compiled Embed::test_2epl->handler
822 foo says: hello
823 Enter file name: ^C
824 Execution of END blocks
826 Traditionally END blocks have been executed at the end of the perl_run.
827 This causes problems for applications that never call perl_run. Since
828 perl 5.7.2 you can specify "PL_exit_flags |= PERL_EXIT_DESTRUCT_END" to
829 get the new behaviour. This also enables the running of END blocks if
830 the perl_parse fails and "perl_destruct" will return the exit value.
831 $0 assignments
833 When a perl script assigns a value to $0 then the perl runtime will try
834 to make this value show up as the program name reported by "ps" by
835 updating the memory pointed to by the argv passed to perl_parse() and
836 also calling API functions like setproctitle() where available. This
837 behaviour might not be appropriate when embedding perl and can be
838 disabled by assigning the value 1 to the variable "PL_origalen" before
839 perl_parse() is called.
840 The persistent.c example above is for instance likely to segfault when
842 $0 is assigned to if the "PL_origalen = 1;" assignment is removed.
843 This because perl will try to write to the read only memory of the
844 "embedding[]" strings.
845 Maintaining multiple interpreter instances
847 Some rare applications will need to create more than one interpreter
848 during a session. Such an application might sporadically decide to
849 release any resources associated with the interpreter.
850 The program must take care to ensure that this takes place before the
852 next interpreter is constructed. By default, when perl is not built
853 with any special options, the global variable "PL_perl_destruct_level"
854 is set to 0, since extra cleaning isn't usually needed when a program
855 only ever creates a single interpreter in its entire lifetime.
856 Setting "PL_perl_destruct_level" to 1 makes everything squeaky clean:
858 while(1) {
860 ...
861 /* reset global variables here with PL_perl_destruct_level = 1 */
862 PL_perl_destruct_level = 1;
863 perl_construct(my_perl);
864 ...
865 /* clean and reset _everything_ during perl_destruct */
866 PL_perl_destruct_level = 1;
867 perl_destruct(my_perl);
868 perl_free(my_perl);
869 ...
870 /* let's go do it again! */
871 }
872 When perl_destruct() is called, the interpreter's syntax parse tree and
874 symbol tables are cleaned up, and global variables are reset. The
875 second assignment to "PL_perl_destruct_level" is needed because
876 perl_construct resets it to 0.
877 Now suppose we have more than one interpreter instance running at the
879 same time. This is feasible, but only if you used the Configure option
880 "-Dusemultiplicity" or the options "-Dusethreads -Duseithreads" when
881 building perl. By default, enabling one of these Configure options
882 sets the per-interpreter global variable "PL_perl_destruct_level" to 1,
883 so that thorough cleaning is automatic and interpreter variables are
884 initialized correctly. Even if you don't intend to run two or more
885 interpreters at the same time, but to run them sequentially, like in
886 the above example, it is recommended to build perl with the
887 "-Dusemultiplicity" option otherwise some interpreter variables may not
888 be initialized correctly between consecutive runs and your application
889 may crash.
890 See also "Thread-aware system interfaces" in perlxs.
892 Using "-Dusethreads -Duseithreads" rather than "-Dusemultiplicity" is
894 more appropriate if you intend to run multiple interpreters
895 concurrently in different threads, because it enables support for
896 linking in the thread libraries of your system with the interpreter.
897 Let's give it a try:
899 #include <EXTERN.h>
901 #include <perl.h>
902 /* we're going to embed two interpreters */
904 #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"
906 int main(int argc, char **argv, char **env)
908 {
909 PerlInterpreter *one_perl, *two_perl;
910 char *one_args[] = { "one_perl", SAY_HELLO, NULL };
911 char *two_args[] = { "two_perl", SAY_HELLO, NULL };
912 PERL_SYS_INIT3(&argc,&argv,&env);
914 one_perl = perl_alloc();
915 two_perl = perl_alloc();
916 PERL_SET_CONTEXT(one_perl);
918 perl_construct(one_perl);
919 PERL_SET_CONTEXT(two_perl);
920 perl_construct(two_perl);
921 PERL_SET_CONTEXT(one_perl);
923 perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
924 PERL_SET_CONTEXT(two_perl);
925 perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
926 PERL_SET_CONTEXT(one_perl);
928 perl_run(one_perl);
929 PERL_SET_CONTEXT(two_perl);
930 perl_run(two_perl);
931 PERL_SET_CONTEXT(one_perl);
933 perl_destruct(one_perl);
934 PERL_SET_CONTEXT(two_perl);
935 perl_destruct(two_perl);
936 PERL_SET_CONTEXT(one_perl);
938 perl_free(one_perl);
939 PERL_SET_CONTEXT(two_perl);
940 perl_free(two_perl);
941 PERL_SYS_TERM();
942 exit(EXIT_SUCCESS);
943 }
944 Note the calls to PERL_SET_CONTEXT(). These are necessary to
946 initialize the global state that tracks which interpreter is the
947 "current" one on the particular process or thread that may be running
948 it. It should always be used if you have more than one interpreter and
949 are making perl API calls on both interpreters in an interleaved
950 fashion.
951 PERL_SET_CONTEXT(interp) should also be called whenever "interp" is
953 used by a thread that did not create it (using either perl_alloc(), or
954 the more esoteric perl_clone()).
955 Compile as usual:
957 % cc -o multiplicity multiplicity.c \
959 `perl -MExtUtils::Embed -e ccopts -e ldopts`
960 Run it, Run it:
962 % multiplicity
964 Hi, I'm one_perl
965 Hi, I'm two_perl
966 Using Perl modules, which themselves use C libraries, from your C program
968 If you've played with the examples above and tried to embed a script
969 that use()s a Perl module (such as Socket) which itself uses a C or C++
970 library, this probably happened:
971 Can't load module Socket, dynamic loading not available in this perl.
973 (You may need to build a new perl executable which either supports
974 dynamic loading or has the Socket module statically linked into it.)
975 What's wrong?
977 Your interpreter doesn't know how to communicate with these extensions
979 on its own. A little glue will help. Up until now you've been calling
980 perl_parse(), handing it NULL for the second argument:
981 perl_parse(my_perl, NULL, argc, my_argv, NULL);
983 That's where the glue code can be inserted to create the initial
985 contact between Perl and linked C/C++ routines. Let's take a look some
986 pieces of perlmain.c to see how Perl does this:
987 static void xs_init (pTHX);
989 EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
991 EXTERN_C void boot_Socket (pTHX_ CV* cv);
992 EXTERN_C void
995 xs_init(pTHX)
996 {
997 char *file = __FILE__;
998 /* DynaLoader is a special case */
999 newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
1000 newXS("Socket::bootstrap", boot_Socket, file);
1001 }
1002 Simply put: for each extension linked with your Perl executable
1004 (determined during its initial configuration on your computer or when
1005 adding a new extension), a Perl subroutine is created to incorporate
1006 the extension's routines. Normally, that subroutine is named
1007 Module::bootstrap() and is invoked when you say use Module. In turn,
1008 this hooks into an XSUB, boot_Module, which creates a Perl counterpart
1009 for each of the extension's XSUBs. Don't worry about this part; leave
1010 that to the xsubpp and extension authors. If your extension is
1011 dynamically loaded, DynaLoader creates Module::bootstrap() for you on
1012 the fly. In fact, if you have a working DynaLoader then there is
1013 rarely any need to link in any other extensions statically.
1014 Once you have this code, slap it into the second argument of
1016 perl_parse():
1017 perl_parse(my_perl, xs_init, argc, my_argv, NULL);
1019 Then compile:
1021 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
1023 % interp
1025 use Socket;
1026 use SomeDynamicallyLoadedModule;
1027 print "Now I can use extensions!\n"'
1029 ExtUtils::Embed can also automate writing the xs_init glue code.
1031 % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c
1033 % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
1034 % cc -c interp.c `perl -MExtUtils::Embed -e ccopts`
1035 % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
1036 Consult perlxs, perlguts, and perlapi for more details.
1038 Using embedded Perl with POSIX locales
1040 (See perllocale for information about these.) When a Perl interpreter
1041 normally starts up, it tells the system it wants to use the system's
1042 default locale. This is often, but not necessarily, the "C" or "POSIX"
1043 locale. Absent a "use locale" within the perl code, this mostly has no
1044 effect (but see "Not within the scope of "use locale"" in perllocale).
1045 Also, there is not a problem if the locale you want to use in your
1046 embedded perl is the same as the system default. However, this doesn't
1047 work if you have set up and want to use a locale that isn't the system
1048 default one. Starting in Perl v5.20, you can tell the embedded Perl
1049 interpreter that the locale is already properly set up, and to skip
1050 doing its own normal initialization. It skips if the environment
1051 variable "PERL_SKIP_LOCALE_INIT" is set (even if set to 0 or ""). A
1052 perl that has this capability will define the C pre-processor symbol
1053 "HAS_SKIP_LOCALE_INIT". This allows code that has to work with
1054 multiple Perl versions to do some sort of work-around when confronted
1055 with an earlier Perl.
1056 If your program is using the POSIX 2008 multi-thread locale
1058 functionality, you should switch into the global locale and set that up
1059 properly before starting the Perl interpreter. It will then properly
1060 switch back to using the thread-safe functions.
1061
1063 If you completely hide the short forms of the Perl public API, add
1064 -DPERL_NO_SHORT_NAMES to the compilation flags. This means that for
1065 example instead of writing
1066 warn("%d bottles of beer on the wall", bottlecount);
1068 you will have to write the explicit full form
1070 Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);
1072 (See "Background and PERL_IMPLICIT_CONTEXT" in perlguts for the
1074 explanation of the "aTHX_". ) Hiding the short forms is very useful
1075 for avoiding all sorts of nasty (C preprocessor or otherwise) conflicts
1076 with other software packages (Perl defines about 2400 APIs with these
1077 short names, take or leave few hundred, so there certainly is room for
1078 conflict.)
1079
1081 You can sometimes write faster code in C, but you can always write code
1082 faster in Perl. Because you can use each from the other, combine them
1083 as you wish.
1084
1086 Jon Orwant <orwant@media.mit.edu> and Doug MacEachern
1087 <dougm@covalent.net>, with small contributions from Tim Bunce, Tom
1088 Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
1089 Zakharevich.
1090 Doug MacEachern has an article on embedding in Volume 1, Issue 4 of The
1092 Perl Journal ( <http://www.tpj.com/> ). Doug is also the developer of
1093 the most widely-used Perl embedding: the mod_perl system
1094 (perl.apache.org), which embeds Perl in the Apache web server. Oracle,
1095 Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl have used
1096 this model for Oracle, Netscape and Internet Information Server Perl
1097 plugins.
1098
1100 Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant.
1101 All Rights Reserved.
1102 This document may be distributed under the same terms as Perl itself.
1104perl v5.28.2 2018-11-01 PERLEMBED(1)