embedding perl

Message-Id: <20030805.205715.113441323.radu@yx.primIT.ro>

p4raw-id: //depot/perl@21514

1 files changed, 15 insertions, 7 deletions

diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index bfa925474a..05feccd1bc 100644
--- a/pod/perlembed.pod
+++ b/pod/perlembed.pod
@@ -381,7 +381,7 @@ returns 1 if the string matches the pattern and 0 otherwise.
 
 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);
@@ -841,7 +841,7 @@ 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_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 Maintaining multiple interpreter instances
 
@@ -858,14 +858,14 @@ in its entire lifetime.
 
 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);
      ...
@@ -873,14 +873,22 @@ Setting C<PL_perl_destruct_level> to C<1> makes everything squeaky clean:
  }
 
 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.
 
 Using C<-Dusethreads -Duseithreads> rather than C<-Dusemultiplicity>
 is more appropriate if you intend to run multiple interpreters