threads::tbb::refcounter proposed API

refcounter.man

NAME
       threads::tbb::refcounter - inside-out refcounts for XS types

SYNOPSIS
        use threads::tbb::refcounter qw(Image::Magick);

DESCRIPTION
       This module allows XS modules which were not written with
       "threads::tbb" in mind (but are thread-safe) to be explicitly marked as
       passable between threads, without requiring the XS type to explicitly
       add a reference count field.

       What is does is it institutes an inside-out refcount for the type.  It
       delivers two methods to the target class: "DESTROY" and
       "CLONE_REFCNT_inc".

       These are simple "wrappers" which just take care to avoid double-free,
       or prematurely freeing XS references as they pass between interpreters.

       The "CLONE_REFCNT_inc" function increments a thread-safe process-global
       hash table mapping reference addresses of instances to counts of
       interpreters holding cloned pointers to that reference.

       The "DESTROY" function finds the entry in that process-global hash
       table, and if it doesn't exist or is already at 0, then it calls the
       original DESTROY function.  Otherwise, it decrements the counter.

       If either of these two functions are called, and the invocant is not an
       XS object (ie, not a PVMG), then they act like they weren't there (ie,
       they call the original DESTROY function, or they do nothing).

       Finally, it defines a "CLONE_SKIP" method in the target class, which
       returns 0.