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