1Devel::MAT::Dumper::HelUpseerr(3C)ontributed Perl DocumeDnetvaetli:o:nMAT::Dumper::Helper(3)
2
3
4

NAME

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

SYNOPSIS

10       In Build.PL
11
12          if( eval { require Devel::MAT::Dumper::Helper } ) {
13             Devel::MAT::Dumper::Helper->extend_module_build( $build );
14          }
15
16       In your module's XS source:
17
18          #ifdef HAVE_DMD_HELPER
19          #  include "DMD_helper.h"
20          #endif
21
22          ...
23
24          #ifdef HAVE_DMD_HELPER
25          static int dumpstruct(pTHX_ const SV *sv)
26          {
27            int ret = 0;
28
29            ret += DMD_ANNOTATE_SV(sv, another_sv,
30              "the description of this field");
31            ...
32
33            return ret;
34          }
35
36          static int dumpmagic(pTHX_ const SV *sv, MAGIC *mg)
37          {
38            int ret = 0;
39
40            ret += DMD_ANNOTATE_SV(sv, another_sv,
41              "the description of this field");
42            ...
43
44            return ret;
45          }
46          #endif
47
48          ...
49
50          BOOT:
51          #ifdef HAVE_DMD_HELPER
52            DMD_SET_PACKAGE_HELPER("My::Package", dumpstruct);
53            DMD_SET_MAGIC_HELPER(&vtbl, dumpmagic);
54          #endif
55

DESCRIPTION

57       This module provides a build-time helper to assist in writing XS
58       modules that can provide extra information to a Devel::MAT heap dump
59       file when dumping data structures relating to that module.
60
61       Following the example in the "SYNOPSIS" section above, the "dumpstruct"
62       function is called whenever Devel::MAT::Dumper finds an SV blessed into
63       the given package, and the "dumpmagic" function is called whenever
64       Devel::MAT::Dumper finds an SV with extension magic matching the given
65       magic virtual table pointer. These functions may then inspect the
66       module's state from the SV or MAGIC pointers, and invoke the
67       "DMD_ANNOTATE_SV" macro to provide extra annotations into the heap dump
68       file about how this SV is related to another one.
69
70       Under this code structure, a module will cleanly build, install and run
71       just fine if Devel::MAT::Dumper::Helper is not available at build time,
72       so it is not necessary to list that as a "configure_requires" or
73       "build_requires" requirement.
74
75       Additionally, the way the inserted code is structured does not cause
76       the XS module to load "Devel::MAT::Dumper" itself, so there is no
77       runtime dependency either, even if the support was made available. The
78       newly inserted code is only invoked if both "Devel::MAT::Dumper" and
79       this XS module are actually loaded.
80
81       Note that this entire mechanism is currently experimental.
82

FUNCTIONS

84   write_DMD_helper_h
85          Devel::MAT::Dumper::Helper->write_DMD_helper_h
86
87       Writes the DMD_helper.h file to the current working directory. To cause
88       the compiler to actually find this file, see extra_compiler_flags.
89
90   extra_compiler_flags
91          @flags = Devel::MAT::Dumper::Helper->extra_compiler_flags
92
93       Returns a list of extra flags that the build scripts should add to the
94       compiler invocation. This enables the C compiler to find the
95       DMD_helper.h file, and also defines a symbol "HAVE_DMD_HELPER" which
96       the XS code can then use in "#ifdef" guards:
97
98          #ifdef HAVE_DMD_HELPER
99          ...
100          #endif
101
102   extend_module_build
103          Devel::MAT::Dumper::Helper->extend_module_build( $build )
104
105       A convenient shortcut for performing all the tasks necessary to make a
106       Module::Build-based distribution use the helper.
107

AUTHOR

109       Paul Evans <leonerd@leonerd.org.uk>
110
111
112
113perl v5.34.0                      2022-01-21     Devel::MAT::Dumper::Helper(3)
Impressum