|author||John Mark Bell <email@example.com>||2007-07-28 23:31:11 +0000|
|committer||John Mark Bell <firstname.lastname@example.org>||2007-07-28 23:31:11 +0000|
Improve description of the list of nodes pending deletion and how it is related to the process of deleting a Document.
svn path=/trunk/dom/; revision=3469
1 files changed, 40 insertions, 0 deletions
diff --git a/docs/RefCnt b/docs/RefCnt
index ba0fa08..1a6d515 100644
@@ -100,3 +100,43 @@ Example
list of nodes pending deletion).
2) The NodeList is destroyed.
+Destruction of Documents
+ 1) Nodes within a document do not hold explicit references upon it.
+ 2) Container data structures which address nodes in a document hold
+ an explicit reference upon the document.
+ [FIXME: and upon the root node of the subtree they address -- this
+ implies that the explicit reference is unnecessary, as the
+ addressed node will be added to the list of nodes pending
+ 3) A document has no parent (i.e. the parent pointer is always NULL).
+ 4) A given node may be located in either the document tree or the
+ list of nodes pending deletion. It may not be located in both
+ data structures simultaneously.
+ 5) Nodes in the list of nodes pending deletion are in use by the
+ The above assumptions imply the following:
+ + If a document has a non-zero reference count, it is in use by
+ the client. (1,2)
+ + If the document's reference count reaches zero, it is no longer
+ in use and is eligible for deletion. (1,2,3)
+ + The document destructor must attempt to forcibly delete the
+ contents of the document tree as the nodes do not hold a reference
+ upon the document. (1)
+ + On destruction of a node, it must be removed from the list of nodes
+ pending deletion. (4)
+ + The document may not be destroyed if the list of nodes pending
+ deletion is non-empty after the destructor has attempted to
+ destroy the document tree. (4,5)
+ Therefore, document destruction proceeds as follows:
+ 1) Forcibly destroy the document tree.
+ 2) If the list of nodes pending deletion is non-empty, stop.
+ 3) The list of nodes pending deletion is empty, so destroy the