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