Clarify build options in perlembed doc

[p5pRT]

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

Searchable as RT129151$

[p5pRT]

From zhouzhen1@gmail.com

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]

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]

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

[p5pRT]

From zhouzhen1@gmail.com

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]

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]

From @jkeenan

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

From d37ee6359f609a9d9fab7f69dd3a9543aa25e416 Mon Sep 17 00:00:00 2001
From: James E Keenan <jkeenan@cpan.org>
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]

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]

From @jkeenan

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

From d37ee6359f609a9d9fab7f69dd3a9543aa25e416 Mon Sep 17 00:00:00 2001
From: James E Keenan <jkeenan@cpan.org>
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]

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.