From a8ce676243573e3e0787a433afc03bb51d029cb0 Mon Sep 17 00:00:00 2001 From: Leon Timmermans Date: Thu, 17 Jul 2025 18:59:22 +0200 Subject: [PATCH 1/2] Revert marking sv_dup and sv_dup_inc as core-only --- embed.fnc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/embed.fnc b/embed.fnc index fa56cb8c0241..b59570a3bc6f 100644 --- a/embed.fnc +++ b/embed.fnc @@ -6364,9 +6364,9 @@ CRdp |PERL_SI *|si_dup |NULLOK PERL_SI *si \ |NN CLONE_PARAMS *param CRdp |ANY * |ss_dup |NN PerlInterpreter *proto_perl \ |NN CLONE_PARAMS *param -CRdp |SV * |sv_dup |NULLOK const SV * const ssv \ +ARdp |SV * |sv_dup |NULLOK const SV * const ssv \ |NN CLONE_PARAMS * const param -CRdp |SV * |sv_dup_inc |NULLOK const SV * const ssv \ +ARdp |SV * |sv_dup_inc |NULLOK const SV * const ssv \ |NN CLONE_PARAMS * const param # if defined(PERL_IN_OP_C) || defined(PERL_IN_PEEP_C) p |void |op_relocate_sv |NN SV **svp \ From d7a4c9f2592f6bad8c8100e7ca4390a760e0c6e4 Mon Sep 17 00:00:00 2001 From: Leon Timmermans Date: Sun, 20 Jul 2025 16:55:13 +0200 Subject: [PATCH 2/2] Improve documentation of sv_dup and sv_dup_inc --- sv.c | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/sv.c b/sv.c index 8525e68fe887..44d98be42cda 100644 --- a/sv.c +++ b/sv.c @@ -14974,18 +14974,18 @@ S_sv_dup_common(pTHX_ const SV *const ssv, CLONE_PARAMS *const param) In spite of their generic names, these are very specialized functions mainly for use when cloning an interpreter instance. You are probably looking for -L. +L. Generally speaking you will only want to use these in +either a C magic handler, or a C method. They duplicate an SV of any type (not just a plain SV, but including AV, HV -I.), returning a pointer to the cloned object. The difference is that the -new SV under C has a reference count of 0, but 1 under C. -Only specialized cases will want a zero reference count, almost certainly only -when you aren't already holding a reference. Thus, you almost always want to -use the C form. - -The cloning process uses a cache, so that if a particular SV address has -already been duped, that duped SV is returned again rather than creating a -second duplicate. +I.), returning a pointer to the cloned object. The cloning process uses a +lookup table, so that if a particular source SV address has already been duped, +that duped SV is returned rather than creating a second duplicate. + +The difference is that the new SV under C will not have its reference count incremented +(potentially causing it to be zero), unlike under C. This is only +desirable when cloning a non-owning pointer. Thus, you almost always want to use +the C form. C has type S>. This is mostly for internal core use when duplicating something more complicated than an SV (code in common is