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>,
-included in the source distribution. Here's a bastardized, nonportable
+included in the source distribution. Here's a bastardized, non-portable
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_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:
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_destruct(my_perl);
perl_free(my_perl);
+ PERL_SYS_TERM();
}
where I<showtime> is a Perl subroutine that takes no arguments (that's the
STRLEN n_a;
char *embedding[] = { "", "-e", "0" };
+ PERL_SYS_INIT3(&argc,&argv,&env);
my_perl = perl_alloc();
perl_construct( my_perl );
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> and L<perlapi>.
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
+store the computed value of our eval'ed expression. It is also
possible and in most cases a better strategy to fetch the return value
from I<eval_pv()> instead. Example:
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
-within the C<AV> at 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(SV *string, char *pattern, AV **matches);
I32 match(SV *string, char *pattern)
{
- SV *command = NEWSV(1099, 0), *retval;
+ SV *command = newSV(0), *retval;
STRLEN n_a;
sv_setpvf(command, "my $string = '%s'; $string =~ %s",
I32 substitute(SV **string, char *pattern)
{
- SV *command = NEWSV(1099, 0), *retval;
+ SV *command = newSV(0), *retval;
STRLEN n_a;
sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
I32 matches(SV *string, char *pattern, AV **match_list)
{
- SV *command = NEWSV(1099, 0);
+ SV *command = newSV(0);
I32 num_matches;
STRLEN n_a;
SV *text;
STRLEN n_a;
+ PERL_SYS_INIT3(&argc,&argv,&env);
my_perl = perl_alloc();
perl_construct(my_perl);
perl_parse(my_perl, NULL, 3, embedding, NULL);
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");
+ text = newSV(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");
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)
{
char *my_argv[] = { "", "power.pl" };
+ PERL_SYS_INIT3(&argc,&argv,&env);
my_perl = perl_alloc();
perl_construct( my_perl );
perl_destruct(my_perl);
perl_free(my_perl);
+ PERL_SYS_TERM();
}
#define DO_CLEAN 0
#endif
+ #define BUFFER_SIZE 1024
+
static PerlInterpreter *my_perl = NULL;
int
{
char *embedding[] = { "", "persistent.pl" };
char *args[] = { "", DO_CLEAN, NULL };
- char filename [1024];
+ char filename[BUFFER_SIZE];
int exitstatus = 0;
STRLEN n_a;
+ PERL_SYS_INIT3(&argc,&argv,&env);
if((my_perl = perl_alloc()) == NULL) {
fprintf(stderr, "no memory!");
exit(1);
}
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: ") && gets(filename)) {
+ 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;
call_argv("Embed::Persistent::eval_file",
PL_perl_destruct_level = 0;
perl_destruct(my_perl);
perl_free(my_perl);
+ PERL_SYS_TERM();
exit(exitstatus);
}
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_prase fails and C<perl_destruct> will return the exit value.
+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
Setting C<PL_perl_destruct_level> to C<1> makes everything squeaky clean:
- PL_perl_destruct_level = 1;
-
while(1) {
...
/* 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 */
+ PL_perl_destruct_level = 1;
perl_destruct(my_perl);
perl_free(my_perl);
...
}
When I<perl_destruct()> is called, the interpreter's syntax parse tree
-and symbol tables are cleaned up, and global variables are reset.
+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 Configure option
C<-Dusemultiplicity> or the options C<-Dusethreads -Duseithreads> when
-building Perl. By default, enabling one of these Configure options
+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.
+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.
+
+See also L<perlxs/Thread-aware system interfaces>.
Using C<-Dusethreads -Duseithreads> rather than C<-Dusemultiplicity>
is more appropriate if you intend to run multiple interpreters
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_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
=head1 Hiding Perl_
If you completely hide the short forms forms of the Perl public API,
-add -DPERL_HIDE_SHORT_NAMES to the compilation flags. This means that
+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);
=head1 AUTHOR
-Jon Orwant <F<orwant@tpj.com>> and Doug MacEachern
-<F<dougm@osf.org>>, with small contributions from Tim Bunce, Tom
+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.
have used this model for Oracle, Netscape and Internet Information
Server Perl plugins.
-July 22, 1998
-
=head1 COPYRIGHT
Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All
https://perl5.git.perl.org / perl5.git / blobdiff