diff --git a/embed.fnc b/embed.fnc index e8409f450d89..308622456266 100644 --- a/embed.fnc +++ b/embed.fnc @@ -1,26 +1,26 @@ : BEGIN{die "You meant to run regen/embed.pl"} # Stop early if fed to perl. : -: WARNING: The meanings of some flags have been changed as of v5.31.0 +: ALL NON-STATIC FUNCTIONS DEFINED BY PERL NEED TO BE LISTED IN THIS FILE. : : This file is known to be processed by regen/embed.pl, autodoc.pl, : makedef.pl, Devel::PPPort, and porting/diag.t. : : This file contains entries for various functions, macros, typedefs, and -: arrays defined by perl. Each entry includes the name, parameters, and +: other values defined by perl. Each entry includes the name, parameters, and : various attributes about it. In most functions listed here, the name is a : short name, and the function's real name is the short one, prefixed by either : 'Perl_' (for publicly visible functions) or 'S_' (for internal-to-a-file : static ones). In many instances a macro is defined that is the name in this : file, and which expands to call the real (full) name, with any appropriate -: thread context paramaters, thus hiding that detail from the typical code. +: thread context parameters, thus hiding that detail from the typical code. : : 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: : 1) proto.h to declare to the compiler the function interfaces; and -: 2) embed.h to create short name macros +: 2) embed.h to create short name macros, and to control the visibility of +: other macros : : Static functions internal to a file need not appear here, but there is : benefit to declaring them here: @@ -72,8 +72,14 @@ : backport the fixed version to modules. The only disadvantage khw can think : of is the namespace pollution one. : -: WARNING: Any macro created in a header file is visible to XS code, unless -: care is taken to wrap it within C preprocessor guards like the following +: The default for any macro created after v5.43.6 is to hide it from all but +: the Perl core. Use the visibility-affecting flags described below to change +: that. +: +: WARNING: The default hiding of symbols from XS code applies only to functions +: and macros. Other types of values that are created in a header file, such as +: typedefs and enum names, will be visible to XS code, unless care is taken to +: wrap them within C preprocessor guards like the following : : #if defined(PERL_CORE) : ... @@ -92,56 +98,49 @@ : file they are intended for, and the generated PERL_ARGS_ macros will only : be available to inline functions in the appropriate context. : -: From time to time it may be necessary to change or expand which files can -: see a function, therefore we prefer the '#if defined()' form of condition -: instead of the '#ifdef' form as the latter only works with one symbol and -: the former can be combined with more than one. It is also why you may see -: functions with an 's' or 'i' export type grouped together into a single -: conditional block separate from most of the other functions from the same -: file with 'p' in them. -: -: The 'A' flag is used to make a function and its short name visible everywhere -: on all platforms. This should be used to make it part of Perl's API -: contract with XS developers. The documentation for these is usually -: placed in perlapi. If no documentation exists, that fact is also -: noted in perlapi. +: The 'A' flag is used to make an element visible everywhere on all platforms. +: This flag should be used to make it part of Perl's API contract with +: XS developers. The documentation for these is usually placed in +: perlapi. If no documentation exists, that fact is also noted in +: perlapi. : -: These require one of the /[iIpS]/ flags to give callers a name to use -: that won't possibly collide with their own +: Functions require one of the /[iIpS]/ flags to give callers a name to +: use that won't possibly collide with their own : -: The 'C' flag is used instead for functions and their short names that need to -: be accessible everywhere, typically because they are called from a -: publicly available macro or inline function, but they are not for -: public use by themselves. The documentation for these is placed in -: perlintern. If no documentation exists, that fact is also noted in -: perlintern. +: The 'C' flag is used instead for elements that need to be accessible +: everywhere, typically because they are called from a publicly +: available macro or inline function, but they are not for public use +: by themselves. The documentation for these is placed in perlintern. +: If no documentation exists, that fact is also noted in perlintern. : -: Use the 'X' flag instead to suppress the short name outside the core +: Use the 'X' flag instead to suppress the short name for functions +: outside the core : -: These require one of the /[iIpS]/ flags to give callers a name to use -: that won't possibly collide with their own +: Functions require one of the /[iIpS]/ flags to give callers a name to +: use that won't possibly collide with their own : : Some of these have been constructed so that the wrapper macro names : begin with an underscore to lessen the chances of a name collision. : However, this is contrary to the C standard, and those should be : changed. : -: The 'E' flag is used instead for a function and its short name that is -: supposed to be used only in the core plus extensions compiled with -: the PERL_EXT symbol defined. Again, on some platforms, the function -: will be visible everywhere, so one of the /[iIpS]/ flags are -: generally needed. Also note that an XS writer can always cheat and -: pretend to be an extension by #defining PERL_EXT. -: -: The 'X' flag is similar to the 'C' flag in that the function (whose entry -: better have the 'p' flag) is accessible everywhere on all platforms. -: However the short name macro that normally gets generated is -: suppressed outside the core. (Except it is also visible in PERL_EXT -: extensions if the 'E' flag is also specified.) This flag is used for -: functions that are called from a public macro, the name of which -: isn't derived from the function name. You'll have to write the macro -: yourself, and from within it, refer to the function in its full -: 'Perl_' form with any necessary thread context parameter. +: The 'E' flag is used instead for elements that are supposed to be used only +: in the core, plus extensions compiled with the PERL_EXT symbol +: defined. Again, on some platforms, functions marked with this will +: be visible everywhere, so one of the /[iIpS]/ flags is generally +: needed. Also note that an XS writer can always cheat and pretend to +: be an extension by #defining PERL_EXT. +: +: The 'X' flag applies only to functions. It is similar to the 'C' flag in +: that the function (whose entry better have the 'p' flag) is +: accessible everywhere on all platforms. However the short name macro +: that normally gets generated is suppressed outside the core. (Except +: it is also visible in PERL_EXT extensions if the 'E' flag is also +: specified.) This flag is used for functions that are called from a +: public macro, the name of which isn't derived from the function name. +: You'll have to write the macro yourself, and from within it, refer to +: the function in its full 'Perl_' form with any necessary thread +: context parameter. : : AUTOMATIC SORTING and FORMATTING of this file : @@ -423,15 +422,15 @@ : The remainder of these introductory comments detail all the possible flags: : : 'A' Both long and short names are accessible fully everywhere (usually -: part of the public API). Requires one of /[iIpS]/ flags. If the -: function is not part of the public API, instead use 'C', 'E', or 'X'. +: part of the public API). If this element is a function, this requires +: one of /[iIpS]/ flags. If the element is not part of the public API, +: instead use 'C', 'E', or 'X'. : : * adds entry to the list of symbols available on all platforms unless : 'e' or 'm' are also specified; : * any doc entry goes in perlapi.pod rather than perlintern.pod. If : there isn't a doc entry, autodoc.pl lists this in perlapi as -: existing and being undocumented; unless 'x' is also specified, in -: which case it simply isn't listed. +: existing and being undocumented. : * makes the short name defined for everywhere, not just for PERL_CORE : or PERL_EXT : @@ -475,32 +474,33 @@ : * create PERL_ARGS_ASSERT_foo; : * add embed.h entry (unless overridden by the 'M' or 'o' flags) : -: 'C' Intended for core use only. This indicates to XS writers that they -: shouldn't be using this function. Devel::PPPort informs them of this, -: for example. Some functions have to be accessible everywhere even if -: they are not intended for public use. An example is helper functions -: that are called from inline ones that are publicly available. -: Requires one of /[iIpS]/ flags. +: 'C' Intended for core use only. XS writers may not even know they exist, +: since they don't get documented in perlapi. But should they try +: to use them anyway, Devel::PPPort informs them that this is a mistake. +: Some functions have to be accessible everywhere even if they are not +: intended for public use. An example is helper functions that are +: called from inline ones that are publicly available. Requires one of +: the /[iIpS]/ flags if the element is a function. : : * add entry to the list of symbols available on all platforms unless e : or m are also specified; : * any doc entry goes in perlintern.pod rather than perlapi.pod. If : there isn't a doc entry, autodoc.pl lists this in perlintern as : existing and being undocumented -: * makes the short name defined for everywhere, not just for PERL_CORE -: or PERL_EXT +: * makes the function's short name defined for everywhere, not just for +: PERL_CORE or PERL_EXT : -: 'D' Function is deprecated. +: 'D' The element is deprecated. : -: (Add a comment to the function source when adding this flag indicating -: what release it is first being deprecated in. This will prevent having -: to dig up this information when deciding if enough releases have passed -: to actually remove the function.) +: (You should add a comment to the source when adding this flag +: indicating what release it is first being deprecated in. This will +: prevent having to dig up this information when deciding if enough +: releases have passed to actually remove it.) : : proto.h: add __attribute__deprecated__ : autodoc.pl adds a note to this effect in the doc entry : -: 'd' Function has documentation (somewhere) in the source: +: 'd' Element has documentation (somewhere) in the source: : : Enables 'no docs for foo" warning in autodoc.pl if the documentation : isn't found. @@ -584,11 +584,20 @@ : instead you define the macro as 'PERL_FOO' (all uppercase), the : embed.h entry will use all uppercase. : +: The default visibility of macros created before 5.43.7 is visible +: everywhere, so the visibility flags are ignored. Starting in that +: release, the default visibility of newly created macros is core-only, +: so the visibility flags do have effect. To cause a pre-5.43.7 symbol +: to be affected by a visibility flag, remove the symbol from its +: override list in regen/embed.pl. +: : 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 (when no 'p' flag), as the implementation : should furnish the macro +: #undef this symbol in embed.h as needed to match the specified +: visibility. : : 'M' The implementation is furnishing its own macro instead of relying on : the automatically generated short name macro (which simply expands to @@ -732,13 +741,15 @@ : : 'x' Experimental, may change: : -: Any doc entry is marked that it may change. An undocumented -: experimental function is listed in perlintern rather than perlapi, -: even if it is allegedly API. +: Any doc entry is marked that this element may change. : -: 'y' Typedef. The element names a type rather than being a macro +: 'y' Typedef. The element names a type rather than being a function or +: macro. These are always visible to XS code unless guarded by +: preprocessor directives, : : '@' The element names an array rather than being a macro or function. +: These are always visible to XS code unless guarded by preprocessor +: directives, : : autodoc.pl automatically suppresses any usage information. :