headers
Florian Ragwitz | 1 Nov 2010 07:14
Picon
Favicon
Gravatar

Documentation for ${^GLOBAL_PHASE}


Hi,

I'm looking for help regarding the documentation of the new variable
${^GLOBAL_PHASE} in the perl core.

All that variable will do is expose the current global interpreter phase
to Perl space, similar to how things like Devel::GlobalDestruction
currently expose "Am I under global destruction?"

Most of the patch, which I'll attach for your convenience, is already
vetted by p5p. What I'm looking for specifically is a place to document
it. Obviously it needs an entry in perlvar, but I don't think explaining
all the details of it there is appropriate. "BEGIN, UNITCHECK, CHECK,
INIT and END" in perlmod explains many things related to
${^GLOBAL_PHASE}, but it does so from the perspective of a single
module, i.e. one compilation unit, for which most of the behaviour of
the new variable is irrelevant, as that's only concert with global
phases. Also it'd seem somewhat unlikely that anyone would look up
"perlmod - Perl modules (packages and symbol tables)" to read about the
phases of the interpreter.

Also, once a place for documenting this is found, I'd also very much
appreciate suggestions on how to actually document it.

Here's some details of the new variable.

Possible values include:

  1. CONSTRUCT
(Continue reading)

Permalink | Reply |
headers
Chas. Owens | 1 Nov 2010 15:55
Picon
Gravatar

Re: Documentation for ${^GLOBAL_PHASE}

On Mon, Nov 1, 2010 at 02:14, Florian Ragwitz <rafl <at> debian.org> wrote:
snip
> Obviously it needs an entry in perlvar, but I don't think explaining
> all the details of it there is appropriate. "BEGIN, UNITCHECK, CHECK,
> INIT and END" in perlmod explains many things related to
> ${^GLOBAL_PHASE}, but it does so from the perspective of a single
> module, i.e. one compilation unit, for which most of the behaviour of
> the new variable is irrelevant, as that's only concert with global
> phases. Also it'd seem somewhat unlikely that anyone would look up
> "perlmod - Perl modules (packages and symbol tables)" to read about the
> phases of the interpreter.
snip

My gut reaction is that the values need to be documented in perlvar in
a similar way to how you have listed them here and a mention of it
should be in each paragraph of perlmod that deals with BEGIN, INIT,
etc.  I will throw something together tonight.

--

-- 
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.
Permalink | Reply |
headers
Chas. Owens | 2 Nov 2010 15:36
Picon
Gravatar

Re: Documentation for ${^GLOBAL_PHASE}

On Mon, Nov 1, 2010 at 10:55, Chas. Owens <chas.owens <at> gmail.com> wrote:
> On Mon, Nov 1, 2010 at 02:14, Florian Ragwitz <rafl <at> debian.org> wrote:
> snip
>> Obviously it needs an entry in perlvar, but I don't think explaining
>> all the details of it there is appropriate. "BEGIN, UNITCHECK, CHECK,
>> INIT and END" in perlmod explains many things related to
>> ${^GLOBAL_PHASE}, but it does so from the perspective of a single
>> module, i.e. one compilation unit, for which most of the behaviour of
>> the new variable is irrelevant, as that's only concert with global
>> phases. Also it'd seem somewhat unlikely that anyone would look up
>> "perlmod - Perl modules (packages and symbol tables)" to read about the
>> phases of the interpreter.
> snip
>
> My gut reaction is that the values need to be documented in perlvar in
> a similar way to how you have listed them here and a mention of it
> should be in each paragraph of perlmod that deals with BEGIN, INIT,
> etc.  I will throw something together tonight.
snip

