What is the public API in respect to PL_* variables?

[Jan Dubois]

We markup functions in embed.fnc to indicate if they are part of
the public API or not. And then we use PERL_CORE to hide private
functions by default from XS code.

The reason I'm bringing this up is that Devel::Declare is not
building with Perl 5.8.8/5.8.9 on Windows because it accesses
the PL_linestart and PL_sublex_info, and those are explicit *not*
exported in makedef.pl (on Windows only).

I haven't been able to figure out _why_ they are not exported,
but assume the reason was that they were supposed to be private.

I talked about this with rafl on IRC, and his position was that
every symbol defined in the header files that is not protected
by PERL_CORE is part of the public API, so not exporting these
symbols on Windows is a Perl bug that maybe should be worked
around using Devel-PPPort.h.

So one question is: are PL_linestart and PL_sublex_info part of
the public API and therefore should be exported?

But the bigger question is: Are all PL_* symbols part of the public
API, and if not, how do we document which ones are public?

Cheers,
-Jan

[Rafael Garcia-Suarez]

On 17 March 2010 19:06, Jan Dubois <ja...@activestate.com> wrote:
> So one question is: are PL_linestart and PL_sublex_info part of
> the public API and therefore should be exported?
>
> But the bigger question is: Are all PL_* symbols part of the public
> API, and if not, how do we document which ones are public?

I would be inclined to think that all PL_* variables should be public, yes.

[Nicholas Clark]

On Thu, Mar 18, 2010 at 10:48:31AM +0100, Rafael Garcia-Suarez wrote:
> On 17 March 2010 19:06, Jan Dubois <ja...@activestate.com> wrote:
> > So one question is: are PL_linestart and PL_sublex_info part of
> > the public API and therefore should be exported?

This is not a question I had really considered.

> > But the bigger question is: Are all PL_* symbols part of the public
> > API, and if not, how do we document which ones are public?
>
> I would be inclined to think that all PL_* variables should be public, yes.

In which case we would need a different naming convention for variables that
need to be shared between compilation units, but aren't public to the world.

In doing maint releases, I always assumed the worst - that anything *visible*
might have been linked against, and hence changing it in an incompatible way
might cause something to break in such a way that the end user would blame
the perl upgrade, whatever the true cause was.

But that was about "not breaking crazy things" rather than "where is the
boundary between genius and insanity?"

Nicholas Clark

[Nicholas Clark]

On Wed, Mar 17, 2010 at 11:06:40AM -0700, Jan Dubois wrote:

> I talked about this with rafl on IRC, and his position was that
> every symbol defined in the header files that is not protected
> by PERL_CORE is part of the public API, so not exporting these
> symbols on Windows is a Perl bug that maybe should be worked
> around using Devel-PPPort.h.

From an implementation point of view, that is tricky, surely?

Nicholas Clark

[Jan Dubois]

Not really, but I had simplified what actually happens in my original
message, so it may not be obvious:

Perl doesn't actually export PL_linestart, but Perl_Ilinestart_ptr(),
which just returns the address of the Ilinestart member of the
perl_interpreter structure, and PL_linestart is defined as

#define PL_linestart *(Perl_Ilinestart_ptr(aTHX))

when PERL_CORE is not defined[*]. So Devel::PPPort just has to pretend to
be inside PERL_CORE and do:

#undef PL_linestart
#define PL_linestart (aTHX->Ilinestart)

It is actually the Perl_Ilinestart_ptr symbol that isn't exported;
the actual structure offset for Ilinestart can always be computed
as a compiletime constant from intrpvar.h

Cheers,
-Jan

[*] The whole reason for redirecting access to structure members through
a function call was to be able to modify structures without affecting
binary compatibility. I'll argue that we should get rid of this layer
once 5.12.1 has shipped (meaning, I don't want to argue about it now).

[Nicholas Clark]

On Thu, Mar 18, 2010 at 10:10:24AM -0700, Jan Dubois wrote:

> [*] The whole reason for redirecting access to structure members through
> a function call was to be able to modify structures without affecting
> binary compatibility. I'll argue that we should get rid of this layer
> once 5.12.1 has shipped (meaning, I don't want to argue about it now).

So I'm not allowed to agree until then? :-)

Nicholas Clark