|
| static int | xml_doc_alloc (xmlDocPtr d) |
| | Allocate a document handle for the given xmlDoc pointer.
|
| static xmlDocPtr | xml_doc_get (int h) |
| | Retrieve a registered xmlDoc by handle.
|
| static int | xml_doc_free_handle (int h) |
| | Free a document handle and the underlying xmlDoc.
|
| static int | xml_node_alloc (xmlNodePtr n) |
| | Allocate a node handle for the given xmlNode pointer.
|
| static xmlNodePtr | xml_node_get (int h) |
| | Retrieve a registered xmlNode by handle.
|
| static int | xml_node_free_handle (int h) |
| | Free a node handle without freeing the underlying node.
|
libxml2 handle registries and helper utilities for the Fun VM extension.
Overview
This translation unit implements compact, fixed-size registries that assign small positive integer handles to libxml2 objects. VM opcodes under src/vm/xml2/*.c and higher-level helpers can exchange these integer handles across the VM stack without exposing raw pointers.
Build-time feature flag
Code in this file is compiled only when the CMake option FUN_WITH_XML2 is enabled (i.e., the preprocessor symbol FUN_WITH_XML2 is defined). When disabled, this file contributes no symbols and the corresponding VM opcodes should be compiled out or provide a graceful fallback.
Ownership and lifetime
- Document registry (XmlDocSlot) TAKES OWNERSHIP of the registered xmlDocPtr. Releasing the document handle will call xmlFreeDoc() for the stored pointer.
- Node registry (XmlNodeSlot) DOES NOT take ownership of xmlNodePtr values. Nodes are owned by their document. Releasing a node handle only clears the registry slot; it does not free the underlying xmlNode memory.
- When a document is freed, the libxml2 tree below it is destroyed by libxml2, thereby invalidating any node pointers previously returned from that document. The small node handle registry in this file does not track which document owns which node. Callers must ensure they do not use node handles after their owning document has been released; they should clear those node handles explicitly if necessary.
Limits and handle ranges
- Document handles are allocated from a fixed-size array of 64 slots. Valid handles are in the inclusive range [1, 63].
- Node handles are allocated from a fixed-size array of 256 slots. Valid handles are in the inclusive range [1, 255].
- The value 0 is reserved and indicates failure or an invalid handle.
Error handling
- Allocation requests fail with a return value of 0 when no free slot is available.
- Lookups return NULL for invalid or unused handles.
- Free functions return 1 when a valid in-use handle was released, and 0 otherwise. Document release also frees the underlying xmlDoc via xmlFreeDoc(). Node release does not free the xmlNode memory.
Thread-safety
- The registries are simple, unsynchronized arrays. They are NOT thread-safe. If the VM uses libxml2 handles across multiple threads, external synchronization is required around all calls into this module.
Example
xmlDocPtr d = xmlReadMemory("<root><x/></root>", 20, "-", NULL, 0);
static int xml_doc_free_handle(int h)
Free a document handle and the underlying xmlDoc.
static int xml_doc_alloc(xmlDocPtr d)
Allocate a document handle for the given xmlDoc pointer.
static xmlDocPtr xml_doc_get(int h)
Retrieve a registered xmlDoc by handle.
Definition in file xml2.c.
| int xml_doc_free_handle |
( |
int | h | ) |
|
|
static |
Free a document handle and the underlying xmlDoc.
If the handle is valid and in use, calls xmlFreeDoc() for the stored document pointer, clears the slot, and returns 1.
- Parameters
-
- Returns
- 1 if the handle was valid and has been released; 0 otherwise.
- Note
- Freeing a document invalidates any xmlNodePtr previously obtained from that document. The node registry in this file does not automatically clear entries that reference nodes from the freed document; callers are responsible for avoiding use-after-free by releasing or ignoring such node handles.
Definition at line 171 of file xml2.c.
1.16.1