Mailing List Archive

DAVEM TPF Grant#3 January, February 2024 report
(this report covers two months)

This is my monthly report on work done during Jan,Feb 2024 covered by my
TPF perl core maintenance grant.


I spent the last two months mainly on two goals.

1) Understanding XS better so that I can then decide how to update the XS
ecosystem to better support a reference-counted stack; as an example,
automatically removing the need to call XSUBs via a wrapper in some
circumstances.

Doing this led me down a rabbit hole of realising how awful our current XS
documentation is. Just about every section I read resulted in confusion,
followed by time out to experiment and/or to look at the ParseXS src code
to try to understand what the documentation was trying to tell me. It's
also very out of date: telling us of exciting "new" features introduced 25
years ago.

The net result of this is that I now have about 1000 lines of notes on
"things to fix in the XS docs". I intend sometime soon to completely
revamp perlxs.pod and perlxstut.pod, based on these notes. Which is a bit
of sidetrack from getting XS working better under PERL_RC_STACK builds.
And doing PERL_RC_STACK was itself initially a sidetrack from doing more
work on perl signatures. Such is often the way when working on perl.

2) General small tasks to help get blead into shape for the 5.40 release,
such as analysing and reducing smoke failures, fixing bugs, and fixing any
Deparse regressions that have crept in over the last year.

SUMMARY:
0:38 #21822: BBC: Blead Breaks Variable::Magic
1:20 #21876: BBC: 5.39.7 breaks GONZUS/Cache-utLRU-0.002000.tar.gz
3:21 #21969: clone-with-stack.t crash
2:17 fix Test -deparse failures
1:35 fix minitest failures
3:39 make __LINE__ etc Deparse batter
1:57 make stack reference counted
30:30 make stack reference counted - XS
19:46 process p5p mailbox
1:28 reduce build stderr noise
8:33 reduce smoke failures
------
75:04 TOTAL (HH::MM)

--
Overhead, without any fuss, the stars were going out.
-- Arthur C Clarke
Re: DAVEM TPF Grant#3 January, February 2024 report [ In reply to ]
Hi there,

On Mon, 4 Mar 2024, Dave Mitchell wrote:

> (this report covers two months)

I'd been wondering... :)

> ... rabbit hole of realising how awful our current XS documentation is.

This isn't a rabbit hole. This is good stuff.

> ... exciting "new" features introduced 25 years ago.

Quite so. It's embarrassing.

> ... I now have about 1000 lines of notes on "things to fix in the XS
> docs". I intend sometime soon to completely revamp perlxs.pod and
> perlxstut.pod, based on these notes.

Good man. It desperately needs to be done.

> Which is a bit of sidetrack from getting XS working better ...

But it's more important, if you want the work to mean anything in the
longer term. If the documentation is cr@p then after struggling with
it for a few minutes people will just walk away. I've done that many
times with open source software. The main reason I'm still around is
because there's something called the Camel Book, but now the distance
between the Camel Book and reality is increasing and soon all that we
will have for reference will be online documentation. It needs to be
at least as good as the Camel Book was (and I'd be happy to pick nits
with The Book all day - it's far from perfect, but it's on my desk).
Frankly I'm not a fan of online documentation, but if it's bad online
documentation I have a lot less patience with it than I do with paper
because on my paper copy I can write stuff and put those sticky notes
all over the place to use for example as bookmarks. There are dozens
of them in my copy of the Camel Book.

Thank you for your continued excellent efforts.

--

73,
Ged.
Re: DAVEM TPF Grant#3 January, February 2024 report [ In reply to ]
On Mon, 4 Mar 2024 10:34:26 +0000, Dave Mitchell <davem@iabyn.com> wrote:

> (this report covers two months)
>
> This is my monthly report on work done during Jan,Feb 2024 covered by my
> TPF perl core maintenance grant.
>
>
> I spent the last two months mainly on two goals.

I can feel the frustration, but in the end, this might be one of the
best net results I have read in your reports. Many will be happy with
the updated docs, including me

THANK YOU!
(also for all the other awesome work)

> 1) Understanding XS better so that I can then decide how to update the XS
> ecosystem to better support a reference-counted stack; as an example,
> automatically removing the need to call XSUBs via a wrapper in some
> circumstances.
>
> Doing this led me down a rabbit hole of realising how awful our current XS
> documentation is. Just about every section I read resulted in confusion,
> followed by time out to experiment and/or to look at the ParseXS src code
> to try to understand what the documentation was trying to tell me. It's
> also very out of date: telling us of exciting "new" features introduced 25
> years ago.
>
> The net result of this is that I now have about 1000 lines of notes on
> "things to fix in the XS docs". I intend sometime soon to completely
> revamp perlxs.pod and perlxstut.pod, based on these notes. Which is a bit
> of sidetrack from getting XS working better under PERL_RC_STACK builds.
> And doing PERL_RC_STACK was itself initially a sidetrack from doing more
> work on perl signatures. Such is often the way when working on perl.
>
> 2) General small tasks to help get blead into shape for the 5.40 release,
> such as analysing and reducing smoke failures, fixing bugs, and fixing any
> Deparse regressions that have crept in over the last year.
>
> SUMMARY:
> 0:38 #21822: BBC: Blead Breaks Variable::Magic
> 1:20 #21876: BBC: 5.39.7 breaks GONZUS/Cache-utLRU-0.002000.tar.gz
> 3:21 #21969: clone-with-stack.t crash
> 2:17 fix Test -deparse failures
> 1:35 fix minitest failures
> 3:39 make __LINE__ etc Deparse batter
> 1:57 make stack reference counted
> 30:30 make stack reference counted - XS
> 19:46 process p5p mailbox
> 1:28 reduce build stderr noise
> 8:33 reduce smoke failures
> ------
> 75:04 TOTAL (HH::MM)
>


--
H.Merijn Brand https://tux.nl Perl Monger http://amsterdam.pm.org/
using perl5.00307 .. 5.37 porting perl5 on HP-UX, AIX, and Linux
https://tux.nl/email.html http://qa.perl.org https://www.test-smoke.org
Re: DAVEM TPF Grant#3 January, February 2024 report [ In reply to ]
On Mon, Mar 4, 2024 at 5:34?AM Dave Mitchell <davem@iabyn.com> wrote:

>
> The net result of this is that I now have about 1000 lines of notes on
> "things to fix in the XS docs". I intend sometime soon to completely
> revamp perlxs.pod and perlxstut.pod, based on these notes.
>

I'm excited for this work!


>
> SUMMARY:
> 0:38 #21822: BBC: Blead Breaks Variable::Magic
> 1:20 #21876: BBC: 5.39.7 breaks GONZUS/Cache-utLRU-0.002000.tar.gz
> 3:21 #21969: clone-with-stack.t crash
> 2:17 fix Test -deparse failures
> 1:35 fix minitest failures
> 3:39 make __LINE__ etc Deparse batter
> 1:57 make stack reference counted
> 30:30 make stack reference counted - XS
> 19:46 process p5p mailbox
> 1:28 reduce build stderr noise
> 8:33 reduce smoke failures
> ------
> 75:04 TOTAL (HH::MM)
>

Thanks Dave. +1 from me.

-- Matthew Horsfall (alh)