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); |
cb198164 YO |
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 | ||
e312a16a YO |
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 | ||
cb198164 YO |
65 | =back |
66 | ||
67 | =head1 AUTHOR | |
68 | ||
69 | Perl core development team. | |
70 | ||
71 | =head1 SEE ALSO | |
72 | ||
73 | L<perlguts> | |
e312a16a YO |
74 | L<Hash::Util> |
75 | L<constant> | |
cb198164 YO |
76 | universal.c |
77 | ||
78 | =cut |