RefEnumProc Class Reference

#include <ref.h>

Class Description

A callback class for ReferenceMaker::EnumRefHierarchy.

This is the callback object for ReferenceMaker::EnumRefHierarchy. This class's proc() method is called for each element in the reference hierarchy. When enumerating indirect references, it is possible to enter an infinite recursive loop unless references are not processed more than once. The system prevents processing duplicates by either maintaining a list of all references processed, or by clearing a flag bit on all references and then testing/setting the flag bit as references are processed. In the ReferenceMaker::EnumRefHierarchy method, this object's BeginEnumeration method is called before starting an enumeration, and EndEnumeration at the end. These methods increment and decrement an internal counter. When the counter is decremented to 0, the list of visited references is cleared. This ensures that the list of visited references is maintained during recursive calls to EnumRefHierarchy, but cleared when the outer most call is exited. In some cases however, it is desirable to maintain the list of visited references across calls to EnumRefHierarchy. In these cases, call this object's BeginEnumeration method prior to the calls to EnumRefHierarchy, and EndEnumeration when done. For example:

FreeMapsRefEnum freeEnum(this);
for ( rmaker = <enum over some refmaker set> )
    -- list of visited references cleared after each call
    EnumRefHierarchy(rmaker, freeEnum); 

versus

FreeMapsRefEnum freeEnum(this);
freeEnum.BeginEnumeration()
for ( rmaker = <enum over some refmaker set> )
    -- list of visited references maintained across each call
    EnumRefHierarchy(rmaker, freeEnum); 
freeEnum.EndEnumeration()

Inheritance diagram for RefEnumProc:

Public Member Functions
virtual int	proc (ReferenceMaker *rm)=0
	This method is called once for each element in the reference hierarchy. More...
virtual CoreExport bool	CheckIfAndSetAsVisited (ReferenceMaker *rmaker)
	This method sets and checks whether a ReferenceMaker was visited. More...
CoreExport void	BeginEnumeration (bool preventDuplicatesViaFlag=true)
	This method prepares the RefEnumProc instance for enumeration. More...
CoreExport void	EndEnumeration ()
	This method finalizes the RefEnumProc instance after enumeration. More...

Protected Member Functions
CoreExport	RefEnumProc ()
virtual CoreExport	~RefEnumProc ()
	RefEnumProc (const RefEnumProc &)
RefEnumProc &	operator= (const RefEnumProc &rhs)

Friends
class	ReferenceTarget

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator. More...
static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary. More...
static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary. More...
static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...

Constructor & Destructor Documentation

CoreExport RefEnumProc ( )

protected

virtual CoreExport ~RefEnumProc ( )

protectedvirtual

RefEnumProc ( const RefEnumProc &  )

protected

Member Function Documentation

RefEnumProc& operator= ( const RefEnumProc &  rhs )

protected

virtual int proc ( ReferenceMaker *  rm )

pure virtual

This method is called once for each element in the reference hierarchy.

This method is called once for each element in the reference hierarchy. The return value specifies whether continue processing the references, indirect references, and custom attributes of the refmaker; whether to skip processing of those and continue to the next element, or whether to terminate enumeration. Typically the return value will be REF_ENUM_CONTINUE.

Parameters

rm	- A pointer to the reference maker to this item.

Returns

One of the following values:

• REF_ENUM_CONTINUE: This continues the enumeration
• REF_ENUM_HALT: This stops the enumeration.
• REF_ENUM_SKIP: Reference Makers can hold multiple References. In certain instances you may not want to travel down all of the "branches". By returning REF_ENUM_SKIP from this method you tell the enumerator to not enumerate the current Reference Maker's references but not to halt the enumeration completely.

virtual CoreExport bool CheckIfAndSetAsVisited ( ReferenceMaker *  rmaker )

virtual

This method sets and checks whether a ReferenceMaker was visited.

Implemented by system. This method is used to check whether a ReferenceMaker was previously visited by this callback object, and registers it as having been visited if not. This method is used to ensure we call the proc only once on each ReferenceMaker.

Parameters

rmaker

- A pointer to the reference maker

Returns

Returns true of the rmaker was previously visited, false if not.

CoreExport void BeginEnumeration

(

bool

preventDuplicatesViaFlag = true

)

This method prepares the RefEnumProc instance for enumeration.

Implemented by system. This method is used to initialize the RefEnumProc instance for tracking the reference makers that have been visited. Normally, you do not need to call this method as ReferenceMaker::EnumRefHierarchy calls this method prior to enumerating the specified reference maker. In some cases though, you may want to have RefEnumProc instance track the reference makers visited over multiple calls to EnumRefHierarchy. For example, you may want to call RefEnumProc::proc() on each node in a selection set, tracking the reference makers that have been visited across the entire selection set. Note that each call this method must be paired with a call to EndEnumeration.

Parameters

preventDuplicatesViaFlag

- Defaults to true. With preventDuplicatesViaFlag set to true, processing of a duplicate reference is detected by requesting and clearing a flag bit on all animatables, and then testing/setting the flag bit prior to calling the proc on each reference maker. When set to false, a list of reference makers visited is maintained. If you expect to enumerate only a small number of references, this argument should be set to false. Note however that you do not know what references are held by the references you may enumerate into, so in most cases this argument should be true. Note that the setting specified here overrides the preventDuplicatesViaFlag argument setting in the EnumRefHierarchy call.

See also

ReferenceMaker::EnumRefHierarchy

CoreExport void EndEnumeration

(

)

This method finalizes the RefEnumProc instance after enumeration.

Implemented by system. This method is used to finalize the RefEnumProc instance after enumeration, freeing any memory or max system resources used to track the reference makers that have been visited. This method should only, and must be, called if you called the BeginEnumeration method.

Friends And Related Function Documentation

friend class ReferenceTarget

friend