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