I have attached my first draft of the documentation (they include
brian d foy's changes from last night).

Also attached is a patch that adds a mention of the fact that string
do and require behave the same way as string eval with respect to UNIT
and INIT blocks.

--

-- 
Chas. Owens
wonkden.net
(Continue reading)

Permalink | Reply |
headers
Florian Ragwitz | 2 Nov 2010 18:02
Picon
Favicon
Gravatar

Re: Documentation for ${^GLOBAL_PHASE}

"Chas. Owens" <chas.owens <at> gmail.com> writes:

> I have attached my first draft of the documentation (they include
> brian d foy's changes from last night).

You're awesome. Thank you *so* much!

> diff --git a/pod/perlmod.pod b/pod/perlmod.pod
> index d6ddd83..44d5924 100644
> --- a/pod/perlmod.pod
> +++ b/pod/perlmod.pod
>  <at>  <at>  -273,6 +273,11  <at>  <at>  and such from other files in time to be visible to the rest of the compile
>  and run time.  Once a C<BEGIN> has run, it is immediately undefined and any
>  code it used is returned to Perl's memory pool.
>
> +Inside of a C<BEGIN> block, the C<${^GLOBAL_PHASE}> variable will be set to
> +C<"START">, unless the C<BEGIN> block was executed by C<require>, string
> +C<do>, or string C<eval>.  In those cases the C<${^GLOBAL_PHASE}> will be
> +set to the phase the C<require>, C<do>, or string C<eval> was executed in.

I find that rather confusing.

Of course ${^GLOBAL_PHASE} is, during a certain phase, always set to the
phase that's currently running :-)

Saying that a value of "START" will only be present in some BEGIN-blocks
is a little misleading. While that's true, as everything where
${^GLOBAL_PHASE} will have a value of "START" will be run from a
BEGIN-block in the main program, it's easy to get that value from code
which doesn't directly contain such a block. For example
(Continue reading)

Permalink | Reply |
headers
Tim Bunce | 4 Nov 2010 11:58
Picon
Favicon

Re: Documentation for ${^GLOBAL_PHASE}

[Sorry I'm late to comment on this.]

On Tue, Nov 02, 2010 at 10:36:25AM -0400, Chas. Owens wrote:
> On Mon, Nov 1, 2010 at 10:55, Chas. Owens <chas.owens <at> gmail.com> wrote:
> > On Mon, Nov 1, 2010 at 02:14, Florian Ragwitz <rafl <at> debian.org> wrote:
> > snip
> >> Obviously it needs an entry in perlvar, but I don't think explaining
> >> all the details of it there is appropriate. "BEGIN, UNITCHECK, CHECK,
> >> INIT and END" in perlmod explains many things related to
> >> ${^GLOBAL_PHASE}, but it does so from the perspective of a single
> >> module, i.e. one compilation unit, for which most of the behaviour of
> >> the new variable is irrelevant, as that's only concert with global
> >> phases. Also it'd seem somewhat unlikely that anyone would look up
> >> "perlmod - Perl modules (packages and symbol tables)" to read about the
> >> phases of the interpreter.

I strongly agree.

> > My gut reaction is that the values need to be documented in perlvar in
> > a similar way to how you have listed them here and a mention of it
> > should be in each paragraph of perlmod that deals with BEGIN, INIT,
> > etc.  I will throw something together tonight.
> 
> I have attached my first draft of the documentation (they include
> brian d foy's changes from last night).
> 
> Also attached is a patch that adds a mention of the fact that string
> do and require behave the same way as string eval with respect to UNIT
> and INIT blocks.
(Continue reading)

Permalink | Reply |
headers
Florian Ragwitz | 4 Nov 2010 12:11
Picon
Favicon
Gravatar

Re: Documentation for ${^GLOBAL_PHASE}

Tim Bunce <Tim.Bunce <at> pobox.com> writes:

> On Tue, Nov 02, 2010 at 10:36:25AM -0400, Chas. Owens wrote:
>
> are full of "unless", "So long as" and "In those cases" indicates a
> problem.
>
> The description of BEGIN and UNITCHECK suggests that the documentation
> is approaching the topic from the wrong point of view. I suggest
> removing the above and just saying something like:
>
>     BEGIN and UNITCHECK blocks are unrelated to the phase of the
>     interpreter.  They can be created and executed during any phase.

I like the suggestion, but I'm not sure it's entirely true. "Anything
directly or indirectly run from a BEGIN-block in the top-level
compilation unit" exactly describes when ${^GLOBAL_PHASE} will be set to
"START". That may or may not be a good way to think about the START
phase.

For UNITCHECK it's right.
Permalink | Reply |
headers
Tim Bunce | 4 Nov 2010 14:30
Picon
Favicon

Re: Documentation for ${^GLOBAL_PHASE}

On Thu, Nov 04, 2010 at 12:11:39PM +0100, Florian Ragwitz wrote:
> Tim Bunce <Tim.Bunce <at> pobox.com> writes:
> 
> > On Tue, Nov 02, 2010 at 10:36:25AM -0400, Chas. Owens wrote:
> >
> > are full of "unless", "So long as" and "In those cases" indicates a
> > problem.
> >
> > The description of BEGIN and UNITCHECK suggests that the documentation
> > is approaching the topic from the wrong point of view. I suggest
> > removing the above and just saying something like:
> >
> >     BEGIN and UNITCHECK blocks are unrelated to the phase of the
> >     interpreter.  They can be created and executed during any phase.
> 
> I like the suggestion, but I'm not sure it's entirely true. "Anything
> directly or indirectly run from a BEGIN-block in the top-level
> compilation unit" exactly describes when ${^GLOBAL_PHASE} will be set to
> "START". That may or may not be a good way to think about the START
> phase.
> 
> For UNITCHECK it's right.

Let's loosen it a little then:

    BEGIN and UNITCHECK blocks are not directly related to the phase of the
    interpreter.  They can be created and executed during any phase.

Tim.
(Continue reading)

Permalink | Reply |
headers
Florian Ragwitz | 12 Nov 2010 22:52
Picon
Favicon
Gravatar

Re: Documentation for ${^GLOBAL_PHASE}

"Chas. Owens" <chas.owens <at> gmail.com> writes:

> I have attached my first draft of the documentation (they include
> brian d foy's changes from last night).

So i've tried to prepare a new branch with the original patch set
rebased against blead and your documentation added. However, I don't
seem to be able to find the changes brian made that you based your work
on.

Where exactly can i find that?
Permalink | Reply |
headers
Chas. Owens | 12 Nov 2010 23:34
Picon
Gravatar

Re: Documentation for ${^GLOBAL_PHASE}

On Fri, Nov 12, 2010 at 16:52, Florian Ragwitz <rafl <at> debian.org> wrote:
> "Chas. Owens" <chas.owens <at> gmail.com> writes:
>
>> I have attached my first draft of the documentation (they include
>> brian d foy's changes from last night).
>
> So i've tried to prepare a new branch with the original patch set
> rebased against blead and your documentation added. However, I don't
> seem to be able to find the changes brian made that you based your work
> on.
>
> Where exactly can i find that?
>

They were made to bleed:
http://perl5.git.perl.org/perl.git/commit/10c97e5d9fc40b1bf201fdd404df828778e564ed

I just realized that I owe you an updated version with things change
per your last email.

--

-- 
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.
Permalink | Reply |
headers
brian d foy | 1 Nov 2010 21:55
Picon
Gravatar

Re: Documentation for ${^GLOBAL_PHASE}

In article <87pquppo2s.fsf <at> tardis.home.perldition.org>, Florian Ragwitz
<rafl <at> debian.org> wrote:

> I'm looking for help regarding the documentation of the new variable
> ${^GLOBAL_PHASE} in the perl core.

Note that there's a new perlvar in briandfoy/perlvar about to be merged
into blead.
Permalink | Reply |

Gmane