Fix libxml manual memory management (#15906)

libxml allows to customize the memory allocators, which we used to plug the GC.

Under certain conditions (e.g. multi-threading, libxml 2.14), **this integration leads to segfaults** when a GC cycle happens within a libxml function.

I'm not quite sure what's happening. Maybe libxml keeps pointers somewhere that the GC doesn't scan (thread locals?) and the GC collects them... though that would create random segfaults, not segfaults during GC. Anyway: removing the GC integration fixes the issue.

In addition, the libxml2 distributed in macOS 15.4 is patched to remove the custom memory allocators API.

Other bindings to external libraries in Crystal don't plug the GC but use manual memory management to free the external allocations when not needed anymore (automated through finalizers).

The difficulty is that we allocate the whole DOM tree with libxml. We could use a libxml parser to build a DOM tree with Crystal objects, and it would be fantastic, but then we'd have to reimplement XPath.

**This patch replaces the GC integration with explicit memory management instead.**

For readers, writers, or XPath contexts, we merely free the libxml allocations in finalizers.

Tree nodes are more complex. The XML free functions will recursively free the whole subtree; a node might be unlinked and thus won't be freed with the rest of the document anymore, etc.

We can store a reference to the XML::Node of documents into the libxml node (using the `_private` struct member) because the XML::Node will live exactly as long as the libxml doc.

We can't do that for subtree nodes that may be collected at any time and would leave dangling pointers. We could not care (and allow multiple XML::Node to represent one libxml node for example, since collecting the doc will free the libxml node) but a XML::Node can be unlinked from the main tree, and must be manually freed. I thus introduced a dual reference:

1. Every XML::Node has a strong reference to its document's XML::Node (can't free document while we have references to a subtree node);
2. Every document XML::Node keeps a cache with weak references to all its subtree XML::Node (only those that have been instantiated).
3. Every document XML::Node keeps a list with strong references to any unlinked XML::Node in order to avoid memory leaks from nodes that have been unlinked and thus wouldn't be freed with the document. The unlinked XML::Node keeps the parent reference to the document (same as libxml's `node->doc`) until it is linked into another document. When that happens, it should also be removed from the unlinked list.

A XML::Node is thus unique per libxml node, yet can be collected when unused without freeing some of the document, after which we can instantiate a new XML::Node.

**NOTE**: I was able to avoid breaking changes, especially in constructors, but I still undocumented the constructors that take an external libxml pointer, or expose internal details. I assume they should be internal API. We should extend the XML integration, for example with DOM manipulation (following the DOM spec, not the libxml API) so nobody has to extend the libxml integration themselves.

Author: ysbaddaden

src/xml/attributes.cr

@@ -3,13 +3,13 @@ require "./node"
 class XML::Attributes
   include Enumerable(Node)
 
+  # :nodoc:
   def initialize(@node : Node)
   end
 
   def empty? : Bool
     return true unless @node.element?
 
-    props = self.props
     props.null?
   end
 
@@ -39,23 +39,54 @@ class XML::Attributes
   end
 
   def []=(name : String, value)
+    if prop = find_prop(name)
+      # manually unlink the prop's children if we have live references, so
+      # xmlSetProp won't free them immediately
+      @node.document.unlink_cached_children(prop)
+    end
+
     LibXML.xmlSetProp(@node, name, value.to_s)
     value
   end
 
   def delete(name : String) : String?
-    value = self[name]?.try &.content
-    res = LibXML.xmlUnsetProp(@node, name)
-    value if res == 0
+    prop = find_prop(name)
+    return unless prop
+
+    value = ""
+    if content = LibXML.xmlNodeGetContent(prop)
+      value = String.new(content)
+    end
+
+    if node = @node.document.cached?(prop)
+      # can't call xmlUnsetProp: it would free the node
+      node.unlink
+      value
+    else
+      # manually unlink the prop's children if we have live references, so
+      # xmlUnsetProp won't free them immediately
+      @node.document.unlink_cached_children(prop)
+      value if LibXML.xmlUnsetProp(@node, name) == 0
+    end
+  end
+
+  private def find_prop(name)
+    prop = @node.to_unsafe.value.properties.as(LibXML::Node*)
+    while prop
+      if String.new(prop.value.name) == name
+        return prop
+      end
+      prop = prop.value.next
+    end
   end
 
   def each(&) : Nil
     return unless @node.element?
 
     props = self.props
     until props.null?
-      yield Node.new(props)
-      props = props.value.next
+      yield Node.new(props.as(LibXML::Node*), @node.document)
+      props = props.value.next.as(LibXML::Attr*)
     end
   end
 
@@ -73,7 +104,7 @@ class XML::Attributes
     pp.list("[", self, "]")
   end
 
-  protected def props
+  protected def props : LibXML::Attr*
     @node.to_unsafe.value.properties
   end
 end

src/xml/builder.cr

@@ -28,6 +28,11 @@ class XML::Builder
     @writer = LibXML.xmlNewTextWriter(buffer)
   end
 
+  # :nodoc:
+  def finalize
+    LibXML.xmlFreeTextWriter(@writer)
+  end
+
   # Emits the start of the document.
   def start_document(version = nil, encoding = nil) : Nil
     call StartDocument, string_to_unsafe(version), string_to_unsafe(encoding), nil

src/xml/libxml2.cr

@@ -149,6 +149,7 @@ lib LibXML
   fun xmlTextReaderReadOuterXml(reader : XMLTextReader) : UInt8*
   fun xmlTextReaderExpand(reader : XMLTextReader) : Node*
   fun xmlTextReaderCurrentNode(reader : XMLTextReader) : Node*
+  fun xmlTextReaderCurrentDoc(reader : XMLTextReader) : Doc*
 
   fun xmlTextReaderSetErrorHandler(reader : XMLTextReader, f : TextReaderErrorFunc) : Void
   fun xmlTextReaderSetStructuredErrorHandler(reader : XMLTextReader, f : StructuredErrorFunc, arg : Void*) : Void
@@ -372,18 +373,14 @@ lib LibXML
   {% if compare_versions(LibXML::VERSION, "2.14.0") >= 0 %}
     fun xmlSaveSetIndentString(SaveCtxPtr, UInt8*)
   {% end %}
+
+  fun xmlFreeDoc(Doc*)
+  fun xmlFreeNode(Node*)
+  fun xmlFreeTextReader(XMLTextReader)
+  fun xmlFreeTextWriter(TextWriter)
+  fun xmlXPathFreeContext(XPathContext*)
+  fun xmlXPathFreeNodeSet(NodeSet*)
+  fun xmlXPathFreeObject(XPathObject*)
 end
 
 LibXML.xmlInitParser
-
-LibXML.xmlMemSetup(
-  ->GC.free,
-  ->GC.malloc(LibC::SizeT),
-  ->GC.realloc(Void*, LibC::SizeT),
-  ->(str) {
-    len = LibC.strlen(str) + 1
-    copy = Pointer(UInt8).malloc(len)
-    copy.copy_from(str, len)
-    copy
-  }
-)

src/xml/namespace.cr

@@ -1,6 +1,7 @@
 class XML::Namespace
   getter document : Node
 
+  # :nodoc:
   def initialize(@document : Node, @ns : LibXML::NS*)
   end