Gain control of macro namespace visibility

embed.fnc

@@ -1117,7 +1117,7 @@ Adpr	|OP *	|die_sv 	|NN SV *baseex
 : Used in util.c
 pr	|void	|die_unwind	|NN SV *msv
 : FIXME
-mp	|bool	|do_aexec	|NULLOK SV *really			\
+m	|bool	|do_aexec	|NULLOK SV *really			\
 				|NN SV **mark				\
 				|NN SV **sp
 : Used in pp_sys.c
@@ -1699,9 +1699,6 @@ Ampx	|SV **	|hv_store_flags |NULLOK HV *hv				\
 				|NULLOK SV *val 			\
 				|U32 hash				\
 				|int flags
-Admp	|SV **	|hv_stores	|NULLOK HV *hv				\
-				|"key"					\
-				|NULLOK SV *val
 Admp	|void	|hv_undef	|NULLOK HV *hv
 Xop	|void	|hv_undef_flags |NULLOK HV *hv				\
 				|U32 flags
@@ -2210,7 +2207,7 @@ Adpr	|void	|my_exit	|U32 status
 Adpr	|void	|my_failure_exit
 Cdp	|I32	|my_fflush_all
 CTdp	|Pid_t	|my_fork
-mp	|I32	|my_lstat
+m	|I32	|my_lstat
 Xp	|I32	|my_lstat_flags |NULLOK const U32 flags
 RTop	|int	|my_mkostemp_cloexec					\
 				|NN char *templte			\
@@ -2231,7 +2228,7 @@ CTdp	|int	|my_socketpair	|int family				\
 				|int type				\
 				|int protocol				\
 				|int fd[2]
-mp	|I32	|my_stat
+m	|I32	|my_stat
 Xp	|I32	|my_stat_flags	|NULLOK const U32 flags
 p	|const char *|my_strerror					\
 				|const int errnum			\
@@ -2692,8 +2689,7 @@ CTp	|Signal_t|perly_sighandler					\
 				|NULLOK void *uap			\
 				|bool safe
 
-Admp	|const char * const|phase_name					\
-				|enum perl_phase
+Admp	|const char *|phase_name|enum perl_phase phase
 Adp	|void	|pmop_dump	|NULLOK PMOP *pm
 : Used in perly.y
 p	|OP *	|pmruntime	|NN OP *o				\
@@ -4494,7 +4490,7 @@ ERXp	|SV *	|add_range_to_invlist_					\
 				|NULLOK SV *invlist			\
 				|UV start				\
 				|UV end
-m	|void	|invlist_intersection_					\
+Em	|void	|invlist_intersection_					\
 				|NN SV * const a			\
 				|NN SV * const b			\
 				|NN SV **i
@@ -4504,11 +4500,11 @@ EXp	|void	|invlist_intersection_maybe_complement_2nd_		\
 				|const bool complement_b		\
 				|NN SV **i
 EXp	|void	|invlist_invert_|NN SV * const invlist
-m	|void	|invlist_subtract_					\
+Em	|void	|invlist_subtract_					\
 				|NN SV * const a			\
 				|NN SV * const b			\
 				|NN SV **result
-m	|void	|invlist_union_ |NULLOK SV * const a			\
+Em	|void	|invlist_union_ |NULLOK SV * const a			\
 				|NN SV * const b			\
 				|NN SV **output
 EXp	|void	|invlist_union_maybe_complement_2nd_			\
@@ -6455,7 +6451,7 @@ Adp	|bool	|dump_c_backtrace					\
 				|NN PerlIO *fp				\
 				|int max_depth				\
 				|int skip
-dm	|void	|free_c_backtrace					\
+dmo	|void	|free_c_backtrace					\
 				|NN Perl_c_backtrace *bt
 dp	|Perl_c_backtrace *|get_c_backtrace				\
 				|int max_depth				\

embed.h

@@ -21,77 +21,11 @@
 
 /* (Doing namespace management portably in C is really gross.) */
 
-/* By defining PERL_NO_SHORT_NAMES (not done by default) the short forms
- * (like warn instead of Perl_warn) for the API are not defined.
- * Not defining the short forms is a good thing for cleaner embedding.
- * BEWARE that a bunch of macros don't have long names, so either must be
- * added or don't use them if you define this symbol */
+/* When this symbol is defined, we undef various symbols we have defined
+ * earlier when this file was #included with this symbol undefined */
+#if !defined(PERL_DO_UNDEFS)
 
