This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update to perl.pod suggested
[perl5.git] / pod / perlembed.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
cb1a09d0 3perlembed - how to embed perl in your C program
a0d0e21e
LW
4
5=head1 DESCRIPTION
6
cb1a09d0
AD
7=head2 PREAMBLE
8
9Do you want to:
10
11=over 5
12
96dbc785 13=item B<Use C from Perl?>
cb1a09d0
AD
14
15Read L<perlcall> and L<perlxs>.
16
96dbc785 17=item B<Use a UNIX program from Perl?>
cb1a09d0 18
5f05dabc 19Read about back-quotes and about C<system> and C<exec> in L<perlfunc>.
cb1a09d0 20
96dbc785 21=item B<Use Perl from Perl?>
cb1a09d0 22
55497cff
PP
23Read about C<do> and C<eval> in L<perlfunc/do> and L<perlfunc/eval> and C<use>
24and C<require> in L<perlmod> and L<perlfunc/require>, L<perlfunc/use>.
cb1a09d0 25
96dbc785 26=item B<Use C from C?>
cb1a09d0
AD
27
28Rethink your design.
29
96dbc785 30=item B<Use Perl from C?>
cb1a09d0
AD
31
32Read on...
33
34=back
35
36=head2 ROADMAP
37
38L<Compiling your C program>
39
a6006777 40There's one example in each of the eight sections:
cb1a09d0
AD
41
42L<Adding a Perl interpreter to your C program>
43
44L<Calling a Perl subroutine from your C program>
45
46L<Evaluating a Perl statement from your C program>
47
48L<Performing Perl pattern matches and substitutions from your C program>
49
50L<Fiddling with the Perl stack from your C program>
51
a6006777
PP
52L<Maintaining a persistent interpreter>
53
8ebc5c01
PP
54L<Maintaining multiple interpreter instances>
55
96dbc785
PP
56L<Using Perl modules, which themselves use C libraries, from your C program>
57
cb1a09d0
AD
58This documentation is UNIX specific.
59
60=head2 Compiling your C program
61
96dbc785 62Every C program that uses Perl must link in the I<perl library>.
cb1a09d0
AD
63
64What's that, you ask? Perl is itself written in C; the perl library
65is the collection of compiled C programs that were used to create your
66perl executable (I</usr/bin/perl> or equivalent). (Corollary: you
67can't use Perl from your C program unless Perl has been compiled on
68your machine, or installed properly--that's why you shouldn't blithely
69copy Perl executables from machine to machine without also copying the
70I<lib> directory.)
71
72Your C program will--usually--allocate, "run", and deallocate a
96dbc785 73I<PerlInterpreter> object, which is defined in the perl library.
cb1a09d0
AD
74
75If your copy of Perl is recent enough to contain this documentation
a6006777 76(version 5.002 or later), then the perl library (and I<EXTERN.h> and
cb1a09d0
AD
77I<perl.h>, which you'll also need) will
78reside in a directory resembling this:
79
80 /usr/local/lib/perl5/your_architecture_here/CORE
81
82or perhaps just
83
84 /usr/local/lib/perl5/CORE
85
86or maybe something like
87
88 /usr/opt/perl5/CORE
89
90Execute this statement for a hint about where to find CORE:
91
96dbc785 92 perl -MConfig -e 'print $Config{archlib}'
cb1a09d0
AD
93
94Here's how you might compile the example in the next section,
95L<Adding a Perl interpreter to your C program>,
96on a DEC Alpha running the OSF operating system:
97
96dbc785 98 % cc -o interp interp.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE
cb1a09d0
AD
99 -I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
100
101You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) and
102library directory (I</usr/local/lib/...>) for your machine. If your
103compiler complains that certain functions are undefined, or that it
104can't locate I<-lperl>, then you need to change the path following the
105-L. If it complains that it can't find I<EXTERN.h> or I<perl.h>, you need
96dbc785 106to change the path following the -I.
cb1a09d0
AD
107
108You may have to add extra libraries as well. Which ones?
96dbc785
PP
109Perhaps those printed by
110
111 perl -MConfig -e 'print $Config{libs}'
112
113We strongly recommend you use the B<ExtUtils::Embed> module to determine
114all of this information for you:
115
116 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
117
118
119If the B<ExtUtils::Embed> module is not part of your perl kit's
120distribution you can retrieve it from:
121http://www.perl.com/cgi-bin/cpan_mod?module=ExtUtils::Embed.
cb1a09d0 122
cb1a09d0
AD
123
124=head2 Adding a Perl interpreter to your C program
125
126In a sense, perl (the C program) is a good example of embedding Perl
127(the language), so I'll demonstrate embedding with I<miniperlmain.c>,
128from the source distribution. Here's a bastardized, non-portable version of
129I<miniperlmain.c> containing the essentials of embedding:
130
cb1a09d0
AD
131 #include <EXTERN.h> /* from the Perl distribution */
132 #include <perl.h> /* from the Perl distribution */
96dbc785 133
cb1a09d0 134 static PerlInterpreter *my_perl; /*** The Perl interpreter ***/
96dbc785 135
c07a80fd 136 int main(int argc, char **argv, char **env)
cb1a09d0
AD
137 {
138 my_perl = perl_alloc();
139 perl_construct(my_perl);
96dbc785 140 perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
cb1a09d0
AD
141 perl_run(my_perl);
142 perl_destruct(my_perl);
143 perl_free(my_perl);
144 }
145
96dbc785
PP
146Note that we do not use the C<env> pointer here or in any of the
147following examples.
5f05dabc 148Normally handed to C<perl_parse> as its final argument,
96dbc785
PP
149we hand it a B<NULL> instead, in which case the current environment
150is used.
151
cb1a09d0
AD
152Now compile this program (I'll call it I<interp.c>) into an executable:
153
96dbc785 154 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
cb1a09d0
AD
155
156After a successful compilation, you'll be able to use I<interp> just
157like perl itself:
158
159 % interp
160 print "Pretty Good Perl \n";
161 print "10890 - 9801 is ", 10890 - 9801;
162 <CTRL-D>
163 Pretty Good Perl
164 10890 - 9801 is 1089
165
166or
167
168 % interp -e 'printf("%x", 3735928559)'
169 deadbeef
170
171You can also read and execute Perl statements from a file while in the
172midst of your C program, by placing the filename in I<argv[1]> before
96dbc785 173calling I<perl_run()>.
cb1a09d0
AD
174
175=head2 Calling a Perl subroutine from your C program
176
8ebc5c01
PP
177To call individual Perl subroutines, you can use any of the B<perl_call_*>
178functions documented in the L<perlcall> man page.
179In this example we'll use I<perl_call_argv>.
cb1a09d0
AD
180
181That's shown below, in a program I'll call I<showtime.c>.
182
cb1a09d0 183 #include <EXTERN.h>
96dbc785
PP
184 #include <perl.h>
185
186 static PerlInterpreter *my_perl;
187
c07a80fd 188 int main(int argc, char **argv, char **env)
cb1a09d0 189 {
8ebc5c01 190 char *args[] = { NULL };
cb1a09d0
AD
191 my_perl = perl_alloc();
192 perl_construct(my_perl);
96dbc785
PP
193
194 perl_parse(my_perl, NULL, argc, argv, NULL);
195
8ebc5c01
PP
196 /*** skipping perl_run() ***/
197
198 perl_call_argv("showtime", G_DISCARD | G_NOARGS, args);
199
cb1a09d0
AD
200 perl_destruct(my_perl);
201 perl_free(my_perl);
202 }
203
204where I<showtime> is a Perl subroutine that takes no arguments (that's the
96dbc785 205I<G_NOARGS>) and for which I'll ignore the return value (that's the
cb1a09d0
AD
206I<G_DISCARD>). Those flags, and others, are discussed in L<perlcall>.
207
208I'll define the I<showtime> subroutine in a file called I<showtime.pl>:
209
210 print "I shan't be printed.";
96dbc785 211
cb1a09d0
AD
212 sub showtime {
213 print time;
214 }
215
216Simple enough. Now compile and run:
217
96dbc785
PP
218 % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
219
cb1a09d0
AD
220 % showtime showtime.pl
221 818284590
222
223yielding the number of seconds that elapsed between January 1, 1970
224(the beginning of the UNIX epoch), and the moment I began writing this
225sentence.
226
8ebc5c01
PP
227Note that in this particular case we are not required to call I<perl_run>,
228however, in general it's considered good practice to ensure proper
229initialization of library code including execution of all object C<DESTROY>
230methods and package C<END {}> blocks.
231
232If you want to pass some arguments to the Perl subroutine, you may add
233strings to the C<NULL> terminated C<args> list passed to I<perl_call_argv>.
234In order to pass arguments of another data type and/or examine return values
235of the subroutine you'll need to manipulate the
96dbc785 236Perl stack, demonstrated in the last section of this document:
cb1a09d0
AD
237L<Fiddling with the Perl stack from your C program>
238
239=head2 Evaluating a Perl statement from your C program
240
a6006777
PP
241One way to evaluate pieces of Perl code is to use L<perlguts/perl_eval_sv>.
242We have wrapped this function with our own I<perl_eval()> function, which
243converts a command string to an SV, passing this and the L<perlcall/G_DISCARD>
244flag to L<perlguts/perl_eval_sv>.
cb1a09d0
AD
245
246Arguably, this is the only routine you'll ever need to execute
247snippets of Perl code from within your C program. Your string can be
248as long as you wish; it can contain multiple statements; it can
8ebc5c01
PP
249include L<perlfunc/use>, L<perlfunc/require> and L<perlfunc/do> to
250include external Perl files.
cb1a09d0 251
96dbc785
PP
252Our I<perl_eval()> lets us evaluate individual Perl strings, and then
253extract variables for coercion into C types. The following program,
cb1a09d0
AD
254I<string.c>, executes three Perl strings, extracting an C<int> from
255the first, a C<float> from the second, and a C<char *> from the third.
256
cb1a09d0
AD
257 #include <EXTERN.h>
258 #include <perl.h>
96dbc785 259
cb1a09d0 260 static PerlInterpreter *my_perl;
96dbc785 261
a6006777 262 I32 perl_eval(char *string)
cb1a09d0 263 {
a6006777 264 return perl_eval_sv(newSVpv(string,0), G_DISCARD);
cb1a09d0 265 }
96dbc785 266
c07a80fd 267 main (int argc, char **argv, char **env)
cb1a09d0 268 {
a6006777 269 char *embedding[] = { "", "-e", "0" };
cb1a09d0 270 STRLEN length;
96dbc785 271
cb1a09d0
AD
272 my_perl = perl_alloc();
273 perl_construct( my_perl );
96dbc785
PP
274
275 perl_parse(my_perl, NULL, 3, embedding, NULL);
8ebc5c01 276 perl_run(my_perl);
cb1a09d0
AD
277 /** Treat $a as an integer **/
278 perl_eval("$a = 3; $a **= 2");
279 printf("a = %d\n", SvIV(perl_get_sv("a", FALSE)));
96dbc785 280
cb1a09d0
AD
281 /** Treat $a as a float **/
282 perl_eval("$a = 3.14; $a **= 2");
283 printf("a = %f\n", SvNV(perl_get_sv("a", FALSE)));
96dbc785 284
cb1a09d0
AD
285 /** Treat $a as a string **/
286 perl_eval("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a); ");
287 printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), length));
96dbc785 288
cb1a09d0
AD
289 perl_destruct(my_perl);
290 perl_free(my_perl);
291 }
292
293All of those strange functions with I<sv> in their names help convert Perl scalars to C types. They're described in L<perlguts>.
294
295If you compile and run I<string.c>, you'll see the results of using
296I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
297I<SvPV()> to create a string:
298
299 a = 9
300 a = 9.859600
301 a = Just Another Perl Hacker
302
303
304=head2 Performing Perl pattern matches and substitutions from your C program
305
306Our I<perl_eval()> lets us evaluate strings of Perl code, so we can
307define some functions that use it to "specialize" in matches and
308substitutions: I<match()>, I<substitute()>, and I<matches()>.
309
96dbc785 310 char match(char *string, char *pattern);
cb1a09d0 311
5f05dabc 312Given a string and a pattern (e.g., "m/clasp/" or "/\b\w*\b/", which in
cb1a09d0
AD
313your program might be represented as C<"/\\b\\w*\\b/">),
314returns 1 if the string matches the pattern and 0 otherwise.
315
316
317 int substitute(char *string[], char *pattern);
318
5f05dabc 319Given a pointer to a string and an "=~" operation (e.g., "s/bob/robert/g" or
cb1a09d0
AD
320"tr[A-Z][a-z]"), modifies the string according to the operation,
321returning the number of substitutions made.
322
323 int matches(char *string, char *pattern, char **matches[]);
324
325Given a string, a pattern, and a pointer to an empty array of strings,
326evaluates C<$string =~ $pattern> in an array context, and fills in
96dbc785 327I<matches> with the array elements (allocating memory as it does so),
cb1a09d0
AD
328returning the number of matches found.
329
96dbc785
PP
330Here's a sample program, I<match.c>, that uses all three (long lines have
331been wrapped here):
cb1a09d0 332
cb1a09d0
AD
333 #include <EXTERN.h>
334 #include <perl.h>
cb1a09d0 335 static PerlInterpreter *my_perl;
a6006777 336 I32 perl_eval(char *string)
cb1a09d0 337 {
a6006777 338 return perl_eval_sv(newSVpv(string,0), G_DISCARD);
cb1a09d0 339 }
cb1a09d0 340 /** match(string, pattern)
96dbc785
PP
341 **
342 ** Used for matches in a scalar context.
343 **
344 ** Returns 1 if the match was successful; 0 otherwise.
345 **/
346 char match(char *string, char *pattern)
cb1a09d0
AD
347 {
348 char *command;
349 command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 37);
96dbc785 350 sprintf(command, "$string = '%s'; $return = $string =~ %s",
8ebc5c01 351 string, pattern);
cb1a09d0
AD
352 perl_eval(command);
353 free(command);
354 return SvIV(perl_get_sv("return", FALSE));
355 }
cb1a09d0 356 /** substitute(string, pattern)
96dbc785
PP
357 **
358 ** Used for =~ operations that modify their left-hand side (s/// and tr///)
359 **
360 ** Returns the number of successful matches, and
361 ** modifies the input string if there were any.
362 **/
363 int substitute(char *string[], char *pattern)
cb1a09d0
AD
364 {
365 char *command;
366 STRLEN length;
367 command = malloc(sizeof(char) * strlen(*string) + strlen(pattern) + 35);
96dbc785 368 sprintf(command, "$string = '%s'; $ret = ($string =~ %s)",
8ebc5c01
PP
369 *string, pattern);
370 perl_eval(command);
371 free(command);
372 *string = SvPV(perl_get_sv("string", FALSE), length);
373 return SvIV(perl_get_sv("ret", FALSE));
cb1a09d0 374 }
cb1a09d0 375 /** matches(string, pattern, matches)
96dbc785
PP
376 **
377 ** Used for matches in an array context.
378 **
379 ** Returns the number of matches,
380 ** and fills in **matches with the matching substrings (allocates memory!)
381 **/
382 int matches(char *string, char *pattern, char **match_list[])
cb1a09d0
AD
383 {
384 char *command;
385 SV *current_match;
386 AV *array;
387 I32 num_matches;
388 STRLEN length;
389 int i;
cb1a09d0 390 command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 38);
96dbc785 391 sprintf(command, "$string = '%s'; @array = ($string =~ %s)",
8ebc5c01 392 string, pattern);
cb1a09d0
AD
393 perl_eval(command);
394 free(command);
395 array = perl_get_av("array", FALSE);
396 num_matches = av_len(array) + 1; /** assume $[ is 0 **/
96dbc785
PP
397 *match_list = (char **) malloc(sizeof(char *) * num_matches);
398 for (i = 0; i <= num_matches; i++) {
cb1a09d0 399 current_match = av_shift(array);
96dbc785 400 (*match_list)[i] = SvPV(current_match, length);
cb1a09d0
AD
401 }
402 return num_matches;
403 }
c07a80fd 404 main (int argc, char **argv, char **env)
cb1a09d0 405 {
a6006777 406 char *embedding[] = { "", "-e", "0" };
96dbc785 407 char *text, **match_list;
cb1a09d0
AD
408 int num_matches, i;
409 int j;
cb1a09d0
AD
410 my_perl = perl_alloc();
411 perl_construct( my_perl );
96dbc785 412 perl_parse(my_perl, NULL, 3, embedding, NULL);
8ebc5c01
PP
413 perl_run(my_perl);
414
cb1a09d0 415 text = (char *) malloc(sizeof(char) * 486); /** A long string follows! **/
96dbc785
PP
416 sprintf(text, "%s", "When he is at a convenience store and the bill \
417 comes to some amount like 76 cents, Maynard is aware that there is \
418 something he *should* do, something that will enable him to get back \
419 a quarter, but he has no idea *what*. He fumbles through his red \
420 squeezey changepurse and gives the boy three extra pennies with his \
421 dollar, hoping that he might luck into the correct amount. The boy \
422 gives him back two of his own pennies and then the big shiny quarter \
423 that is his prize. -RICHH");
424 if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
425 printf("match: Text contains the word 'quarter'.\n\n");
426 else
427 printf("match: Text doesn't contain the word 'quarter'.\n\n");
428 if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
429 printf("match: Text contains the word 'eighth'.\n\n");
430 else
431 printf("match: Text doesn't contain the word 'eighth'.\n\n");
432 /** Match all occurrences of /wi../ **/
433 num_matches = matches(text, "m/(wi..)/g", &match_list);
434 printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
435 for (i = 0; i < num_matches; i++)
436 printf("match: %s\n", match_list[i]);
cb1a09d0
AD
437 printf("\n");
438 for (i = 0; i < num_matches; i++) {
96dbc785 439 free(match_list[i]);
cb1a09d0 440 }
96dbc785
PP
441 free(match_list);
442 /** Remove all vowels from text **/
443 num_matches = substitute(&text, "s/[aeiou]//gi");
cb1a09d0 444 if (num_matches) {
96dbc785 445 printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
8ebc5c01 446 num_matches);
cb1a09d0
AD
447 printf("Now text is: %s\n\n", text);
448 }
96dbc785
PP
449 /** Attempt a substitution **/
450 if (!substitute(&text, "s/Perl/C/")) {
451 printf("substitute: s/Perl/C...No substitution made.\n\n");
cb1a09d0 452 }
cb1a09d0 453 free(text);
cb1a09d0
AD
454 perl_destruct(my_perl);
455 perl_free(my_perl);
456 }
457
96dbc785 458which produces the output (again, long lines have been wrapped here)
cb1a09d0
AD
459
460 perl_match: Text contains the word 'quarter'.
96dbc785 461
cb1a09d0 462 perl_match: Text doesn't contain the word 'eighth'.
96dbc785 463
cb1a09d0
AD
464 perl_matches: m/(wi..)/g found 2 matches...
465 match: will
466 match: with
96dbc785 467
cb1a09d0 468 perl_substitute: s/[aeiou]//gi...139 substitutions made.
96dbc785
PP
469 Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
470 Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck
471 qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd gvs th by
472 thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt. Th by gvs
473 hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH
474
cb1a09d0 475 perl_substitute: s/Perl/C...No substitution made.
96dbc785 476
cb1a09d0
AD
477=head2 Fiddling with the Perl stack from your C program
478
479When trying to explain stacks, most computer science textbooks mumble
480something about spring-loaded columns of cafeteria plates: the last
481thing you pushed on the stack is the first thing you pop off. That'll
482do for our purposes: your C program will push some arguments onto "the Perl
483stack", shut its eyes while some magic happens, and then pop the
484results--the return value of your Perl subroutine--off the stack.
96dbc785 485
cb1a09d0
AD
486First you'll need to know how to convert between C types and Perl
487types, with newSViv() and sv_setnv() and newAV() and all their
488friends. They're described in L<perlguts>.
489
490Then you'll need to know how to manipulate the Perl stack. That's
491described in L<perlcall>.
492
96dbc785 493Once you've understood those, embedding Perl in C is easy.
cb1a09d0 494
5f05dabc 495Because C has no built-in function for integer exponentiation, let's
cb1a09d0 496make Perl's ** operator available to it (this is less useful than it
5f05dabc 497sounds, because Perl implements ** with C's I<pow()> function). First
cb1a09d0
AD
498I'll create a stub exponentiation function in I<power.pl>:
499
500 sub expo {
501 my ($a, $b) = @_;
502 return $a ** $b;
503 }
504
505Now I'll create a C program, I<power.c>, with a function
506I<PerlPower()> that contains all the perlguts necessary to push the
507two arguments into I<expo()> and to pop the return value out. Take a
508deep breath...
509
cb1a09d0
AD
510 #include <EXTERN.h>
511 #include <perl.h>
96dbc785 512
cb1a09d0 513 static PerlInterpreter *my_perl;
96dbc785 514
cb1a09d0
AD
515 static void
516 PerlPower(int a, int b)
517 {
518 dSP; /* initialize stack pointer */
519 ENTER; /* everything created after here */
520 SAVETMPS; /* ...is a temporary variable. */
521 PUSHMARK(sp); /* remember the stack pointer */
522 XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
523 XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
524 PUTBACK; /* make local stack pointer global */
525 perl_call_pv("expo", G_SCALAR); /* call the function */
526 SPAGAIN; /* refresh stack pointer */
527 /* pop the return value from stack */
528 printf ("%d to the %dth power is %d.\n", a, b, POPi);
96dbc785 529 PUTBACK;
cb1a09d0
AD
530 FREETMPS; /* free that return value */
531 LEAVE; /* ...and the XPUSHed "mortal" args.*/
532 }
96dbc785
PP
533
534 int main (int argc, char **argv, char **env)
cb1a09d0
AD
535 {
536 char *my_argv[2];
96dbc785 537
cb1a09d0
AD
538 my_perl = perl_alloc();
539 perl_construct( my_perl );
96dbc785 540
cb1a09d0
AD
541 my_argv[1] = (char *) malloc(10);
542 sprintf(my_argv[1], "power.pl");
96dbc785
PP
543
544 perl_parse(my_perl, NULL, argc, my_argv, NULL);
8ebc5c01 545 perl_run(my_perl);
96dbc785 546
cb1a09d0 547 PerlPower(3, 4); /*** Compute 3 ** 4 ***/
96dbc785 548
cb1a09d0
AD
549 perl_destruct(my_perl);
550 perl_free(my_perl);
551 }
96dbc785 552
cb1a09d0
AD
553
554
555Compile and run:
556
96dbc785
PP
557 % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
558
559 % power
cb1a09d0
AD
560 3 to the 4th power is 81.
561
a6006777
PP
562=head2 Maintaining a persistent interpreter
563
564When developing interactive, potentially long-running applications, it's
565a good idea to maintain a persistent interpreter rather than allocating
566and constructing a new interpreter multiple times. The major gain here is
567speed, avoiding the penalty of Perl start-up time. However, a persistent
568interpreter will require you to be more cautious in your use of namespace
569and variable scoping. In previous examples we've been using global variables
570in the default package B<main>. We knew exactly what code would be run,
571making it safe to assume we'd avoid any variable collision or outrageous
572symbol table growth.
573
574Let's say your application is a server, which must run perl code from an
575arbitrary file during each transaction. Your server has no way of knowing
576what code is inside anyone of these files.
577If the file was pulled in by B<perl_parse()>, compiled into a newly
578constructed interpreter, then cleaned out with B<perl_destruct()> after the
579the transaction, you'd be shielded from most namespace troubles.
580
581One way to avoid namespace collisions in this scenerio, is to translate the
582file name into a valid Perl package name, which is most likely to be unique,
583then compile the code into that package using L<perlfunc/eval>.
584In the example below, each file will only be compiled once, unless it is
585updated on disk.
586Optionally, the application may choose to clean out the symbol table
587associated with the file after we are done with it. We'll call the subroutine
588B<Embed::Persistent::eval_file> which lives in the file B<persistent.pl>, with
589L<perlcall/perl_call_argv>, passing the filename and boolean cleanup/cache
590flag as arguments.
591
592Note that the process will continue to grow for each file that is compiled,
593and each file it pulls in via L<perlfunc/require>, L<perlfunc/use> or
594L<perlfunc/do>. In addition, there maybe B<AUTOLOAD>ed subroutines and
595other conditions that cause Perl's symbol table to grow. You may wish to
596add logic which keeps track of process size or restarts itself after n number
597of requests to ensure memory consumption is kept to a minimum. You also need
598to consider the importance of variable scoping with L<perlfunc/my> to futher
599reduce symbol table growth.
600
601
602 package Embed::Persistent;
603 #persistent.pl
604
605 use strict;
606 use vars '%Cache';
607
608 #use Devel::Symdump ();
609
610 sub valid_package_name {
611 my($string) = @_;
612 $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
613 # second pass only for words starting with a digit
614 $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;
615
616 # Dress it up as a real package name
617 $string =~ s|/|::|g;
618 return "Embed" . $string;
619 }
620
621 #borrowed from Safe.pm
622 sub delete_package {
623 my $pkg = shift;
624 my ($stem, $leaf);
625
626 no strict 'refs';
8ebc5c01 627 $pkg = "main::$pkg\::"; # expand to full symbol table name
a6006777
PP
628 ($stem, $leaf) = $pkg =~ m/(.*::)(\w+::)$/;
629
630 my $stem_symtab = *{$stem}{HASH};
631
632 delete $stem_symtab->{$leaf};
633 }
634
635 sub eval_file {
636 my($filename, $delete) = @_;
637 my $package = valid_package_name($filename);
638 my $mtime = -M $filename;
639 if(defined $Cache{$package}{mtime}
640 &&
641 $Cache{$package}{mtime} <= $mtime)
642 {
8ebc5c01
PP
643 # we have compiled this subroutine already,
644 # it has not been updated on disk, nothing left to do
645 print STDERR "already compiled $package->handler\n";
a6006777
PP
646 }
647 else {
8ebc5c01
PP
648 local *FH;
649 open FH, $filename or die "open '$filename' $!";
650 local($/) = undef;
651 my $sub = <FH>;
652 close FH;
a6006777 653
8ebc5c01
PP
654 #wrap the code into a subroutine inside our unique package
655 my $eval = qq{package $package; sub handler { $sub; }};
656 {
657 # hide our variables within this block
658 my($filename,$mtime,$package,$sub);
659 eval $eval;
660 }
661 die $@ if $@;
a6006777 662
8ebc5c01
PP
663 #cache it unless we're cleaning out each time
664 $Cache{$package}{mtime} = $mtime unless $delete;
a6006777
PP
665 }
666
667 eval {$package->handler;};
668 die $@ if $@;
669
670 delete_package($package) if $delete;
671
672 #take a look if you want
673 #print Devel::Symdump->rnew($package)->as_string, $/;
674 }
675
676 1;
677
678 __END__
679
680 /* persistent.c */
681 #include <EXTERN.h>
682 #include <perl.h>
683
684 /* 1 = clean out filename's symbol table after each request, 0 = don't */
685 #ifndef DO_CLEAN
686 #define DO_CLEAN 0
687 #endif
688
689 static PerlInterpreter *perl = NULL;
690
691 int
692 main(int argc, char **argv, char **env)
693 {
694 char *embedding[] = { "", "persistent.pl" };
695 char *args[] = { "", DO_CLEAN, NULL };
696 char filename [1024];
697 int exitstatus = 0;
698
699 if((perl = perl_alloc()) == NULL) {
8ebc5c01
PP
700 fprintf(stderr, "no memory!");
701 exit(1);
a6006777
PP
702 }
703 perl_construct(perl);
704
705 exitstatus = perl_parse(perl, NULL, 2, embedding, NULL);
706
707 if(!exitstatus) {
8ebc5c01 708 exitstatus = perl_run(perl);
a6006777 709
8ebc5c01 710 while(printf("Enter file name: ") && gets(filename)) {
a6006777 711
8ebc5c01
PP
712 /* call the subroutine, passing it the filename as an argument */
713 args[0] = filename;
714 perl_call_argv("Embed::Persistent::eval_file",
715 G_DISCARD | G_EVAL, args);
a6006777 716
8ebc5c01
PP
717 /* check $@ */
718 if(SvTRUE(GvSV(errgv)))
719 fprintf(stderr, "eval error: %s\n", SvPV(GvSV(errgv),na));
720 }
a6006777
PP
721 }
722
723 perl_destruct_level = 0;
724 perl_destruct(perl);
725 perl_free(perl);
726 exit(exitstatus);
727 }
728
729
730Now compile:
731
732 % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ldopts`
733
734Here's a example script file:
735
736 #test.pl
737 my $string = "hello";
738 foo($string);
739
740 sub foo {
741 print "foo says: @_\n";
742 }
743
744Now run:
745
746 % persistent
747 Enter file name: test.pl
748 foo says: hello
749 Enter file name: test.pl
750 already compiled Embed::test_2epl->handler
751 foo says: hello
752 Enter file name: ^C
753
8ebc5c01
PP
754=head2 Maintaining multiple interpreter instances
755
756The previous examples have gone through several steps to startup, use and
757shutdown an embedded Perl interpreter. Certain applications may require
758more than one instance of an interpreter to be created during the lifespan
759of a single process. Such an application may take different approaches in
760it's use of interpreter objects. For example, a particular transaction may
761want to create an interpreter instance, then release any resources associated
762with the object once the transaction is completed. When a single process
763does this once, resources are released upon exit of the program and the next
764time it starts, the interpreter's global state is fresh.
765
766In the same process, the program must take care to ensure that these
767actions take place before constructing a new interpreter. By default, the
768global variable C<perl_destruct_level> is set to C<0> since extra cleaning
769is not needed when a program constructs a single interpreter, such as the
770perl executable itself in C</usr/bin/perl> or some such.
771
772You can tell Perl to make everything squeeky clean by setting
773C<perl_destruct_level> to C<1>.
774
775 perl_destruct_level = 1; /* perl global variable */
776 while(1) {
777 ...
778 /* reset global variables here with perl_destruct_level = 1 */
779 perl_contruct(my_perl);
780 ...
781 /* clean and reset _everything_ during perl_destruct */
782 perl_destruct(my_perl); /* ah, nice and fresh */
783 perl_free(my_perl);
784 ...
785 /* let's go do it again! */
786 }
787
788Now, when I<perl_destruct()> is called, the interpreter's syntax parsetree
789and symbol tables are cleaned out, along with reseting global variables.
790
791So, we've seen how to startup and shutdown an interpreter more than once
792in the same process, but there was only one instance in existance at any
793one time. Hmm, wonder if we can have more than one interpreter instance
794running at the _same_ time?
795Indeed this is possible, however when you build Perl, you must compile with
796C<-DMULTIPLICITY>.
797
798It's a little tricky for the Perl runtime to handle multiple interpreters,
799introducing some overhead that most programs with a single interpreter don't
800get burdened with. When you compile with C<-DMULTIPLICITY>, by default,
801C<perl_destruct_level> is set to C<1> for each interpreter.
802
803Let's give it a try:
804
805
806 #include <EXTERN.h>
807 #include <perl.h>
808
809
810 /* we're going to embed two interpreters */
811 /* we're going to embed two interpreters */
812
813
814 #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"
815
816
817 int main(int argc, char **argv, char **env)
818 {
819 PerlInterpreter
820 *one_perl = perl_alloc(),
821 *two_perl = perl_alloc();
822 char *one_args[] = { "one_perl", SAY_HELLO };
823 char *two_args[] = { "two_perl", SAY_HELLO };
824
825 perl_construct(one_perl);
826 perl_construct(two_perl);
827
828 perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
829 perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
830
831 perl_run(one_perl);
832 perl_run(two_perl);
833
834 perl_destruct(one_perl);
835 perl_destruct(two_perl);
836
837 perl_free(one_perl);
838 perl_free(two_perl);
839 }
840
841
842Compile as usual:
843
844 % cc -o multiplicity multiplicity.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
845
846Run it, Run it:
847
848 % multiplicity
849 Hi, I'm one_perl
850 Hi, I'm two_perl
851
96dbc785
PP
852=head2 Using Perl modules, which themselves use C libraries, from your C program
853
854If you've played with the examples above and tried to embed a script
855that I<use()>s a Perl module (such as I<Socket>) which itself uses a C or C++ library,
856this probably happened:
857
858
859 Can't load module Socket, dynamic loading not available in this perl.
860 (You may need to build a new perl executable which either supports
861 dynamic loading or has the Socket module statically linked into it.)
862
863
864What's wrong?
865
866Your interpreter doesn't know how to communicate with these extensions
867on its own. A little glue will help. Up until now you've been
868calling I<perl_parse()>, handing it NULL for the second argument:
869
870 perl_parse(my_perl, NULL, argc, my_argv, NULL);
871
872That's where the glue code can be inserted to create the initial contact between
873Perl and linked C/C++ routines. Let's take a look some pieces of I<perlmain.c>
874to see how Perl does this:
875
876
877 #ifdef __cplusplus
878 # define EXTERN_C extern "C"
879 #else
880 # define EXTERN_C extern
881 #endif
882
883 static void xs_init _((void));
884
885 EXTERN_C void boot_DynaLoader _((CV* cv));
886 EXTERN_C void boot_Socket _((CV* cv));
887
888
889 EXTERN_C void
890 xs_init()
891 {
892 char *file = __FILE__;
893 /* DynaLoader is a special case */
894 newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
895 newXS("Socket::bootstrap", boot_Socket, file);
896 }
897
898Simply put: for each extension linked with your Perl executable
899(determined during its initial configuration on your
900computer or when adding a new extension),
901a Perl subroutine is created to incorporate the extension's
902routines. Normally, that subroutine is named
903I<Module::bootstrap()> and is invoked when you say I<use Module>. In
904turn, this hooks into an XSUB, I<boot_Module>, which creates a Perl
905counterpart for each of the extension's XSUBs. Don't worry about this
906part; leave that to the I<xsubpp> and extension authors. If your
907extension is dynamically loaded, DynaLoader creates I<Module::bootstrap()>
908for you on the fly. In fact, if you have a working DynaLoader then there
5f05dabc 909is rarely any need to link in any other extensions statically.
96dbc785
PP
910
911
912Once you have this code, slap it into the second argument of I<perl_parse()>:
913
914
915 perl_parse(my_perl, xs_init, argc, my_argv, NULL);
916
917
918Then compile:
919
920 % cc -o interp interp.c `perl -MExtUtils::Embed -e ldopts`
921
922 % interp
923 use Socket;
924 use SomeDynamicallyLoadedModule;
925
926 print "Now I can use extensions!\n"'
927
928B<ExtUtils::Embed> can also automate writing the I<xs_init> glue code.
929
930 % perl -MExtUtils::Embed -e xsinit -o perlxsi.c
931 % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
932 % cc -c interp.c `perl -MExtUtils::Embed -e ccopts`
774d564b
PP
933 % cc -o interp perlxsi.o interp.o \
934 `perl -MExtUtils::Embed -e ccdlflags -e ldopts`
96dbc785
PP
935
936Consult L<perlxs> and L<perlguts> for more details.
937
938
cb1a09d0
AD
939=head1 MORAL
940
941You can sometimes I<write faster code> in C, but
5f05dabc 942you can always I<write code faster> in Perl. Because you can use
cb1a09d0
AD
943each from the other, combine them as you wish.
944
945
946=head1 AUTHOR
947
96dbc785
PP
948Jon Orwant F<E<lt>orwant@media.mit.eduE<gt>>,
949co-authored by Doug MacEachern F<E<lt>dougm@osf.orgE<gt>>,
950with contributions from
951Tim Bunce, Tom Christiansen, Dov Grobgeld, and Ilya
952Zakharevich.
cb1a09d0 953
96dbc785 954June 17, 1996
cb1a09d0 955
96dbc785 956Some of this material is excerpted from my book: I<Perl 5 Interactive>,
cb1a09d0
AD
957Waite Group Press, 1996 (ISBN 1-57169-064-6) and appears
958courtesy of Waite Group Press.