Internals.pod revision 1.1.1.2
1=head1 NAME 2 3Internals - Reserved special namespace for internals related functions 4 5=head1 SYNOPSIS 6 7 $is_ro= Internals::SvREADONLY($x) 8 $refcnt= Internals::SvREFCNT($x) 9 hv_clear_placeholders(%hash); 10 11=head1 DESCRIPTION 12 13The Internals namespace is used by the core Perl development team to 14expose certain low level internals routines for testing and other purposes. 15 16In theory these routines were not and are not intended to be used outside 17of the perl core, and are subject to change and removal at any time. 18 19In practice people have come to depend on these over the years, despite 20being historically undocumented, so we will provide some level of 21forward compatibility for some time. Nevertheless you can assume that any 22routine documented here is experimental or deprecated and you should find 23alternatives to their use. 24 25=head2 FUNCTIONS 26 27=over 4 28 29=item SvREFCNT(THING [, $value]) 30 31Historically Perl has been a refcounted language. This means that each 32variable tracks how many things reference it, and when the variable is no 33longer referenced it will automatically free itself. In theory Perl code 34should not have to care about this, and in a future version Perl might 35change to some other strategy, although in practice this is unlikely. 36 37This function allows one to violate the abstraction of variables and get 38or set the refcount of a variable, and in generally is really only useful 39in code that is testing refcount behavior. 40 41*NOTE* You are strongly discouraged from using this function in non-test 42code and especially discouraged from using the set form of this function. 43The results of doing so may result in segmentation faults or other undefined 44behavior. 45 46=item SvREADONLY(THING, [, $value]) 47 48Set or get whether a variable is readonly or not. Exactly what the 49readonly flag means depend on the type of the variable affected and the 50version of perl used. 51 52You are strongly discouraged from using this function directly. It is used 53by various core modules, like C<Hash::Util>, and the C<constant> pragma 54to implement higher-level behavior which should be used instead. 55 56See the core implementation for the exact meaning of the readonly flag for 57each internal variable type. 58 59=item hv_clear_placeholders(%hash) 60 61Clear any placeholders from a locked hash. Should not be used directly. 62You should use the wrapper functions provided by Hash::Util instead. 63As of 5.25 also available as C< Hash::Util::_clear_placeholders(%hash) > 64 65=back 66 67=head1 AUTHOR 68 69Perl core development team. 70 71=head1 SEE ALSO 72 73L<perlguts> 74L<Hash::Util> 75L<constant> 76universal.c 77 78=cut 79