lib/Internals.pod

   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     if (Internals::stack_refcounted & 1) { .... }
  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
  60 =item hv_clear_placeholders(%hash)
  61
  62 Clear any placeholders from a locked hash. Should not be used directly.
  63 You should use the wrapper functions provided by Hash::Util instead.
  64 As of 5.25 also available as C< Hash::Util::_clear_placeholders(%hash) >
  65
  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
  73 =back
  74
  75 =head1 AUTHOR
  76
  77 Perl core development team.
  78
  79 =head1 SEE ALSO
  80
  81 L<perlguts>
  82 L<Hash::Util>
  83 L<constant>
  84 universal.c
  85
  86 =cut