NAME

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

SYNOPSIS

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

 # alternately:
 use threads::tbb::refcounter;
 threads::tbb::refcounter->setup("Some::XS::Type");

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.

The package must already be loaded when the DESTROY must be implemented by the class you are marking with (otherwise, it doesn't even make sense to use this module). So, if it doesn't find DESTROY, it will die early.

SEE ALSO

threads::tbb::concurrent