=item B<Use C from Perl?>
-Read L<perlcall> and L<perlxs>.
+Read L<perlxstut>, L<perlxs>, L<h2xs>, L<perlguts>, and L<perlapi>.
-=item B<Use a UNIX program from Perl?>
+=item B<Use a Unix program from Perl?>
Read about back-quotes and about C<system> and C<exec> in L<perlfunc>.
=item B<Use Perl from Perl?>
-Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlfunc/require>
+Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlfunc/require>
and L<perlfunc/use>.
=item B<Use C from C?>
=head2 ROADMAP
-L<Compiling your C program>
+=over 5
+
+=item *
+
+Compiling your C program
+
+=item *
+
+Adding a Perl interpreter to your C program
+
+=item *
+
+Calling a Perl subroutine from your C program
+
+=item *
+
+Evaluating a Perl statement from your C program
-There's one example in each of the eight sections:
+=item *
-L<Adding a Perl interpreter to your C program>
+Performing Perl pattern matches and substitutions from your C program
-L<Calling a Perl subroutine from your C program>
+=item *
-L<Evaluating a Perl statement from your C program>
+Fiddling with the Perl stack from your C program
-L<Performing Perl pattern matches and substitutions from your C program>
+=item *
-L<Fiddling with the Perl stack from your C program>
+Maintaining a persistent interpreter
-L<Maintaining a persistent interpreter>
+=item *
-L<Maintaining multiple interpreter instances>
+Maintaining multiple interpreter instances
-L<Using Perl modules, which themselves use C libraries, from your C program>
+=item *
-This documentation is Unix specific; if you have information about how
-to embed Perl on other platforms, please send e-mail to <F<orwant@tpj.com>>.
+Using Perl modules, which themselves use C libraries, from your C program
+
+=item *
+
+Embedding Perl under Win32
+
+=back
=head2 Compiling your C program
perl -MConfig -e 'print $Config{archlib}'
-Here's how you'd compile the example in the next section,
+Here's how you'd compile the example in the next section,
L<Adding a Perl interpreter to your C program>, on my Linux box:
- % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
+ % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
-I/usr/local/lib/perl5/i586-linux/5.003/CORE
- -L/usr/local/lib/perl5/i586-linux/5.003/CORE
+ -L/usr/local/lib/perl5/i586-linux/5.003/CORE
-o interp interp.c -lperl -lm
-(That's all one line.) On my DEC Alpha running 5.00305, the incantation
-is a bit different:
+(That's all one line.) On my DEC Alpha running old 5.003_05, the
+incantation is a bit different:
- % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include
- -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
- -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib
+ % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include
+ -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
+ -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib
-D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm
How can you figure out what to add? Assuming your Perl is post-5.001,
execute a C<perl -V> command and pay special attention to the "cc" and
-"ccflags" information.
+"ccflags" information.
-You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) for
+You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) for
your machine: C<perl -MConfig -e 'print $Config{cc}'> will tell you what
-to use.
+to use.
You'll also have to choose the appropriate library directory
(I</usr/local/lib/...>) for your machine. If your compiler complains
perl -MConfig -e 'print $Config{libs}'
-Provided your perl binary was properly configured and installed the
+Provided your perl binary was properly configured and installed the
B<ExtUtils::Embed> module will determine all of this information for
you:
If the B<ExtUtils::Embed> module isn't part of your Perl distribution,
you can retrieve it from
-http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils::Embed. (If
-this documentation came from your Perl distribution, then you're
+http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/
+(If this documentation came from your Perl distribution, then you're
running 5.004 or better and you already have it.)
The B<ExtUtils::Embed> kit on CPAN also contains all source code for
-the examples in this document, tests, additional examples and other
+the examples in this document, tests, additional examples and other
information you may find useful.
=head2 Adding a Perl interpreter to your C program
In a sense, perl (the C program) is a good example of embedding Perl
(the language), so I'll demonstrate embedding with I<miniperlmain.c>,
-from the source distribution. Here's a bastardized, non-portable
+included in the source distribution. Here's a bastardized, nonportable
version of I<miniperlmain.c> containing the essentials of embedding:
#include <EXTERN.h> /* from the Perl distribution */
int main(int argc, char **argv, char **env)
{
+ PERL_SYS_INIT3(&argc,&argv,&env);
my_perl = perl_alloc();
perl_construct(my_perl);
+ PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
perl_run(my_perl);
perl_destruct(my_perl);
perl_free(my_perl);
+ PERL_SYS_TERM();
}
Notice that we don't use the C<env> pointer. Normally handed to
C<perl_parse> as its final argument, C<env> here is replaced by
-C<NULL>, which means that the current environment will be used.
+C<NULL>, which means that the current environment will be used. The macros
+PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific tune up
+of the C runtime environment necessary to run Perl interpreters; since
+PERL_SYS_INIT3() may change C<env>, it may be more appropriate to provide
+C<env> as an argument to perl_parse().
Now compile this program (I'll call it I<interp.c>) into an executable:
You can also read and execute Perl statements from a file while in the
midst of your C program, by placing the filename in I<argv[1]> before
-calling I<perl_run()>.
+calling I<perl_run>.
=head2 Calling a Perl subroutine from your C program
-To call individual Perl subroutines, you can use any of the B<perl_call_*>
-functions documented in the L<perlcall> man page.
-In this example we'll use I<perl_call_argv>.
+To call individual Perl subroutines, you can use any of the B<call_*>
+functions documented in L<perlcall>.
+In this example we'll use C<call_argv>.
That's shown below, in a program I'll call I<showtime.c>.
int main(int argc, char **argv, char **env)
{
char *args[] = { NULL };
+ PERL_SYS_INIT3(&argc,&argv,&env);
my_perl = perl_alloc();
perl_construct(my_perl);
perl_parse(my_perl, NULL, argc, argv, NULL);
+ PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
/*** skipping perl_run() ***/
- perl_call_argv("showtime", G_DISCARD | G_NOARGS, args);
+ call_argv("showtime", G_DISCARD | G_NOARGS, args);
perl_destruct(my_perl);
perl_free(my_perl);
+ PERL_SYS_TERM();
}
where I<showtime> is a Perl subroutine that takes no arguments (that's the
(the beginning of the Unix epoch), and the moment I began writing this
sentence.
-In this particular case we don't have to call I<perl_run>, but in
-general it's considered good practice to ensure proper initialization
-of library code, including execution of all object C<DESTROY> methods
-and package C<END {}> blocks.
+In this particular case we don't have to call I<perl_run>, as we set
+the PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
+perl_destruct.
If you want to pass arguments to the Perl subroutine, you can add
strings to the C<NULL>-terminated C<args> list passed to
-I<perl_call_argv>. For other data types, or to examine return values,
-you'll need to manipulate the Perl stack. That's demonstrated in the
-last section of this document: L<Fiddling with the Perl stack from
-your C program>.
+I<call_argv>. For other data types, or to examine return values,
+you'll need to manipulate the Perl stack. That's demonstrated in
+L<Fiddling with the Perl stack from your C program>.
=head2 Evaluating a Perl statement from your C program
-One way to evaluate pieces of Perl code is to use
-L<perlguts/perl_eval_sv()>. We've wrapped this inside our own
-I<perl_eval()> function, which converts a command string to an SV,
-passing this and the L<perlcall/G_DISCARD> flag to
-L<perlguts/perl_eval_sv()>.
+Perl provides two API functions to evaluate pieces of Perl code.
+These are L<perlapi/eval_sv> and L<perlapi/eval_pv>.
-Arguably, this is the only routine you'll ever need to execute
-snippets of Perl code from within your C program. Your string can be
-as long as you wish; it can contain multiple statements; it can employ
-L<perlfunc/use>, L<perlfunc/require> and L<perlfunc/do> to include
-external Perl files.
+Arguably, these are the only routines you'll ever need to execute
+snippets of Perl code from within your C program. Your code can be as
+long as you wish; it can contain multiple statements; it can employ
+L<perlfunc/use>, L<perlfunc/require>, and L<perlfunc/do> to
+include external Perl files.
-Our I<perl_eval()> lets us evaluate individual Perl strings, and then
+I<eval_pv> lets us evaluate individual Perl strings, and then
extract variables for coercion into C types. The following program,
I<string.c>, executes three Perl strings, extracting an C<int> from
the first, a C<float> from the second, and a C<char *> from the third.
static PerlInterpreter *my_perl;
- I32 perl_eval(char *string)
- {
- return perl_eval_sv(newSVpv(string,0), G_DISCARD);
- }
-
main (int argc, char **argv, char **env)
{
- char *embedding[] = { "", "-e", "0" };
- STRLEN length;
+ STRLEN n_a;
+ char *embedding[] = { "", "-e", "0" };
- my_perl = perl_alloc();
- perl_construct( my_perl );
+ PERL_SYS_INIT3(&argc,&argv,&env);
+ my_perl = perl_alloc();
+ perl_construct( my_perl );
- perl_parse(my_perl, NULL, 3, embedding, NULL);
- perl_run(my_perl);
- /** Treat $a as an integer **/
- perl_eval("$a = 3; $a **= 2");
- printf("a = %d\n", SvIV(perl_get_sv("a", FALSE)));
+ perl_parse(my_perl, NULL, 3, embedding, NULL);
+ PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
+ perl_run(my_perl);
- /** Treat $a as a float **/
- perl_eval("$a = 3.14; $a **= 2");
- printf("a = %f\n", SvNV(perl_get_sv("a", FALSE)));
+ /** Treat $a as an integer **/
+ eval_pv("$a = 3; $a **= 2", TRUE);
+ printf("a = %d\n", SvIV(get_sv("a", FALSE)));
- /** Treat $a as a string **/
- perl_eval("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a); ");
- printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), length));
+ /** Treat $a as a float **/
+ eval_pv("$a = 3.14; $a **= 2", TRUE);
+ printf("a = %f\n", SvNV(get_sv("a", FALSE)));
- perl_destruct(my_perl);
- perl_free(my_perl);
+ /** Treat $a as a string **/
+ eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
+ printf("a = %s\n", SvPV(get_sv("a", FALSE), n_a));
+
+ perl_destruct(my_perl);
+ perl_free(my_perl);
+ PERL_SYS_TERM();
}
-All of those strange functions with I<sv> in their names help convert Perl scalars to C types. They're described in L<perlguts>.
+All 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>.
If you compile and run I<string.c>, you'll see the results of using
I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
a = 9.859600
a = Just Another Perl Hacker
+In the example above, we've created a global variable to temporarily
+store the computed value of our eval'd expression. It is also
+possible and in most cases a better strategy to fetch the return value
+from I<eval_pv()> instead. Example:
+
+ ...
+ STRLEN n_a;
+ SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
+ printf("%s\n", SvPV(val,n_a));
+ ...
+
+This way, we avoid namespace pollution by not creating global
+variables and we've simplified our code as well.
=head2 Performing Perl pattern matches and substitutions from your C program
-Our I<perl_eval()> lets us evaluate strings of Perl code, so we can
+The I<eval_sv()> function lets us evaluate strings of Perl code, so we can
define some functions that use it to "specialize" in matches and
substitutions: I<match()>, I<substitute()>, and I<matches()>.
- char match(char *string, char *pattern);
+ I32 match(SV *string, char *pattern);
Given a string and a pattern (e.g., C<m/clasp/> or C</\b\w*\b/>, which
in your C program might appear as "/\\b\\w*\\b/"), match()
returns 1 if the string matches the pattern and 0 otherwise.
- int substitute(char *string[], char *pattern);
+ int substitute(SV **string, char *pattern);
-Given a pointer to a string and an C<=~> operation (e.g.,
+Given a pointer to an C<SV> and an C<=~> operation (e.g.,
C<s/bob/robert/g> or C<tr[A-Z][a-z]>), substitute() modifies the string
-according to the operation, returning the number of substitutions
+within the C<SV> as according to the operation, returning the number of substitutions
made.
- int matches(char *string, char *pattern, char **matches[]);
+ int matches(SV *string, char *pattern, AV **matches);
-Given a string, a pattern, and a pointer to an empty array of strings,
-matches() evaluates C<$string =~ $pattern> in an array context, and
-fills in I<matches> with the array elements (allocating memory as it
-does so), returning the number of matches found.
+Given an C<SV>, a pattern, and a pointer to an empty C<AV>,
+matches() evaluates C<$string =~ $pattern> in a list context, and
+fills in I<matches> with the array elements, returning the number of matches found.
Here's a sample program, I<match.c>, that uses all three (long lines have
been wrapped here):
- #include <EXTERN.h>
+ #include <EXTERN.h>
+ #include <perl.h>
- static PerlInterpreter *my_perl;
- I32 perl_eval(char *string)
- {
- return perl_eval_sv(newSVpv(string,0), G_DISCARD);
- }
- /** match(string, pattern)
- **
- ** Used for matches in a scalar context.
- **
- ** Returns 1 if the match was successful; 0 otherwise.
- **/
- char match(char *string, char *pattern)
- {
- char *command;
- command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 37);
- sprintf(command, "$string = '%s'; $return = $string =~ %s",
- string, pattern);
- perl_eval(command);
- free(command);
- return SvIV(perl_get_sv("return", FALSE));
- }
- /** substitute(string, pattern)
- **
- ** Used for =~ operations that modify their left-hand side (s/// and tr///)
- **
- ** Returns the number of successful matches, and
- ** modifies the input string if there were any.
- **/
- int substitute(char *string[], char *pattern)
- {
- char *command;
- STRLEN length;
- command = malloc(sizeof(char) * strlen(*string) + strlen(pattern) + 35);
- sprintf(command, "$string = '%s'; $ret = ($string =~ %s)",
- *string, pattern);
- perl_eval(command);
- free(command);
- *string = SvPV(perl_get_sv("string", FALSE), length);
- return SvIV(perl_get_sv("ret", FALSE));
- }
- /** matches(string, pattern, matches)
- **
- ** Used for matches in an array context.
- **
- ** Returns the number of matches,
- ** and fills in **matches with the matching substrings (allocates memory!)
- **/
- int matches(char *string, char *pattern, char **match_list[])
- {
- char *command;
- SV *current_match;
- AV *array;
+ static PerlInterpreter *my_perl;
+
+ /** my_eval_sv(code, error_check)
+ ** kinda like eval_sv(),
+ ** but we pop the return value off the stack
+ **/
+ SV* my_eval_sv(SV *sv, I32 croak_on_error)
+ {
+ dSP;
+ SV* retval;
+ STRLEN n_a;
+
+ PUSHMARK(SP);
+ eval_sv(sv, G_SCALAR);
+
+ SPAGAIN;
+ retval = POPs;
+ PUTBACK;
+
+ if (croak_on_error && SvTRUE(ERRSV))
+ croak(SvPVx(ERRSV, n_a));
+
+ return retval;
+ }
+
+ /** match(string, pattern)
+ **
+ ** Used for matches in a scalar context.
+ **
+ ** Returns 1 if the match was successful; 0 otherwise.
+ **/
+
+ I32 match(SV *string, char *pattern)
+ {
+ SV *command = NEWSV(1099, 0), *retval;
+ STRLEN n_a;
+
+ sv_setpvf(command, "my $string = '%s'; $string =~ %s",
+ SvPV(string,n_a), pattern);
+
+ retval = my_eval_sv(command, TRUE);
+ SvREFCNT_dec(command);
+
+ return SvIV(retval);
+ }
+
+ /** substitute(string, pattern)
+ **
+ ** Used for =~ operations that modify their left-hand side (s/// and tr///)
+ **
+ ** Returns the number of successful matches, and
+ ** modifies the input string if there were any.
+ **/
+
+ I32 substitute(SV **string, char *pattern)
+ {
+ SV *command = NEWSV(1099, 0), *retval;
+ STRLEN n_a;
+
+ sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
+ SvPV(*string,n_a), pattern);
+
+ retval = my_eval_sv(command, TRUE);
+ SvREFCNT_dec(command);
+
+ *string = get_sv("string", FALSE);
+ return SvIV(retval);
+ }
+
+ /** matches(string, pattern, matches)
+ **
+ ** Used for matches in a list context.
+ **
+ ** Returns the number of matches,
+ ** and fills in **matches with the matching substrings
+ **/
+
+ I32 matches(SV *string, char *pattern, AV **match_list)
+ {
+ SV *command = NEWSV(1099, 0);
I32 num_matches;
- STRLEN length;
- int i;
- command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 38);
- sprintf(command, "$string = '%s'; @array = ($string =~ %s)",
- string, pattern);
- perl_eval(command);
- free(command);
- array = perl_get_av("array", FALSE);
- num_matches = av_len(array) + 1; /** assume $[ is 0 **/
- *match_list = (char **) malloc(sizeof(char *) * num_matches);
- for (i = 0; i <= num_matches; i++) {
- current_match = av_shift(array);
- (*match_list)[i] = SvPV(current_match, length);
- }
+ STRLEN n_a;
+
+ sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
+ SvPV(string,n_a), pattern);
+
+ my_eval_sv(command, TRUE);
+ SvREFCNT_dec(command);
+
+ *match_list = get_av("array", FALSE);
+ num_matches = av_len(*match_list) + 1; /** assume $[ is 0 **/
+
return num_matches;
- }
- main (int argc, char **argv, char **env)
- {
+ }
+
+ main (int argc, char **argv, char **env)
+ {
char *embedding[] = { "", "-e", "0" };
- char *text, **match_list;
- int num_matches, i;
- int j;
+ AV *match_list;
+ I32 num_matches, i;
+ SV *text;
+ STRLEN n_a;
+
+ PERL_SYS_INIT3(&argc,&argv,&env);
my_perl = perl_alloc();
- perl_construct( my_perl );
+ perl_construct(my_perl);
perl_parse(my_perl, NULL, 3, embedding, NULL);
- perl_run(my_perl);
-
- text = (char *) malloc(sizeof(char) * 486); /** A long string follows! **/
- sprintf(text, "%s", "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");
+ PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
+
+ text = NEWSV(1099,0);
+ 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");
+
if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
- printf("match: Text contains the word 'quarter'.\n\n");
+ printf("match: Text contains the word 'quarter'.\n\n");
else
- printf("match: Text doesn't contain the word 'quarter'.\n\n");
+ printf("match: Text doesn't contain the word 'quarter'.\n\n");
+
if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
- printf("match: Text contains the word 'eighth'.\n\n");
+ printf("match: Text contains the word 'eighth'.\n\n");
else
- printf("match: Text doesn't contain the word 'eighth'.\n\n");
+ printf("match: Text doesn't contain the word 'eighth'.\n\n");
+
/** Match all occurrences of /wi../ **/
num_matches = matches(text, "m/(wi..)/g", &match_list);
printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
+
for (i = 0; i < num_matches; i++)
- printf("match: %s\n", match_list[i]);
+ printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),n_a));
printf("\n");
- for (i = 0; i < num_matches; i++) {
- free(match_list[i]);
- }
- free(match_list);
+
/** Remove all vowels from text **/
num_matches = substitute(&text, "s/[aeiou]//gi");
if (num_matches) {
- printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
- num_matches);
- printf("Now text is: %s\n\n", text);
+ printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
+ num_matches);
+ printf("Now text is: %s\n\n", SvPV(text,n_a));
}
+
/** Attempt a substitution **/
if (!substitute(&text, "s/Perl/C/")) {
- printf("substitute: s/Perl/C...No substitution made.\n\n");
+ printf("substitute: s/Perl/C...No substitution made.\n\n");
}
- free(text);
+
+ SvREFCNT_dec(text);
+ PL_perl_destruct_level = 1;
perl_destruct(my_perl);
perl_free(my_perl);
- }
+ PERL_SYS_TERM();
+ }
which produces the output (again, long lines have been wrapped here)
match: with
substitute: s/[aeiou]//gi...139 substitutions made.
- Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
+ Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck
qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd gvs th by
thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt. Th by gvs
First you'll need to know how to convert between C types and Perl
types, with newSViv() and sv_setnv() and newAV() and all their
-friends. They're described in L<perlguts>.
+friends. They're described in L<perlguts> and L<perlapi>.
Then you'll need to know how to manipulate the Perl stack. That's
described in L<perlcall>.
Once you've understood those, embedding Perl in C is easy.
-Because C has no built-in function for integer exponentiation, let's
+Because C has no builtin function for integer exponentiation, let's
make Perl's ** operator available to it (this is less useful than it
sounds, because Perl implements ** with C's I<pow()> function). First
I'll create a stub exponentiation function in I<power.pl>:
dSP; /* initialize stack pointer */
ENTER; /* everything created after here */
SAVETMPS; /* ...is a temporary variable. */
- PUSHMARK(sp); /* remember the stack pointer */
+ PUSHMARK(SP); /* remember the stack pointer */
XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
PUTBACK; /* make local stack pointer global */
- perl_call_pv("expo", G_SCALAR); /* call the function */
+ call_pv("expo", G_SCALAR); /* call the function */
SPAGAIN; /* refresh stack pointer */
/* pop the return value from stack */
printf ("%d to the %dth power is %d.\n", a, b, POPi);
int main (int argc, char **argv, char **env)
{
- char *my_argv[2];
+ char *my_argv[] = { "", "power.pl" };
+ PERL_SYS_INIT3(&argc,&argv,&env);
my_perl = perl_alloc();
perl_construct( my_perl );
- my_argv[1] = (char *) malloc(10);
- sprintf(my_argv[1], "power.pl");
-
- perl_parse(my_perl, NULL, argc, my_argv, NULL);
+ perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
+ PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
perl_run(my_perl);
PerlPower(3, 4); /*** Compute 3 ** 4 ***/
perl_destruct(my_perl);
perl_free(my_perl);
+ PERL_SYS_TERM();
}
applications, it's a good idea to maintain a persistent interpreter
rather than allocating and constructing a new interpreter multiple
times. The major reason is speed: since Perl will only be loaded into
-memory once.
+memory once.
However, you have to be more cautious with namespace and variable
scoping when using a persistent interpreter. In previous examples
the code into that package using L<perlfunc/eval>. In the example
below, each file will only be compiled once. Or, the application
might choose to clean out the symbol table associated with the file
-after it's no longer needed. Using L<perlcall/perl_call_argv>, We'll
+after it's no longer needed. Using L<perlapi/call_argv>, We'll
call the subroutine C<Embed::Persistent::eval_file> which lives in the
file C<persistent.pl> and pass the filename and boolean cleanup/cache
flag as arguments.
consumption is minimized. You'll also want to scope your variables
with L<perlfunc/my> whenever possible.
-
+
package Embed::Persistent;
#persistent.pl
-
+
use strict;
- use vars '%Cache';
-
+ our %Cache;
+ use Symbol qw(delete_package);
+
sub valid_package_name {
my($string) = @_;
$string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
# second pass only for words starting with a digit
$string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;
-
+
# Dress it up as a real package name
$string =~ s|/|::|g;
return "Embed" . $string;
}
-
- #borrowed from Safe.pm
- sub delete_package {
- my $pkg = shift;
- my ($stem, $leaf);
-
- no strict 'refs';
- $pkg = "main::$pkg\::"; # expand to full symbol table name
- ($stem, $leaf) = $pkg =~ m/(.*::)(\w+::)$/;
-
- my $stem_symtab = *{$stem}{HASH};
-
- delete $stem_symtab->{$leaf};
- }
-
+
sub eval_file {
my($filename, $delete) = @_;
my $package = valid_package_name($filename);
my $mtime = -M $filename;
if(defined $Cache{$package}{mtime}
&&
- $Cache{$package}{mtime} <= $mtime)
+ $Cache{$package}{mtime} <= $mtime)
{
- # we have compiled this subroutine already,
+ # we have compiled this subroutine already,
# it has not been updated on disk, nothing left to do
print STDERR "already compiled $package->handler\n";
}
local($/) = undef;
my $sub = <FH>;
close FH;
-
+
#wrap the code into a subroutine inside our unique package
my $eval = qq{package $package; sub handler { $sub; }};
{
eval $eval;
}
die $@ if $@;
-
+
#cache it unless we're cleaning out each time
$Cache{$package}{mtime} = $mtime unless $delete;
}
-
+
eval {$package->handler;};
die $@ if $@;
-
+
delete_package($package) if $delete;
-
+
#take a look if you want
#print Devel::Symdump->rnew($package)->as_string, $/;
}
-
+
1;
-
+
__END__
/* persistent.c */
- #include <EXTERN.h>
- #include <perl.h>
-
+ #include <EXTERN.h>
+ #include <perl.h>
+
/* 1 = clean out filename's symbol table after each request, 0 = don't */
#ifndef DO_CLEAN
#define DO_CLEAN 0
#endif
-
- static PerlInterpreter *perl = NULL;
-
+
+ #define BUFFER_SIZE 1024
+
+ static PerlInterpreter *my_perl = NULL;
+
int
main(int argc, char **argv, char **env)
{
char *embedding[] = { "", "persistent.pl" };
char *args[] = { "", DO_CLEAN, NULL };
- char filename [1024];
+ char filename[BUFFER_SIZE];
int exitstatus = 0;
-
- if((perl = perl_alloc()) == NULL) {
+ STRLEN n_a;
+
+ PERL_SYS_INIT3(&argc,&argv,&env);
+ if((my_perl = perl_alloc()) == NULL) {
fprintf(stderr, "no memory!");
exit(1);
}
- perl_construct(perl);
-
- exitstatus = perl_parse(perl, NULL, 2, embedding, NULL);
-
- if(!exitstatus) {
- exitstatus = perl_run(perl);
-
- while(printf("Enter file name: ") && gets(filename)) {
-
+ perl_construct(my_perl);
+
+ PL_origalen = 1; /* don't let $0 assignment update the proctitle or embedding[0] */
+ exitstatus = perl_parse(my_perl, NULL, 2, embedding, NULL);
+ PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
+ if(!exitstatus) {
+ exitstatus = perl_run(my_perl);
+
+ while(printf("Enter file name: ") &&
+ fgets(filename, BUFFER_SIZE, stdin)) {
+
+ filename[strlen(filename)-1] = '\0'; /* strip \n */
/* call the subroutine, passing it the filename as an argument */
args[0] = filename;
- perl_call_argv("Embed::Persistent::eval_file",
+ call_argv("Embed::Persistent::eval_file",
G_DISCARD | G_EVAL, args);
-
+
/* check $@ */
- if(SvTRUE(GvSV(errgv)))
- fprintf(stderr, "eval error: %s\n", SvPV(GvSV(errgv),na));
+ if(SvTRUE(ERRSV))
+ fprintf(stderr, "eval error: %s\n", SvPV(ERRSV,n_a));
}
}
-
- perl_destruct_level = 0;
- perl_destruct(perl);
- perl_free(perl);
+
+ PL_perl_destruct_level = 0;
+ perl_destruct(my_perl);
+ perl_free(my_perl);
+ PERL_SYS_TERM();
exit(exitstatus);
}
-
Now compile:
- % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
+ % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
-Here's a example script file:
+Here's an example script file:
#test.pl
my $string = "hello";
foo says: hello
Enter file name: ^C
+=head2 Execution of END blocks
+
+Traditionally END blocks have been executed at the end of the perl_run.
+This causes problems for applications that never call perl_run. Since
+perl 5.7.2 you can specify C<PL_exit_flags |= PERL_EXIT_DESTRUCT_END>
+to get the new behaviour. This also enables the running of END blocks if
+the perl_parse fails and C<perl_destruct> will return the exit value.
+
+=head2 $0 assignments
+
+When a perl script assigns a value to $0 then the perl runtime will
+try to make this value show up as the program name reported by "ps" by
+updating the memory pointed to by the argv passed to perl_parse() and
+also calling API functions like setproctitle() where available. This
+behaviour might not be appropriate when embedding perl and can be
+disabled by assigning the value C<1> to the variable C<PL_origalen>
+before perl_parse() is called.
+
+The F<persistent.c> example above is for instance likely to segfault
+when $0 is assigned to if the C<PL_origalen = 1;> assignment is
+removed. This because perl will try to write to the read only memory
+of the C<embedding[]> strings.
+
=head2 Maintaining multiple interpreter instances
Some rare applications will need to create more than one interpreter
during a session. Such an application might sporadically decide to
-release any resources associated with the interpreter.
+release any resources associated with the interpreter.
The program must take care to ensure that this takes place I<before>
-the next interpreter is constructed. By default, the global variable
-C<perl_destruct_level> is set to C<0>, since extra cleaning isn't
-needed when a program has only one interpreter.
-
-Setting C<perl_destruct_level> to C<1> makes everything squeaky clean:
+the next interpreter is constructed. By default, when perl is not
+built with any special options, the global variable
+C<PL_perl_destruct_level> is set to C<0>, since extra cleaning isn't
+usually needed when a program only ever creates a single interpreter
+in its entire lifetime.
- perl_destruct_level = 1;
+Setting C<PL_perl_destruct_level> to C<1> makes everything squeaky clean:
while(1) {
...
- /* reset global variables here with perl_destruct_level = 1 */
- perl_construct(my_perl);
+ /* reset global variables here with PL_perl_destruct_level = 1 */
+ PL_perl_destruct_level = 1;
+ perl_construct(my_perl);
...
/* clean and reset _everything_ during perl_destruct */
- perl_destruct(my_perl);
- perl_free(my_perl);
+ PL_perl_destruct_level = 1;
+ perl_destruct(my_perl);
+ perl_free(my_perl);
...
/* let's go do it again! */
}
-When I<perl_destruct()> is called, the interpreter's syntax parse tree
-and symbol tables are cleaned up, and global variables are reset.
+When I<perl_destruct()> is called, the interpreter's syntax parse tree
+and symbol tables are cleaned up, and global variables are reset. The
+second assignment to C<PL_perl_destruct_level> is needed because
+perl_construct resets it to C<0>.
Now suppose we have more than one interpreter instance running at the
-same time. This is feasible, but only if you used the
-C<-DMULTIPLICITY> flag when building Perl. By default, that sets
-C<perl_destruct_level> to C<1>.
+same time. This is feasible, but only if you used the Configure option
+C<-Dusemultiplicity> or the options C<-Dusethreads -Duseithreads> when
+building perl. By default, enabling one of these Configure options
+sets the per-interpreter global variable C<PL_perl_destruct_level> to
+C<1>, so that thorough cleaning is automatic and interpreter variables
+are initialized correctly. Even if you don't intend to run two or
+more interpreters at the same time, but to run them sequentially, like
+in the above example, it is recommended to build perl with the
+C<-Dusemultiplicity> option otherwise some interpreter variables may
+not be initialized correctly between consecutive runs and your
+application may crash.
+
+Using C<-Dusethreads -Duseithreads> rather than C<-Dusemultiplicity>
+is more appropriate if you intend to run multiple interpreters
+concurrently in different threads, because it enables support for
+linking in the thread libraries of your system with the interpreter.
Let's give it a try:
int main(int argc, char **argv, char **env)
{
- PerlInterpreter
- *one_perl = perl_alloc(),
- *two_perl = perl_alloc();
+ PerlInterpreter *one_perl, *two_perl;
char *one_args[] = { "one_perl", SAY_HELLO };
char *two_args[] = { "two_perl", SAY_HELLO };
+ PERL_SYS_INIT3(&argc,&argv,&env);
+ one_perl = perl_alloc();
+ two_perl = perl_alloc();
+
+ PERL_SET_CONTEXT(one_perl);
perl_construct(one_perl);
+ PERL_SET_CONTEXT(two_perl);
perl_construct(two_perl);
+ PERL_SET_CONTEXT(one_perl);
perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
+ PERL_SET_CONTEXT(two_perl);
perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
+ PERL_SET_CONTEXT(one_perl);
perl_run(one_perl);
+ PERL_SET_CONTEXT(two_perl);
perl_run(two_perl);
+ PERL_SET_CONTEXT(one_perl);
perl_destruct(one_perl);
+ PERL_SET_CONTEXT(two_perl);
perl_destruct(two_perl);
+ PERL_SET_CONTEXT(one_perl);
perl_free(one_perl);
+ PERL_SET_CONTEXT(two_perl);
perl_free(two_perl);
+ PERL_SYS_TERM();
}
+Note the calls to PERL_SET_CONTEXT(). These are necessary to initialize
+the global state that tracks which interpreter is the "current" one on
+the particular process or thread that may be running it. It should
+always be used if you have more than one interpreter and are making
+perl API calls on both interpreters in an interleaved fashion.
+
+PERL_SET_CONTEXT(interp) should also be called whenever C<interp> is
+used by a thread that did not create it (using either perl_alloc(), or
+the more esoteric perl_clone()).
Compile as usual:
Perl and linked C/C++ routines. Let's take a look some pieces of I<perlmain.c>
to see how Perl does this:
+ static void xs_init (pTHX);
- #ifdef __cplusplus
- # define EXTERN_C extern "C"
- #else
- # define EXTERN_C extern
- #endif
-
- static void xs_init _((void));
-
- EXTERN_C void boot_DynaLoader _((CV* cv));
- EXTERN_C void boot_Socket _((CV* cv));
+ EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
+ EXTERN_C void boot_Socket (pTHX_ CV* cv);
EXTERN_C void
- xs_init()
+ xs_init(pTHX)
{
char *file = __FILE__;
/* DynaLoader is a special case */
% cc -c interp.c `perl -MExtUtils::Embed -e ccopts`
% cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
-Consult L<perlxs> and L<perlguts> for more details.
+Consult L<perlxs>, L<perlguts>, and L<perlapi> for more details.
+
+=head1 Embedding Perl under Win32
+
+In general, all of the source code shown here should work unmodified under
+Windows.
+
+However, there are some caveats about the command-line examples shown.
+For starters, backticks won't work under the Win32 native command shell.
+The ExtUtils::Embed kit on CPAN ships with a script called
+B<genmake>, which generates a simple makefile to build a program from
+a single C source file. It can be used like this:
+
+ C:\ExtUtils-Embed\eg> perl genmake interp.c
+ C:\ExtUtils-Embed\eg> nmake
+ C:\ExtUtils-Embed\eg> interp -e "print qq{I'm embedded in Win32!\n}"
+
+You may wish to use a more robust environment such as the Microsoft
+Developer Studio. In this case, run this to generate perlxsi.c:
+
+ perl -MExtUtils::Embed -e xsinit
+Create a new project and Insert -> Files into Project: perlxsi.c,
+perl.lib, and your own source files, e.g. interp.c. Typically you'll
+find perl.lib in B<C:\perl\lib\CORE>, if not, you should see the
+B<CORE> directory relative to C<perl -V:archlib>. The studio will
+also need this path so it knows where to find Perl include files.
+This path can be added via the Tools -> Options -> Directories menu.
+Finally, select Build -> Build interp.exe and you're ready to go.
+
+=head1 Hiding Perl_
+
+If you completely hide the short forms forms of the Perl public API,
+add -DPERL_NO_SHORT_NAMES to the compilation flags. This means that
+for example instead of writing
+
+ warn("%d bottles of beer on the wall", bottlecount);
+
+you will have to write the explicit full form
+
+ Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);
+
+(See L<perlguts/Background and PERL_IMPLICIT_CONTEXT for the explanation
+of the C<aTHX_>.> ) Hiding the short forms is very useful for avoiding
+all sorts of nasty (C preprocessor or otherwise) conflicts with other
+software packages (Perl defines about 2400 APIs with these short names,
+take or leave few hundred, so there certainly is room for conflict.)
=head1 MORAL
=head1 AUTHOR
-Jon Orwant and <F<orwant@tpj.com>> and Doug MacEachern <F<dougm@osf.org>>,
-with small contributions from Tim Bunce, Tom Christiansen, Hallvard Furuseth,
-Dov Grobgeld, and Ilya Zakharevich.
-
-Check out Doug's article on embedding in Volume 1, Issue 4 of The Perl
-Journal. Info about TPJ is available from http://tpj.com.
-
-February 1, 1997
+Jon Orwant <F<orwant@media.mit.edu>> and Doug MacEachern
+<F<dougm@covalent.net>>, with small contributions from Tim Bunce, Tom
+Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
+Zakharevich.
-Some of this material is excerpted from Jon Orwant's book: I<Perl 5
-Interactive>, Waite Group Press, 1996 (ISBN 1-57169-064-6) and appears
-courtesy of Waite Group Press.
+Doug MacEachern has an article on embedding in Volume 1, Issue 4 of
+The Perl Journal ( http://www.tpj.com/ ). Doug is also the developer of the
+most widely-used Perl embedding: the mod_perl system
+(perl.apache.org), which embeds Perl in the Apache web server.
+Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl
+have used this model for Oracle, Netscape and Internet Information
+Server Perl plugins.
=head1 COPYRIGHT
-Copyright (C) 1995, 1996, 1997 Doug MacEachern and Jon Orwant. All
+Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All
Rights Reserved.
-Although destined for release with the standard Perl distribution,
-this document is not public domain, nor is any of Perl and its
-documentation. Permission is granted to freely distribute verbatim
-copies of this document provided that no modifications outside of
-formatting be made, and that this notice remain intact. You are
-permitted and encouraged to use its code and derivatives thereof in
-your own source code for fun or for profit as you see fit.
+Permission is granted to make and distribute verbatim copies of this
+documentation provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+documentation under the conditions for verbatim copying, provided also
+that they are marked clearly as modified versions, that the authors'
+names and title are unchanged (though subtitles and additional
+authors' names may be added), and that the entire resulting derived
+work is distributed under the terms of a permission notice identical
+to this one.
+
+Permission is granted to copy and distribute translations of this
+documentation into another language, under the above conditions for
+modified versions.
https://perl5.git.perl.org / perl5.git / blobdiff