another threads reliability fix: serialize writes to thr->threadsv

avoid most uses of PL_na (which is much more inefficient than a
simple local); update docs to suit; PL_na now being thr->Tna may
be a minor compatibility issue for extensions--will require dTHR
outside of XSUBs (those get automatic dTHR)

p4raw-id: //depot/perl@2387

4 files changed, 34 insertions, 20 deletions

diff --git a/pod/perlcall.pod b/pod/perlcall.pod
index c239cfe324..e3e02de613 100644
--- a/pod/perlcall.pod
+++ b/pod/perlcall.pod
@@ -971,7 +971,8 @@ and some C to call it
         /* Check the eval first */
         if (SvTRUE(ERRSV))
         {
-            printf ("Uh oh - %s\n", SvPV(ERRSV, PL_na)) ;
+	    STRLEN n_a;
+            printf ("Uh oh - %s\n", SvPV(ERRSV, n_a)) ;
             POPs ;
         }
         else
@@ -1013,7 +1014,8 @@ The code
 
     if (SvTRUE(ERRSV))
     {
-        printf ("Uh oh - %s\n", SvPV(ERRSV, PL_na)) ;
+	STRLEN n_a;
+        printf ("Uh oh - %s\n", SvPV(ERRSV, n_a)) ;
         POPs ;
     }
 
diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index c09d6e33cb..1314350f9e 100644
--- a/pod/perlembed.pod
+++ b/pod/perlembed.pod
@@ -285,6 +285,7 @@ the first, a C<float> from the second, and a C<char *> from the third.
    
    main (int argc, char **argv, char **env)
    {
+       STRLEN n_a;
        char *embedding[] = { "", "-e", "0" };
    
        my_perl = perl_alloc();
@@ -303,7 +304,7 @@ the first, a C<float> from the second, and a C<char *> from the third.
    
        /** Treat $a as a string **/
        perl_eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
-       printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), PL_na));
+       printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), n_a));
    
        perl_destruct(my_perl);
        perl_free(my_perl);
@@ -325,8 +326,9 @@ possible and in most cases a better strategy to fetch the return value
 from I<perl_eval_pv()> instead.  Example:
 
    ...
+   STRLEN n_a;
    SV *val = perl_eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
-   printf("%s\n", SvPV(val,PL_na));
+   printf("%s\n", SvPV(val,n_a));
    ...
 
 This way, we avoid namespace pollution by not creating global
@@ -371,6 +373,7 @@ been wrapped here):
  {
      dSP;
      SV* retval;
+     STRLEN n_a;
  
      PUSHMARK(SP);
      perl_eval_sv(sv, G_SCALAR);
@@ -380,7 +383,7 @@ been wrapped here):
      PUTBACK;
  
      if (croak_on_error && SvTRUE(ERRSV))
- 	croak(SvPVx(ERRSV, PL_na));
+ 	croak(SvPVx(ERRSV, n_a));
  
      return retval;
  }
@@ -395,9 +398,10 @@ been wrapped here):
  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,PL_na), pattern);
+ 	      SvPV(string,n_a), pattern);
  
      retval = my_perl_eval_sv(command, TRUE);
      SvREFCNT_dec(command);
@@ -416,9 +420,10 @@ been wrapped here):
  I32 substitute(SV **string, char *pattern)
  {
      SV *command = NEWSV(1099, 0), *retval;
+     STRLEN n_a;
  
      sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
- 	      SvPV(*string,PL_na), pattern);
+ 	      SvPV(*string,n_a), pattern);
  
      retval = my_perl_eval_sv(command, TRUE);
      SvREFCNT_dec(command);
@@ -439,9 +444,10 @@ been wrapped here):
  {
      SV *command = NEWSV(1099, 0);
      I32 num_matches;
+     STRLEN n_a;
  
      sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
- 	      SvPV(string,PL_na), pattern);
+ 	      SvPV(string,n_a), pattern);
  
      my_perl_eval_sv(command, TRUE);
      SvREFCNT_dec(command);
@@ -459,6 +465,7 @@ been wrapped here):
      AV *match_list;
      I32 num_matches, i;
      SV *text = NEWSV(1099,0);
+     STRLEN n_a;
  
      perl_construct(my_perl);
      perl_parse(my_perl, NULL, 3, embedding, NULL);
@@ -480,7 +487,7 @@ been wrapped here):
      printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
  
      for (i = 0; i < num_matches; i++)
- 	printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),PL_na));
+ 	printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),n_a));
      printf("\n");
  
      /** Remove all vowels from text **/
