Front page | perl.perl5.porters |
Postings from August 2016
Re: Internals:: undocumented
Thread Previous
|
Thread Next
From:
demerphq
Date:
August 8, 2016 13:24
Subject:
Re: Internals:: undocumented
Message ID:
CANgJU+X8hHn2Fi4J2W=vqeGBjqKraLyi+FxCa1xX6jrwizngmQ@mail.gmail.com
This is response to three mails at once, which I will summarize here,
and then put more details below:
Internals:: shouldn't exist as a namespace. That it exists, and what
it contains is wrong and evil. Documenting wrong and evil just makes
things worse, because people might actually read the documentation and
decide to increase the amount of wrong and evil in the universe.
Instead, even if it is short term more work we should act to reduce
the amount of wrong and evil in the universe. The way to do so here is
to get rid of the Internals:: namespace.
Luckily the Internals namespace contains only three functions. Two
dangerous ones where you can sort of understand why they ended up in a
namespace like Internals, and one which really should have ended up
elsewhere.
So I propose:
0. We should move hv_clear_placeholders() out of Internals:: and put
it in Hash::Util.
1. We should remove SvREFCNT() from Internals::, and replace it with a
set/get pair, possibly which live in different namespaces. I don't
think any Perl code outside of our test suite has any reason to ever
set a refcount.
2. We should remove SvREADONLY() from Internals, and replace it with a
set_readonly() function and a is_readonly() function which is injected
into the namespaces where it is used, for instance Hash::Util and
constant.pm.
On 8 August 2016 at 12:51, Dave Mitchell <davem@iabyn.com> wrote:
> On Sun, Aug 07, 2016 at 12:25:14PM +0200, demerphq wrote:
>> On 7 Aug 2016 11:34, "Sawyer X" <xsawyerx@gmail.com> wrote:
>> >
>> > On 08/06/2016 03:39 PM, Tony Cook wrote:
>> > > On Sat, Aug 06, 2016 at 09:05:23AM -0400, James E Keenan wrote:
>> > >> What is Internals?
>> > > Internals is deliberately undocumented, unsupported.
>> >
>> > Not documenting as a form of keeping possible users away feels like
>> > security by obscurity. Documentation should not imply support. We can
>> > document it clearly for other core developers and note *very* clearly
>> > that it is unsupported.
>>
>> I don't agree. We document indirectly those functions that are intended to
>> be user serviceable. The rest imo should not be documented because they
>> should not exist but do because they are needed to test perl. Furthermore
>> they are typically documented at the XS or perl internals level, and all
>> the perl level functions do is expose internals routines.
>>
>> I also think that if we are going to document them we should move them to
>> better namespace.
>
> We already document non-API C functions - see pod/perlintern.pod - so
> there is a precedent for documenting non-API functions. Personally I think
> we should
>
> 1) Keep the Internals:: namespace as-is;
> 2) If there's something in that namespace which is general-purpose enough
> that it deserves to be part of the API, then give it a new name in
> a different namespace (probably maintaining the old name for
> compatibility);
These are related points, and is what I meant when i said "move them
to a better namespace".
Or to put it differently, anything that is in Internals that has a
good case to be generally exposed should be exposed via a different
namespace.
> 3) Create pod/Internals.pod which explains what the purpose of the
> Internals:: namespace is for, the fact that non-core isn't allowed to
> use it, and that the (non-)API can change without notice; then
> document each function in the Internals:: namespace - even if its
> just to say that its just a perl wrapper for a C function.
As far as I can tell there are three functions in Internals.
SvREFCNT(), SvREADONLY() and hv_clear_placeholders().
I don't think we should document any of them at the perl level.
SvREFCNT() is properly documented in sv.h, so is SvREADONLY(). The
only people who should be using either are people that know the C
code. If we /must/ document them somewhere then IMO we should add a
note to the perlguts docs on the two functions. If we /must/ document
the Internals namespace we should simply specify that the namespace is
reserved, and is used to facilitate core test and library development
by providing simple wrappers to internals routines which should never
be used or depended on by non-core code.
hv_clear_placeholders() has no reason nor excuse for being in
Internals. It could have just as easily been injected or moved
outright into Hash::Util as that is the only place it is used. IMO
moving this function should occur before we document anything.
Part of the reason I feel strongly about this is that we DO document
the things that legitimately USE these functions, and we DO document
the C level behaviour and meaning of these functions. I think the only
purpose served by documenting them at the Perl level is for someone to
use them when they shouldn't, which means that they create a backwards
compatibility problem that we do not want to have. Both of the Sv
functions are inherently dangerous, and should never be used by anyone
but a core internals hacker.
For instance SvREADONLY() is used in producing constants, and along
with hv_clear_placeholders() for locking and unlocking and unlocking
hashes. We document how to produce a constant in constant.pm, and we
document how to lock and unlock hashes in Hash::Util. I see no reason
we should document the underlying C/Perl internals API call that
currently /happens/ to implement this behavior.
SvREFCNT() is used in testing, and arguably should not exist, and
instead should be exposed via an extension, perhaps Devel::Peek, or
perhaps some build time only module.
In other words, I would like people to reconsider this situation from
a more holistic perspective. When you problem this issue as "we have
undocumented stuff", you could respond with "ok so lets document it",
or you could ask "why is it undocumented", and on seeing the answer in
historical context ask "can we /get rid of it/ instead of documenting
it".
So in response to this:
On 7 August 2016 at 20:11, Father Chrysostomos <sprout@cpan.org> wrote:
> demerphq wrote:
>> I also think that if we are going to document them we should move them
>> to better namespace.
>
> For Internals::SvREADONLY, that would just cause problems, because
> constant.pm lives a dual life and needs to call it from Internals:: on
> older perls. Adding extra logic to constant.pm just for that does not
> seem worthwhile.
>
My answer is that I think eliminating the Internals namespace entirely
seems a reasonable cost.
I wonder, do you think we should document constant::_make_const()?
IMO that function has far more call being documented than anything in
the Internals namespace.
On 7 August 2016 at 19:09, Karl Williamson <public@khwilliamson.com> wrote:
> They should be documented in the source or perlguts or perlhacktips, so
> people like me would know about their existence.
Yes, this seems reasonable providing we continue to expose them via Internals::
> This is the first I've
> heard of them, and I've been working on the core for coming up 7 years now.
While I realize you are implying this is bad, I think it is just as
reasonable to say that not having them documented does not appear to
have impacted your ability to hack on Perl. :-)
> There is a difference between encouraging external use and letting porters
> know the existence of things that could make their lives easier,
I suggest that had you really needed what Internals contained you
would have quickly found it. I say this as someone who has needed
them, and I readily found them.
Anyway, I really think that we would be far better off removing the
Internals namespace than we would be documenting it.
Yves
--
perl -Mre=debug -e "/just|another|perl|hacker/"
Thread Previous
|
Thread Next