r3469 jmb - /trunk/dom/docs/RefCnt

Author: jmb Date: Sun Jul 29 00:31:11 2007 New Revision: 3469 URL: http://source.netsurf-browser.org?rev=3469&view=rev Log: Improve description of the list of nodes pending deletion and how it is related to the process of deleting a Document. Modified: trunk/dom/docs/RefCnt Modified: trunk/dom/docs/RefCnt URL: http://source.netsurf-browser.org/trunk/dom/docs/RefCnt?rev=3469&r1=3... ============================================================================== --- trunk/dom/docs/RefCnt (original) +++ trunk/dom/docs/RefCnt Sun Jul 29 00:31:11 2007 @@ -100,3 +100,43 @@ list of nodes pending deletion). 2) The NodeList is destroyed. +Destruction of Documents +------------------------ + + Assumptions: + + 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 + deletion] + 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 + client. + + 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 + document.