develooper Front page | perl.perl5.porters | Postings from July 2020

Re: Asking for help in deciding what functions should be in the API

Thread Previous | Thread Next
From:
Tony Cook
Date:
July 27, 2020 05:58
Subject:
Re: Asking for help in deciding what functions should be in the API
Message ID:
20200727055759.GC4099@mars.tony.develop-help.com
On Sun, Jul 26, 2020 at 09:09:43PM -0600, Karl Williamson wrote:
> Tl;Dr  Please scan the list below for functions, variables, and macros that
> really XS writers have no business accessing directly.
> 
> There are about 200 functions and macros that Devel::PPPort thinks are
> public, in the API, but for which there is no documentation.  This is
> somewhat more than perlapi lists as being public but not documented.
> 
> I view this as scandalous.  We apparently have a bunch more things
> implemented that could make contributors' lives easier, if only they knew
> about them.  Just yesterday I stumbled on delimcpy, undocumented. I asked
> sisyphus earlier about several function that he was unaware of and it turns
> that could have helped him solve a problem last year.
> 
> The bottom line is that it hurts us to have this sub-tribal knowledge hidden
> away.
> 
> I suspect that Devel::PPPort is thinking more of these functions are API
> than really are, due to flaws in it.  And others in the list shouldn't be
> API either.  Just today I discovered that my_stat, while listed as API,
> can't actually be being used, as it is simply a wrapper macro that
> immediately calls a function not accessible outside the perl core; hence
> will lead to a loader error if used.
> 
> I'm hoping those of you who are familiar with using XS and interfacing with
> the API functions will scan the list below for things that really only the
> core should be using.  Like all the PL_foo variables.  I bet most of those
> should not be used directly outside the core, but rather only though macros
> and functions that are public.
> 
> I've already cut this list down by dozens, either by documenting things I
> know about or that I thought I could learn sufficiently, or by deciding that
> they shouldn't be in the API.  Afterwards is the  list of those.  Correct me
> if I'm wrong.
> 
> Maybe the problem isn't as bad as it appears.
> 
> Things I'm particularly suspicious of are the PL_ variables, the things that
> create OPs (I'm not sure that XS should be doing that), dumping functions
> 
>  amagic_call
>  amagic_deref_call

Both should be API so XS code can resolve overloaded operators.

>  any_dup

Used on CPAN and I think it's reasonable for use in XS.

>  atfork_lock
>  atfork_unlock

Needed so code that forks can lock correctly, and for calls to PTHREAD_ATFORK()

>  block_gimme

API.

>  call_atexit

API (so modules can register function to call when perl exits)

>  call_list

API (it isn't essential, but it's useful utility)

>  clear_defarray

API (but I don't expect to see much usage)

>  clone_params_del
>  clone_params_new

Both definitely API (see perl5140delta)

>  deb
>  deb_nocontext

Both definitely API

>  debop
>  debprofdump
>  debstack
>  debstackptrs

API, mostly for debugging.

>  despatch_signals

This may need to be visible, but I don't think anything should be
directly calling it (including win32_async_check()), since we have
PL_signalhook.

That's about as far as I can go through this list for now.

I think this list needs to be worked on incrementally, both in
determining which are APIs and actual documentation.

Tony

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About