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