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 \ 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