-#if !defined(MULTIPLICITY)
-/* undefined symbols, point them back at the usual ones */
-# define Perl_deb_nocontext                     Perl_deb
-# define Perl_form_nocontext                    Perl_form
-# define Perl_load_module_nocontext             Perl_load_module
-# define Perl_mess_nocontext                    Perl_mess
-# define Perl_newSVpvf_nocontext                Perl_newSVpvf
-# define Perl_sv_catpvf_nocontext               Perl_sv_catpvf
-# define Perl_sv_catpvf_mg_nocontext            Perl_sv_catpvf_mg
-# define Perl_sv_setpvf_nocontext               Perl_sv_setpvf
-# define Perl_sv_setpvf_mg_nocontext            Perl_sv_setpvf_mg
-# define Perl_warn_nocontext                    Perl_warn
-# define Perl_warner_nocontext                  Perl_warner
-#endif /* !defined(MULTIPLICITY) */
-#if !defined(PERL_CORE)
-/* Compatibility stubs.  Compile extensions with -DPERL_NOCOMPAT to
- * disable them.
- */
-# define sv_setptrobj(rv,ptr,name)              sv_setref_iv(rv,name,PTR2IV(ptr))
-# define sv_setptrref(rv,ptr)                   sv_setref_iv(rv,NULL,PTR2IV(ptr))
-# if !defined(PERL_NOCOMPAT)
-
-/* Compatibility for this renamed function. */
-#   define perl_atexit(a,b)                     Perl_call_atexit(aTHX_ a,b)
-
-/* Compatibility for these functions that had a 'perl_' prefix before
- * 'Perl_' became the standard */
-#   define perl_call_argv(a,b,c)                Perl_call_argv(aTHX_ a,b,c)
-#   define perl_call_method(a,b)                Perl_call_method(aTHX_ a,b)
-#   define perl_call_pv(a,b)                    Perl_call_pv(aTHX_ a,b)
-#   define perl_call_sv(a,b)                    Perl_call_sv(aTHX_ a,b)
-#   define perl_eval_pv(a,b)                    Perl_eval_pv(aTHX_ a,b)
-#   define perl_eval_sv(a,b)                    Perl_eval_sv(aTHX_ a,b)
-#   define perl_get_av(a,b)                     Perl_get_av(aTHX_ a,b)
-#   define perl_get_cv(a,b)                     Perl_get_cv(aTHX_ a,b)
-#   define perl_get_hv(a,b)                     Perl_get_hv(aTHX_ a,b)
-#   define perl_get_sv(a,b)                     Perl_get_sv(aTHX_ a,b)
-#   define perl_init_i18nl10n(a)                Perl_init_i18nl10n(aTHX_ a)
-#   define perl_require_pv(a)                   Perl_require_pv(aTHX_ a)
-
-/* Before C99, macros could not wrap varargs functions. This
-   provides a set of compatibility functions that don't take an
-   extra argument but grab the context pointer using the macro dTHX.
- */
-
-#   if  defined(MULTIPLICITY) && !defined(PERL_NO_SHORT_NAMES) && \
-       !defined(PERL_WANT_VARARGS)
-#     define deb                                Perl_deb_nocontext
-#     define form                               Perl_form_nocontext
-#     define load_module                        Perl_load_module_nocontext
-#     define mess                               Perl_mess_nocontext
-#     define newSVpvf                           Perl_newSVpvf_nocontext
-#     define sv_catpvf                          Perl_sv_catpvf_nocontext
-#     define sv_catpvf_mg                       Perl_sv_catpvf_mg_nocontext
-#     define sv_setpvf                          Perl_sv_setpvf_nocontext
-#     define sv_setpvf_mg                       Perl_sv_setpvf_mg_nocontext
-#     define warn                               Perl_warn_nocontext
-#     define warner                             Perl_warner_nocontext
-#   endif /*  defined(MULTIPLICITY) && !defined(PERL_NO_SHORT_NAMES) &&
-             !defined(PERL_WANT_VARARGS) */
-# endif /* !defined(PERL_NOCOMPAT) */
-#endif /* !defined(PERL_CORE) */
-#if !defined(PERL_NO_SHORT_NAMES)
-
-/* Hide global symbols */
+/* Create short name macros that hide any need for thread context */
 
 # define AvFILL_(a)                             Perl_AvFILL_(aTHX_ a)
 # define Gv_AMupdate(a,b)                       Perl_Gv_AMupdate(aTHX_ a,b)
