NodeRef

Description

The NodeRef class encapsulates a "safe" pointer to a node in 's tree. It is usually used as a class member of an SDT or ODT. It is essentially a "safe" TreeNode*. The primary advantage of using a NodeRef instead of a TreeNode* directly is that it makes sure that if the thing that you are pointing to ever gets deleted, then your reference to that thing will immediately go to NULL, preventing you from retaining a pointer into invalid memory. So when should you use a NodeRef instead of a TreeNode*? If there is ever a chance that the thing you are pointing at could get deleted without your class knowing about it, then you should always always always use a NodeRef instead of a TreeNode*. There is some overhead associated with using a NodeRef because there are some checks that must be done when dereferencing, but if the thing you are pointing at might get deleted, then you're going to have to do some checking anyway; might as well let the NodeRef encapsulate those checks. It will save a lot of headache.

As an example of using a NodeRef instead of a TreeNode*, see the code below.

		class MySDT : public SimpleDataType
		{
			public:
			TreeNode* someNode;
			...
		};
		

To use a NodeRef instead, just replace TreeNode* with NodeRef.

		class MySDT : public SimpleDataType
		{
			public:
			NodeRef someNode;
			...
		};
		

For the most part, you can then just use someNode exactly the same way as you would a TreeNode*. In some cases, though, the c++ compiler may give you errors saying that it doesn't know how to cast a NodeRef into something else, or that a function call's parameters are ambiguous. In that case you can use the NodeRef::get() method to explicitly get a TreeNode*.

		someNode.get()
		

ObjRef

The ObjRef class is just like the NodeRef class, but it instead encapsulates a "safe" pointer to a SimpleDataType/ObjectDataType. For example, if instead of having a pointer to a node, you want a safe pointer to a TaskExecuter, you can use ObjRef to accomplish that. Take for example the following code:

		class MySDT : public SimpleDataType
		{
			public:
			TaskExecuter* someTE;
			...
		};
		

You can have a safe pointer instead by using the following code:

		class MySDT : public SimpleDataType
		{
			public:
			ObjRef<TaskExecuter> someTE;
			...
		};
		

Like NodeRef, once added, you can essentially use an ObjRef just like it's the pointer itself. The ObjRef has the same advantages as the NodeRef, namely that if the object is deleted, then your reference to it will automatically go to NULL.