CDOM References Concept Document - Revision history

Tom Parker: /* Characteristics/Weaknesses of the defined solution */

2018-02-25T21:50:27Z

‎Characteristics/Weaknesses of the defined solution

Tom Parker at 21:46, 25 February 2018

2018-02-25T21:46:13Z

Tom Parker at 21:45, 25 February 2018

2018-02-25T21:45:22Z

Show changes

Tom Parker at 01:51, 3 April 2009

2009-04-03T01:51:29Z

Tom Parker: /* Benefits of the defined solution */

2009-04-03T01:48:25Z

‎Benefits of the defined solution

Tom Parker: /* Characteristics/Weaknesses of the defined solution */

2009-04-03T01:46:19Z

‎Characteristics/Weaknesses of the defined solution

Tom Parker at 00:34, 3 April 2009

2009-04-03T00:34:07Z

Nuance at 17:16, 1 April 2009

2009-04-01T17:16:26Z

Nuance at 17:12, 1 April 2009

2009-04-01T17:12:03Z

Nuance at 16:38, 1 April 2009

2009-04-01T16:38:11Z

@@ Line 97: / Line 97: @@
 =Characteristics/Weaknesses of the defined solution=
-# Currently, the LoadContext system uses WeakReferences to control the Disposal of CDOM Reference objects when FORGET is encountered.  In theory this does not guarantee that irrelevant CDOM Reference objects do not produce load errors due to missing information.  In practice, this error is unlikely to be encountered.  However, an ideal structure would design around this problem.  This issue is partially a function of the method of storage used in PCGen 5.16 (the Graph structure envisioned for CDOM is not in place), and partially a function of using a one-pass load.  There are multiple solutions to this problem, but since it's mostly a theoretical issue, it is not being addressed as a critical issue.
+# Currently, the LoadContext system uses WeakReferences to control the Disposal of CDOM Reference objects when FORGET is encountered.  In theory this does not guarantee that irrelevant CDOM Reference objects do not produce load errors due to missing information.  In practice, this error is unlikely to be encountered.
-# Currently, BONUS, CHOOSE, and the PRExxx tokens have not been converted to the new Token/Loader system and do not yet provide all of the benefits outlined above.  A CHOOSE rebuild has been proposed as part of the PCGen 5.17 cycle (which leads to the next stable release, either 5.18 or 6.0).
+# Currently, BONUS, CHOOSE, and the PRExxx tokens have not been converted to the new Token/Loader system and do not yet provide all of the benefits outlined above.
 # Currently CDOM References are classes and are not provided into CDOM Objects as an Interface.  In order to reduce potential for corruption of CDOMReferences, the single references are controlled to allow them to only be resolved once.  This is done without providing a method for resetting a CDOM Reference.  This is done to provide a strict mechanism to prevent errors and abuse of the CDOM Reference objects during runtime (this can be thought of as a short-term overly strict system to train developers and force separation between load and runtime).  Once we have a more stable and modular core in place, this strict mechanism may be relaxed and/or exchanged for interfaces.  Currently, this strict mechanism makes Game Mode references slightly more complex than other references.
 # Some References are resolved at runtime.  Theoretically, this is a performance issue, but practically, the dynamic references are rare enough that this is not an issue.  The core of PCGen has much larger performance issues that should be addressed first before this is addressed as a performance issue.  It may turn out to be unnecessary optimization, so addressing this weakness is currently not scheduled for any release.
-# Resolution may be an issue.  This is mostly a theoretical issue at this point, but the dereferencing driven by the use of CDOM Reference objects is slightly slower than direct objects.  This is considered a minor performance issue, and unless demonstrated as a performance issue, will not be addressed.  There are some concerns about references in relation to lists (such as adding Spells to a ClassSpellList) and the complexity required to access the underlying information.  While this is a recognized issue, this pain point will be addressed in a near-future release as the PlayerCharacter data structure is changed to a Graph-based structure.
+# Resolution may be an issue.  This is mostly a theoretical issue at this point, but the dereferencing driven by the use of CDOM Reference objects is slightly slower than direct objects.  This is considered a minor performance issue, and unless demonstrated as a performance issue, will not be addressed.  There are some concerns about references in relation to lists (such as adding Spells to a ClassSpellList) and the complexity required to access the underlying information.
 # In certain conditions, duplicate objects are not hazardous (This is possible as some objects are retrieved during runtime in a way that provides additional context beyond the KEY to establish uniqueness).  However, this is an artifact that limits the capabilities of PCGen and should be eliminated.  In the meantime, for the limited cases where duplicate objects are allowed, the ALLOWDUPES token is available in PCC files.

@@ Line 7: / Line 7: @@
 =Requirement=
-Objects (such as Races, Languages, etc.) which are loaded from LST files need to have a unique identifier so that relationships between objects can be created without ambiguity.  We call that identifier and must reference an object by its KEY.
+Objects (such as Races, Languages, etc.) which are loaded from LST files need to have a unique identifier so that relationships between objects can be created without ambiguity.  We call that identifier its KEY, and its how the data must refer to any object.
 Objects can reference each other (e.g. a Race settings available starting Languages).  This is a challenge because circular references are likely.  More specifically, due to known interactions, it is impossible to choose a load order for files and entries that guarantees objects will be constructed before references to those objects are encountered. Order independence of persistent data is therefore an architectural requirement. (As an example, consider a restriction on the language to limit it to the particular Race that allows it as a starting Language)

