From ac176ae4e2b2b0316c14ed9c0b95bd8da60213ee Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Sat, 3 May 2025 20:50:29 -0600 Subject: [PATCH 1/2] perlembed, perlthrtut, Clarify threads vs ithreads This fixes #15573 --- pod/perlembed.pod | 31 +++++++++++++++++++++---------- pod/perlthrtut.pod | 11 ++++++++++- 2 files changed, 31 insertions(+), 11 deletions(-) diff --git a/pod/perlembed.pod b/pod/perlembed.pod index 520da51fabc6..66c20de3e93c 100644 --- a/pod/perlembed.pod +++ b/pod/perlembed.pod @@ -927,16 +927,27 @@ 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 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 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 +appearing later. But C 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, so it seems best to +retain both. If you don't care about the threading model used, use +plain C to protect your code from having to change with future +developments. If your code is dependent on the C model, use +C to make sure you will always get that. This applies as well +to the C language symbols C and C.) See also L. diff --git a/pod/perlthrtut.pod b/pod/perlthrtut.pod index 4a121210310a..d8635f486878 100644 --- a/pod/perlthrtut.pod +++ b/pod/perlthrtut.pod @@ -13,7 +13,7 @@ between threads must be explicit. The user-level interface for I uses the L class. B: There was another older Perl threading flavor called the 5.005 model -that used the L class. This old model was known to have problems, is +that used the L class. This old model was known to have problems, was deprecated, and was removed for release 5.10. You are strongly encouraged to migrate any existing 5.005 threads code to the new model as soon as possible. @@ -25,6 +25,15 @@ have C 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 and C are +synonymous, and are used interchangeably. The best practice is to use +C if your code is dependent on something specific about that +implementation, and to use C 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 corresponding symbols at +the C language level are C and C; these are +currently totally synonymous, but not absolutely guaranteed to remain so.) + The L and L 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. From be4a09dd1d983eb0da660bbc0cec1527bd81a611 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Wed, 7 May 2025 05:31:06 -0600 Subject: [PATCH 2/2] lib/Thread.pm: Fix typo --- lib/Thread.pm | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/Thread.pm b/lib/Thread.pm index 70bcac3898aa..3c1ac9e21bdb 100644 --- a/lib/Thread.pm +++ b/lib/Thread.pm @@ -4,7 +4,7 @@ use strict; use warnings; no warnings 'redefine'; -our $VERSION = '3.05'; +our $VERSION = '3.06'; $VERSION = eval $VERSION; BEGIN { @@ -61,7 +61,7 @@ In Perl 5.005, the thread model was that all data is implicitly shared, and shared access to data has to be explicitly synchronized. This model is called I<5005threads>. -In Perl 5.6, a new model was introduced in which all is was thread local and +In Perl 5.6, a new model was introduced in which all data is thread local and shared access to data has to be explicitly declared. This model is called I, for "interpreter threads".