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