@@ -908,7 +842,20 @@
 #   define sv_setpvf_nocontext                  Perl_sv_setpvf_nocontext
 #   define warn_nocontext                       Perl_warn_nocontext
 #   define warner_nocontext                     Perl_warner_nocontext
-# endif /* defined(MULTIPLICITY) */
+# else /* if !defined(MULTIPLICITY) */
+/* undefined symbols, point them back at the usual ones */
+#   define Perl_deb_nocontext                   Perl_deb
+#   define Perl_form_nocontext                  Perl_form
+#   define Perl_load_module_nocontext           Perl_load_module
+#   define Perl_mess_nocontext                  Perl_mess
+#   define Perl_newSVpvf_nocontext              Perl_newSVpvf
+#   define Perl_sv_catpvf_nocontext             Perl_sv_catpvf
+#   define Perl_sv_catpvf_mg_nocontext          Perl_sv_catpvf_mg
+#   define Perl_sv_setpvf_nocontext             Perl_sv_setpvf
+#   define Perl_sv_setpvf_mg_nocontext          Perl_sv_setpvf_mg
+#   define Perl_warn_nocontext                  Perl_warn
+#   define Perl_warner_nocontext                Perl_warner
+# endif /* !defined(MULTIPLICITY) */
 # if !defined(MULTIPLICITY) || defined(PERL_CORE) || \
       defined(PERL_WANT_VARARGS)
 #   define deb(...)                             Perl_deb(aTHX_ __VA_ARGS__)
@@ -1829,21 +1776,57 @@
 #     define quadmath_format_needed             Perl_quadmath_format_needed
 #     define quadmath_format_valid              Perl_quadmath_format_valid
 #   endif
-#   if defined(USE_THREADS)
-#     define Perl_do_aexec(mTHX,a,b,c)          do_aexec(a,b,c)
-#     define Perl_my_lstat(mTHX)                my_lstat()
-#     define Perl_my_stat(mTHX)                 my_stat()
-#   else
-#     define Perl_do_aexec                      do_aexec
-#     define Perl_my_lstat                      my_lstat
-#     define Perl_my_stat                       my_stat
-#   endif
 #   if defined(WIN32)
 #     define get_win32_message_utf8ness(a)      Perl_get_win32_message_utf8ness(aTHX_ a)
 #   else
 #     define do_exec3(a,b,c)                    Perl_do_exec3(aTHX_ a,b,c)
 #   endif
-# endif /* defined(PERL_CORE) */
+# else /* if !defined(PERL_CORE) */
+/* Compatibility stubs.  Compile extensions with -DPERL_NOCOMPAT to
+ * disable them.
+ */
+#   define sv_setptrobj(rv,ptr,name)            sv_setref_iv(rv,name,PTR2IV(ptr))
+#   define sv_setptrref(rv,ptr)                 sv_setref_iv(rv,NULL,PTR2IV(ptr))
+#   if !defined(PERL_NOCOMPAT)
+
+/* Compatibility for this renamed function. */
+#     define perl_atexit(a,b)                   Perl_call_atexit(aTHX_ a,b)
+
+/* Compatibility for these functions that had a 'perl_' prefix before
+ * 'Perl_' became the standard */
+#     define perl_call_argv(a,b,c)              Perl_call_argv(aTHX_ a,b,c)
+#     define perl_call_method(a,b)              Perl_call_method(aTHX_ a,b)
+#     define perl_call_pv(a,b)                  Perl_call_pv(aTHX_ a,b)
+#     define perl_call_sv(a,b)                  Perl_call_sv(aTHX_ a,b)
+#     define perl_eval_pv(a,b)                  Perl_eval_pv(aTHX_ a,b)
+#     define perl_eval_sv(a,b)                  Perl_eval_sv(aTHX_ a,b)
+#     define perl_get_av(a,b)                   Perl_get_av(aTHX_ a,b)
+#     define perl_get_cv(a,b)                   Perl_get_cv(aTHX_ a,b)
+#     define perl_get_hv(a,b)                   Perl_get_hv(aTHX_ a,b)
+#     define perl_get_sv(a,b)                   Perl_get_sv(aTHX_ a,b)
+#     define perl_init_i18nl10n(a)              Perl_init_i18nl10n(aTHX_ a)
+#     define perl_require_pv(a)                 Perl_require_pv(aTHX_ a)
+
+/* Before C99, macros could not wrap varargs functions. This
+   provides a set of compatibility functions that don't take an
+   extra argument but grab the context pointer using the macro dTHX.
+ */
+
+#     if defined(MULTIPLICITY) && !defined(PERL_WANT_VARARGS)
+#       define deb                              Perl_deb_nocontext
+#       define form                             Perl_form_nocontext
+#       define load_module                      Perl_load_module_nocontext
+#       define mess                             Perl_mess_nocontext
+#       define newSVpvf                         Perl_newSVpvf_nocontext
+#       define sv_catpvf                        Perl_sv_catpvf_nocontext
+#       define sv_catpvf_mg                     Perl_sv_catpvf_mg_nocontext
+#       define sv_setpvf                        Perl_sv_setpvf_nocontext
+#       define sv_setpvf_mg                     Perl_sv_setpvf_mg_nocontext
+#       define warn                             Perl_warn_nocontext
+#       define warner                           Perl_warner_nocontext
+#     endif /* defined(MULTIPLICITY) && !defined(PERL_WANT_VARARGS) */
+#   endif /* !defined(PERL_NOCOMPAT) */
+# endif /* !defined(PERL_CORE) */
 # if defined(PERL_CORE) || defined(PERL_EXT)
 #   define append_utf8_from_native_byte         Perl_append_utf8_from_native_byte
 #   define av_reify(a)                          Perl_av_reify(aTHX_ a)
