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