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>

perl v5.34.0                                       2022-02-06                    Devel::MAT::Dumper::Helper(3pm)