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 <https://metacpan.org/pod/ExtUtils::Embed> (If
131 this documentation came from your Perl distribution, then you're
132 running 5.004 or better and you already have it.)
133 The ExtUtils::Embed kit on CPAN also contains all source code for the
135 examples in this document, tests, additional examples and other
136 information you may find useful.
137 Adding a Perl interpreter to your C program
139 In a sense, perl (the C program) is a good example of embedding Perl
140 (the language), so I'll demonstrate embedding with miniperlmain.c,
141 included in the source distribution. Here's a bastardized, non-
142 portable version of miniperlmain.c containing the essentials of
143 embedding:
144 #include <EXTERN.h> /* from the Perl distribution */
146 #include <perl.h> /* from the Perl distribution */
147 static PerlInterpreter *my_perl; /*** The Perl interpreter ***/
149 int main(int argc, char **argv, char **env)
151 {
152 PERL_SYS_INIT3(&argc,&argv,&env);
153 my_perl = perl_alloc();
154 perl_construct(my_perl);
155 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
156 perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
157 perl_run(my_perl);
158 perl_destruct(my_perl);
159 perl_free(my_perl);
160 PERL_SYS_TERM();
161 exit(EXIT_SUCCESS);
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 exit(EXIT_SUCCESS);
238 }
239 where showtime is a Perl subroutine that takes no arguments (that's the
241 G_NOARGS) and for which I'll ignore the return value (that's the
242 G_DISCARD). Those flags, and others, are discussed in perlcall.
243 I'll define the showtime subroutine in a file called showtime.pl:
245 print "I shan't be printed.";
247 sub showtime {
249 print time;
250 }
251 Simple enough. Now compile and run:
253 % cc -o showtime showtime.c \
255 `perl -MExtUtils::Embed -e ccopts -e ldopts`
256 % showtime showtime.pl
257 818284590
258 yielding the number of seconds that elapsed between January 1, 1970
260 (the beginning of the Unix epoch), and the moment I began writing this
261 sentence.
262 In this particular case we don't have to call perl_run, as we set the
264 PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
265 perl_destruct.
266 If you want to pass arguments to the Perl subroutine, you can add
268 strings to the "NULL"-terminated "args" list passed to call_argv. For
269 other data types, or to examine return values, you'll need to
270 manipulate the Perl stack. That's demonstrated in "Fiddling with the
271 Perl stack from your C program".
272 Evaluating a Perl statement from your C program
274 Perl provides two API functions to evaluate pieces of Perl code. These
275 are "eval_sv" in perlapi and "eval_pv" in perlapi.
276 Arguably, these are the only routines you'll ever need to execute
278 snippets of Perl code from within your C program. Your code can be as
279 long as you wish; it can contain multiple statements; it can employ
280 "use" in perlfunc, "require" in perlfunc, and "do" in perlfunc to
281 include external Perl files.
282 eval_pv lets us evaluate individual Perl strings, and then extract
284 variables for coercion into C types. The following program, string.c,
285 executes three Perl strings, extracting an "int" from the first, a
286 "float" from the second, and a "char *" from the third.
287 #include <EXTERN.h>
289 #include <perl.h>
290 static PerlInterpreter *my_perl;
292 main (int argc, char **argv, char **env)
294 {
295 char *embedding[] = { "", "-e", "0", NULL };
296 PERL_SYS_INIT3(&argc,&argv,&env);
298 my_perl = perl_alloc();
299 perl_construct( my_perl );
300 perl_parse(my_perl, NULL, 3, embedding, NULL);
302 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
303 perl_run(my_perl);
304 /** Treat $a as an integer **/
306 eval_pv("$a = 3; $a **= 2", TRUE);
307 printf("a = %d\n", SvIV(get_sv("a", 0)));
308 /** Treat $a as a float **/
310 eval_pv("$a = 3.14; $a **= 2", TRUE);
311 printf("a = %f\n", SvNV(get_sv("a", 0)));
312 /** Treat $a as a string **/
314 eval_pv(
315 "$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
316 printf("a = %s\n", SvPV_nolen(get_sv("a", 0)));
317 perl_destruct(my_perl);
319 perl_free(my_perl);
320 PERL_SYS_TERM();
321 }
322 All of those strange functions with sv in their names help convert Perl
324 scalars to C types. They're described in perlguts and perlapi.
325 If you compile and run string.c, you'll see the results of using SvIV()
327 to create an "int", SvNV() to create a "float", and SvPV() to create a
328 string:
329 a = 9
331 a = 9.859600
332 a = Just Another Perl Hacker
333 In the example above, we've created a global variable to temporarily
335 store the computed value of our eval'ed expression. It is also
336 possible and in most cases a better strategy to fetch the return value
337 from eval_pv() instead. Example:
338 ...
340 SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
341 printf("%s\n", SvPV_nolen(val));
342 ...
343 This way, we avoid namespace pollution by not creating global variables
345 and we've simplified our code as well.
346 Performing Perl pattern matches and substitutions from your C program
348 The eval_sv() function lets us evaluate strings of Perl code, so we can
349 define some functions that use it to "specialize" in matches and
350 substitutions: match(), substitute(), and matches().
351 I32 match(SV *string, char *pattern);
353 Given a string and a pattern (e.g., "m/clasp/" or "/\b\w*\b/", which in
355 your C program might appear as "/\\b\\w*\\b/"), match() returns 1 if
356 the string matches the pattern and 0 otherwise.
357 int substitute(SV **string, char *pattern);
359 Given a pointer to an "SV" and an "=~" operation (e.g.,
361 "s/bob/robert/g" or "tr[A-Z][a-z]"), substitute() modifies the string
362 within the "SV" as according to the operation, returning the number of
363 substitutions made.
364 SSize_t matches(SV *string, char *pattern, AV **matches);
366 Given an "SV", a pattern, and a pointer to an empty "AV", matches()
368 evaluates "$string =~ $pattern" in a list context, and fills in matches
369 with the array elements, returning the number of matches found.
370 Here's a sample program, match.c, that uses all three (long lines have
372 been wrapped here):
373 #include <EXTERN.h>
375 #include <perl.h>
376 static PerlInterpreter *my_perl;
378 /** my_eval_sv(code, error_check)
380 ** kinda like eval_sv(),
381 ** but we pop the return value off the stack
382 **/
383 SV* my_eval_sv(SV *sv, I32 croak_on_error)
384 {
385 dSP;
386 SV* retval;
387 PUSHMARK(SP);
390 eval_sv(sv, G_SCALAR);
391 SPAGAIN;
393 retval = POPs;
394 PUTBACK;
395 if (croak_on_error && SvTRUE(ERRSV))
397 croak_sv(ERRSV);
398 return retval;
400 }
401 /** match(string, pattern)
403 **
404 ** Used for matches in a scalar context.
405 **
406 ** Returns 1 if the match was successful; 0 otherwise.
407 **/
408 I32 match(SV *string, char *pattern)
410 {
411 SV *command = newSV(0), *retval;
412 sv_setpvf(command, "my $string = '%s'; $string =~ %s",
414 SvPV_nolen(string), pattern);
415 retval = my_eval_sv(command, TRUE);
417 SvREFCNT_dec(command);
418 return SvIV(retval);
420 }
421 /** substitute(string, pattern)
423 **
424 ** Used for =~ operations that
425 ** modify their left-hand side (s/// and tr///)
426 **
427 ** Returns the number of successful matches, and
428 ** modifies the input string if there were any.
429 **/
430 I32 substitute(SV **string, char *pattern)
432 {
433 SV *command = newSV(0), *retval;
434 sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
436 SvPV_nolen(*string), pattern);
437 retval = my_eval_sv(command, TRUE);
439 SvREFCNT_dec(command);
440 *string = get_sv("string", 0);
442 return SvIV(retval);
443 }
444 /** matches(string, pattern, matches)
446 **
447 ** Used for matches in a list context.
448 **
449 ** Returns the number of matches,
450 ** and fills in **matches with the matching substrings
451 **/
452 SSize_t matches(SV *string, char *pattern, AV **match_list)
454 {
455 SV *command = newSV(0);
456 SSize_t num_matches;
457 sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
459 SvPV_nolen(string), pattern);
460 my_eval_sv(command, TRUE);
462 SvREFCNT_dec(command);
463 *match_list = get_av("array", 0);
465 num_matches = av_top_index(*match_list) + 1;
466 return num_matches;
468 }
469 main (int argc, char **argv, char **env)
471 {
472 char *embedding[] = { "", "-e", "0", NULL };
473 AV *match_list;
474 I32 num_matches, i;
475 SV *text;
476 PERL_SYS_INIT3(&argc,&argv,&env);
478 my_perl = perl_alloc();
479 perl_construct(my_perl);
480 perl_parse(my_perl, NULL, 3, embedding, NULL);
481 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
482 text = newSV(0);
484 sv_setpv(text, "When he is at a convenience store and the "
485 "bill comes to some amount like 76 cents, Maynard is "
486 "aware that there is something he *should* do, something "
487 "that will enable him to get back a quarter, but he has "
488 "no idea *what*. He fumbles through his red squeezey "
489 "changepurse and gives the boy three extra pennies with "
490 "his dollar, hoping that he might luck into the correct "
491 "amount. The boy gives him back two of his own pennies "
492 "and then the big shiny quarter that is his prize. "
493 "-RICHH");
494 if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
496 printf("match: Text contains the word 'quarter'.\n\n");
497 else
498 printf("match: Text doesn't contain the word 'quarter'.\n\n");
499 if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
501 printf("match: Text contains the word 'eighth'.\n\n");
502 else
503 printf("match: Text doesn't contain the word 'eighth'.\n\n");
504 /** Match all occurrences of /wi../ **/
506 num_matches = matches(text, "m/(wi..)/g", &match_list);
507 printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
508 for (i = 0; i < num_matches; i++)
510 printf("match: %s\n",
511 SvPV_nolen(*av_fetch(match_list, i, FALSE)));
512 printf("\n");
513 /** Remove all vowels from text **/
515 num_matches = substitute(&text, "s/[aeiou]//gi");
516 if (num_matches) {
517 printf("substitute: s/[aeiou]//gi...%lu substitutions made.\n",
518 (unsigned long)num_matches);
519 printf("Now text is: %s\n\n", SvPV_nolen(text));
520 }
521 /** Attempt a substitution **/
523 if (!substitute(&text, "s/Perl/C/")) {
524 printf("substitute: s/Perl/C...No substitution made.\n\n");
525 }
526 SvREFCNT_dec(text);
528 PL_perl_destruct_level = 1;
529 perl_destruct(my_perl);
530 perl_free(my_perl);
531 PERL_SYS_TERM();
532 }
533 which produces the output (again, long lines have been wrapped here)
535 match: Text contains the word 'quarter'.
537 match: Text doesn't contain the word 'eighth'.
539 matches: m/(wi..)/g found 2 matches...
541 match: will
542 match: with
543 substitute: s/[aeiou]//gi...139 substitutions made.
545 Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
546 Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt
547 bck qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd
548 gvs th by thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct
549 mnt. Th by gvs hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s
550 hs prz. -RCHH
551 substitute: s/Perl/C...No substitution made.
553 Fiddling with the Perl stack from your C program
555 When trying to explain stacks, most computer science textbooks mumble
556 something about spring-loaded columns of cafeteria plates: the last
557 thing you pushed on the stack is the first thing you pop off. That'll
558 do for our purposes: your C program will push some arguments onto "the
559 Perl stack", shut its eyes while some magic happens, and then pop the
560 results--the return value of your Perl subroutine--off the stack.
561 First you'll need to know how to convert between C types and Perl
563 types, with newSViv() and sv_setnv() and newAV() and all their friends.
564 They're described in perlguts and perlapi.
565 Then you'll need to know how to manipulate the Perl stack. That's
567 described in perlcall.
568 Once you've understood those, embedding Perl in C is easy.
570 Because C has no builtin function for integer exponentiation, let's
572 make Perl's ** operator available to it (this is less useful than it
573 sounds, because Perl implements ** with C's pow() function). First
574 I'll create a stub exponentiation function in power.pl:
575 sub expo {
577 my ($a, $b) = @_;
578 return $a ** $b;
579 }
580 Now I'll create a C program, power.c, with a function PerlPower() that
582 contains all the perlguts necessary to push the two arguments into
583 expo() and to pop the return value out. Take a deep breath...
584 #include <EXTERN.h>
586 #include <perl.h>
587 static PerlInterpreter *my_perl;
589 static void
591 PerlPower(int a, int b)
592 {
593 dSP; /* initialize stack pointer */
594 ENTER; /* everything created after here */
595 SAVETMPS; /* ...is a temporary variable. */
596 PUSHMARK(SP); /* remember the stack pointer */
597 XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
598 XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
599 PUTBACK; /* make local stack pointer global */
600 call_pv("expo", G_SCALAR); /* call the function */
601 SPAGAIN; /* refresh stack pointer */
602 /* pop the return value from stack */
603 printf ("%d to the %dth power is %d.\n", a, b, POPi);
604 PUTBACK;
605 FREETMPS; /* free that return value */
606 LEAVE; /* ...and the XPUSHed "mortal" args.*/
607 }
608 int main (int argc, char **argv, char **env)
610 {
611 char *my_argv[] = { "", "power.pl", NULL };
612 PERL_SYS_INIT3(&argc,&argv,&env);
614 my_perl = perl_alloc();
615 perl_construct( my_perl );
616 perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
618 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
619 perl_run(my_perl);
620 PerlPower(3, 4); /*** Compute 3 ** 4 ***/
622 perl_destruct(my_perl);
624 perl_free(my_perl);
625 PERL_SYS_TERM();
626 exit(EXIT_SUCCESS);
627 }
628 Compile and run:
630 % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
632 % power
634 3 to the 4th power is 81.
635 Maintaining a persistent interpreter
637 When developing interactive and/or potentially long-running
638 applications, it's a good idea to maintain a persistent interpreter
639 rather than allocating and constructing a new interpreter multiple
640 times. The major reason is speed: since Perl will only be loaded into
641 memory once.
642 However, you have to be more cautious with namespace and variable
644 scoping when using a persistent interpreter. In previous examples
645 we've been using global variables in the default package "main". We
646 knew exactly what code would be run, and assumed we could avoid
647 variable collisions and outrageous symbol table growth.
648 Let's say your application is a server that will occasionally run Perl
650 code from some arbitrary file. Your server has no way of knowing what
651 code it's going to run. Very dangerous.
652 If the file is pulled in by perl_parse(), compiled into a newly
654 constructed interpreter, and subsequently cleaned out with
655 perl_destruct() afterwards, you're shielded from most namespace
656 troubles.
657 One way to avoid namespace collisions in this scenario is to translate
659 the filename into a guaranteed-unique package name, and then compile
660 the code into that package using "eval" in perlfunc. In the example
661 below, each file will only be compiled once. Or, the application might
662 choose to clean out the symbol table associated with the file after
663 it's no longer needed. Using "call_argv" in perlapi, We'll call the
664 subroutine "Embed::Persistent::eval_file" which lives in the file
665 "persistent.pl" and pass the filename and boolean cleanup/cache flag as
666 arguments.
667 Note that the process will continue to grow for each file that it uses.
669 In addition, there might be "AUTOLOAD"ed subroutines and other
670 conditions that cause Perl's symbol table to grow. You might want to
671 add some logic that keeps track of the process size, or restarts itself
672 after a certain number of requests, to ensure that memory consumption
673 is minimized. You'll also want to scope your variables with "my" in
674 perlfunc whenever possible.
675 package Embed::Persistent;
677 #persistent.pl
678 use strict;
680 our %Cache;
681 use Symbol qw(delete_package);
682 sub valid_package_name {
684 my($string) = @_;
685 $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
686 # second pass only for words starting with a digit
687 $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;
688 # Dress it up as a real package name
690 $string =~ s|/|::|g;
691 return "Embed" . $string;
692 }
693 sub eval_file {
695 my($filename, $delete) = @_;
696 my $package = valid_package_name($filename);
697 my $mtime = -M $filename;
698 if(defined $Cache{$package}{mtime}
699 &&
700 $Cache{$package}{mtime} <= $mtime)
701 {
702 # we have compiled this subroutine already,
703 # it has not been updated on disk, nothing left to do
704 print STDERR "already compiled $package->handler\n";
705 }
706 else {
707 local *FH;
708 open FH, $filename or die "open '$filename' $!";
709 local($/) = undef;
710 my $sub = <FH>;
711 close FH;
712 #wrap the code into a subroutine inside our unique package
714 my $eval = qq{package $package; sub handler { $sub; }};
715 {
716 # hide our variables within this block
717 my($filename,$mtime,$package,$sub);
718 eval $eval;
719 }
720 die $@ if $@;
721 #cache it unless we're cleaning out each time
723 $Cache{$package}{mtime} = $mtime unless $delete;
724 }
725 eval {$package->handler;};
727 die $@ if $@;
728 delete_package($package) if $delete;
730 #take a look if you want
732 #print Devel::Symdump->rnew($package)->as_string, $/;
733 }
734 1;
736 __END__
738 /* persistent.c */
740 #include <EXTERN.h>
741 #include <perl.h>
742 /* 1 = clean out filename's symbol table after each request,
744 0 = don't
745 */
746 #ifndef DO_CLEAN
747 #define DO_CLEAN 0
748 #endif
749 #define BUFFER_SIZE 1024
751 static PerlInterpreter *my_perl = NULL;
753 int
755 main(int argc, char **argv, char **env)
756 {
757 char *embedding[] = { "", "persistent.pl", NULL };
758 char *args[] = { "", DO_CLEAN, NULL };
759 char filename[BUFFER_SIZE];
760 int failing, exitstatus;
761 PERL_SYS_INIT3(&argc,&argv,&env);
763 if((my_perl = perl_alloc()) == NULL) {
764 fprintf(stderr, "no memory!");
765 exit(EXIT_FAILURE);
766 }
767 perl_construct(my_perl);
768 PL_origalen = 1; /* don't let $0 assignment update the
770 proctitle or embedding[0] */
771 failing = perl_parse(my_perl, NULL, 2, embedding, NULL);
772 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
773 if(!failing)
774 failing = perl_run(my_perl);
775 if(!failing) {
776 while(printf("Enter file name: ") &&
777 fgets(filename, BUFFER_SIZE, stdin)) {
778 filename[strlen(filename)-1] = '\0'; /* strip \n */
780 /* call the subroutine,
781 passing it the filename as an argument */
782 args[0] = filename;
783 call_argv("Embed::Persistent::eval_file",
784 G_DISCARD | G_EVAL, args);
785 /* check $@ */
787 if(SvTRUE(ERRSV))
788 fprintf(stderr, "eval error: %s\n", SvPV_nolen(ERRSV));
789 }
790 }
791 PL_perl_destruct_level = 0;
793 exitstatus = perl_destruct(my_perl);
794 perl_free(my_perl);
795 PERL_SYS_TERM();
796 exit(exitstatus);
797 }
798 Now compile:
800 % cc -o persistent persistent.c \
802 `perl -MExtUtils::Embed -e ccopts -e ldopts`
803 Here's an example script file:
805 #test.pl
807 my $string = "hello";
808 foo($string);
809 sub foo {
811 print "foo says: @_\n";
812 }
813 Now run:
815 % persistent
817 Enter file name: test.pl
818 foo says: hello
819 Enter file name: test.pl
820 already compiled Embed::test_2epl->handler
821 foo says: hello
822 Enter file name: ^C
823 Execution of END blocks
825 Traditionally END blocks have been executed at the end of the perl_run.
826 This causes problems for applications that never call perl_run. Since
827 perl 5.7.2 you can specify "PL_exit_flags |= PERL_EXIT_DESTRUCT_END" to
828 get the new behaviour. This also enables the running of END blocks if
829 the perl_parse fails and "perl_destruct" will return the exit value.
830 $0 assignments
832 When a perl script assigns a value to $0 then the perl runtime will try
833 to make this value show up as the program name reported by "ps" by
834 updating the memory pointed to by the argv passed to perl_parse() and
835 also calling API functions like setproctitle() where available. This
836 behaviour might not be appropriate when embedding perl and can be
837 disabled by assigning the value 1 to the variable "PL_origalen" before
838 perl_parse() is called.
839 The persistent.c example above is for instance likely to segfault when
841 $0 is assigned to if the "PL_origalen = 1;" assignment is removed.
842 This because perl will try to write to the read only memory of the
843 "embedding[]" strings.
844 Maintaining multiple interpreter instances
846 Some rare applications will need to create more than one interpreter
847 during a session. Such an application might sporadically decide to
848 release any resources associated with the interpreter.
849 The program must take care to ensure that this takes place before the
851 next interpreter is constructed. By default, when perl is not built
852 with any special options, the global variable "PL_perl_destruct_level"
853 is set to 0, since extra cleaning isn't usually needed when a program
854 only ever creates a single interpreter in its entire lifetime.
855 Setting "PL_perl_destruct_level" to 1 makes everything squeaky clean:
857 while(1) {
859 ...
860 /* reset global variables here with PL_perl_destruct_level = 1 */
861 PL_perl_destruct_level = 1;
862 perl_construct(my_perl);
863 ...
864 /* clean and reset _everything_ during perl_destruct */
865 PL_perl_destruct_level = 1;
866 perl_destruct(my_perl);
867 perl_free(my_perl);
868 ...
869 /* let's go do it again! */
870 }
871 When perl_destruct() is called, the interpreter's syntax parse tree and
873 symbol tables are cleaned up, and global variables are reset. The
874 second assignment to "PL_perl_destruct_level" is needed because
875 perl_construct resets it to 0.
876 Now suppose we have more than one interpreter instance running at the
878 same time. This is feasible, but only if you used the Configure option
879 "-Dusemultiplicity" or the options "-Dusethreads -Duseithreads" when
880 building perl. By default, enabling one of these Configure options
881 sets the per-interpreter global variable "PL_perl_destruct_level" to 1,
882 so that thorough cleaning is automatic and interpreter variables are
883 initialized correctly. Even if you don't intend to run two or more
884 interpreters at the same time, but to run them sequentially, like in
885 the above example, it is recommended to build perl with the
886 "-Dusemultiplicity" option otherwise some interpreter variables may not
887 be initialized correctly between consecutive runs and your application
888 may crash.
889 See also "Thread-aware system interfaces" in perlxs.
891 Using "-Dusethreads -Duseithreads" rather than "-Dusemultiplicity" is
893 more appropriate if you intend to run multiple interpreters
894 concurrently in different threads, because it enables support for
895 linking in the thread libraries of your system with the interpreter.
896 Let's give it a try:
898 #include <EXTERN.h>
900 #include <perl.h>
901 /* we're going to embed two interpreters */
903 #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"
905 int main(int argc, char **argv, char **env)
907 {
908 PerlInterpreter *one_perl, *two_perl;
909 char *one_args[] = { "one_perl", SAY_HELLO, NULL };
910 char *two_args[] = { "two_perl", SAY_HELLO, NULL };
911 PERL_SYS_INIT3(&argc,&argv,&env);
913 one_perl = perl_alloc();
914 two_perl = perl_alloc();
915 PERL_SET_CONTEXT(one_perl);
917 perl_construct(one_perl);
918 PERL_SET_CONTEXT(two_perl);
919 perl_construct(two_perl);
920 PERL_SET_CONTEXT(one_perl);
922 perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
923 PERL_SET_CONTEXT(two_perl);
924 perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
925 PERL_SET_CONTEXT(one_perl);
927 perl_run(one_perl);
928 PERL_SET_CONTEXT(two_perl);
929 perl_run(two_perl);
930 PERL_SET_CONTEXT(one_perl);
932 perl_destruct(one_perl);
933 PERL_SET_CONTEXT(two_perl);
934 perl_destruct(two_perl);
935 PERL_SET_CONTEXT(one_perl);
937 perl_free(one_perl);
938 PERL_SET_CONTEXT(two_perl);
939 perl_free(two_perl);
940 PERL_SYS_TERM();
941 exit(EXIT_SUCCESS);
942 }
943 Note the calls to PERL_SET_CONTEXT(). These are necessary to
945 initialize the global state that tracks which interpreter is the
946 "current" one on the particular process or thread that may be running
947 it. It should always be used if you have more than one interpreter and
948 are making perl API calls on both interpreters in an interleaved
949 fashion.
950 PERL_SET_CONTEXT(interp) should also be called whenever "interp" is
952 used by a thread that did not create it (using either perl_alloc(), or
953 the more esoteric perl_clone()).
954 Compile as usual:
956 % cc -o multiplicity multiplicity.c \
958 `perl -MExtUtils::Embed -e ccopts -e ldopts`
959 Run it, Run it:
961 % multiplicity
963 Hi, I'm one_perl
964 Hi, I'm two_perl
965 Using Perl modules, which themselves use C libraries, from your C program
967 If you've played with the examples above and tried to embed a script
968 that use()s a Perl module (such as Socket) which itself uses a C or C++
969 library, this probably happened:
970 Can't load module Socket, dynamic loading not available in this perl.
972 (You may need to build a new perl executable which either supports
973 dynamic loading or has the Socket module statically linked into it.)
974 What's wrong?
976 Your interpreter doesn't know how to communicate with these extensions
978 on its own. A little glue will help. Up until now you've been calling
979 perl_parse(), handing it NULL for the second argument:
980 perl_parse(my_perl, NULL, argc, my_argv, NULL);
982 That's where the glue code can be inserted to create the initial
984 contact between Perl and linked C/C++ routines. Let's take a look some
985 pieces of perlmain.c to see how Perl does this:
986 static void xs_init (pTHX);
988 EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
990 EXTERN_C void boot_Socket (pTHX_ CV* cv);
991 EXTERN_C void
994 xs_init(pTHX)
995 {
996 char *file = __FILE__;
997 /* DynaLoader is a special case */
998 newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
999 newXS("Socket::bootstrap", boot_Socket, file);
1000 }
1001 Simply put: for each extension linked with your Perl executable
1003 (determined during its initial configuration on your computer or when
1004 adding a new extension), a Perl subroutine is created to incorporate
1005 the extension's routines. Normally, that subroutine is named
1006 Module::bootstrap() and is invoked when you say use Module. In turn,
1007 this hooks into an XSUB, boot_Module, which creates a Perl counterpart
1008 for each of the extension's XSUBs. Don't worry about this part; leave
1009 that to the xsubpp and extension authors. If your extension is
1010 dynamically loaded, DynaLoader creates Module::bootstrap() for you on
1011 the fly. In fact, if you have a working DynaLoader then there is
1012 rarely any need to link in any other extensions statically.
1013 Once you have this code, slap it into the second argument of
1015 perl_parse():
1016 perl_parse(my_perl, xs_init, argc, my_argv, NULL);
1018 Then compile:
1020 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
1022 % interp
1024 use Socket;
1025 use SomeDynamicallyLoadedModule;
1026 print "Now I can use extensions!\n"'
1028 ExtUtils::Embed can also automate writing the xs_init glue code.
1030 % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c
1032 % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
1033 % cc -c interp.c `perl -MExtUtils::Embed -e ccopts`
1034 % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
1035 Consult perlxs, perlguts, and perlapi for more details.
1037 Using embedded Perl with POSIX locales
1039 (See perllocale for information about these.) When a Perl interpreter
1040 normally starts up, it tells the system it wants to use the system's
1041 default locale. This is often, but not necessarily, the "C" or "POSIX"
1042 locale. Absent a "use locale" within the perl code, this mostly has no
1043 effect (but see "Not within the scope of "use locale"" in perllocale).
1044 Also, there is not a problem if the locale you want to use in your
1045 embedded perl is the same as the system default. However, this doesn't
1046 work if you have set up and want to use a locale that isn't the system
1047 default one. Starting in Perl v5.20, you can tell the embedded Perl
1048 interpreter that the locale is already properly set up, and to skip
1049 doing its own normal initialization. It skips if the environment
1050 variable "PERL_SKIP_LOCALE_INIT" is set (even if set to 0 or ""). A
1051 perl that has this capability will define the C pre-processor symbol
1052 "HAS_SKIP_LOCALE_INIT". This allows code that has to work with
1053 multiple Perl versions to do some sort of work-around when confronted
1054 with an earlier Perl.
1055 If your program is using the POSIX 2008 multi-thread locale
1057 functionality, you should switch into the global locale and set that up
1058 properly before starting the Perl interpreter. It will then properly
1059 switch back to using the thread-safe functions.
1060
1062 If you completely hide the short forms of the Perl public API, add
1063 -DPERL_NO_SHORT_NAMES to the compilation flags. This means that for
1064 example instead of writing
1065 warn("%d bottles of beer on the wall", bottlecount);
1067 you will have to write the explicit full form
1069 Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);
1071 (See "Background and MULTIPLICITY" in perlguts for the explanation of
1073 the "aTHX_". ) Hiding the short forms is very useful for avoiding all
1074 sorts of nasty (C preprocessor or otherwise) conflicts with other
1075 software packages (Perl defines about 2400 APIs with these short names,
1076 take or leave few hundred, so there certainly is room for conflict.)
1077
1079 You can sometimes write faster code in C, but you can always write code
1080 faster in Perl. Because you can use each from the other, combine them
1081 as you wish.
1082
1084 Jon Orwant <orwant@media.mit.edu> and Doug MacEachern
1085 <dougm@covalent.net>, with small contributions from Tim Bunce, Tom
1086 Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
1087 Zakharevich.
1088 Doug MacEachern has an article on embedding in Volume 1, Issue 4 of The
1090 Perl Journal ( <http://www.tpj.com/> ). Doug is also the developer of
1091 the most widely-used Perl embedding: the mod_perl system
1092 (perl.apache.org), which embeds Perl in the Apache web server. Oracle,
1093 Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl have used
1094 this model for Oracle, Netscape and Internet Information Server Perl
1095 plugins.
1096
1098 Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant.
1099 All Rights Reserved.
1100 This document may be distributed under the same terms as Perl itself.
1102perl v5.38.2 2023-11-30 PERLEMBED(1)