xs-fun | XS is fun : a simple and easy tutorial on writing Perl XS | Learning library

Upon further research, it turns out that SAVEDESTRUCTOR is in fact documented – in perlguts rather than perlapi. The exact semantics are documented there.

I therefore assume that SAVEDESTRUCTOR is supposed to be used as a "finally" block for cleanup, and is sufficiently safe and stable.

Excerpt from Localizing changes in perlguts, which discusses the equivalent to { local $foo; ... } blocks:

There is a way to achieve a similar task from C via Perl API: create a pseudo-block, and arrange for some changes to be automatically undone at the end of it, either explicit, or via a non-local exit (via die()). A block-like construct is created by a pair of ENTER/LEAVE macros (see Returning a Scalar in perlcall). Such a construct may be created specially for some important localized task, or an existing one (like boundaries of enclosing Perl subroutine/block, or an existing pair for freeing TMPs) may be used. (In the second case the overhead of additional localization must be almost negligible.) Note that any XSUB is automatically enclosed in an ENTER/LEAVE pair.

Inside such a pseudo-block the following service is available:

• […]

• SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)

  At the end of pseudo-block the function f is called with the only argument p.

• SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)

  At the end of pseudo-block the function f is called with the implicit context argument (if any), and p.

The section also lists a couple of specialized destructors, like SAVEFREESV(SV *sv) and SAVEMORTALIZESV(SV *sv) that may be more correct than a premature sv_2mortal() in some cases.

These macros have basically been available since effectively forever, at least Perl 5.6 or older.