@@ -2298,7 +2281,6 @@
 #   define Perl_hv_store(mTHX,a,b,c,d,e)        hv_store(a,b,c,d,e)
 #   define Perl_hv_store_ent(mTHX,a,b,c,d)      hv_store_ent(a,b,c,d)
 #   define Perl_hv_store_flags(mTHX,a,b,c,d,e,f) hv_store_flags(a,b,c,d,e,f)
-#   define Perl_hv_stores(mTHX,a,b,c)           hv_stores(a,b,c)
 #   define Perl_hv_undef(mTHX,a)                hv_undef(a)
 #   define Perl_ibcmp(mTHX,a,b,c)               ibcmp(a,b,c)
 #   define Perl_ibcmp_locale(mTHX,a,b,c)        ibcmp_locale(a,b,c)
@@ -2399,7 +2381,6 @@
 #   define Perl_hv_store                        hv_store
 #   define Perl_hv_store_ent                    hv_store_ent
 #   define Perl_hv_store_flags                  hv_store_flags
-#   define Perl_hv_stores                       hv_stores
 #   define Perl_hv_undef                        hv_undef
 #   define Perl_ibcmp                           ibcmp
 #   define Perl_ibcmp_locale                    ibcmp_locale
@@ -2485,6 +2466,6 @@
 # else
 #   define get_context                          Perl_get_context
 # endif
-#endif /* !defined(PERL_NO_SHORT_NAMES) */
+#endif /* !defined(PERL_DO_UNDEFS) */
 
 /* ex: set ro ft=c: */

handy.h

@@ -450,7 +450,7 @@ a string/length pair.
 
 
 /*
-=for apidoc_defn mx|void|lex_stuff_pvs|"pv"|U32 flags
+=for apidoc_defn Emx|void|lex_stuff_pvs|"pv"|U32 flags
 
 =cut
 */

hv.h

@@ -584,6 +584,7 @@ whether it is valid to call C<HvAUX()>.
 =for apidoc_defn Am|SV**|hv_fetchs|HV* hv|"key"|I32 lval
 =for apidoc_defn Am|SV *|hv_deletes|HV *hv|"key"|U32 flags
 =for apidoc_defn Am|void|hv_name_sets|HV *hv|"name"|U32 flags
+=for apidoc_defn Am|SV**|hv_stores|HV *hv|"name"|U32 flags
 =cut
 */
 #define hv_fetchs(hv, key, lval) \

mathoms.c

@@ -27,6 +27,9 @@
  * 1) A function has been replaced by a macro within a minor release,
  *    so XS modules compiled against an older release will expect to
  *    still be able to link against the function
+ * 2) A function is deprecated, and so placing it here will cause a compiler
+ *    warning to be generated (for participating compilers).
+ * 3) A few other reasons, documented with the functions below
  *
  * It used to be that this was the way to handle the case were a function
  * Perl_foo(...) had been replaced by a macro.  But see the 'm' flag discussion

perl.h

@@ -9354,6 +9354,12 @@ END_EXTERN_C
 
 */
 
+/* #including a second time causes it to #undef any unwanted symbols to avoid
+ * polluting the user name space */
+#  define PERL_DO_UNDEFS
+#  include "embed.h"
+#  undef PERL_DO_UNDEFS
+
 #endif /* Include guard */
 
 /*