← Older revision		Revision as of 01:51, 3 April 2009
Line 3:		Line 3:
	\|}		\|}

		+	CDOM References were added to PCGen in revision 5.16

	==Overview==		==Overview==

@@ Line 86: / Line 86: @@
 # Duplicate keys are detected at load, regardless of their source file, thus no references should be ambiguous
 # Empty Group references can flag a warning if they do not contain any contents.  This serves as LST error checking to catch accidental typos in a group identifier
 # Since References can be constructed well before they are resolved, references allow Game Mode information to be loaded once, thus preventing re-parsing of those files when a different set of sources is loaded.

← Older revision		Revision as of 01:46, 3 April 2009
Line 98:		Line 98:
	# Some References are resolved at runtime. Theoretically, this is a performance issue, but practically, the dynamic references are rare enough that this is not an issue. The core of PCGen has much larger performance issues that should be addressed first before this is addressed as a performance issue. It may turn out to be unnecessary optimization, so addressing this weakness is currently not scheduled for any release.		# Some References are resolved at runtime. Theoretically, this is a performance issue, but practically, the dynamic references are rare enough that this is not an issue. The core of PCGen has much larger performance issues that should be addressed first before this is addressed as a performance issue. It may turn out to be unnecessary optimization, so addressing this weakness is currently not scheduled for any release.
	# Resolution may be an issue. This is mostly a theoretical issue at this point, but the dereferencing driven by the use of CDOM Reference objects is slightly slower than direct objects. This is considered a minor performance issue, and unless demonstrated as a performance issue, will not be addressed. There are some concerns about references in relation to lists (such as adding Spells to a ClassSpellList) and the complexity required to access the underlying information. While this is a recognized issue, this pain point will be addressed in a near-future release as the PlayerCharacter data structure is changed to a Graph-based structure.		# Resolution may be an issue. This is mostly a theoretical issue at this point, but the dereferencing driven by the use of CDOM Reference objects is slightly slower than direct objects. This is considered a minor performance issue, and unless demonstrated as a performance issue, will not be addressed. There are some concerns about references in relation to lists (such as adding Spells to a ClassSpellList) and the complexity required to access the underlying information. While this is a recognized issue, this pain point will be addressed in a near-future release as the PlayerCharacter data structure is changed to a Graph-based structure.
		+	# In certain conditions, duplicate objects are not hazardous (This is possible as some objects are retrieved during runtime in a way that provides additional context beyond the KEY to establish uniqueness). However, this is an artifact that limits the capabilities of PCGen and should be eliminated. In the meantime, for the limited cases where duplicate objects are allowed, the ALLOWDUPES token is available in PCC files.

@@ Line 28: / Line 28: @@
 ===Group References===
-Group referenfes refer to one or more objects.  These can share various characteristics, such as a TYPE, or be universal for a given type of object by using the ANY reference.  In limited cases, pattern matching references are also available.
+Group references refer to one or more objects.  These can share various characteristics, such as a TYPE, or be universal for a given type of object by using the ANY reference.  In limited cases, pattern matching references are also available.
 ===Transparent References===

@@ Line 38: / Line 38: @@
 References are used in multiple ways:
-# Reference can be directly used: References can be stored in ListKey or ObjectKey locations within a CDOM Object.
+# A Reference can be used directly: References can be stored in ListKey or ObjectKey locations within a CDOM Object.
-# References are used as an index: This is referring to a list of objects, such as the CLASSES token in the Spell LST file referring to ClassSpellLists.
+# A Reference can be used as an index: i.e. referring to a list of objects, such as the reference constructed from the CLASSES token in the Spell LST file referring to ClassSpellLists.
 However, there is one infrastructure to support lists, and those lists may be either static or unconstructed at LST load.  The static references are known lists, yet in order to share infrastructure with unknown lists, even the known lists have to be wrapped in a CDOM Reference. For this reason, there is the ability to create Direct References. These CDOM References do not require resolution, as they are passed the single CDOM Object they will contain at the time the Direct Reference is constructed.

@@ Line 6: / Line 6: @@
 ==Overview==
-CDOM References are effectively pointers to CDOM Objects.  A Single reference directly refers to a single object (something like referring to the Feat Dodge), and it follows very closely the pointer analogy. Group references, which can be refer to multiple objects (something like TYPE=Foo) effectively serve as a pointer to a one or more objects.
+CDOM References are effectively pointers to CDOM Objects.  A Single reference directly refers to a single object (something like referring to the Feat Dodge), and it follows very closely the pointer analogy. Group references, which can be refer to multiple objects (something like TYPE=Foo) effectively serve as a pointer to a group of one or more objects.
-CDOM References are created and be aware of their underlying contents during the load of PCC/LST files, and with some minor exceptions, are not dynamic (meaning they do not change at runtime).
+CDOM References are created and are aware of their underlying contents during the load of PCC/LST files, and with some minor exceptions, are not dynamic (meaning they do not change at runtime).
 CDOM Reference objects can be found in the pcgen.cdom.reference package.