Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Devel::MAT::Dumper::HeUser(Contributed Perl DocumDevel::MAT::Dumper::Helper(3)

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.32.0			  2020-08-08	 Devel::MAT::Dumper::Helper(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Devel::MAT::Dumper::Helper&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help