perlembed, perlthrtut, Clarify threads vs ithreads

This fixes #15573

Author: khwilliamson

pod/perlembed.pod

@@ -927,16 +927,26 @@ 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
-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.
+C<-Dusemultiplicity> or either of 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.
+
+(It used to be that there were two forms of threads, with C<ithreads>
+appearing later.  But C<ithreads> proved to be superior, and support for
+the older model was removed in Perl v5.10.  But the documentation and
+code have never been purged of the earlier terminology; and perhaps some
+newer model will come along to supplant C<ithreads>, so it seems best to
+retain both.  If you don't care about the threading model used, use
+plain C<threads> to protect your code from having to change with future
+developments.  If your code is dependent on the C<ithreads> model, use
+C<ithreads> to make sure you will always get that.)
 
 See also L<perlclib/Dealing with embedded perls and threads>.
 

pod/perlthrtut.pod

@@ -25,6 +25,13 @@ have C<use5005threads=define> you have 5.005 threads.
 If you have neither, you don't have any thread support built in.
 If you have both, you are in trouble.
 
+In more modern times, the terms C<ithreads> and C<threads> are
+synonymous, and are used interchangeably.  The best practice is to use
+C<ithreads> if your code is dependent on something specific about that
+implementation, and to use C<threads> if it isn't.  That way, in the
+very unlikely event that some new threading model comes along, your code
+is more protected from needing to change.
+
 The L<threads> and L<threads::shared> modules are included in the core Perl
 distribution.  Additionally, they are maintained as separate modules on
 CPAN, so you can check there for any updates.