Class implementing ability to keep track of when objects are changed. More...

#include <adskCheckpointed.h>

Inheritance diagram for Checkpointed:

Public Member Functions
Checkpoint	checkpoint () const
	Retrieve the current object checkpoint state. More...

bool	changedSinceCheckpoint (const Checkpoint &check) const
	Determine if the object has been altered since the given checkpoint. More...

	Checkpointed ()
	Default constructor - initialize counter.

virtual	~Checkpointed ()
	Destructor, updates checkpoint count for the class.

	Checkpointed (const Checkpointed &rhs)
	Copy constructor - counter starts where copy left off. More...

Checkpointed &	operator= (const Checkpointed &rhs)
	Assignment operator and copy constructor are just to allow objects with counters embedded or derived to copy properly. More...

Static Public Member Functions
static Checkpoint	globalCheckpoint ()
	Retrieve the global checkpoint. More...

static Checkpoint	globalChange ()
	Update the global checkpoint and return the new value. More...

static bool	Debug (const Checkpointed *me, Debug::Print &request)
	Answer a Print request for a Checkpointed object. More...

static bool	Debug (const Checkpointed *me, Debug::Footprint &request)
	Answer a footprint request for an Checkpointed object. More...

Protected Member Functions
Checkpoint	objectChanged ()
	Call this whenever an object changes, increments the class and object checkpoint counters. More...

Protected Attributes
Checkpoint	fCheckpoint
	ID updating when the object changes.

Static Protected Attributes
static Checkpoint	sfGlobalCheckpoint = 0
	Global monotonic checkpoint. More...

Detailed Description

Class implementing ability to keep track of when objects are changed.

Often the question arises "has this object changed since I did X?". Using this class gives you the ability to create a unique monotonic ID to identify how recently something has changed, usually accompanied by the queryer remembering a checkpoint value to compare against.

This class must be a mixin to the class being tracked. The important thing is to insert this call at every point that object is changed:

objectChanged();

Since the virtual function table isn't correct until the top level class constructor is called unfortunately you also have to insert checkpoint updates into the constructors and destructor of your class. The macros

CheckpointCreate( MyClass );

CheckpointDestroy( MyClass );

will do that for you.

Object changes will also flag the class as changed but if any other changes happen which apply to the class as a whole they can be tagged with:

classChanged();

Example 1: An external object handler wishes to know when any object of class type MyObject was changed.

class MyObject : public adsk::Checkpointed {
...
};
MyObject::MyObject()
    { CheckpointCreate(MyObject); ... }
MyObject::~MyObject()
    { CheckpointDestroy(MyObject); ... }
void MyObject::anyMethodChangingAnObject()
    { objectChanged(); doTheChanges(); }
... in the handler ...
adsk::Checkpoint checkpoint = MyObject::sClassCheckpoint();
doHandlerStuff();
if( MyObject::sClassChangedSinceCheckpoint( checkpoint ) )
    doHandlerChangedStuff();

Note that since construction and destruction of objects count as changes to "the set of" MyObject they also get the edit flag updated.

Example 2: An external object handler wishes to know when a specific object has been changed.

class MyObject : public adsk::Checkpointed {
...
};
MyObject::MyObject()
    { CheckpointCreate(MyObject); ... }
MyObject::~MyObject()
    { CheckpointDestroy(MyObject); ... }
void MyObject::anyMethodChangingAnObject()
    { objectChanged(); doTheChanges(); }
... in the handler ...
MyObject mObj;
adsk::Checkpoint checkpoint = myObj.checkpoint();
doObjectStuff( mObj );
if( mObj.changedSinceCheckpoint( checkpoint ) )
    doObjectChangedStuff();

Constructor & Destructor Documentation

Checkpointed ( const Checkpointed & rhs )

Copy constructor - counter starts where copy left off.

It won't hurt to be higher and this prevents any unintended clash between objects who have copied counters.

Parameters

[in] rhs Counter to be copied

Member Function Documentation

Checkpoint objectChanged ( )

protected

Call this whenever an object changes, increments the class and object checkpoint counters.

Returns: New object checkpoint value

Checkpoint checkpoint ( ) const

Retrieve the current object checkpoint state.

Returns: Current object checkpoint value

bool changedSinceCheckpoint ( const Checkpoint & check ) const

Determine if the object has been altered since the given checkpoint.

Parameters

[in] check Previous checkpoint to compare against

Returns: True if the object has been changed since the checkpoint, otherwise false

Checkpointed & operator= ( const Checkpointed & rhs )

Assignment operator and copy constructor are just to allow objects with counters embedded or derived to copy properly.

Assignment operator, updates the checkpoint and copies values.

Parameters

[in]	rhs	Counter to copy
[in]	rhs	Counter to copy

Returns: Reference to this copied object (to allow chained assignments)

Checkpoint globalCheckpoint ( )

static

Retrieve the global checkpoint.

Maintaining a single global checkpoint value ensures that any objects that are checkpointed can be compared against not only themselves but also each other. A fine enough grained timer would serve the same function but a monotonic counter is more flexible since its updates are asynchronous.

Returns: Current global checkpoint value

Checkpoint globalChange ( )

static

Update the global checkpoint and return the new value.

This is called after any change to any checkpointed object.

Returns: New global checkpoint value

bool Debug	(	const Checkpointed *	me,
		Debug::Print &	request
	)

static

Answer a Print request for a Checkpointed object.

Use the request object to dump all information on the "me" Checkpointed, or all static Checkpointed information if "me" is NULL.

Parameters

[in]	me	Pointer to object to debug, NULL means class static
[out]	request	Print request object

Returns: True if the request was successfully processed.

bool Debug	(	const Checkpointed *	me,
		Debug::Footprint &	request
	)

static

Answer a footprint request for an Checkpointed object.

Populate the Footprint request with the information on all data stored within this class if "me" is NULL, otherwise the information stored in the Checkpointed object pointed at by "me".

Parameters

[in]	me	Pointer to object to footprint, NULL means class static
[out]	request	Footprint object to populate

Returns: True if the request was successfully processed. The Footprint object will have all information added to it.

Member Data Documentation

Checkpoint sfGlobalCheckpoint = 0

staticprotected

Global monotonic checkpoint.

Monotonically increasing global checkpoint.

Bumped any time any object or class of any time changes.

The documentation for this class was generated from the following files:

adskCheckpointed.h
adskCheckpointed.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation