diff options
| author | Karl Williamson <khw@cpan.org> | 2016-12-10 20:19:39 -0700 |
|---|---|---|
| committer | Karl Williamson <khw@cpan.org> | 2016-12-11 14:33:47 -0700 |
| commit | d8bd2bed4a68714bf8bd23de5e3981c0c2800c01 (patch) | |
| tree | f353ed1ccf4a36e1bedf92c911921f788d2ec51e | |
| parent | c6baab6cc5f7f4a35548b6d4a990d99d9b6a1704 (diff) | |
| download | perl-d8bd2bed4a68714bf8bd23de5e3981c0c2800c01.tar.gz | |
embed.fnc: Add comments; wordsmith others
After some years of working on the Perl core, I did not realize that the
default for functions in this file is to make them invisible outside the
core. I've jumped through hoops to try to do that, not realizing it was
automatic. This adds comments so newbies don't make the same mistake.
And it rewords slightly various other comments.
| -rw-r--r-- | embed.fnc | 20 |
1 files changed, 16 insertions, 4 deletions
@@ -1,6 +1,11 @@ : BEGIN{die "You meant to run regen/embed.pl"} # Stop early if fed to perl. : : This file is processed by regen/embed.pl and autodoc.pl +: It is used to declare the interfaces to the functions defined by perl. All +: non-static functions must have entries here. Static functions need not, but +: there is benefit to declaring them here, as it generally handles the thread +: context parameter invisibly, as well as making sure a PERL_ARGS_ASSERT_foo +: macro is defined, which can save you debugging time. : : Lines are of the form: : flags|return_type|function_name|arg1|arg2|...|argN @@ -8,6 +13,11 @@ : A line may be continued on another by ending it with a backslash. : Leading and trailing whitespace will be ignored in each component. : +: The default without flags is to declare a function for internal perl-core use +: only, not visible to XS code nor to Perl extensions. Use the A and E flags to +: modify this. Most non-static functions should have the 'p' flag to avoid +: namespace clashes with programs that embed perl. +: : flags are single letters with following meanings: : : A Available fully everywhere (usually part of the public API): @@ -55,7 +65,7 @@ : This flag effectively causes nothing to happen if the perl interpreter : is compiled with -DNO_MATHOMS; otherwise these happen: : add entry to the list of exported symbols; -: create PERL_ARGS_ASSERT_FOO; +: create PERL_ARGS_ASSERT_foo; : add embed.h entry (unless overridden by the 'm' flag) : : D Function is deprecated: @@ -75,7 +85,7 @@ : 1) must be static to its containing file ("i" or "s" flag); or : 2) be combined with the "X" flag. : -: f Function takes a format string. If the function name /strftime/ +: f Function takes a format string. If the function name =~ qr/strftime/ : then its assumed to take a strftime-style format string as 1st arg; : otherwise it's assumed to be a printf style format string, varargs : (hence any entry that would otherwise go in embed.h is suppressed): @@ -116,8 +126,10 @@ : : embed.h: suppress "#define foo Perl_foo" : -: P Pure function: Also implies "R". No effects except the return value; -: return value depends only on params and/or globals: +: P Pure function: +: +: A pure function has no effects except the return value, and the return +: value depends only on params and/or globals. Also implies "R": : : proto.h: add __attribute__pure__ : |