Clarify build options in perlembed doc #15573

p5pRT · 2016-08-31T12:57:30Z

Migrated from rt.perl.org#129151 (status was 'open')

Searchable as RT129151$

p5pRT · 2016-08-31T12:57:30Z

From [email protected]

https://metacpan.org/source/RJBS/perl-5.24.0/pod/perlembed.pod#L920
https://metacpan.org/source/RJBS/perl-5.24.0/pod/perlembed.pod#L933

At above lines in perlembed doc it mentions options "-Dusethreads
-Duseithreads". But useithreads is mostly documented nowhere else. And
today this is always equivalent to a single "-Dusethreads", which is
mentioned in Perl INSTALL doc. IMHO mentioning both "-Dusethreads
-Duseithreads" can confuse people. And I would suggest change these two
places to "-Dusethreads".

btw, while that paragraph at
https://metacpan.org/source/RJBS/perl-5.24.0/pod/perlembed.pod#L933 talks
about running multiple interpreters in multiple OS threads, the example
after it (at
https://metacpan.org/source/RJBS/perl-5.24.0/pod/perlembed.pod#L941) is
just about interleaving two interpreters in one thread. I wonder if we can
add an example for multiple OS threads.

Thanks,
Zhenyi

p5pRT · 2016-09-01T22:59:58Z

From @jkeenan

On Wed Aug 31 05:57:30 2016, zhouzhen1@gmail.com wrote:

https://metacpan.org/source/RJBS/perl-5.24.0/pod/perlembed.pod#L920
https://metacpan.org/source/RJBS/perl-5.24.0/pod/perlembed.pod#L933

At above lines in perlembed doc it mentions options "-Dusethreads
-Duseithreads".

I should note that these lines are unchanged since 2001.

But useithreads is mostly documented nowhere else.

Actually, 'useithreads' is extensively discussed in pod/perlthrtut.pod.

And
today this is always equivalent to a single "-Dusethreads", which is
mentioned in Perl INSTALL doc.

What is your source for the equivalence of "-Dusethreads" and "-Duseithreads"? (I'm not enough of a threads user/expert to confirm that statement. I do know that when I do smoke tests for FreeBSD, I include '-Duseithreads' because that's how the system perl on that OS is configured.)

IMHO mentioning both "-Dusethreads
-Duseithreads" can confuse people. And I would suggest change these two
places to "-Dusethreads".

I suspect you are correct, but I think we need input from people who know more about threads than I do.

btw, while that paragraph at
https://metacpan.org/source/RJBS/perl-5.24.0/pod/perlembed.pod#L933 talks
about running multiple interpreters in multiple OS threads, the example
after it (at
https://metacpan.org/source/RJBS/perl-5.24.0/pod/perlembed.pod#L941) is
just about interleaving two interpreters in one thread. I wonder if we can
add an example for multiple OS threads.

Again, need comment from more informed people.

Thanks,
Zhenyi

--
James E Keenan (jkeenan@cpan.org)

p5pRT · 2016-09-01T22:59:59Z

The RT System itself - Status changed from 'new' to 'open'

p5pRT · 2016-09-03T07:26:37Z

From [email protected]

I should note that these lines are unchanged since 2001.

IMHO while these lines are still effective today, they actually can be updated.

Actually, 'useithreads' is extensively discussed in pod/perlthrtut.pod.

That doc has also not been updated for long I guess.

I believe today both $Config{useithreads} and $Config{usethreads}
would return "define" on all of below cases (, at some time in history
they may not all work though):
* -Dusethread -Duseithread
* -Dusethread
* -Duseithread

Since Perl 5.6 (https://metacpan.org/source/GSAR/perl-5.6.0/INSTALL#L623)
"-Dusethread" has been equivalent to "-Dusethread -Duseithread", and
the notion of "-Duseithreads" was to differentiate with
"-Duse5005threads". But since 5.10 the 5005threads mode has been
completely removed from Perl.

What is your source for the equivalence of "-Dusethreads" and "-Duseithreads"?

I read the Configure script of Perl source.

Also there are below links indicating it's not just me find it
confusing. (I really doubt the observations in the second link. )
http://www.perlmonks.org/?node_id=581365
http://ptxdist.pengutronix.narkive.com/0eqK2XJ5/how-to-configure-perl-scripting-to-compile-with-thread-support

On 9/2/16, James E Keenan via RT <perlbug-followup@perl.org> wrote:

On Wed Aug 31 05:57:30 2016, zhouzhen1@gmail.com wrote:

https://metacpan.org/source/RJBS/perl-5.24.0/pod/perlembed.pod#L920
https://metacpan.org/source/RJBS/perl-5.24.0/pod/perlembed.pod#L933

At above lines in perlembed doc it mentions options "-Dusethreads
-Duseithreads".

I should note that these lines are unchanged since 2001.

But useithreads is mostly documented nowhere else.

Actually, 'useithreads' is extensively discussed in pod/perlthrtut.pod.

And
today this is always equivalent to a single "-Dusethreads", which is
mentioned in Perl INSTALL doc.

What is your source for the equivalence of "-Dusethreads" and
"-Duseithreads"? (I'm not enough of a threads user/expert to confirm that
statement. I do know that when I do smoke tests for FreeBSD, I include
'-Duseithreads' because that's how the system perl on that OS is
configured.)

IMHO mentioning both "-Dusethreads
-Duseithreads" can confuse people. And I would suggest change these two
places to "-Dusethreads".

I suspect you are correct, but I think we need input from people who know
more about threads than I do.

btw, while that paragraph at
https://metacpan.org/source/RJBS/perl-5.24.0/pod/perlembed.pod#L933 talks
about running multiple interpreters in multiple OS threads, the example
after it (at
https://metacpan.org/source/RJBS/perl-5.24.0/pod/perlembed.pod#L941) is
just about interleaving two interpreters in one thread. I wonder if we
can
add an example for multiple OS threads.

Again, need comment from more informed people.

Thanks,
Zhenyi

--
James E Keenan (jkeenan@cpan.org)

---
via perlbug: queue: perl5 status: new
https://rt-archive.perl.org/perl5/Ticket/Display.html?id=129151

--
Regards,
Zhenyi Zhou

p5pRT · 2016-09-03T17:36:51Z

From @jkeenan

On Sat Sep 03 00:26:37 2016, zhouzhen1@gmail.com wrote:
[snip]

I believe today both $Config{useithreads} and $Config{usethreads}
would return "define" on all of below cases (, at some time in history
they may not all work though):
* -Dusethread -Duseithread
* -Dusethread
* -Duseithread

In blead, if you configure with '-Dusethreads' only, you will get in %Config:

#####
useithreads define
...
usethreads define
#####

However, to further muddy the waters, in the output of './perl -Ilib -V', you will only get:

#####
config_args='-des -Dusedevel -Dusethreads'
...
useithreads=define
#####

That is, you will *not* get an entry for 'usethreads' in the output of './perl -Ilib -V'. (It is that output which the Perl 5 Porters request as part of bug reports.)

In any event, I agree that for someone trying to embed 'perl', it would probably be less confusing to be told to say '-Dusethreads'. I am attaching a patch for that purpose. Please review.

The second point raised by the OP still needs discussion by others.

Thank you very much.

--
James E Keenan (jkeenan@cpan.org)

p5pRT · 2016-09-03T17:36:51Z

From @jkeenan

129151-0001-Dusethreads-and-Duseithreads-are-now-equivalent.patch

From d37ee6359f609a9d9fab7f69dd3a9543aa25e416 Mon Sep 17 00:00:00 2001
From: James E Keenan <[email protected]>
Date: Sat, 3 Sep 2016 12:04:50 -0400
Subject: [PATCH] '-Dusethreads' and '-Duseithreads' are now equivalent.

So, to reduce confusion for users trying to embed perl, mention only the
former, as it's more self-documenting (even though only 'useithreads=define'
is what currently shows up in 'perl -V').

Per recommendation by Zhenyi Zhou. For RT #129151.
---
 pod/perlembed.pod | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index 7bc7a8c..a9b36f2 100644
--- a/pod/perlembed.pod
+++ b/pod/perlembed.pod
@@ -917,7 +917,7 @@ 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
+C<-Dusemultiplicity> or the option C<-Dusethreads> 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
@@ -930,7 +930,7 @@ application may crash.
 
 See also L<perlxs/Thread-aware system interfaces>.
 
-Using C<-Dusethreads -Duseithreads> rather than C<-Dusemultiplicity>
+Using C<-Dusethreads> rather than C<-Dusemultiplicity>
 is more appropriate if you intend to run multiple interpreters
 concurrently in different threads, because it enables support for
 linking in the thread libraries of your system with the interpreter.
-- 
2.7.4

p5pRT · 2016-09-03T22:56:28Z

From @jkeenan

On Sat Sep 03 00:26:37 2016, zhouzhen1@gmail.com wrote:
[snip]

I believe today both $Config{useithreads} and $Config{usethreads}
would return "define" on all of below cases (, at some time in history
they may not all work though):
* -Dusethread -Duseithread
* -Dusethread
* -Duseithread

In blead, if you configure with '-Dusethreads' only, you will get in %Config:

#####
useithreads define
...
usethreads define
#####

However, to further muddy the waters, in the output of './perl -Ilib -V', you will only get:

#####
config_args='-des -Dusedevel -Dusethreads'
...
useithreads=define
#####

That is, you will *not* get an entry for 'usethreads' in the output of './perl -Ilib -V'. (It is that output which the Perl 5 Porters request as part of bug reports.)

In any event, I agree that for someone trying to embed 'perl', it would probably be less confusing to be told to say '-Dusethreads'. I am attaching a patch for that purpose. Please review.

The second point raised by the OP still needs discussion by others.

Thank you very much.

--
James E Keenan (jkeenan@cpan.org)

p5pRT · 2016-09-03T22:56:28Z

From @jkeenan

129151-0001-Dusethreads-and-Duseithreads-are-now-equivalent.patch

From d37ee6359f609a9d9fab7f69dd3a9543aa25e416 Mon Sep 17 00:00:00 2001
From: James E Keenan <[email protected]>
Date: Sat, 3 Sep 2016 12:04:50 -0400
Subject: [PATCH] '-Dusethreads' and '-Duseithreads' are now equivalent.

So, to reduce confusion for users trying to embed perl, mention only the
former, as it's more self-documenting (even though only 'useithreads=define'
is what currently shows up in 'perl -V').

Per recommendation by Zhenyi Zhou. For RT #129151.
---
 pod/perlembed.pod | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index 7bc7a8c..a9b36f2 100644
--- a/pod/perlembed.pod
+++ b/pod/perlembed.pod
@@ -917,7 +917,7 @@ 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
+C<-Dusemultiplicity> or the option C<-Dusethreads> 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
@@ -930,7 +930,7 @@ application may crash.
 
 See also L<perlxs/Thread-aware system interfaces>.
 
-Using C<-Dusethreads -Duseithreads> rather than C<-Dusemultiplicity>
+Using C<-Dusethreads> rather than C<-Dusemultiplicity>
 is more appropriate if you intend to run multiple interpreters
 concurrently in different threads, because it enables support for
 linking in the thread libraries of your system with the interpreter.
-- 
2.7.4

p5pRT · 2016-09-03T23:52:07Z

From @craigberry

On Thu, Sep 1, 2016 at 5:59 PM, James E Keenan via RT
<perlbug-followup@perl.org> wrote:

What is your source for the equivalence of "-Dusethreads" and "-Duseithreads"?

The authority on what's configurable is Configure. See:

http://perl5.git.perl.org/perl.git/blob/HEAD:/Configure#l4376

Interpreter threads have long been the only option for threads,
5005threads having been long since deprecated. I guess if someone
came up with an entirely new threading model, there could
theoretically be some future distinction between threads and ithreads,
but it seems unlikely.

This fixes Perl#15573

This fixes #15573

p5pRT added Severity Low documentation labels Oct 19, 2019

xenu removed the Severity Low label Dec 29, 2021

khwilliamson added a commit to khwilliamson/perl5 that referenced this issue May 4, 2025

perlembed, perlthrtut, Clarify threads vs ithreads

a5f284a

This fixes Perl#15573

khwilliamson mentioned this issue May 4, 2025

perlembed, perlthrtut, Clarify threads vs ithreads #23254

Merged

khwilliamson added a commit to khwilliamson/perl5 that referenced this issue May 4, 2025

perlembed, perlthrtut, Clarify threads vs ithreads

e21b820

This fixes Perl#15573

khwilliamson added a commit to khwilliamson/perl5 that referenced this issue May 7, 2025

perlembed, perlthrtut, Clarify threads vs ithreads

ac176ae

This fixes Perl#15573

khwilliamson added a commit that referenced this issue May 8, 2025

perlembed, perlthrtut, Clarify threads vs ithreads

9205e6a

This fixes #15573

khwilliamson closed this as completed in #23254 May 8, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarify build options in perlembed doc #15573

Clarify build options in perlembed doc #15573

p5pRT commented Aug 31, 2016

p5pRT commented Aug 31, 2016

p5pRT commented Sep 1, 2016

p5pRT commented Sep 1, 2016

p5pRT commented Sep 3, 2016

p5pRT commented Sep 3, 2016

p5pRT commented Sep 3, 2016

p5pRT commented Sep 3, 2016

p5pRT commented Sep 3, 2016

p5pRT commented Sep 3, 2016

Clarify build options in perlembed doc #15573

Clarify build options in perlembed doc #15573

Comments

p5pRT commented Aug 31, 2016

p5pRT commented Aug 31, 2016

From [email protected]

p5pRT commented Sep 1, 2016

From @jkeenan

p5pRT commented Sep 1, 2016

p5pRT commented Sep 3, 2016

From [email protected]

p5pRT commented Sep 3, 2016

From @jkeenan

p5pRT commented Sep 3, 2016

From @jkeenan

p5pRT commented Sep 3, 2016

From @jkeenan

p5pRT commented Sep 3, 2016

From @jkeenan

p5pRT commented Sep 3, 2016

From @craigberry