perlapi: Document sv_dup(_inc)?

[khwilliamson]

This replaces #19741

[iabyn]

LGTM. I'd suggest also mentioning briefly that the cloning process uses use a cache, so that if a particular SV address has already been duped, that duped SV is returned again rather than creating a second dup.

[Leont]

TBH I liked the old version better. Explaining one probably wants to use the _inc version is pretty crucial.

It may also be helpful to mention the ah/hv/etc… versions of this.

[jkeenan]

@khwilliamson, we have a difference of opinions among the code reviewers as to this merge request. Could you comment? Thanks.

[jkeenan]

@khwilliamson, we have a difference of opinions among the code reviewers as to this merge request. Could you comment? Thanks.

@khwilliamson, ^^

[bulk88]

LGTM. I'd suggest also mentioning briefly that the cloning process uses use a cache, so that if a particular SV address has already been duped, that duped SV is returned again rather than creating a second dup.

ptr_table_store() / ptr_table_find(tbl, oldsv) is internal api i think, but its underused and under documented in core, i dont know off my head of any bugs or flaws with ptr_tab api. Yes, the _dup() vs no _dup() is important but its not for cpan, just other future core devs to read. You have to be aware what C struct fields/arrays own SV-HV-CV refcnts, and what fields are only high speed shortcut lookups. Important to figure that out always before touching the ithread cloning code.

I see the "A" apidoc tag, but idk if sv_dup really was supposed to be public API, mg_dup is also not public api, Found only ONE xs module, total count. Didn't search too extensively.

sub CLONE, CLONE_SKIP, AV of weak SVRVs, and mg_dup work well enough I think. sv_dup()'s only use case is for XS mods, that really did "break" the last pointer link of a SV* back to main:: and gave over the 1 and only refcount to an SV*, over to an unreachable 3rd party c lib. so the perl clone/fork code can't find it. I want to call that a memory leak, others will disagree.

[Leont]

ptr_table_store() / ptr_table_find(tbl, oldsv) is internal api i think, but its underused and under documented in core, i dont know off my head of any bugs or flaws with ptr_tab api. Yes, the _dup() vs no _dup() is important but its not for cpan, just other future core devs to read. You have to be aware what C struct fields/arrays own SV-HV-CV refcnts, and what fields are only high speed shortcut lookups. Important to figure that out always before touching the ithread cloning code.

sub CLONE, CLONE_SKIP, AV of weak SVRVs, and mg_dup work well enough I think. sv_dup()'s only use case is for XS mods, that really did "break" the last pointer link of a SV* back to main:: and gave over the 1 and only refcount to an SV*, over to an unreachable 3rd party c lib. so the perl clone/fork code can't find it. I want to call that a memory leak, others will disagree.

As a side note, CLONE not getting a pointer to that cache (or actually clone parameters as a whole) makes it unusable IMHO. I really should get around to fixing that at some point.