perl-xs

Write an .xs file with the standard preamble (EXTERN.h, perl.h, XSUB.h, ppport.h), declare MODULE/PACKAGE sections, and define XSUBs whose arguments convert through a per-distribution typemap. Store C pointers as magic on blessed SVs using sv_magicext with a per-type MGVTBL whose svt_free hook releases the C resource.

Use sv_magicext to attach the pointer as PERL_MAGIC_ext magic on the blessed referent, with a static const MGVTBL unique to that type. The vtable address doubles as the type check via mg_findext, and its svt_free hook acts as the destructor, so no Perl DESTROY method is needed.

The child object likely incremented the refcount on ST(0), the reference, instead of SvRV(ST(0)), the blessed referent carrying the magic. Holding the reference does not keep the referent alive after undef or reassignment, so the child's C pointer dangles. Increment the referent and test all three ways of losing the variable.

The usual cause is an unescaped double quote in a typemap INPUT or OUTPUT template, which xsubpp evaluates as a Perl double-quoted string. Write quotes meant for the generated C as \". Spaces instead of literal TABs for template indentation cause similar silent parse failures.

Run crash-prone scenarios in forked children so a segfault fails one test instead of killing prove. Use Test::LeakTrace's no_leaks_ok for Perl-level leaks and valgrind with PERL_DESTRUCT_LEVEL=2 for C-level leaks. Guard blocking C calls with alarm so hangs become reported failures.

Avoid T_PTROBJ whenever the wrapped pointer needs cleanup or type safety. It stores the pointer with sv_setref_pv, offering no free hook and no vtable-based type check, so a hand-blessed hashref passes the boundary and segfaults. Use sv_magicext with a dedicated MGVTBL instead.