Re: PPC: Document pattern of symbols reserved for Perl in XS code

On Fri, 6 Feb 2026 15:36:40 -0700
Karl Williamson <[email protected]> wrote:

> XS writers don't know what symbols to avoid creating for their own
> purposes.
> 
> Thousands of undocumented Perl symbols are exposed to XS code.  Many
> C symbols are as well.  However, C furnishes a template giving their 
> syntax.  Basically, anything matching the template is a reserved word 
> for the C implementation.
> 
> I am proposing that we do the same, and the one regen/embed.pl
> currently is using is
> 
> Any symbol beginning with "PL_"
> Any symbol containing perl, Perl, or PERL, usually delimitted on
>      both sides so as to keep it from being part of a larger word.
> 
> POSIX feels free to add new functions that could possibly collide
> with ones in existing code.  'atomic_int', for example in Posix 2024.
>  I think we can do the same.
> 
> Many symbols we've created end in an underscore, as an undocumented 
> attempt to indicate that these are not intended for public use.  Tony 
> Cook has pointed out that other projects that use Perl do the same.
> I'm proposing that we thus restrict ourselves further for new symbols
> to ending in
> 
>   m/ _ [[:alnum:]]* pl_ \z /x
> 
> And document this.

That sounds a useful thing to do, but I'm not sure if the PPC document
process is the best way forward for it.. That's usually more for Perl
source-visible new features, or at least new core features that XS
authors could use to eventually provide features.

At the very least, I don't think the usual document template for a PPC
doc is the best shape for this.

This feels more like it's just "write some docs in a PR" territory.

-- 
Paul "LeoNerd" Evans

[email protected]
http://www.leonerd.org.uk/  |  https://metacpan.org/author/PEVANS