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