NAME¶

"Devel::MAT::Dumper::Helper" - give XS modules extensions for memory dumping

SYNOPSIS¶

In Build.PL

   if( eval { require Devel::MAT::Dumper::Helper } ) {
      Devel::MAT::Dumper::Helper->extend_module_build( $build );
   }

In your module's XS source:

   #ifdef HAVE_DMD_HELPER
   #  include "DMD_helper.h"
   #endif
   ...
   #ifdef HAVE_DMD_HELPER
   static int dumpstruct(pTHX_ const SV *sv)
   {
     int ret = 0;
     ret += DMD_ANNOTATE_SV(sv, another_sv,
       "the description of this field");
     ...
     return ret;
   }
   static int dumpmagic(pTHX_ const SV *sv, MAGIC *mg)
   {
     int ret = 0;
     ret += DMD_ANNOTATE_SV(sv, another_sv,
       "the description of this field");
     ...
     return ret;
   }
   #endif
   ...
   BOOT:
   #ifdef HAVE_DMD_HELPER
     DMD_SET_PACKAGE_HELPER("My::Package", dumpstruct);
     DMD_SET_MAGIC_HELPER(&vtbl, dumpmagic);
   #endif

DESCRIPTION¶

This module provides a build-time helper to assist in writing XS modules that can provide extra information to a Devel::MAT heap dump file when dumping data structures relating to that module.

Following the example in the "SYNOPSIS" section above, the "dumpstruct" function is called whenever Devel::MAT::Dumper finds an SV blessed into the given package, and the "dumpmagic" function is called whenever Devel::MAT::Dumper finds an SV with extension magic matching the given magic virtual table pointer. These functions may then inspect the module's state from the SV or MAGIC pointers, and invoke the "DMD_ANNOTATE_SV" macro to provide extra annotations into the heap dump file about how this SV is related to another one.

Under this code structure, a module will cleanly build, install and run just fine if Devel::MAT::Dumper::Helper is not available at build time, so it is not necessary to list that as a "configure_requires" or "build_requires" requirement.

Additionally, the way the inserted code is structured does not cause the XS module to load "Devel::MAT::Dumper" itself, so there is no runtime dependency either, even if the support was made available. The newly inserted code is only invoked if both "Devel::MAT::Dumper" and this XS module are actually loaded.

Note that this entire mechanism is currently experimental.

FUNCTIONS¶

   Devel::MAT::Dumper::Helper->write_DMD_helper_h

   @flags = Devel::MAT::Dumper::Helper->extra_compiler_flags

   #ifdef HAVE_DMD_HELPER
   ...
   #endif

   Devel::MAT::Dumper::Helper->extend_module_build( $build )

AUTHOR¶

Paul Evans <leonerd@leonerd.org.uk>