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

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

Thread Next
From:
Karl Williamson
Date:
July 27, 2020 03:09
Subject:
Asking for help in deciding what functions should be in the API
Message ID:
ac05264d-d2bb-dc11-9f05-ce019d74cd08@khwilliamson.com
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
  any_dup
  atfork_lock
  atfork_unlock
  block_gimme
  call_atexit
  call_list
  clear_defarray
  clone_params_del
  clone_params_new
  deb
  deb_nocontext
  debop
  debprofdump
  debstack
  debstackptrs
  despatch_signals
  dirp_dup
  do_aspawn
  do_close
  do_join
  do_open
  do_openn
  doref
  do_spawn
  do_spawn_nowait
  dowantarray
  dump_eval
  dump_form
  dump_mstats
  dump_sub
  dXSTARG
  filter_del
  fp_dup
  get_context
  get_mstats
  get_op_descs
  get_op_names
  get_ppaddr
  get_vtbl
  gp_dup
  gp_free
  gp_ref
  gv_add_by_type
  Gv_AMupdate
  gv_AVadd
  gv_dump
  gv_efullname3
  gv_efullname4
  gv_fullname3
  gv_fullname4
  gv_handler
  gv_HVadd
  gv_IOadd
  gv_name_set
  he_dup
  hek_dup
  hv_delayfree_ent
  hv_eiter_p
  hv_eiter_set
  hv_free_ent
  hv_ksplit
  hv_name_set
  hv_placeholders_get
  hv_placeholders_set
  hv_rand_set
  hv_riter_p
  hv_riter_set
  init_stacks
  init_tm
  is_lvalue_sub
  leave_scope
  magic_dump
  markstack_grow
  mfree
  mg_dup
  mg_size
  mro_get_from_name
  mro_set_mro
  my_chsize
  my_cxt_init
  my_dirfd
  my_failure_exit
  my_fflush_all
  my_fork
  my_pclose
  my_popen
  my_popen_list
  my_socketpair
  newANONATTRSUB
  newANONHASH
  newANONLIST
  newANONSUB
  newAVREF
  newCVREF
  newFORM
  newGVgen
  newGVgen_flags
  newGVREF
  newHVhv
  newHVREF
  newIO
  newMYSUB
  newPROG
  newRV
  new_stackinfo
  newSVREF
  op_refcnt_lock
  op_refcnt_unlock
  parser_dup
  perl_alloc_using
  perl_clone_using
  PerlIO_context_layers
  PerlIO_fill
  PerlIO_unread
  PL_compiling
  PL_DBsignal
  PL_debstash
  PL_diehook
  PL_dirty
  PL_hints
  PL_laststatval
  PL_mess_sv
  PL_no_modify
  PL_perldb
  PL_ppaddr
  PL_signals
  PL_stack_base
  PL_stack_sp
  PL_statcache
  PL_stdingv
  PL_sv_arenaroot
  PL_tainted
  PL_tainting
  PL_Xpv
  pmop_dump
  pop_scope
  pregfree
  ptr_table_fetch
  ptr_table_free
  ptr_table_new
  ptr_table_split
  ptr_table_store
  push_scope
  re_compile
  repeatcpy
  rsignal_state
  rvpv_dup
  save_adelete
  save_aelem
  save_aelem_flags
  save_alloc
  save_generic_pvref
  save_generic_svref
  save_hdelete
  save_helem
  save_helem_flags
  save_hints
  save_op
  save_padsv_and_mortalize
  save_pushi32ptr
  save_pushptr
  save_pushptrptr
  save_set_svflags
  save_shared_pvref
  savestack_grow
  savestack_grow_cnt
  save_vptr
  scan_vstring
  seed
  set_context
  share_hek
  si_dup
  ss_dup
  start_subparse
  sv_2pvutf8_flags
  SV_CONST_RETURN
  SV_COW_SHARED_HASH_KEYS
  sv_dup
  sv_dup_inc
  sv_len_utf8_nomg
  SV_MUTABLE_RETURN
  sv_peek
  sys_intern_clear
  sys_intern_dup
  sys_intern_init
  unsharepvn
  vdeb
  XSprePUSH

Things I've removed from the above list; correct me if I made a mistake. 
  Some of these are because we have a macro (that should be documented 
if it isn't already) that we prefer to be used instead.  Such as CXINC 
vs cxinc,  I haven't listed most of those that I've changed in a branch
av_arylen_p
av_iter_p
cast_i32
cast_iv
cast_ulong
cast_uv
csighandler
csighandler1
csighandler3
cx_dump
cx_dup
do_gv_dump
do_gvgv_dump
do_hv_dump
do_op_dump
do_pmop_dump
do_sprintf
do_sv_dump
dounwind
dump_indent
dump_vindent
gv_check
hv_assert
hv_common
hv_common_key_len
moreswitches
newSVsv_flags
pad_setsv
perly_sighandler
pregfree2
regdump
regexec_flags
regfree_internal
reginitcolors
reg_named_buff_all
reg_named_buff_exists
reg_named_buff_fetch
reg_named_buff_firstkey
reg_named_buff_nextkey
reg_named_buff_scalar
regnext
runops_debug
runops_standard
stack_grow
str_to_version
sv_2pv
sys_init
sys_init3

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