This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
https://perl5.git.perl.org / perl5.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Update perlfaq to CPAN version 5.20200523
[perl5.git] / pad.h
diff --git a/pad.h b/pad.h
index 941ca10..07c4d86 100644 (file)
--- a/pad.h
+++ b/pad.h
@@ -11,20 +11,9 @@
  * variables, op targets and constants.
  */
 
  * variables, op targets and constants.
  */
 
-/*
-=head1 Pad Data Structures
-*/
-
-
 /* offsets within a pad */
 
 /* offsets within a pad */
 
-#if PTRSIZE == 4
-typedef U32TYPE PADOFFSET;
-#else
-#   if PTRSIZE == 8
-typedef U64TYPE PADOFFSET;
-#   endif
-#endif
+typedef SSize_t PADOFFSET; /* signed so that -1 is a valid value */
 #define NOT_IN_PAD ((PADOFFSET) -1)
 
 /* B.xs expects the first members of these two structs to line up
 #define NOT_IN_PAD ((PADOFFSET) -1)
 
 /* B.xs expects the first members of these two structs to line up
@@ -34,13 +23,13 @@ typedef U64TYPE PADOFFSET;
 struct padlist {
     SSize_t    xpadl_max;      /* max index for which array has space */
     union {
 struct padlist {
     SSize_t    xpadl_max;      /* max index for which array has space */
     union {
-       PAD **  xpadlarr_alloc; /* Pointer to beginning of array of AVs.
-                                  index 0 is a padnamelist *          */
-       struct {
-           PADNAMELIST * padnl;
-           PAD * pad_1;        /* this slice of PAD * array always alloced */
-           PAD * pad_2;        /* maybe unalloced */
-       } * xpadlarr_dbg;       /* for use with a C debugger only */
+        PAD ** xpadlarr_alloc; /* Pointer to beginning of array of AVs.
+                                   index 0 is a padnamelist *          */
+        struct {
+            PADNAMELIST * padnl;
+            PAD * pad_1;        /* this slice of PAD * array always alloced */
+            PAD * pad_2;        /* maybe unalloced */
+        } * xpadlarr_dbg;       /* for use with a C debugger only */
     } xpadl_arr;
     U32                xpadl_id;       /* Semi-unique ID, shared between clones */
     U32                xpadl_outid;    /* ID of outer pad */
     } xpadl_arr;
     U32                xpadl_id;       /* Semi-unique ID, shared between clones */
     U32                xpadl_outid;    /* ID of outer pad */
@@ -69,8 +58,8 @@ struct padnamelist {
     char *     xpadn_pv;               \
     HV *       xpadn_ourstash;         \
     union {                            \
     char *     xpadn_pv;               \
     HV *       xpadn_ourstash;         \
     union {                            \
-       HV *    xpadn_typestash;        \
-       CV *    xpadn_protocv;          \
+        HV *   xpadn_typestash;        \
+        CV *   xpadn_protocv;          \
     } xpadn_type_u;                    \
     U32                xpadn_low;              \
     U32                xpadn_high;             \
     } xpadn_type_u;                    \
     U32                xpadn_low;              \
     U32                xpadn_high;             \
@@ -103,8 +92,8 @@ struct padname_with_str {
  */
 #define PERL_PADSEQ_INTRO  U32_MAX
 #define COP_SEQMAX_INC \
  */
 #define PERL_PADSEQ_INTRO  U32_MAX
 #define COP_SEQMAX_INC \
-       (PL_cop_seqmax++, \
-        (void)(PL_cop_seqmax == PERL_PADSEQ_INTRO && PL_cop_seqmax++))
+        (PL_cop_seqmax++, \
+         (void)(PL_cop_seqmax == PERL_PADSEQ_INTRO && PL_cop_seqmax++))
 
 
 /* B.xs needs these for the benefit of B::Deparse */
 
 
 /* B.xs needs these for the benefit of B::Deparse */
@@ -130,9 +119,9 @@ struct padname_with_str {
 /* values for the pad_tidy() function */
 
 typedef enum {
 /* values for the pad_tidy() function */
 
 typedef enum {
-       padtidy_SUB,            /* tidy up a pad for a sub, */
-       padtidy_SUBCLONE,       /* a cloned sub, */
-       padtidy_FORMAT          /* or a format */
+        padtidy_SUB,           /* tidy up a pad for a sub, */
+        padtidy_SUBCLONE,      /* a cloned sub, */
+        padtidy_FORMAT         /* or a format */
 } padtidy_type;
 
 /* flags for pad_add_name_pvn. */
 } padtidy_type;
 
 /* flags for pad_add_name_pvn. */
@@ -141,7 +130,7 @@ typedef enum {
 #define padadd_STATE           0x02       /* state declaration. */
 #define padadd_NO_DUP_CHECK    0x04       /* skip warning on dups. */
 #define padadd_STALEOK         0x08       /* allow stale lexical in active
 #define padadd_STATE           0x02       /* state declaration. */
 #define padadd_NO_DUP_CHECK    0x04       /* skip warning on dups. */
 #define padadd_STALEOK         0x08       /* allow stale lexical in active
-                                           * sub, but only one level up */
+                                            * sub, but only one level up */
 
 /* ASSERT_CURPAD_LEGAL and ASSERT_CURPAD_ACTIVE respectively determine
  * whether PL_comppad and PL_curpad are consistent and whether they have
 
 /* ASSERT_CURPAD_LEGAL and ASSERT_CURPAD_ACTIVE respectively determine
  * whether PL_comppad and PL_curpad are consistent and whether they have
@@ -153,15 +142,15 @@ typedef enum {
 #  define ASSERT_CURPAD_LEGAL(label) \
     pad_peg(label); \
     if (PL_comppad ? (AvARRAY(PL_comppad) != PL_curpad) : (PL_curpad != 0))  \
 #  define ASSERT_CURPAD_LEGAL(label) \
     pad_peg(label); \
     if (PL_comppad ? (AvARRAY(PL_comppad) != PL_curpad) : (PL_curpad != 0))  \
-       Perl_croak(aTHX_ "panic: illegal pad in %s: 0x%" UVxf "[0x%" UVxf "]",\
-           label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
+        Perl_croak(aTHX_ "panic: illegal pad in %s: 0x%" UVxf "[0x%" UVxf "]",\
+            label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
 
 
 #  define ASSERT_CURPAD_ACTIVE(label) \
     pad_peg(label); \
     if (!PL_comppad || (AvARRAY(PL_comppad) != PL_curpad))               \
 
 
 #  define ASSERT_CURPAD_ACTIVE(label) \
     pad_peg(label); \
     if (!PL_comppad || (AvARRAY(PL_comppad) != PL_curpad))               \
-       Perl_croak(aTHX_ "panic: invalid pad in %s: 0x%" UVxf "[0x%" UVxf "]",\
-           label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
+        Perl_croak(aTHX_ "panic: invalid pad in %s: 0x%" UVxf "[0x%" UVxf "]",\
+            label, PTR2UV(PL_comppad), PTR2UV(PL_curpad));
 #else
 #  define ASSERT_CURPAD_LEGAL(label)
 #  define ASSERT_CURPAD_ACTIVE(label)
 #else
 #  define ASSERT_CURPAD_LEGAL(label)
 #  define ASSERT_CURPAD_ACTIVE(label)
@@ -176,7 +165,10 @@ typedef enum {
 =for apidoc m|void|SAVEPADSV   |PADOFFSET po
 Save a pad slot (used to restore after an iteration)
 
 =for apidoc m|void|SAVEPADSV   |PADOFFSET po
 Save a pad slot (used to restore after an iteration)
 
+=cut
+
 XXX DAPM it would make more sense to make the arg a PADOFFSET
 XXX DAPM it would make more sense to make the arg a PADOFFSET
+
 =for apidoc m|void|SAVECLEARSV |SV **svp
 Clear the pointed to pad value on scope exit.  (i.e. the runtime action of
 C<my>)
 =for apidoc m|void|SAVECLEARSV |SV **svp
 Clear the pointed to pad value on scope exit.  (i.e. the runtime action of
 C<my>)
@@ -185,79 +177,79 @@ C<my>)
 save C<PL_comppad> and C<PL_curpad>
 
 
 save C<PL_comppad> and C<PL_curpad>
 
 
-=for apidoc Amx|PAD **|PadlistARRAY|PADLIST padlist
+=for apidoc Amx|PAD **|PadlistARRAY|PADLIST * padlist
 The C array of a padlist, containing the pads.  Only subscript it with
 numbers >= 1, as the 0th entry is not guaranteed to remain usable.
 
 The C array of a padlist, containing the pads.  Only subscript it with
 numbers >= 1, as the 0th entry is not guaranteed to remain usable.
 
-=for apidoc Amx|SSize_t|PadlistMAX|PADLIST padlist
+=for apidoc Amx|SSize_t|PadlistMAX|PADLIST * padlist
 The index of the last allocated space in the padlist.  Note that the last
 pad may be in an earlier slot.  Any entries following it will be C<NULL> in
 that case.
 
 The index of the last allocated space in the padlist.  Note that the last
 pad may be in an earlier slot.  Any entries following it will be C<NULL> in
 that case.
 
-=for apidoc Amx|PADNAMELIST *|PadlistNAMES|PADLIST padlist
+=for apidoc Amx|PADNAMELIST *|PadlistNAMES|PADLIST * padlist
 The names associated with pad entries.
 
 The names associated with pad entries.
 
-=for apidoc Amx|PADNAME **|PadlistNAMESARRAY|PADLIST padlist
+=for apidoc Amx|PADNAME **|PadlistNAMESARRAY|PADLIST * padlist
 The C array of pad names.
 
 The C array of pad names.
 
-=for apidoc Amx|SSize_t|PadlistNAMESMAX|PADLIST padlist
+=for apidoc Amx|SSize_t|PadlistNAMESMAX|PADLIST * padlist
 The index of the last pad name.
 
 The index of the last pad name.
 
-=for apidoc Amx|U32|PadlistREFCNT|PADLIST padlist
+=for apidoc Amx|U32|PadlistREFCNT|PADLIST * padlist
 The reference count of the padlist.  Currently this is always 1.
 
 The reference count of the padlist.  Currently this is always 1.
 
-=for apidoc Amx|PADNAME **|PadnamelistARRAY|PADNAMELIST pnl
+=for apidoc Amx|PADNAME **|PadnamelistARRAY|PADNAMELIST * pnl
 The C array of pad names.
 
 The C array of pad names.
 
-=for apidoc Amx|SSize_t|PadnamelistMAX|PADNAMELIST pnl
+=for apidoc Amx|SSize_t|PadnamelistMAX|PADNAMELIST * pnl
 The index of the last pad name.
 
 The index of the last pad name.
 
-=for apidoc Amx|SSize_t|PadnamelistREFCNT|PADNAMELIST pnl
+=for apidoc Amx|SSize_t|PadnamelistREFCNT|PADNAMELIST * pnl
 The reference count of the pad name list.
 
 The reference count of the pad name list.
 
-=for apidoc Amx|void|PadnamelistREFCNT_dec|PADNAMELIST pnl
+=for apidoc Amx|void|PadnamelistREFCNT_dec|PADNAMELIST * pnl
 Lowers the reference count of the pad name list.
 
 Lowers the reference count of the pad name list.
 
-=for apidoc Amx|SV **|PadARRAY|PAD pad
+=for apidoc Amx|SV **|PadARRAY|PAD * pad
 The C array of pad entries.
 
 The C array of pad entries.
 
-=for apidoc Amx|SSize_t|PadMAX|PAD pad
+=for apidoc Amx|SSize_t|PadMAX|PAD * pad
 The index of the last pad entry.
 
 The index of the last pad entry.
 
-=for apidoc Amx|char *|PadnamePV|PADNAME pn    
+=for apidoc Amx|char *|PadnamePV|PADNAME * pn
 The name stored in the pad name struct.  This returns C<NULL> for a target
 slot.
 
 The name stored in the pad name struct.  This returns C<NULL> for a target
 slot.
 
-=for apidoc Amx|STRLEN|PadnameLEN|PADNAME pn   
+=for apidoc Amx|STRLEN|PadnameLEN|PADNAME * pn
 The length of the name.
 
 The length of the name.
 
-=for apidoc Amx|bool|PadnameUTF8|PADNAME pn
+=for apidoc Amx|bool|PadnameUTF8|PADNAME * pn
 Whether PadnamePV is in UTF-8.  Currently, this is always true.
 
 Whether PadnamePV is in UTF-8.  Currently, this is always true.
 
-=for apidoc Amx|SV *|PadnameSV|PADNAME pn
+=for apidoc Amx|SV *|PadnameSV|PADNAME * pn
 Returns the pad name as a mortal SV.
 
 Returns the pad name as a mortal SV.
 
-=for apidoc m|bool|PadnameIsOUR|PADNAME pn
+=for apidoc m|bool|PadnameIsOUR|PADNAME * pn
 Whether this is an "our" variable.
 
 Whether this is an "our" variable.
 
-=for apidoc m|HV *|PadnameOURSTASH
+=for apidoc m|HV *|PadnameOURSTASH|PADNAME * pn
 The stash in which this "our" variable was declared.
 
 The stash in which this "our" variable was declared.
 
-=for apidoc m|bool|PadnameOUTER|PADNAME pn
+=for apidoc m|bool|PadnameOUTER|PADNAME * pn
 Whether this entry belongs to an outer pad.  Entries for which this is true
 are often referred to as 'fake'.
 
 Whether this entry belongs to an outer pad.  Entries for which this is true
 are often referred to as 'fake'.
 
-=for apidoc m|bool|PadnameIsSTATE|PADNAME pn
+=for apidoc m|bool|PadnameIsSTATE|PADNAME * pn
 Whether this is a "state" variable.
 
 Whether this is a "state" variable.
 
-=for apidoc m|HV *|PadnameTYPE|PADNAME pn
+=for apidoc m|HV *|PadnameTYPE|PADNAME * pn
 The stash associated with a typed lexical.  This returns the C<%Foo::> hash
 for C<my Foo $bar>.
 
 The stash associated with a typed lexical.  This returns the C<%Foo::> hash
 for C<my Foo $bar>.
 
-=for apidoc Amx|SSize_t|PadnameREFCNT|PADNAME pn
+=for apidoc Amx|SSize_t|PadnameREFCNT|PADNAME * pn
 The reference count of the pad name.
 
 The reference count of the pad name.
 
-=for apidoc Amx|void|PadnameREFCNT_dec|PADNAME pn
+=for apidoc Amx|void|PadnameREFCNT_dec|PADNAME * pn
 Lowers the reference count of the pad name.
 
 
 Lowers the reference count of the pad name.
 
 
@@ -321,7 +313,7 @@ Restore the old pad saved into the local variable C<opad> by C<PAD_SAVE_LOCAL()>
 #define PadnameLEN(pn)         (pn)->xpadn_len
 #define PadnameUTF8(pn)                1
 #define PadnameSV(pn) \
 #define PadnameLEN(pn)         (pn)->xpadn_len
 #define PadnameUTF8(pn)                1
 #define PadnameSV(pn) \
-       newSVpvn_flags(PadnamePV(pn), PadnameLEN(pn), SVs_TEMP|SVf_UTF8)
+        newSVpvn_flags(PadnamePV(pn), PadnameLEN(pn), SVs_TEMP|SVf_UTF8)
 #define PadnameFLAGS(pn)       (pn)->xpadn_flags
 #define PadnameIsOUR(pn)       (!!(pn)->xpadn_ourstash)
 #define PadnameOURSTASH(pn)    (pn)->xpadn_ourstash
 #define PadnameFLAGS(pn)       (pn)->xpadn_flags
 #define PadnameIsOUR(pn)       (!!(pn)->xpadn_ourstash)
 #define PadnameOURSTASH(pn)    (pn)->xpadn_ourstash
@@ -368,43 +360,43 @@ Restore the old pad saved into the local variable C<opad> by C<PAD_SAVE_LOCAL()>
 #define PAD_SVl(po)       (PL_curpad[po])
 
 #define PAD_BASE_SV(padlist, po) \
 #define PAD_SVl(po)       (PL_curpad[po])
 
 #define PAD_BASE_SV(padlist, po) \
-       (PadlistARRAY(padlist)[1])                                      \
-           ? AvARRAY(MUTABLE_AV((PadlistARRAY(padlist)[1])))[po] \
-           : NULL;
+        (PadlistARRAY(padlist)[1])                                     \
+            ? AvARRAY(MUTABLE_AV((PadlistARRAY(padlist)[1])))[po] \
+            : NULL;
 
 
 #define PAD_SET_CUR_NOSAVE(padlist,nth) \
 
 
 #define PAD_SET_CUR_NOSAVE(padlist,nth) \
-       PL_comppad = (PAD*) (PadlistARRAY(padlist)[nth]);       \
-       PL_curpad = AvARRAY(PL_comppad);                        \
-       DEBUG_Xv(PerlIO_printf(Perl_debug_log,                  \
-             "Pad 0x%" UVxf "[0x%" UVxf "] set_cur    depth=%d\n",     \
-             PTR2UV(PL_comppad), PTR2UV(PL_curpad), (int)(nth)));
+        PL_comppad = (PAD*) (PadlistARRAY(padlist)[nth]);      \
+        PL_curpad = AvARRAY(PL_comppad);                       \
+        DEBUG_Xv(PerlIO_printf(Perl_debug_log,                 \
+              "Pad 0x%" UVxf "[0x%" UVxf "] set_cur    depth=%d\n",    \
+              PTR2UV(PL_comppad), PTR2UV(PL_curpad), (int)(nth)));
 
 
 #define PAD_SET_CUR(padlist,nth) \
 
 
 #define PAD_SET_CUR(padlist,nth) \
-       SAVECOMPPAD();                                          \
-       PAD_SET_CUR_NOSAVE(padlist,nth);
+        SAVECOMPPAD();                                         \
+        PAD_SET_CUR_NOSAVE(padlist,nth);
 
 
 #define PAD_SAVE_SETNULLPAD()  SAVECOMPPAD(); \
 
 
 #define PAD_SAVE_SETNULLPAD()  SAVECOMPPAD(); \
-       PL_comppad = NULL; PL_curpad = NULL;    \
-       DEBUG_Xv(PerlIO_printf(Perl_debug_log, "Pad set_null\n"));
+        PL_comppad = NULL; PL_curpad = NULL;   \
+        DEBUG_Xv(PerlIO_printf(Perl_debug_log, "Pad set_null\n"));
 
 #define PAD_SAVE_LOCAL(opad,npad) \
 
 #define PAD_SAVE_LOCAL(opad,npad) \
-       opad = PL_comppad;                                      \
-       PL_comppad = (npad);                                    \
-       PL_curpad =  PL_comppad ? AvARRAY(PL_comppad) : NULL;   \
-       DEBUG_Xv(PerlIO_printf(Perl_debug_log,                  \
-             "Pad 0x%" UVxf "[0x%" UVxf "] save_local\n",              \
-             PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
+        opad = PL_comppad;                                     \
+        PL_comppad = (npad);                                   \
+        PL_curpad =  PL_comppad ? AvARRAY(PL_comppad) : NULL;  \
+        DEBUG_Xv(PerlIO_printf(Perl_debug_log,                 \
+              "Pad 0x%" UVxf "[0x%" UVxf "] save_local\n",             \
+              PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
 
 #define PAD_RESTORE_LOCAL(opad) \
         assert(!opad || !SvIS_FREED(opad));                                    \
 
 #define PAD_RESTORE_LOCAL(opad) \
         assert(!opad || !SvIS_FREED(opad));                                    \
-       PL_comppad = opad;                                              \
-       PL_curpad =  PL_comppad ? AvARRAY(PL_comppad) : NULL;   \
-       DEBUG_Xv(PerlIO_printf(Perl_debug_log,                  \
-             "Pad 0x%" UVxf "[0x%" UVxf "] restore_local\n",   \
-             PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
+        PL_comppad = opad;                                             \
+        PL_curpad =  PL_comppad ? AvARRAY(PL_comppad) : NULL;  \
+        DEBUG_Xv(PerlIO_printf(Perl_debug_log,                 \
+              "Pad 0x%" UVxf "[0x%" UVxf "] restore_local\n",  \
+              PTR2UV(PL_comppad), PTR2UV(PL_curpad)));
 
 
 /*
 
 
 /*
@@ -487,7 +479,7 @@ Clone the state variables associated with running and compiling pads.
     PL_comppad                 = av_dup(proto_perl->Icomppad, param);  \
     PL_curpad = PL_comppad ?  AvARRAY(PL_comppad) : NULL;              \
     PL_comppad_name            =                                       \
     PL_comppad                 = av_dup(proto_perl->Icomppad, param);  \
     PL_curpad = PL_comppad ?  AvARRAY(PL_comppad) : NULL;              \
     PL_comppad_name            =                                       \
-                 padnamelist_dup(proto_perl->Icomppad_name, param);    \
+                  padnamelist_dup(proto_perl->Icomppad_name, param);   \
     PL_comppad_name_fill       = proto_perl->Icomppad_name_fill;       \
     PL_comppad_name_floor      = proto_perl->Icomppad_name_floor;      \
     PL_min_intro_pending       = proto_perl->Imin_intro_pending;       \
     PL_comppad_name_fill       = proto_perl->Icomppad_name_fill;       \
     PL_comppad_name_floor      = proto_perl->Icomppad_name_floor;      \
     PL_min_intro_pending       = proto_perl->Imin_intro_pending;       \
@@ -498,10 +490,10 @@ Clone the state variables associated with running and compiling pads.
     PL_cop_seqmax              = proto_perl->Icop_seqmax;
 
 /*
     PL_cop_seqmax              = proto_perl->Icop_seqmax;
 
 /*
-=for apidoc Am|PADOFFSET|pad_add_name_pvs|const char *name|U32 flags|HV *typestash|HV *ourstash
+=for apidoc Am|PADOFFSET|pad_add_name_pvs|"name"|U32 flags|HV *typestash|HV *ourstash
 
 
-Exactly like L</pad_add_name_pvn>, but takes a literal string instead
-of a string/length pair.
+Exactly like L</pad_add_name_pvn>, but takes a literal string
+instead of a string/length pair.
 
 =cut
 */
 
 =cut
 */
@@ -510,10 +502,10 @@ of a string/length pair.
     Perl_pad_add_name_pvn(aTHX_ STR_WITH_LEN(name), flags, typestash, ourstash)
 
 /*
     Perl_pad_add_name_pvn(aTHX_ STR_WITH_LEN(name), flags, typestash, ourstash)
 
 /*
-=for apidoc Am|PADOFFSET|pad_findmy_pvs|const char *name|U32 flags
+=for apidoc Am|PADOFFSET|pad_findmy_pvs|"name"|U32 flags
 
 
-Exactly like L</pad_findmy_pvn>, but takes a literal string instead
-of a string/length pair.
+Exactly like L</pad_findmy_pvn>, but takes a literal string
+instead of a string/length pair.
 
 =cut
 */
 
 =cut
 */
Unnamed repository; edit this file 'description' to name the repository.