From d2c37d3cee2dc3caa1b08905f855f01d28ee09b1 Mon Sep 17 00:00:00 2001 From: Daniel Dragan Date: Sat, 28 Dec 2024 05:34:05 -0500 Subject: [PATCH] sv.h: struct body_details bodies_by_type is unreadable, add more comments -Comments only patch. -Note! This commit edits sv_inline.h. sv.h is NOT edited. "sv_inline.h" is too long to fit in the git title. "sv.h: improve comments" is the same thing as "sv_inline.h: improve comments" for anyone looking at the git log. -the C type decl of "struct body_details" is more than 1 screenful up, from the initialization and setting contents of "struct body_details". -setting up a split-screen in an IDE takes a couple clicks/key-strokes and a few seconds of time -alternative of pressing PgUp/PgDwn still takes wall time -pressing key F1 "Jump next bookmark" takes less wall time PgUp/PgDwn but still takes wall time -pressing any key even once, is slower than moving your eyes -no core or CPAN XS dev needs to unconditionally memorizing what is inside "struct body_details" as bare minimum Perl C API knowledge required to write bug-free-stable Perl C code and stop SEGVs/heap corruption. Remembering "SV *nsv = newSV(0); *nsv = *old_sv;" is illegal, is the law. Remembering "struct body_details" values and ghost fields is optional. -CPAN perl illguts is nice, but too out of date to be safe to use or code against. Last updated was in 2014 for 5.20. Right now this is blead 5.41. -Recently perl has gotten alot of newSVAnyX(the_X) and sv_setAnyX_fresh(the_X) optimizations, like inline, and to understand those commits and changes requires looking at struct body_details alot. -So to fix all these issues. Add a comment summarizing the field names, right next to the values of the fields. If you see any line of code, with a SV body details value initializer, you always will see the summary comment somewhere on the same screen without scrolling. -make sure the comment is only 1 line for best screen space use - ", NV=0;, " is harder/slower to read than ", NV=0; , " -make sure the comment is always visible in the IDE whenever the cursor is inside the values, so the same comment is duplicated a few times to fix this bullet point -maybe in near future blead will get an optimization, shaving newSV(0x00000000) newSV_false() newSV_true() newSV_zero() newSVbool(a_bool) newSViv(2) newSVnv(3.0) down to 3 CPU OPs if x86-32b perl. Makes the body table more readable for any dev writing any future commit in this category or style. -Chk this commit's PR/ticket for newSVnv() is 3 CPU OP details. --- intrpvar.h | 3 ++- sv_inline.h | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/intrpvar.h b/intrpvar.h index 482f46d71885..3889d683e966 100644 --- a/intrpvar.h +++ b/intrpvar.h @@ -198,7 +198,8 @@ C<&PL_sv_undef>. =for apidoc Amn|SV|PL_sv_no This is the C SV. It is readonly. See C>. Always refer -to this as C<&PL_sv_no>. +to this as C<&PL_sv_no>. Also see C>. That is similar except +for its string value. C<&PL_sv_no>'s string value is empty string C<"">. =for apidoc Amn|SV|PL_sv_yes This is the C SV. It is readonly. See C>. Always refer to diff --git a/sv_inline.h b/sv_inline.h index 57a68796cb02..6f85df263804 100644 --- a/sv_inline.h +++ b/sv_inline.h @@ -180,6 +180,7 @@ ALIGNED_TYPE(XPVOBJ); STRUCT_OFFSET(type, last_member) \ + sizeof (((type*)SvANY((const SV *)0))->last_member) +/* sz_if_arena, copy_sz, ghost_sz, SVt, !upg, NV=0; , has_arena, arena_sz */ static const struct body_details bodies_by_type[] = { /* HEs use this offset for their arena. */ { 0, 0, 0, SVt_NULL, FALSE, NONV, NOARENA, 0 }, @@ -206,7 +207,7 @@ static const struct body_details bodies_by_type[] = { + STRUCT_OFFSET(XPV, xpv_cur), SVt_PV, FALSE, NONV, HASARENA, FIT_ARENA(0, sizeof(XPV) - STRUCT_OFFSET(XPV, xpv_cur)) }, - +/* sz_if_arena, copy_sz, ghost_sz, SVt, !upg, NV=0; , has_arena, arena_sz */ { sizeof(XINVLIST) - STRUCT_OFFSET(XPV, xpv_cur), copy_length(XINVLIST, is_offset) - STRUCT_OFFSET(XPV, xpv_cur), + STRUCT_OFFSET(XPV, xpv_cur), @@ -238,6 +239,7 @@ static const struct body_details bodies_by_type[] = { SVt_PVNV, FALSE, HADNV, HASARENA, FIT_ARENA(0, sizeof(XPVNV) - STRUCT_OFFSET(XPV, xpv_cur)) }, #endif +/* sz_if_arena, copy_sz, ghost_sz, SVt, !upg, NV=0; , has_arena, arena_sz */ { sizeof(XPVMG), copy_length(XPVMG, xnv_u), 0, SVt_PVMG, FALSE, HADNV, HASARENA, FIT_ARENA(0, sizeof(XPVMG)) }, @@ -271,7 +273,7 @@ static const struct body_details bodies_by_type[] = { 0, SVt_PVCV, TRUE, NONV, HASARENA, FIT_ARENA(0, sizeof(ALIGNED_TYPE_NAME(XPVCV))) }, - +/* sz_if_arena, copy_sz, ghost_sz, SVt, !upg, NV=0; , has_arena, arena_sz */ { sizeof(ALIGNED_TYPE_NAME(XPVFM)), sizeof(XPVFM), 0,