Skip to content

Enable removing most of mathoms.c and stub functions #22691

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Oct 28, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion autodoc.pl
Original file line number Diff line number Diff line change
Expand Up @@ -1878,7 +1878,11 @@ ($fh, $section_name, $element_name, $docref)
|| $needs_Perl_entry
|| $cant_use_short_name)
{
$name = "Perl_$name";
# An all uppercase macro name gets an uppercase prefix.
my $perl = ($flags =~ /m/ && $name !~ /[[:lower:]]/)
? "PERL_"
: "Perl_";
$name = "$perl$name";

# We can't hide the existence of any thread context
# parameter when using the "Perl_" long form. So it must
Expand Down
133 changes: 81 additions & 52 deletions embed.fnc
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@
: real (full) name, with any appropriate thread context paramaters, thus hiding
: that detail from the typical code.
:
: Most macros (as opposed to functions) listed here are the complete full name.
: Many macros (as opposed to functions) listed here are the complete full name,
: though we may want to start converting those to have full names.
:
: All non-static functions defined by perl need to be listed in this file.
: embed.pl uses the entries here to construct:
Expand Down Expand Up @@ -157,8 +158,9 @@
: and you know at a glance that the macro actually has documentation. It
: doesn't by itself create any documentation; instead the other apidoc lines
: pull in information specified by these lines. Many of the lines in this
: file for macros could be pulled out of here and replaced by these lines
: throughout the source. It is a goal to do that as convenience dictates.
: file for macros that don't also have the 'p' flag (described below) could be
: pulled out of here and replaced by these lines throughout the source. It is
: a goal to do that as convenience dictates.
:
: The other apidoc lines either have the usage data as part of the line, or
: pull in the data from this file or apidoc_defn lines.
Expand Down Expand Up @@ -210,10 +212,10 @@
: line that begins with an '='. In particular, an '=cut' line ends that
: documentation without introducing something new.
:
: Various macros and other elements aren't listed here in embed.fnc. They are
: documented in the same manner, but since they don't have this file to get
: information from, the defining lines have the syntax and meaning they do in
: this file, so it can be specified:
: Various macros and other elements aren't listed here in embed.fnc (though
: they could be). They are documented in the same manner, but since they don't
: have this file to get information from, the defining lines have the syntax
: and meaning they do in this file, so it can be specified:
:
: =for apidoc flags|return_type|name|arg1|arg2|...|argN
: =for apidoc_item flags|return_type|name|arg1|arg2|...|argN
Expand Down Expand Up @@ -301,22 +303,21 @@
: functions flagged with this, the installation can run Configure with
: the -Accflags='-DNO_MATHOMS' parameter to not even compile them.
:
: Sometimes the function has been subsumed by a more general one (say,
: by adding a flags parameter), and a macro exists with the original
: short name API, and it calls the new function, bypassing this one, and
: the original 'Perl_' form is being deprecated. In this case also
: specify the 'M' flag.
: If the function can be implemented as a macro (that evaluates its
: arguments exactly once), use the 'm' and 'p' flags together to implement
: this. (See the discussion under 'm'.) Another option for this is to
: use the 'M' flag.
:
: Without the M flag, these functions should be deprecated, and it is an
: error to not also specify the 'D' flag.
: Without the m or M flags, these functions should be deprecated, and it
: is an error to not also specify the 'D' flag.
:
: The 'b' functions are normally moved to mathoms.c, but if
: circumstances dictate otherwise, they can be anywhere, provided the
: whole function is wrapped with
:
: #ifndef NO_MATHOMS
: ...
: #endif
: #ifndef NO_MATHOMS
: ...
: #endif
:
: Note that this flag no longer automatically adds a 'Perl_' prefix to
: the name. Additionally specify 'p' to do that.
Expand Down Expand Up @@ -370,10 +371,10 @@
: then it is assumed to take a strftime-style format string as the 1st
: arg; otherwise it's assumed to take a printf style format string, not
: necessarily the 1st arg. All the arguments following the second form
: (including possibly '...') are assumed to be for the format.
: (including possibly '...') are assumed to be for the format.
:
: embed.h: any entry in here for the second form is suppressed because
: of varargs
: of varargs
: proto.h: add __attribute__format__ (or ...null_ok__)
:
: 'F' Function has a '...' parameter, but don't assume it is a format. This
Expand All @@ -396,7 +397,7 @@
: one NN argument.
:
: proto.h: PERL_ARGS_ASSERT macro is not defined unless the function
: has NN arguments
: has NN arguments
:
: 'h' Hide any documentation that would normally go into perlapi or
: perlintern. This is typically used when the documentation is actually
Expand Down Expand Up @@ -427,7 +428,7 @@
: particular C file(s) or in the perl core.) Therefore, all non-guarded
: functions should also have the 'p' flag specified to avoid polluting
: the XS code name space. Otherwise, this flag also turns on the 'S'
: flag.
: flag.
:
: proto.h: function is declared as PERL_STATIC_INLINE
:
Expand All @@ -439,23 +440,50 @@
: __attribute__always_inline__ is added
:
: 'm' Implemented as a macro; there is no function associated with this
: name, and hence no long Perl_ or S_ name. However, if the macro name
: itself begins with 'Perl_', autodoc.pl will show a thread context
: parameter unless the 'T' flag is specified.
: name. There is no long S_ name.
:
: However, you may #define the macro with a long name like 'Perl_foo',
: and specify the 'p' flag. This will cause an embed.h entry to be
: created that #defines 'foo' as 'Perl_foo'. This can be used to make
: any macro have a long name, perhaps to avoid name collisions. If
: instead you define the macro as 'PERL_FOO' (all uppercase), the
: embed.h entry will use all uppercase.
:
: It is particularly useful tp preserve backward compatibility when a
: function is converted to be a macro (remembering to not create a macro
: which evaluates its parameters more than once). Most of mathoms.c
: could be converted to use this facility. When there is no thread
: context involved, you just do something like
:
: #define Perl_foo(a, b, c) Perl_bar(a, b, 0, c)
:
: Otherwise consider this general case where there is a series of macros
: that build on the previous ones by calling something with a different
: name or with an extra parameter beyond what the previous one did:
:
: #define Perl_foo(mTHX, a) Perl_bar1(aTHX, a)
: #define Perl_bar1(mTHX, a) Perl_bar2(aTHX, a, 0)
: #define Perl_bar2(mTHX, a, b) Perl_bar3(aTHX, a, b, 0)
: #define Perl_bar3(mTHX, a, b, c) Perl_func(aTHX_ a, b, c, 0)
:
: Use the formal parameter name 'mTHX,' (which stands for "macro thread
: context") as the first in each macro definition, and call the next
: macro in the sequence with 'aTHX,' (Note the commas). Eventually, the
: sequence will end with a function call (or else there would be no need
: for thread context). For that instead call it with 'aTHX_' (with an
: underscore instead of a comma).
:
: suppress proto.h entry (actually, not suppressed, but commented out)
: suppress entry in the list of exported symbols available on all platforms
: suppress embed.h entry, as the implementation should furnish the macro
: suppress entry in the list of exported symbols available on all
: platforms
: suppress embed.h entry (when no 'p' flag), as the implementation
: should furnish the macro
:
: 'M' The implementation is furnishing its own macro instead of relying on
: the automatically generated short name macro (which simply expands to
: call the real name function). One reason to do this is if the
: parameters need to be cast from what the caller has, or if there is a
: macro that bypasses this function (whose long name is being retained
: for backward compatibility for those who call it with that name). An
: example is when a new function is created with an extra parameter and
: a wrapper macro is added that has the old API, but calls the new one
: with the exta parameter set to a default.
: parameters need to be cast from what the caller has. There is less
: need to do this now that 'm' and 'p' together is supported.
:
: This flag requires the 'p' flag to be specified, as there would be no
: need to do this if the function weren't publicly accessible before.
Expand Down Expand Up @@ -489,10 +517,10 @@
:
: 'o' Has no Perl_foo or S_foo compatibility macro:
:
: This is used for whatever reason to force the function to be called
: with the long name. Perhaps there is a varargs issue. Use the 'M'
: flag instead for wrapper macros, and legacy-only functions should
: also use 'b'.
: This is used for whatever reason to force the function to be called
: with the long name. Perhaps there is a varargs issue. Use the 'M'
: or 'm' flags instead for wrapper macros, and legacy-only functions
: should also use 'b'.
:
: embed.h: suppress "#define foo Perl_foo"
:
Expand All @@ -517,9 +545,10 @@
:
: proto.h: add __attribute__pure__
:
: 'p' Function in source code has a Perl_ prefix:
: 'p' Function or macro in source code has a Perl_ prefix:
:
: proto.h: function is declared as Perl_foo rather than foo
: proto.h: function or macro is declared as Perl_foo rather than foo
: (though the entries for macros will be commented out)
: embed.h: "#define foo Perl_foo" entries added
:
: 'R' Return value must not be ignored (also implied by 'a' and 'P' flags):
Expand All @@ -543,8 +572,8 @@
:
: 's' Static function, but function in source code has a Perl_ prefix:
:
: This is used for functions that have always had a Perl_ prefix, but
: have been moved to a header file and declared static.
: This is used for functions that have always had a Perl_ prefix, but
: have been moved to a header file and declared static.
:
: proto.h: function is declared as Perl_foo rather than foo
: STATIC is added to declaration;
Expand Down Expand Up @@ -579,11 +608,11 @@
: compatibility issues.
:
: 'W' Add a comma_pDEPTH argument to function prototypes, and a comma_aDEPTH
: argument to the function calls. This means that under DEBUGGING a
: depth argument is added to the functions, which is used for example by
: the regex engine for debugging and trace output. A non DEBUGGING build
: will not pass the unused argument. Currently restricted to functions
: with at least one argument.
: argument to the function calls. This means that under DEBUGGING a
: depth argument is added to the functions, which is used for example by
: the regex engine for debugging and trace output. A non DEBUGGING build
: will not pass the unused argument. Currently restricted to functions
: with at least one argument.
:
: 'X' Explicitly exported:
:
Expand Down Expand Up @@ -1597,7 +1626,7 @@ Cp |void |init_stacks
Cp |void |init_tm |NN struct tm *ptm
p |void |init_uniprops
: Used in perly.y
AMPRTbdp|char * |instr |NN const char *big \
APRTdmp |char * |instr |NN const char *big \
|NN const char *little
Adp |U32 |intro_my
ERXp |Size_t |_inverse_folds |const UV cp \
Expand Down Expand Up @@ -1711,7 +1740,7 @@ ARTdip |bool |is_utf8_string_flags \
|NN const U8 *s \
|STRLEN len \
|const U32 flags
AMTbdp |bool |is_utf8_string_loc \
ATdmp |bool |is_utf8_string_loc \
|NN const U8 *s \
|const STRLEN len \
|NN const U8 **ep
Expand Down Expand Up @@ -2887,7 +2916,7 @@ Cp |void |save_destructor_x \
|NULLOK void *p
: Used in SAVEFREOP(), used in op.c, pp_ctl.c
CMbp |void |save_freeop |NULLOK OP *o
CMbp |void |save_freepv |NULLOK char *pv
Cmp |void |save_freepv |NULLOK char *pv
Cdp |void |save_freercpv |NN char *rcpv
CMbp |void |save_freesv |NULLOK SV *sv
Cdp |void |save_generic_pvref \
Expand Down Expand Up @@ -3715,13 +3744,13 @@ p |void |utilize |int aver \
|NN OP *idop \
|NULLOK OP *arg

Adm |U8 * |uvchr_to_utf8 |NN U8 *d \
Admp |U8 * |uvchr_to_utf8 |NN U8 *d \
|UV uv
Adm |U8 * |uvchr_to_utf8_flags \
Admp |U8 * |uvchr_to_utf8_flags \
|NN U8 *d \
|UV uv \
|UV flags
Adm |U8 * |uvchr_to_utf8_flags_msgs \
Admp |U8 * |uvchr_to_utf8_flags_msgs \
|NN U8 *d \
|UV uv \
|UV flags \
Expand Down Expand Up @@ -4060,7 +4089,7 @@ Mp |bool |do_exec |NN const char *cmd
p |bool |do_exec |NN const char *cmd
#endif
#if defined(PERL_DONT_CREATE_GVSV)
AMbdp |GV * |gv_SVadd |NULLOK GV *gv
Admp |GV * |gv_SVadd |NULLOK GV *gv
#endif
#if defined(PERL_IMPLICIT_SYS)
CTo |PerlInterpreter *|perl_alloc_using \
Expand Down
9 changes: 9 additions & 0 deletions embed.h
Original file line number Diff line number Diff line change
Expand Up @@ -307,6 +307,7 @@
# define init_i18nl10n(a) Perl_init_i18nl10n(aTHX_ a)
# define init_stacks() Perl_init_stacks(aTHX)
# define init_tm(a) Perl_init_tm(aTHX_ a)
# define instr Perl_instr
# define intro_my() Perl_intro_my(aTHX)
# define isC9_STRICT_UTF8_CHAR Perl_isC9_STRICT_UTF8_CHAR
# define isSTRICT_UTF8_CHAR Perl_isSTRICT_UTF8_CHAR
Expand All @@ -322,6 +323,7 @@
# define is_utf8_fixed_width_buf_loclen_flags Perl_is_utf8_fixed_width_buf_loclen_flags
# define is_utf8_invariant_string_loc Perl_is_utf8_invariant_string_loc
# define is_utf8_string_flags Perl_is_utf8_string_flags
# define is_utf8_string_loc Perl_is_utf8_string_loc
# define is_utf8_string_loclen Perl_is_utf8_string_loclen
# define is_utf8_string_loclen_flags Perl_is_utf8_string_loclen_flags
# define is_utf8_valid_partial_char_flags Perl_is_utf8_valid_partial_char_flags
Expand Down Expand Up @@ -593,6 +595,7 @@
# define save_delete(a,b,c) Perl_save_delete(aTHX_ a,b,c)
# define save_destructor(a,b) Perl_save_destructor(aTHX_ a,b)
# define save_destructor_x(a,b) Perl_save_destructor_x(aTHX_ a,b)
# define save_freepv(a) Perl_save_freepv(aTHX,a)
# define save_freercpv(a) Perl_save_freercpv(aTHX_ a)
# define save_generic_pvref(a) Perl_save_generic_pvref(aTHX_ a)
# define save_generic_svref(a) Perl_save_generic_svref(aTHX_ a)
Expand Down Expand Up @@ -796,6 +799,9 @@
# define utf8_to_bytes(a,b) Perl_utf8_to_bytes(aTHX_ a,b)
# define utf8_to_uvchr_buf_helper(a,b,c) Perl_utf8_to_uvchr_buf_helper(aTHX_ a,b,c)
# define utf8n_to_uvchr_msgs Perl_utf8n_to_uvchr_msgs
# define uvchr_to_utf8(a,b) Perl_uvchr_to_utf8(aTHX,a,b)
# define uvchr_to_utf8_flags(a,b,c) Perl_uvchr_to_utf8_flags(aTHX,a,b,c)
# define uvchr_to_utf8_flags_msgs(a,b,c,d) Perl_uvchr_to_utf8_flags_msgs(aTHX,a,b,c,d)
# define uvoffuni_to_utf8_flags_msgs(a,b,c,d) Perl_uvoffuni_to_utf8_flags_msgs(aTHX_ a,b,c,d)
# define valid_utf8_to_uvchr Perl_valid_utf8_to_uvchr
# define vcmp(a,b) Perl_vcmp(aTHX_ a,b)
Expand Down Expand Up @@ -2012,6 +2018,9 @@
# define finalize_optree(a) Perl_finalize_optree(aTHX_ a)
# define optimize_optree(a) Perl_optimize_optree(aTHX_ a)
# endif
# if defined(PERL_DONT_CREATE_GVSV)
# define gv_SVadd(a) Perl_gv_SVadd(aTHX,a)
# endif
# if !defined(PERL_IMPLICIT_SYS)
# define my_pclose(a) Perl_my_pclose(aTHX_ a)
# define my_popen(a,b) Perl_my_popen(aTHX_ a,b)
Expand Down
2 changes: 1 addition & 1 deletion gv.h
Original file line number Diff line number Diff line change
Expand Up @@ -346,7 +346,7 @@ Make sure there is a slot of the given type (AV, HV, IO, SV) in the GV C<gv>.
#define gv_AVadd(gv) gv_add_by_type((gv), SVt_PVAV)
#define gv_HVadd(gv) gv_add_by_type((gv), SVt_PVHV)
#define gv_IOadd(gv) gv_add_by_type((gv), SVt_PVIO)
#define gv_SVadd(gv) gv_add_by_type((gv), SVt_NULL)
#define Perl_gv_SVadd(mTHX, gv) Perl_gv_add_by_type(aTHX_ (gv), SVt_NULL)

/*
* ex: set ts=8 sts=4 sw=4 et:
Expand Down
3 changes: 2 additions & 1 deletion inline.h
Original file line number Diff line number Diff line change
Expand Up @@ -2114,7 +2114,8 @@ Perl_is_utf8_string_flags(const U8 *s, STRLEN len, const U32 flags)
return TRUE;
}

#define is_utf8_string_loc(s, len, ep) is_utf8_string_loclen(s, len, ep, 0)
#define Perl_is_utf8_string_loc(s, len, ep) \
Perl_is_utf8_string_loclen(s, len, ep, 0)

PERL_STATIC_INLINE bool
Perl_is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
Expand Down
Loading