@@ -488,7 +495,7 @@ been wrapped here):
      if (num_matches) {
  	printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
  	       num_matches);
- 	printf("Now text is: %s\n\n", SvPV(text,PL_na));
+ 	printf("Now text is: %s\n\n", SvPV(text,n_a));
      }
  
      /** Attempt a substitution **/
@@ -726,6 +733,7 @@ with L<perlfunc/my> whenever possible.
      char *args[] = { "", DO_CLEAN, NULL };
      char filename [1024];
      int exitstatus = 0;
+     STRLEN n_a;
 
      if((perl = perl_alloc()) == NULL) {
         fprintf(stderr, "no memory!");
@@ -747,7 +755,7 @@ with L<perlfunc/my> whenever possible.
 
             /* check $@ */
             if(SvTRUE(ERRSV))
-                fprintf(stderr, "eval error: %s\n", SvPV(ERRSV,PL_na));
+                fprintf(stderr, "eval error: %s\n", SvPV(ERRSV,n_a));
         }
      }
 
diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index b835b59a38..38d75691f2 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -95,7 +95,8 @@ or string.
 
 In the C<SvPV> macro, the length of the string returned is placed into the
 variable C<len> (this is a macro, so you do I<not> use C<&len>).  If you do not
-care what the length of the data is, use the global variable C<PL_na>.  Remember,
+care what the length of the data is, use the global variable C<PL_na>, though
+this is rather less efficient than using a local variable.  Remember,
 however, that Perl allows arbitrary strings of data that may both contain
 NULs and might not be terminated by a NUL.
 
@@ -1636,7 +1637,7 @@ the SV which holds the name of the sub being debugged.  This is the C
 variable which corresponds to Perl's $DB::sub variable.  See C<PL_DBsingle>.
 The sub name can be found by
 
-	SvPV( GvSV( PL_DBsub ), PL_na )
+	SvPV( GvSV( PL_DBsub ), len )
 
 =item PL_DBtrace
 
@@ -1856,7 +1857,8 @@ Returns the key slot of the hash entry as a C<char*> value, doing any
 necessary dereferencing of possibly C<SV*> keys.  The length of
 the string is placed in C<len> (this is a macro, so do I<not> use
 C<&len>).  If you do not care about what the length of the key is,
-you may use the global variable C<PL_na>.  Remember though, that hash
+you may use the global variable C<PL_na>, though this is rather less
+efficient than using a local variable.  Remember though, that hash
 keys in perl are free to contain embedded nulls, so using C<strlen()>
 or similar is not a good way to find the length of hash keys.
 This is very similar to the C<SvPV()> macro described elsewhere in
@@ -2179,8 +2181,9 @@ the type.  Can do overlapping moves.  See also C<Copy>.
 
 =item PL_na
 
-A variable which may be used with C<SvPV> to tell Perl to calculate the
-string length.
+A convenience variable which is typically used with C<SvPV> when one doesn't
+care about the length of the string.  It is usually more efficient to
+declare a local variable and use that instead.
 
 =item New
 
@@ -3008,8 +3011,7 @@ Checks the B<private> setting.  Use C<SvPOK>.
 =item SvPV
 
 Returns a pointer to the string in the SV, or a stringified form of the SV
-if the SV does not contain a string.  If C<len> is C<PL_na> then Perl will
-handle the length on its own.  Handles 'get' magic.
+if the SV does not contain a string.  Handles 'get' magic.
 
 	char*	SvPV (SV* sv, int len )
 
diff --git a/pod/perlxs.pod b/pod/perlxs.pod
index 2e022477ea..89ddf3e132 100644
--- a/pod/perlxs.pod
+++ b/pod/perlxs.pod
@@ -553,9 +553,10 @@ The XS code, with ellipsis, follows.
           time_t timep = NO_INIT
 	  PREINIT:
           char *host = "localhost";
+	  STRLEN n_a;
           CODE:
 		  if( items > 1 )
-		       host = (char *)SvPV(ST(1), PL_na);
+		       host = (char *)SvPV(ST(1), n_a);
 		  RETVAL = rpcb_gettime( host, &timep );
           OUTPUT:
           timep
@@ -786,9 +787,10 @@ prototypes.
 	  PROTOTYPE: $;$
 	  PREINIT:
           char *host = "localhost";
+	  STRLEN n_a;
           CODE:
 		  if( items > 1 )
-		       host = (char *)SvPV(ST(1), PL_na);
+		       host = (char *)SvPV(ST(1), n_a);
 		  RETVAL = rpcb_gettime( host, &timep );
           OUTPUT:
           timep