summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Internals.pod
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-03-08 00:16:42 +0000
committerKarl Berry <karl@freefriends.org>2018-03-08 00:16:42 +0000
commit34a8597760ab5740abd49b6d8be10e1876f5ce98 (patch)
tree099a794912a28b3ebbc857961643ba29b28e674a /Master/tlpkg/tlperl/lib/Internals.pod
parent2ca3610031316a7312d046d3ae4c783452831216 (diff)
(tl)perl 5.26.1 from siep
git-svn-id: svn://tug.org/texlive/trunk@46882 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Internals.pod')
-rwxr-xr-xMaster/tlpkg/tlperl/lib/Internals.pod78
1 files changed, 78 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Internals.pod b/Master/tlpkg/tlperl/lib/Internals.pod
new file mode 100755
index 00000000000..4a1144afd6d
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Internals.pod
@@ -0,0 +1,78 @@
+=head1 NAME
+
+Internals - Reserved special namespace for internals related functions
+
+=head1 SYNOPSIS
+
+ $is_ro= Internals::SvREADONLY($x)
+ $refcnt= Internals::SvREFCNT($x)
+ hv_clear_placeholders(%hash);
+
+=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.
+
+=item hv_clear_placeholders(%hash)
+
+Clear any placeholders from a locked hash. Should not be used directly.
+You should use the wrapper functions providewd by Hash::Util instead.
+As of 5.25 also available as C< Hash::Util::_clear_placeholders(%hash) >
+
+=back
+
+=head1 AUTHOR
+
+Perl core development team.
+
+=head1 SEE ALSO
+
+L<perlguts>
+L<Hash::Util>
+L<constant>
+universal.c
+
+=cut