3 perlembed - how to embed perl in your C program
13 =item B<Use C from Perl?>
15 Read L<perlxstut>, L<perlxs>, L<h2xs>, L<perlguts>, and L<perlapi>.
17 =item B<Use a Unix program from Perl?>
19 Read about back-quotes and about C<system> and C<exec> in L<perlfunc>.
21 =item B<Use Perl from Perl?>
23 Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlfunc/require>
26 =item B<Use C from C?>
30 =item B<Use Perl from C?>
42 Compiling your C program
46 Adding a Perl interpreter to your C program
50 Calling a Perl subroutine from your C program
54 Evaluating a Perl statement from your C program
58 Performing Perl pattern matches and substitutions from your C program
62 Fiddling with the Perl stack from your C program
66 Maintaining a persistent interpreter
70 Maintaining multiple interpreter instances
74 Using Perl modules, which themselves use C libraries, from your C program
78 Embedding Perl under Win32
82 =head2 Compiling your C program
84 If you have trouble compiling the scripts in this documentation,
85 you're not alone. The cardinal rule: COMPILE THE PROGRAMS IN EXACTLY
86 THE SAME WAY THAT YOUR PERL WAS COMPILED. (Sorry for yelling.)
88 Also, every C program that uses Perl must link in the I<perl library>.
89 What's that, you ask? Perl is itself written in C; the perl library
90 is the collection of compiled C programs that were used to create your
91 perl executable (I</usr/bin/perl> or equivalent). (Corollary: you
92 can't use Perl from your C program unless Perl has been compiled on
93 your machine, or installed properly--that's why you shouldn't blithely
94 copy Perl executables from machine to machine without also copying the
97 When you use Perl from C, your C program will--usually--allocate,
98 "run", and deallocate a I<PerlInterpreter> object, which is defined by
101 If your copy of Perl is recent enough to contain this documentation
102 (version 5.002 or later), then the perl library (and I<EXTERN.h> and
103 I<perl.h>, which you'll also need) will reside in a directory
104 that looks like this:
106 /usr/local/lib/perl5/your_architecture_here/CORE
110 /usr/local/lib/perl5/CORE
112 or maybe something like
116 Execute this statement for a hint about where to find CORE:
118 perl -MConfig -e 'print $Config{archlib}'
120 Here's how you'd compile the example in the next section,
121 L<Adding a Perl interpreter to your C program>, on my Linux box:
123 % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
124 -I/usr/local/lib/perl5/i586-linux/5.003/CORE
125 -L/usr/local/lib/perl5/i586-linux/5.003/CORE
126 -o interp interp.c -lperl -lm
128 (That's all one line.) On my DEC Alpha running old 5.003_05, the
129 incantation is a bit different:
131 % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include
132 -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
133 -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib
134 -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm
136 How can you figure out what to add? Assuming your Perl is post-5.001,
137 execute a C<perl -V> command and pay special attention to the "cc" and
138 "ccflags" information.
140 You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) for
141 your machine: C<perl -MConfig -e 'print $Config{cc}'> will tell you what
144 You'll also have to choose the appropriate library directory
145 (I</usr/local/lib/...>) for your machine. If your compiler complains
146 that certain functions are undefined, or that it can't locate
147 I<-lperl>, then you need to change the path following the C<-L>. If it
148 complains that it can't find I<EXTERN.h> and I<perl.h>, you need to
149 change the path following the C<-I>.
151 You may have to add extra libraries as well. Which ones?
152 Perhaps those printed by
154 perl -MConfig -e 'print $Config{libs}'
156 Provided your perl binary was properly configured and installed the
157 B<ExtUtils::Embed> module will determine all of this information for
160 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
162 If the B<ExtUtils::Embed> module isn't part of your Perl distribution,
163 you can retrieve it from
164 http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/
165 (If this documentation came from your Perl distribution, then you're
166 running 5.004 or better and you already have it.)
168 The B<ExtUtils::Embed> kit on CPAN also contains all source code for
169 the examples in this document, tests, additional examples and other
170 information you may find useful.
172 =head2 Adding a Perl interpreter to your C program
174 In a sense, perl (the C program) is a good example of embedding Perl
175 (the language), so I'll demonstrate embedding with I<miniperlmain.c>,
176 included in the source distribution. Here's a bastardized, non-portable
177 version of I<miniperlmain.c> containing the essentials of embedding:
179 #include <EXTERN.h> /* from the Perl distribution */
180 #include <perl.h> /* from the Perl distribution */
182 static PerlInterpreter *my_perl; /*** The Perl interpreter ***/
184 int main(int argc, char **argv, char **env)
186 PERL_SYS_INIT3(&argc,&argv,&env);
187 my_perl = perl_alloc();
188 perl_construct(my_perl);
189 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
190 perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
192 perl_destruct(my_perl);
197 Notice that we don't use the C<env> pointer. Normally handed to
198 C<perl_parse> as its final argument, C<env> here is replaced by
199 C<NULL>, which means that the current environment will be used.
201 The macros PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific
202 tune up of the C runtime environment necessary to run Perl interpreters;
203 they should only be called once regardless of how many interpreters you
204 create or destroy. Call PERL_SYS_INIT3() before you create your first
205 interpreter, and PERL_SYS_TERM() after you free your last interpreter.
207 Since PERL_SYS_INIT3() may change C<env>, it may be more appropriate to
208 provide C<env> as an argument to perl_parse().
210 Now compile this program (I'll call it I<interp.c>) into an executable:
212 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
214 After a successful compilation, you'll be able to use I<interp> just
218 print "Pretty Good Perl \n";
219 print "10890 - 9801 is ", 10890 - 9801;
226 % interp -e 'printf("%x", 3735928559)'
229 You can also read and execute Perl statements from a file while in the
230 midst of your C program, by placing the filename in I<argv[1]> before
233 =head2 Calling a Perl subroutine from your C program
235 To call individual Perl subroutines, you can use any of the B<call_*>
236 functions documented in L<perlcall>.
237 In this example we'll use C<call_argv>.
239 That's shown below, in a program I'll call I<showtime.c>.
244 static PerlInterpreter *my_perl;
246 int main(int argc, char **argv, char **env)
248 char *args[] = { NULL };
249 PERL_SYS_INIT3(&argc,&argv,&env);
250 my_perl = perl_alloc();
251 perl_construct(my_perl);
253 perl_parse(my_perl, NULL, argc, argv, NULL);
254 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
256 /*** skipping perl_run() ***/
258 call_argv("showtime", G_DISCARD | G_NOARGS, args);
260 perl_destruct(my_perl);
265 where I<showtime> is a Perl subroutine that takes no arguments (that's the
266 I<G_NOARGS>) and for which I'll ignore the return value (that's the
267 I<G_DISCARD>). Those flags, and others, are discussed in L<perlcall>.
269 I'll define the I<showtime> subroutine in a file called I<showtime.pl>:
271 print "I shan't be printed.";
277 Simple enough. Now compile and run:
279 % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
281 % showtime showtime.pl
284 yielding the number of seconds that elapsed between January 1, 1970
285 (the beginning of the Unix epoch), and the moment I began writing this
288 In this particular case we don't have to call I<perl_run>, as we set
289 the PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
292 If you want to pass arguments to the Perl subroutine, you can add
293 strings to the C<NULL>-terminated C<args> list passed to
294 I<call_argv>. For other data types, or to examine return values,
295 you'll need to manipulate the Perl stack. That's demonstrated in
296 L<Fiddling with the Perl stack from your C program>.
298 =head2 Evaluating a Perl statement from your C program
300 Perl provides two API functions to evaluate pieces of Perl code.
301 These are L<perlapi/eval_sv> and L<perlapi/eval_pv>.
303 Arguably, these are the only routines you'll ever need to execute
304 snippets of Perl code from within your C program. Your code can be as
305 long as you wish; it can contain multiple statements; it can employ
306 L<perlfunc/use>, L<perlfunc/require>, and L<perlfunc/do> to
307 include external Perl files.
309 I<eval_pv> lets us evaluate individual Perl strings, and then
310 extract variables for coercion into C types. The following program,
311 I<string.c>, executes three Perl strings, extracting an C<int> from
312 the first, a C<float> from the second, and a C<char *> from the third.
317 static PerlInterpreter *my_perl;
319 main (int argc, char **argv, char **env)
321 char *embedding[] = { "", "-e", "0" };
323 PERL_SYS_INIT3(&argc,&argv,&env);
324 my_perl = perl_alloc();
325 perl_construct( my_perl );
327 perl_parse(my_perl, NULL, 3, embedding, NULL);
328 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
331 /** Treat $a as an integer **/
332 eval_pv("$a = 3; $a **= 2", TRUE);
333 printf("a = %d\n", SvIV(get_sv("a", 0)));
335 /** Treat $a as a float **/
336 eval_pv("$a = 3.14; $a **= 2", TRUE);
337 printf("a = %f\n", SvNV(get_sv("a", 0)));
339 /** Treat $a as a string **/
340 eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
341 printf("a = %s\n", SvPV_nolen(get_sv("a", 0)));
343 perl_destruct(my_perl);
348 All of those strange functions with I<sv> in their names help convert Perl scalars to C types. They're described in L<perlguts> and L<perlapi>.
350 If you compile and run I<string.c>, you'll see the results of using
351 I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
352 I<SvPV()> to create a string:
356 a = Just Another Perl Hacker
358 In the example above, we've created a global variable to temporarily
359 store the computed value of our eval'ed expression. It is also
360 possible and in most cases a better strategy to fetch the return value
361 from I<eval_pv()> instead. Example:
364 SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
365 printf("%s\n", SvPV_nolen(val));
368 This way, we avoid namespace pollution by not creating global
369 variables and we've simplified our code as well.
371 =head2 Performing Perl pattern matches and substitutions from your C program
373 The I<eval_sv()> function lets us evaluate strings of Perl code, so we can
374 define some functions that use it to "specialize" in matches and
375 substitutions: I<match()>, I<substitute()>, and I<matches()>.
377 I32 match(SV *string, char *pattern);
379 Given a string and a pattern (e.g., C<m/clasp/> or C</\b\w*\b/>, which
380 in your C program might appear as "/\\b\\w*\\b/"), match()
381 returns 1 if the string matches the pattern and 0 otherwise.
383 int substitute(SV **string, char *pattern);
385 Given a pointer to an C<SV> and an C<=~> operation (e.g.,
386 C<s/bob/robert/g> or C<tr[A-Z][a-z]>), substitute() modifies the string
387 within the C<SV> as according to the operation, returning the number of substitutions
390 int matches(SV *string, char *pattern, AV **matches);
392 Given an C<SV>, a pattern, and a pointer to an empty C<AV>,
393 matches() evaluates C<$string =~ $pattern> in a list context, and
394 fills in I<matches> with the array elements, returning the number of matches found.
396 Here's a sample program, I<match.c>, that uses all three (long lines have
402 static PerlInterpreter *my_perl;
404 /** my_eval_sv(code, error_check)
405 ** kinda like eval_sv(),
406 ** but we pop the return value off the stack
408 SV* my_eval_sv(SV *sv, I32 croak_on_error)
415 eval_sv(sv, G_SCALAR);
421 if (croak_on_error && SvTRUE(ERRSV))
422 croak(SvPVx_nolen(ERRSV));
427 /** match(string, pattern)
429 ** Used for matches in a scalar context.
431 ** Returns 1 if the match was successful; 0 otherwise.
434 I32 match(SV *string, char *pattern)
436 SV *command = newSV(0), *retval;
438 sv_setpvf(command, "my $string = '%s'; $string =~ %s",
439 SvPV_nolen(string), pattern);
441 retval = my_eval_sv(command, TRUE);
442 SvREFCNT_dec(command);
447 /** substitute(string, pattern)
449 ** Used for =~ operations that modify their left-hand side (s/// and tr///)
451 ** Returns the number of successful matches, and
452 ** modifies the input string if there were any.
455 I32 substitute(SV **string, char *pattern)
457 SV *command = newSV(0), *retval;
459 sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
460 SvPV_nolen(*string), pattern);
462 retval = my_eval_sv(command, TRUE);
463 SvREFCNT_dec(command);
465 *string = get_sv("string", 0);
469 /** matches(string, pattern, matches)
471 ** Used for matches in a list context.
473 ** Returns the number of matches,
474 ** and fills in **matches with the matching substrings
477 I32 matches(SV *string, char *pattern, AV **match_list)
479 SV *command = newSV(0);
482 sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
483 SvPV_nolen(string), pattern);
485 my_eval_sv(command, TRUE);
486 SvREFCNT_dec(command);
488 *match_list = get_av("array", 0);
489 num_matches = av_len(*match_list) + 1; /** assume $[ is 0 **/
494 main (int argc, char **argv, char **env)
496 char *embedding[] = { "", "-e", "0" };
501 PERL_SYS_INIT3(&argc,&argv,&env);
502 my_perl = perl_alloc();
503 perl_construct(my_perl);
504 perl_parse(my_perl, NULL, 3, embedding, NULL);
505 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
508 sv_setpv(text, "When he is at a convenience store and the "
509 "bill comes to some amount like 76 cents, Maynard is "
510 "aware that there is something he *should* do, something "
511 "that will enable him to get back a quarter, but he has "
512 "no idea *what*. He fumbles through his red squeezey "
513 "changepurse and gives the boy three extra pennies with "
514 "his dollar, hoping that he might luck into the correct "
515 "amount. The boy gives him back two of his own pennies "
516 "and then the big shiny quarter that is his prize. "
519 if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
520 printf("match: Text contains the word 'quarter'.\n\n");
522 printf("match: Text doesn't contain the word 'quarter'.\n\n");
524 if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
525 printf("match: Text contains the word 'eighth'.\n\n");
527 printf("match: Text doesn't contain the word 'eighth'.\n\n");
529 /** Match all occurrences of /wi../ **/
530 num_matches = matches(text, "m/(wi..)/g", &match_list);
531 printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
533 for (i = 0; i < num_matches; i++)
534 printf("match: %s\n", SvPV_nolen(*av_fetch(match_list, i, FALSE)));
537 /** Remove all vowels from text **/
538 num_matches = substitute(&text, "s/[aeiou]//gi");
540 printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
542 printf("Now text is: %s\n\n", SvPV_nolen(text));
545 /** Attempt a substitution **/
546 if (!substitute(&text, "s/Perl/C/")) {
547 printf("substitute: s/Perl/C...No substitution made.\n\n");
551 PL_perl_destruct_level = 1;
552 perl_destruct(my_perl);
557 which produces the output (again, long lines have been wrapped here)
559 match: Text contains the word 'quarter'.
561 match: Text doesn't contain the word 'eighth'.
563 matches: m/(wi..)/g found 2 matches...
567 substitute: s/[aeiou]//gi...139 substitutions made.
568 Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
569 Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck
570 qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd gvs th by
571 thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt. Th by gvs
572 hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH
574 substitute: s/Perl/C...No substitution made.
576 =head2 Fiddling with the Perl stack from your C program
578 When trying to explain stacks, most computer science textbooks mumble
579 something about spring-loaded columns of cafeteria plates: the last
580 thing you pushed on the stack is the first thing you pop off. That'll
581 do for our purposes: your C program will push some arguments onto "the Perl
582 stack", shut its eyes while some magic happens, and then pop the
583 results--the return value of your Perl subroutine--off the stack.
585 First you'll need to know how to convert between C types and Perl
586 types, with newSViv() and sv_setnv() and newAV() and all their
587 friends. They're described in L<perlguts> and L<perlapi>.
589 Then you'll need to know how to manipulate the Perl stack. That's
590 described in L<perlcall>.
592 Once you've understood those, embedding Perl in C is easy.
594 Because C has no builtin function for integer exponentiation, let's
595 make Perl's ** operator available to it (this is less useful than it
596 sounds, because Perl implements ** with C's I<pow()> function). First
597 I'll create a stub exponentiation function in I<power.pl>:
604 Now I'll create a C program, I<power.c>, with a function
605 I<PerlPower()> that contains all the perlguts necessary to push the
606 two arguments into I<expo()> and to pop the return value out. Take a
612 static PerlInterpreter *my_perl;
615 PerlPower(int a, int b)
617 dSP; /* initialize stack pointer */
618 ENTER; /* everything created after here */
619 SAVETMPS; /* ...is a temporary variable. */
620 PUSHMARK(SP); /* remember the stack pointer */
621 XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
622 XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
623 PUTBACK; /* make local stack pointer global */
624 call_pv("expo", G_SCALAR); /* call the function */
625 SPAGAIN; /* refresh stack pointer */
626 /* pop the return value from stack */
627 printf ("%d to the %dth power is %d.\n", a, b, POPi);
629 FREETMPS; /* free that return value */
630 LEAVE; /* ...and the XPUSHed "mortal" args.*/
633 int main (int argc, char **argv, char **env)
635 char *my_argv[] = { "", "power.pl" };
637 PERL_SYS_INIT3(&argc,&argv,&env);
638 my_perl = perl_alloc();
639 perl_construct( my_perl );
641 perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
642 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
645 PerlPower(3, 4); /*** Compute 3 ** 4 ***/
647 perl_destruct(my_perl);
656 % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
659 3 to the 4th power is 81.
661 =head2 Maintaining a persistent interpreter
663 When developing interactive and/or potentially long-running
664 applications, it's a good idea to maintain a persistent interpreter
665 rather than allocating and constructing a new interpreter multiple
666 times. The major reason is speed: since Perl will only be loaded into
669 However, you have to be more cautious with namespace and variable
670 scoping when using a persistent interpreter. In previous examples
671 we've been using global variables in the default package C<main>. We
672 knew exactly what code would be run, and assumed we could avoid
673 variable collisions and outrageous symbol table growth.
675 Let's say your application is a server that will occasionally run Perl
676 code from some arbitrary file. Your server has no way of knowing what
677 code it's going to run. Very dangerous.
679 If the file is pulled in by C<perl_parse()>, compiled into a newly
680 constructed interpreter, and subsequently cleaned out with
681 C<perl_destruct()> afterwards, you're shielded from most namespace
684 One way to avoid namespace collisions in this scenario is to translate
685 the filename into a guaranteed-unique package name, and then compile
686 the code into that package using L<perlfunc/eval>. In the example
687 below, each file will only be compiled once. Or, the application
688 might choose to clean out the symbol table associated with the file
689 after it's no longer needed. Using L<perlapi/call_argv>, We'll
690 call the subroutine C<Embed::Persistent::eval_file> which lives in the
691 file C<persistent.pl> and pass the filename and boolean cleanup/cache
694 Note that the process will continue to grow for each file that it
695 uses. In addition, there might be C<AUTOLOAD>ed subroutines and other
696 conditions that cause Perl's symbol table to grow. You might want to
697 add some logic that keeps track of the process size, or restarts
698 itself after a certain number of requests, to ensure that memory
699 consumption is minimized. You'll also want to scope your variables
700 with L<perlfunc/my> whenever possible.
703 package Embed::Persistent;
708 use Symbol qw(delete_package);
710 sub valid_package_name {
712 $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
713 # second pass only for words starting with a digit
714 $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;
716 # Dress it up as a real package name
718 return "Embed" . $string;
722 my($filename, $delete) = @_;
723 my $package = valid_package_name($filename);
724 my $mtime = -M $filename;
725 if(defined $Cache{$package}{mtime}
727 $Cache{$package}{mtime} <= $mtime)
729 # we have compiled this subroutine already,
730 # it has not been updated on disk, nothing left to do
731 print STDERR "already compiled $package->handler\n";
735 open FH, $filename or die "open '$filename' $!";
740 #wrap the code into a subroutine inside our unique package
741 my $eval = qq{package $package; sub handler { $sub; }};
743 # hide our variables within this block
744 my($filename,$mtime,$package,$sub);
749 #cache it unless we're cleaning out each time
750 $Cache{$package}{mtime} = $mtime unless $delete;
753 eval {$package->handler;};
756 delete_package($package) if $delete;
758 #take a look if you want
759 #print Devel::Symdump->rnew($package)->as_string, $/;
770 /* 1 = clean out filename's symbol table after each request, 0 = don't */
775 #define BUFFER_SIZE 1024
777 static PerlInterpreter *my_perl = NULL;
780 main(int argc, char **argv, char **env)
782 char *embedding[] = { "", "persistent.pl" };
783 char *args[] = { "", DO_CLEAN, NULL };
784 char filename[BUFFER_SIZE];
787 PERL_SYS_INIT3(&argc,&argv,&env);
788 if((my_perl = perl_alloc()) == NULL) {
789 fprintf(stderr, "no memory!");
792 perl_construct(my_perl);
794 PL_origalen = 1; /* don't let $0 assignment update the proctitle or embedding[0] */
795 exitstatus = perl_parse(my_perl, NULL, 2, embedding, NULL);
796 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
798 exitstatus = perl_run(my_perl);
800 while(printf("Enter file name: ") &&
801 fgets(filename, BUFFER_SIZE, stdin)) {
803 filename[strlen(filename)-1] = '\0'; /* strip \n */
804 /* call the subroutine, passing it the filename as an argument */
806 call_argv("Embed::Persistent::eval_file",
807 G_DISCARD | G_EVAL, args);
811 fprintf(stderr, "eval error: %s\n", SvPV_nolen(ERRSV));
815 PL_perl_destruct_level = 0;
816 perl_destruct(my_perl);
824 % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
826 Here's an example script file:
829 my $string = "hello";
833 print "foo says: @_\n";
839 Enter file name: test.pl
841 Enter file name: test.pl
842 already compiled Embed::test_2epl->handler
846 =head2 Execution of END blocks
848 Traditionally END blocks have been executed at the end of the perl_run.
849 This causes problems for applications that never call perl_run. Since
850 perl 5.7.2 you can specify C<PL_exit_flags |= PERL_EXIT_DESTRUCT_END>
851 to get the new behaviour. This also enables the running of END blocks if
852 the perl_parse fails and C<perl_destruct> will return the exit value.
854 =head2 $0 assignments
856 When a perl script assigns a value to $0 then the perl runtime will
857 try to make this value show up as the program name reported by "ps" by
858 updating the memory pointed to by the argv passed to perl_parse() and
859 also calling API functions like setproctitle() where available. This
860 behaviour might not be appropriate when embedding perl and can be
861 disabled by assigning the value C<1> to the variable C<PL_origalen>
862 before perl_parse() is called.
864 The F<persistent.c> example above is for instance likely to segfault
865 when $0 is assigned to if the C<PL_origalen = 1;> assignment is
866 removed. This because perl will try to write to the read only memory
867 of the C<embedding[]> strings.
869 =head2 Maintaining multiple interpreter instances
871 Some rare applications will need to create more than one interpreter
872 during a session. Such an application might sporadically decide to
873 release any resources associated with the interpreter.
875 The program must take care to ensure that this takes place I<before>
876 the next interpreter is constructed. By default, when perl is not
877 built with any special options, the global variable
878 C<PL_perl_destruct_level> is set to C<0>, since extra cleaning isn't
879 usually needed when a program only ever creates a single interpreter
880 in its entire lifetime.
882 Setting C<PL_perl_destruct_level> to C<1> makes everything squeaky clean:
886 /* reset global variables here with PL_perl_destruct_level = 1 */
887 PL_perl_destruct_level = 1;
888 perl_construct(my_perl);
890 /* clean and reset _everything_ during perl_destruct */
891 PL_perl_destruct_level = 1;
892 perl_destruct(my_perl);
895 /* let's go do it again! */
898 When I<perl_destruct()> is called, the interpreter's syntax parse tree
899 and symbol tables are cleaned up, and global variables are reset. The
900 second assignment to C<PL_perl_destruct_level> is needed because
901 perl_construct resets it to C<0>.
903 Now suppose we have more than one interpreter instance running at the
904 same time. This is feasible, but only if you used the Configure option
905 C<-Dusemultiplicity> or the options C<-Dusethreads -Duseithreads> when
906 building perl. By default, enabling one of these Configure options
907 sets the per-interpreter global variable C<PL_perl_destruct_level> to
908 C<1>, so that thorough cleaning is automatic and interpreter variables
909 are initialized correctly. Even if you don't intend to run two or
910 more interpreters at the same time, but to run them sequentially, like
911 in the above example, it is recommended to build perl with the
912 C<-Dusemultiplicity> option otherwise some interpreter variables may
913 not be initialized correctly between consecutive runs and your
914 application may crash.
916 See also L<perlxs/Thread-aware system interfaces>.
918 Using C<-Dusethreads -Duseithreads> rather than C<-Dusemultiplicity>
919 is more appropriate if you intend to run multiple interpreters
920 concurrently in different threads, because it enables support for
921 linking in the thread libraries of your system with the interpreter.
929 /* we're going to embed two interpreters */
930 /* we're going to embed two interpreters */
932 #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"
934 int main(int argc, char **argv, char **env)
936 PerlInterpreter *one_perl, *two_perl;
937 char *one_args[] = { "one_perl", SAY_HELLO };
938 char *two_args[] = { "two_perl", SAY_HELLO };
940 PERL_SYS_INIT3(&argc,&argv,&env);
941 one_perl = perl_alloc();
942 two_perl = perl_alloc();
944 PERL_SET_CONTEXT(one_perl);
945 perl_construct(one_perl);
946 PERL_SET_CONTEXT(two_perl);
947 perl_construct(two_perl);
949 PERL_SET_CONTEXT(one_perl);
950 perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
951 PERL_SET_CONTEXT(two_perl);
952 perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
954 PERL_SET_CONTEXT(one_perl);
956 PERL_SET_CONTEXT(two_perl);
959 PERL_SET_CONTEXT(one_perl);
960 perl_destruct(one_perl);
961 PERL_SET_CONTEXT(two_perl);
962 perl_destruct(two_perl);
964 PERL_SET_CONTEXT(one_perl);
966 PERL_SET_CONTEXT(two_perl);
971 Note the calls to PERL_SET_CONTEXT(). These are necessary to initialize
972 the global state that tracks which interpreter is the "current" one on
973 the particular process or thread that may be running it. It should
974 always be used if you have more than one interpreter and are making
975 perl API calls on both interpreters in an interleaved fashion.
977 PERL_SET_CONTEXT(interp) should also be called whenever C<interp> is
978 used by a thread that did not create it (using either perl_alloc(), or
979 the more esoteric perl_clone()).
983 % cc -o multiplicity multiplicity.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
991 =head2 Using Perl modules, which themselves use C libraries, from your C program
993 If you've played with the examples above and tried to embed a script
994 that I<use()>s a Perl module (such as I<Socket>) which itself uses a C or C++ library,
995 this probably happened:
998 Can't load module Socket, dynamic loading not available in this perl.
999 (You may need to build a new perl executable which either supports
1000 dynamic loading or has the Socket module statically linked into it.)
1005 Your interpreter doesn't know how to communicate with these extensions
1006 on its own. A little glue will help. Up until now you've been
1007 calling I<perl_parse()>, handing it NULL for the second argument:
1009 perl_parse(my_perl, NULL, argc, my_argv, NULL);
1011 That's where the glue code can be inserted to create the initial contact between
1012 Perl and linked C/C++ routines. Let's take a look some pieces of I<perlmain.c>
1013 to see how Perl does this:
1015 static void xs_init (pTHX);
1017 EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
1018 EXTERN_C void boot_Socket (pTHX_ CV* cv);
1024 char *file = __FILE__;
1025 /* DynaLoader is a special case */
1026 newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
1027 newXS("Socket::bootstrap", boot_Socket, file);
1030 Simply put: for each extension linked with your Perl executable
1031 (determined during its initial configuration on your
1032 computer or when adding a new extension),
1033 a Perl subroutine is created to incorporate the extension's
1034 routines. Normally, that subroutine is named
1035 I<Module::bootstrap()> and is invoked when you say I<use Module>. In
1036 turn, this hooks into an XSUB, I<boot_Module>, which creates a Perl
1037 counterpart for each of the extension's XSUBs. Don't worry about this
1038 part; leave that to the I<xsubpp> and extension authors. If your
1039 extension is dynamically loaded, DynaLoader creates I<Module::bootstrap()>
1040 for you on the fly. In fact, if you have a working DynaLoader then there
1041 is rarely any need to link in any other extensions statically.
1044 Once you have this code, slap it into the second argument of I<perl_parse()>:
1047 perl_parse(my_perl, xs_init, argc, my_argv, NULL);
1052 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
1056 use SomeDynamicallyLoadedModule;
1058 print "Now I can use extensions!\n"'
1060 B<ExtUtils::Embed> can also automate writing the I<xs_init> glue code.
1062 % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c
1063 % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
1064 % cc -c interp.c `perl -MExtUtils::Embed -e ccopts`
1065 % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
1067 Consult L<perlxs>, L<perlguts>, and L<perlapi> for more details.
1069 =head1 Embedding Perl under Win32
1071 In general, all of the source code shown here should work unmodified under
1074 However, there are some caveats about the command-line examples shown.
1075 For starters, backticks won't work under the Win32 native command shell.
1076 The ExtUtils::Embed kit on CPAN ships with a script called
1077 B<genmake>, which generates a simple makefile to build a program from
1078 a single C source file. It can be used like this:
1080 C:\ExtUtils-Embed\eg> perl genmake interp.c
1081 C:\ExtUtils-Embed\eg> nmake
1082 C:\ExtUtils-Embed\eg> interp -e "print qq{I'm embedded in Win32!\n}"
1084 You may wish to use a more robust environment such as the Microsoft
1085 Developer Studio. In this case, run this to generate perlxsi.c:
1087 perl -MExtUtils::Embed -e xsinit
1089 Create a new project and Insert -> Files into Project: perlxsi.c,
1090 perl.lib, and your own source files, e.g. interp.c. Typically you'll
1091 find perl.lib in B<C:\perl\lib\CORE>, if not, you should see the
1092 B<CORE> directory relative to C<perl -V:archlib>. The studio will
1093 also need this path so it knows where to find Perl include files.
1094 This path can be added via the Tools -> Options -> Directories menu.
1095 Finally, select Build -> Build interp.exe and you're ready to go.
1099 If you completely hide the short forms forms of the Perl public API,
1100 add -DPERL_NO_SHORT_NAMES to the compilation flags. This means that
1101 for example instead of writing
1103 warn("%d bottles of beer on the wall", bottlecount);
1105 you will have to write the explicit full form
1107 Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);
1109 (See L<perlguts/Background and PERL_IMPLICIT_CONTEXT for the explanation
1110 of the C<aTHX_>.> ) Hiding the short forms is very useful for avoiding
1111 all sorts of nasty (C preprocessor or otherwise) conflicts with other
1112 software packages (Perl defines about 2400 APIs with these short names,
1113 take or leave few hundred, so there certainly is room for conflict.)
1117 You can sometimes I<write faster code> in C, but
1118 you can always I<write code faster> in Perl. Because you can use
1119 each from the other, combine them as you wish.
1124 Jon Orwant <F<orwant@media.mit.edu>> and Doug MacEachern
1125 <F<dougm@covalent.net>>, with small contributions from Tim Bunce, Tom
1126 Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
1129 Doug MacEachern has an article on embedding in Volume 1, Issue 4 of
1130 The Perl Journal ( http://www.tpj.com/ ). Doug is also the developer of the
1131 most widely-used Perl embedding: the mod_perl system
1132 (perl.apache.org), which embeds Perl in the Apache web server.
1133 Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl
1134 have used this model for Oracle, Netscape and Internet Information
1135 Server Perl plugins.
1139 Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All
1142 Permission is granted to make and distribute verbatim copies of this
1143 documentation provided the copyright notice and this permission notice are
1144 preserved on all copies.
1146 Permission is granted to copy and distribute modified versions of this
1147 documentation under the conditions for verbatim copying, provided also
1148 that they are marked clearly as modified versions, that the authors'
1149 names and title are unchanged (though subtitles and additional
1150 authors' names may be added), and that the entire resulting derived
1151 work is distributed under the terms of a permission notice identical
1154 Permission is granted to copy and distribute translations of this
1155 documentation into another language, under the above conditions for