In perl.git, the branch blead has been updated <http://perl5.git.perl.org/perl.git/commitdiff/cb198164564566deec7e26370654b1378a1a5f1d?hp=48c0e89d40bfde5337dd013112467554427c1279>
- Log ----------------------------------------------------------------- commit cb198164564566deec7e26370654b1378a1a5f1d Author: Yves Orton <[email protected]> Date: Sun Aug 14 13:56:56 2016 +0200 first step to documenting the Internals namespace After discussion, we have decided to document Internals. This is a first step doing so, with lib/Internals.pod. At the same time I updated sv.h that there were equivalents for SvREFCNT and SvREADONLY in the Internals namespace, this required adding docs for SvREADONLY. I also tweaked the test name in Porting/Maintainers.pm so that it pointed at Porting/Maintainers.pl to make it more obvious how to specify a maintainer for a new file. ----------------------------------------------------------------------- Summary of changes: MANIFEST | 1 + Porting/Maintainers.pl | 1 + Porting/Maintainers.pm | 4 +-- lib/Internals.pod | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++ sv.h | 19 +++++++++++++- 5 files changed, 91 insertions(+), 3 deletions(-) create mode 100644 lib/Internals.pod diff --git a/MANIFEST b/MANIFEST index 606b654..4eceaeb 100644 --- a/MANIFEST +++ b/MANIFEST @@ -4418,6 +4418,7 @@ lib/h2ph.t See if h2ph works like it should lib/h2xs.t See if h2xs produces expected lists of files lib/integer.pm For "use integer" lib/integer.t For "use integer" testing +lib/Internals.pod Document the Internals namespace (implemented by universal.c) lib/Internals.t For Internals::* testing lib/less.pm For "use less" lib/less.t See if less support works diff --git a/Porting/Maintainers.pl b/Porting/Maintainers.pl index 64135bf..58a74b6 100755 --- a/Porting/Maintainers.pl +++ b/Porting/Maintainers.pl @@ -1467,6 +1467,7 @@ use File::Glob qw(:case); lib/FileHandle.{pm,t} lib/FindBin.{pm,t} lib/Getopt/Std.{pm,t} + lib/Internals.pod lib/Internals.t lib/meta_notation.{pm,t} lib/Net/hostent.{pm,t} diff --git a/Porting/Maintainers.pm b/Porting/Maintainers.pm index 6b28ea7..ef56abb 100644 --- a/Porting/Maintainers.pm +++ b/Porting/Maintainers.pm @@ -22,7 +22,7 @@ use vars qw(@ISA @EXPORT_OK $VERSION); show_results process_options files_to_modules finish_tap_output reload_manifest); -$VERSION = 0.10; +$VERSION = 0.11; require Exporter; @@ -356,7 +356,7 @@ sub duplicated_maintainers { sub warn_maintainer { my $name = shift; - ok($files{$name}, "$name has a maintainer"); + ok($files{$name}, "$name has a maintainer (see Porting/Maintainer.pl)"); } sub missing_maintainers { diff --git a/lib/Internals.pod b/lib/Internals.pod new file mode 100644 index 0000000..28f6711 --- /dev/null +++ b/lib/Internals.pod @@ -0,0 +1,69 @@ +=head1 NAME + +Internals - Reserved special namespace for internals related functions + +=head1 SYNOPSIS + + $is_ro= Internals::SvREADONLY($x) + $refcnt= Internals::SvREFCNT($x) + +=head1 DESCRIPTION + +The Internals namespace is used by the core Perl development team to +expose certain low level internals routines for testing and other purposes. + +In theory these routines were not and are not intended to be used outside +of the perl core, and are subject to change and removal at any time. + +In practice people have come to depend on these over the years, despite +being historically undocumented, so we will provide some level of +forward compatibility for some time. Nevertheless you can assume that any +routine documented here is experimental or deprecated and you should find +alternatives to their use. + +=head2 FUNCTIONS + +=over 4 + +=item SvREFCNT(THING [, $value]) + +Historically Perl has been a refcounted language. This means that each +variable tracks how many things reference it, and when the variable is no +longer referenced it will automatically free itself. In theory Perl code +should not have to care about this, and in a future version Perl might +change to some other strategy, although in practice this is unlikely. + +This function allows one to violate the abstraction of variables and get +or set the refcount of a variable, and in generally is really only useful +in code that is testing refcount behavior. + +*NOTE* You are strongly discouraged from using this function in non-test +code and especially discouraged from using the set form of this function. +The results of doing so may result in segmentation faults or other undefined +behavior. + +=item SvREADONLY(THING, [, $value]) + +Set or get whether a variable is readonly or not. Exactly what the +readonly flag means depend on the type of the variable affected and the +version of perl used. + +You are strongly discouraged from using this function directly. It is used +by various core modules, like C<Hash::Util>, and the C<constant> pragma +to implement higher-level behavior which should be used instead. + +See the core implementation for the exact meaning of the readonly flag for +each internal variable type. + +=back + +=head1 AUTHOR + +Perl core development team. + +=head1 SEE ALSO + +L<perlguts> +universal.c + +=cut diff --git a/sv.h b/sv.h index db42a66..07719a6 100644 --- a/sv.h +++ b/sv.h @@ -269,7 +269,8 @@ struct p5rx { =head1 SV Manipulation Functions =for apidoc Am|U32|SvREFCNT|SV* sv -Returns the value of the object's reference count. +Returns the value of the object's reference count. Exposed +to perl code via Internals::SvREFCNT(). =for apidoc Am|SV*|SvREFCNT_inc|SV* sv Increments the reference count of the given SV, returning the SV. @@ -1089,6 +1090,22 @@ C<sv_force_normal> does nothing. #define SvOBJECT_on(sv) (SvFLAGS(sv) |= SVs_OBJECT) #define SvOBJECT_off(sv) (SvFLAGS(sv) &= ~SVs_OBJECT) +/* +=for apidoc Am|U32|SvREADONLY|SV* sv +Returns true if the argument is readonly, otherwise returns false. +Exposed to to perl code via Internals::SvREADONLY(). + +=for apidoc Am|U32|SvREADONLY_on|SV* sv +Mark an object as readonly. Exactly what this means depends on the object +type. Exposed to perl code via Internals::SvREADONLY(). + +=for apidoc Am|U32|SvREADONLY_off|SV* sv +Mark an object as not-readonly. Exactly what this mean depends on the +object type. Exposed to perl code via Internals::SvREADONLY(). + +=cut +*/ + #define SvREADONLY(sv) (SvFLAGS(sv) & (SVf_READONLY|SVf_PROTECT)) #ifdef PERL_CORE # define SvREADONLY_on(sv) (SvFLAGS(sv) |= (SVf_READONLY|SVf_PROTECT)) -- Perl5 Master Repository
