1XML::LibXML::Devel(3) User Contributed Perl DocumentationXML::LibXML::Devel(3)
2
3
4

NAME

6       XML::LibXML::Devel - makes functions from LibXML.xs available
7

SYNOPSIS

9         /**********************************************
10          * C functions you want to access
11          */
12         xmlNode *return_node();
13         void receive_node(xmlNode *);
14
15         ###############################################
16         # XS Code
17         void *
18           xs_return_node
19           CODE:
20               RETVAL = return_node();
21           OUTPUT:
22               RETVAL
23
24         void
25           xs_receive_node
26               void *n
27           CODE:
28               receive_node(n);
29
30         ###############################################
31         # Perl code
32         use XML::LibXML::Devel;
33
34         sub return_node
35         {
36           my $raw_node = xs_return_node();
37           my $node = XML::LibXML::Devel::node_to_perl($raw_node);
38           XML::LibXML::Devel::refcnt_inc($raw_node);
39           return $node;
40         }
41
42         sub receive_node
43         {
44           my ($node) = @_;
45           my $raw_node = XML::LibXML::Devel::node_from_perl($node);
46           xs_receive_node($raw_node);
47           XML::LibXML::Devel::refcnt_inc($raw_node);
48         }
49

DESCRIPTION

51       "XML::LibXML::Devel" makes functions from LibXML.xs available that are
52       needed to wrap libxml2 nodes in and out of XML::LibXML::Nodes.  This
53       gives cleaner dependencies than using LibXML.so directly.
54
55       To XS a library that uses libxml2 nodes the first step is to do this so
56       that xmlNodePtr is passed as void *. These raw nodes are then turned
57       into libxml nodes by using this "Devel" functions.
58
59       Be aware that this module is currently rather experimental. The
60       function names may change if I XS more functions and introduce a
61       reasonable naming convention.
62
63       Be also aware that this module is a great tool to cause segfaults and
64       introduce memory leaks. It does however provide a partial cure by
65       making "xmlMemUsed" available as "mem_used".
66

FUNCTIONS

68   NODE MANAGEMENT
69       node_to_perl
70          node_to_perl($raw_node);
71
72        Returns a LibXML::Node object. This has a proxy node with a reference
73        counter and an owner attached. The raw node will be deleted as soon as
74        the reference counter reaches zero.  If the C library is keeping a
75        pointer to the raw node, you need to call refcnt_inc immediately.  You
76        also need to replace xmlFreeNode by a call to refcnt_dec.
77
78       node_to_perl
79          node_from_perl($node);
80
81        Returns a raw node. This is a void * pointer and you can do nothing
82        but passing it to functions that treat it as an xmlNodePtr. The raw
83        node will be freed as soon as its reference counter reaches zero.  If
84        the C library is keeping a pointer to the raw node, you need to call
85        refcnt_inc immediately.  You also need to replace xmlFreeNode by a
86        call to refcnt_dec.
87
88       refcnt_inc
89          refcnt_inc($raw_node);
90
91        Increments the raw nodes reference counter. The raw node must already
92        be known to perl to have a reference counter.
93
94       refcnt_dec
95          refcnt_dec($raw_node);
96
97        Decrements the raw nodes reference counter and returns the value it
98        had before. if the counter becomes zero or less, this method will free
99        the proxy node holding the reference counter.  If the node is part of
100        a subtree, refcnt_dec will fix the reference counts and delete the
101        subtree if it is not required any more.
102
103       refcnt
104          refcnt($raw_node);
105
106        Returns the value of the reference counter.
107
108       fix_owner
109          fix_owner($raw_node, $raw_parent);
110
111        This functions fixes the reference counts for an entire subtree.  it
112        is very important to fix an entire subtree after node operations where
113        the documents or the owner node may get changed. this method is aware
114        about nodes that already belong to a certain owner node.
115
116   MEMORY DEBUGGING
117       $ENV{DEBUG_MEMORY}
118          BEGIN {$ENV{DEBUG_MEMORY} = 1;};
119          use XML::LibXML;
120
121        This turns on libxml2 memory debugging. It must be set before
122        XML::LibXML is loaded.
123
124       mem_used
125          mem_used();
126
127        Returns the number of bytes currently allocated.
128
129   EXPORT
130       None by default.
131

SEE ALSO

133       This was created to support the needs of Apache2::ModXml2. So this can
134       serve as an example.
135

AUTHOR

137       Joachim Zobel <jz-2011@heute-morgen.de>
138

140       Copyright (C) 2011 by Joachim Zobel
141
142       This library is free software; you can redistribute it and/or modify it
143       under the same terms as Perl itself, either Perl version 5.10.1 or, at
144       your option, any later version of Perl 5 you may have available.
145
146
147
148perl v5.36.0                      2023-01-20             XML::LibXML::Devel(3)
Impressum