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 | 9 comments |
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 | 7 comments |
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 | 0 comments |
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 | 0 comments |
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 | 1 comment |
headers
Shlomi Fish | 7 Nov 2010 20:23
Picon
Gravatar

Re: [PATCH] perlipc.pod Revamp

OK, now replying in detail.

On Monday 01 November 2010 19:49:54 Tom Christiansen wrote:
> Thank you for your edits.  I agree with most of them.
> 
> A lot of these are just personal style things.  It's nearly not worth
> commenting on.  My own style *has* gotten more regular since I wrote that,
> but not much looks too seriously different from how I'd write things today.
> This is mostly quibbling, although there are a few genuine items that
> reauire addressing.
> 
> I haven't read the replies yet.
> 
> >+    our $shucks = 0;
> 
> I'm always nervous about initializing a global through our().
> You should only do so once, but nothing guarantees that you do.
> I'd never such in an example, because it's too fragile.
> 

Well, without this our declaration, the example won't pass "use strict;", so I 
had to add it. Would "my" be better here? "my" should work I think But I 
wasn't sure about it.

> >     sub catch_zap {
> >     
> >         my $signame = shift;
> >
> >+
> >
(Continue reading)

Permalink | Reply | 38 comments |
headers
Shlomi Fish | 8 Nov 2010 00:18
Picon
Gravatar

Re: [PATCH] perlipc.pod Revamp

On Sunday 07 November 2010 22:37:44 Paul Johnson wrote:
> On Sun, Nov 07, 2010 at 03:32:12PM -0500, Jesse Vincent wrote:
> > On Sun, Nov 07, 2010 at 09:23:54PM +0200, Shlomi Fish wrote:
> > > > >     eval {
> > > > >
> > > > >-        local $SIG{ALRM} = sub { die "alarm clock restart" };
> > > > >+
> > > > >+        local $SIG{ALRM} = sub { die "alarm clock restart"; };
> > > > 
> > > > No new semicolon.
> > > 
> > > OK, who gets to veto this?
> > 
> > That may well be me. I'm not a fan of those ;s.
> 
> Or how about Larry?
> 
> See perlstyle.pod.

I see. I removed these semicolons here:

https://github.com/shlomif/perl/tree/perlipc-revamp

Thanks!

Regards,

	Shlomi Fish

--

--
(Continue reading)

Permalink | Reply | 0 comments |
headers
Shlomi Fish | 8 Nov 2010 15:14
Picon
Gravatar

Re: [PATCH] perlipc.pod Revamp

On Monday 08 November 2010 15:45:02 demerphq wrote:
> On 7 November 2010 20:23, Shlomi Fish <shlomif <at> iglu.org.il> wrote:
> >> >     } else {     # child
> >> > 
> >> >         ($EUID, $EGID) = ($UID, $GID); # suid progs only
> >> >
> >> >-        open (FILE, "> /safe/file")
> >> >-            || die "can't open /safe/file: $!";
> >> >+        open (my $file, ">", "/safe/file")
> >> 
> >> Why?  There is 100.00000000000% chance that that will behave.
> >> It's a constant string of known content.
> > 
> > Still, we should not encourage such potentially bad idioms. Here it is
> > harmless, but people can learn that it's OK to do ">$myfile" too.
> 
> If the intent of these changes is to demonstrate a better style, then
> I would expect the filename to be stored in a var so that it isn't
> duplicated in the error message.

Good point.

> 
> Also, im not sure that i agree that changing open(FILE, ... ) to
> open(my $file, ...) is very sensible, in that to me it is not clear
> what "$file" is (in my coding style such a var would almost always be
> a file /name/), whereas FILE is very clearly a handle, accordingly I
> would tend to use var names like $out_fh for a write handle and $in_fh
> for a read handle, in particular I almost always suffix the var with
> '_fh' or something to make it clear that it is not the name of a file
(Continue reading)

Permalink | Reply | 3 comments |
headers
Tom Christiansen | 8 Nov 2010 16:27
Favicon

Re: [PATCH] perlipc.pod Revamp

What the heck is this:
	
    Section 5 of the F<modules> file is devoted to "Networking, Device Control
    (modems), and Interprocess Communication", and contains numerous unbundled
    modules numerous networking modules, Chat and Expect operations, CGI
    programming, DCE, FTP, IPC, NNTP, Proxy, Ptty, RPC, SNMP, SMTP, Telnet,
    Threads, and ToolTalk--just to name a few.

What "modules" file is this talking about?

--tom
Permalink | Reply | 2 comments |
headers
Tom Christiansen | 8 Nov 2010 19:19
Favicon

authorial perlipc edit

Yves wrote:

> If the intent of these changes is to demonstrate a better style, then
> I would expect the filename to be stored in a var so that it isn't
> duplicated in the error message.

Quite.

> Also, im not sure that i agree that changing open(FILE, ... ) to
> open(my $file, ...) is very sensible, 

Ayup.

> in that to me it is not clear what "$file" is (in my coding style such
> a var would almost always be a file /name/), whereas FILE is very
> clearly a handle, accordingly I would tend to use var names like
> $out_fh for a write handle and $in_fh for a read handle, in particular
> I almost always suffix the var with '_fh' or something to make it
> clear that it is not the name of a file but a handle to one.

Yes, that also.

> IOW, (respecting Tom's style expectations):

***Thank you.***

>    my $safe_file = "/safe/file";
>    open(my $safe_fh, ">", $safe_file) 
>	|| die "Failed to open '$safe_file' for writing: $!";
(Continue reading)

Permalink | Reply | 27 comments |

Gmane