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>