Skip to content

Commit 13a98d6

Browse files
committed
perlintern: Document sv_dup(_inc)?
This moves these from perlapi to perlintern, adding documentation.
1 parent 22496f1 commit 13a98d6

File tree

2 files changed

+31
-2
lines changed

2 files changed

+31
-2
lines changed

embed.fnc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6364,9 +6364,9 @@ CRdp |PERL_SI *|si_dup |NULLOK PERL_SI *si \
63646364
|NN CLONE_PARAMS *param
63656365
CRdp |ANY * |ss_dup |NN PerlInterpreter *proto_perl \
63666366
|NN CLONE_PARAMS *param
6367-
ARp |SV * |sv_dup |NULLOK const SV * const ssv \
6367+
CRdp |SV * |sv_dup |NULLOK const SV * const ssv \
63686368
|NN CLONE_PARAMS * const param
6369-
ARp |SV * |sv_dup_inc |NULLOK const SV * const ssv \
6369+
CRdp |SV * |sv_dup_inc |NULLOK const SV * const ssv \
63706370
|NN CLONE_PARAMS * const param
63716371
# if defined(PERL_IN_OP_C) || defined(PERL_IN_PEEP_C)
63726372
p |void |op_relocate_sv |NN SV **svp \

sv.c

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14968,6 +14968,35 @@ S_sv_dup_common(pTHX_ const SV *const ssv, CLONE_PARAMS *const param)
1496814968
return dsv;
1496914969
}
1497014970

14971+
/*
14972+
=for apidoc sv_dup
14973+
=for apidoc_item sv_dup_inc
14974+
14975+
In spite of their generic names, these are very specialized functions mainly
14976+
for use when cloning an interpreter instance. You are probably looking for
14977+
L<perlapi/newSVsv>.
14978+
14979+
They duplicate an SV of any type (not just a plain SV, but including AV, HV
14980+
I<etc>.), returning a pointer to the cloned object. The difference is that the
14981+
new SV under C<sv_dup> has a reference count of 0, but 1 under C<sv_dup_inc>.
14982+
Only specialized cases will want a zero reference count, almost certainly only
14983+
when you aren't already holding a reference. Thus, you almost always want to
14984+
use the C<sv_dup_inc> form.
14985+
14986+
The cloning process uses a cache, so that if a particular SV address has
14987+
already been duped, that duped SV is returned again rather than creating a
14988+
second duplicate.
14989+
14990+
C<param> has type S<C<CLONE_PARAMS *>>. This is mostly for internal core use
14991+
when duplicating something more complicated than an SV (code in common is
14992+
used). Your code may inherit this parameter, which you merely pass on, but you
14993+
can initialize it by using C<clone_params_new>. Don't forget to
14994+
free it when done, via C<clone_params_del>>. Its only member that is
14995+
public is C<flags>, all which are documented in L<perlapi/perl_clone>.
14996+
14997+
=cut
14998+
*/
14999+
1497115000
SV *
1497215001
Perl_sv_dup_inc(pTHX_ const SV *const ssv, CLONE_PARAMS *const param)
1497315002
{

0 commit comments

Comments
 (0)