This reference page is linked to from the following overview topics: Incremental Improvements, Writing Reference Targets, Using Indirect References Instead of Pointers, Reference Hierarchy Functions, Cloning Reference Targets, Implementing Clone in a Plug-in.

Detailed Description

For remapping references during a Clone.

See also:: CloneRefHierarchy(), ReferenceTarget::Clone() This class is used for remapping references during a Clone. It is used when cloning items that are instanced so that the plugin can maintain the same instance relationship within the clone. All methods of this class are implemented by the system.

#include <ref.h>

Inheritance diagram for RemapDir:

[legend]

List of all members.

Public Member Functions
Clone Methods
virtual RefTargetHandle	FindMapping (RefTargetHandle from)=0
	Returns a pointer to a target's clone if it was cloned or NULL otherwise.
virtual RefTargetHandle	CloneRef (RefTargetHandle oldTarg)
	Creates a clone of a reference target only if it hasn't been cloned already.
virtual void	PatchPointer (RefTargetHandle *patchThis, RefTargetHandle oldTarg)=0
	This method is used to back patch the pointer for cloned items.
virtual void	AddPostPatchProc (PostPatchProc *proc, bool toDelete)=0
	Adds a Procedure that is called after cloning and back patching.
Internal methods
virtual void	AddEntry (RefTargetHandle hfrom, RefTargetHandle hto)=0
	Registers a mapping of original object to clone.
virtual void	Backpatch ()=0
	Runs back patch procedures and PostPatchProcs.
virtual bool	BackpatchPending ()=0
	Used internally.
virtual void	Clear ()=0
	Used internally.
virtual void	ClearBackpatch ()=0
	Used internally.
virtual void	DeleteThis ()=0
	Used internally.
virtual	~RemapDir ()
	Used internally.

Constructor & Destructor Documentation

virtual ~RemapDir ( ) [inline, virtual]

Used internally.

{}

Member Function Documentation

virtual RefTargetHandle FindMapping ( RefTargetHandle from ) [pure virtual]

Search for all occurrences

Returns a pointer to a target's clone if it was cloned or NULL otherwise.

Implemented in DefaultRemapDir.

virtual RefTargetHandle CloneRef ( RefTargetHandle oldTarg ) [virtual]

Search for all occurrences

Creates a clone of a reference target only if it hasn't been cloned already.

This method will clone the item if was not already cloned, register the item and its clone with the RemapDir, and return a pointer to the clone. If the item was previously cloned, a pointer to the clone is returned. In the ReferenceTarget::Clone() procedure when an item is cloning itself it should clone all its references. Instead of calling Clone() on its references it should instead call this method passing it the item to clone. This ensures that all objects are cloned at most one time. For example:

                class MyDerivedPlugin
                    : public MyBasePlugin
                {
                    const int MY_REFERENCE = 1;

                    ReferenceTarget* Clone(RemapDir& remap)
                    {
                        ReferenceTarget* result = new MyDerivedPlugin();
                        BaseClone(this, result, remap);
                        return result;
                    }

                    void BaseClone(ReferenceTarget* from, ReferenceTarget* to, RemapDir& remap)
                    {
                        if (!to || !from || from == to)
                            return;    
                        MyBasePlugin::BaseClone(from, to, remap);
                        to->ReplaceReference(MY_REFERENCE, remap->CloneRef(from->GetReference(MY_REFERENCE)));
                    }
                };

Parameters:

oldTarg - This is the item that is to be cloned.

Returns:: A pointer to the clone of the item.

virtual void PatchPointer	(	RefTargetHandle *	patchThis,
		RefTargetHandle	oldTarg
	)		`[pure virtual]`

Search for all occurrences

This method is used to back patch the pointer for cloned items.

If oldTarg has already been cloned, then the RefTargetHandle variable pointed to by patchThis is set to the pointer of the clone. If oldTarg has not been cloned, a back patch procedure is registered that is run after all cloning is completed but before the PostPatchProcs are run. The back patch procedure checks to see if oldTarg has been cloned, and if so the the RefTargetHandle variable pointed to by patchThis is set to the pointer of the clone. If oldTarg has not been cloned, the RefTargetHandle variable pointed to by patchThis is set to oldTarg. Because there may be a delayed write to the RefTargetHandle variable, this variable should not be a stack variable. Note that this method is primarily used when an object being cloned holds a raw pointer to a ReferenceTarget (i.e., it does not hold a reference to the ReferenceTarget). In general, this is not safe due to the potential for a dangling pointer when that ReferenceTarget is deleted. It is better to use a SingleRefMaker or a SingleWeakRefMaker member variable to hold the pointer as it will hold a reference to the ReferenceTarget and properly NULL the pointer when/if the ReferenceTarget is deleted.

See also:: SingleRefMaker, SingleWeakRefMaker

Parameters:

patchThis	- The RefTargetHandle variable to be set.
oldTarg	- The original target.

Implemented in DefaultRemapDir.

virtual void AddPostPatchProc	(	PostPatchProc *	proc,
		bool	toDelete
	)		`[pure virtual]`

Search for all occurrences

Adds a Procedure that is called after cloning and back patching.

This method is used for adding a PostPatchProc whose procedure method is called after the reference hierarchy has been cloned and any back patching has occurred. These will be called in the order that they are registered. The PostPatchProc procs are called from the RemapDirImp::Backpatch(). More information can be found at the RefTargMonitorRefMaker::Proc method. See NodeMonitor::Clone for an example.

Parameters: