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

write_DMD_helper_h

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

Writes the DMD_helper.h file to the current working directory. To cause the compiler to actually find this file, see extra_compiler_flags.

extra_compiler_flags

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

Returns a list of extra flags that the build scripts should add to the compiler invocation. This enables the C compiler to find the DMD_helper.h file, and also defines a symbol HAVE_DMD_HELPER which the XS code can then use in #ifdef guards:

   #ifdef HAVE_DMD_HELPER
   ...
   #endif

extend_module_build

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

A convenient shortcut for performing all the tasks necessary to make a Module::Build-based distribution use the helper.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>