This Measure holds the result of some externally-determined computation, and helps to coordinate the validity of that computation with respect to the state variables. More...

Inheritance diagram for SimTK::Measure_< T >::Result:

Classes
class	Implementation

Public Member Functions
	SimTK_MEASURE_HANDLE_PREAMBLE (Result, Measure_< T >)

	Result (Subsystem &sub, Stage dependsOn, Stage invalidated)
	Create a new Result measure and add it to the indicated subsystem. More...

Stage	getDependsOnStage () const
	Get the dependsOn stage for this measure's value. More...

Stage	getInvalidatedStage () const
	Get the invalidated stage for this measure's value. More...

Result &	setDependsOnStage (Stage dependsOn)
	Change the dependsOn stage for this measure's value, which must be strictly less than the current setting for the invalidated stage. More...

Result &	setInvalidatedStage (Stage invalidated)
	Change the invalidated stage for this measure's value, which must be strictly greater than the current setting for the dependsOn stage. More...

Result &	setIsPresumedValidAtDependsOnStage (bool presume)
	Normally a Result measure's value is not considered valid unless we are notified explicitly that it is, via a call to markAsValid() or setValue(); this method allows the value to be assumed valid after the dependsOn stage has been realized. More...

bool	getIsPresumedValidAtDependsOnStage () const
	Return the value of the "presumed valid at dependsOn stage" flag. More...

T &	updValue (const State &state) const
	Obtain write access to the Measure's value in order to modify it. More...

void	markAsValid (const State &state) const
	Mark the current value as valid. More...

bool	isValid (const State &state) const
	Check whether the value contained in this Measure is currently valid. More...

void	markAsNotValid (const State &state) const
	Manually mark the contained value as invalid. More...

void	setValue (const State &state, const T &value) const
	Set a new value and mark it as valid. More...

	SimTK_MEASURE_HANDLE_POSTSCRIPT (Result, Measure_< T >)

Public Member Functions inherited from SimTK::Measure_< T >
	SimTK_MEASURE_HANDLE_PREAMBLE_ABSTRACT (Measure_, AbstractMeasure)
	This class is still abstract so we don't want it to allocate an Implementation object in its default constructor. More...

const T &	getValue (const State &s, int derivOrder=0) const
	Retrieve the Value of this Measure or one of its time derivatives, assuming the supplied State has been realized to at least the required stage for the selected value or derivative, as reported by getDependsOnStage(). More...

Measure_ &	setDefaultValue (const T &defaultValue)
	Change the default value associated with this Measure. More...

const T &	getDefaultValue () const
	Obtain a reference to the default value associated with this Measure. More...

	SimTK_MEASURE_HANDLE_POSTSCRIPT (Measure_, AbstractMeasure)

Public Member Functions inherited from SimTK::AbstractMeasure
	AbstractMeasure (Implementation *g=0)
	Provide an Implementation for this AbstractMeasure and bump its reference count. More...

	AbstractMeasure (Subsystem &, Implementation *g, const SetHandle &)
	Construct this handle with a given Implementation object (whose reference count will be bumped) and then let the given Subsystem adopt this Measure (which will again bump the Implementation's reference count, leaving us with two new handles). More...

	AbstractMeasure (const AbstractMeasure &)
	Shallow copy constructor copies the pointer from the source Implementation object and bumps its reference count. More...

AbstractMeasure &	operator= (const AbstractMeasure &source)
	Shallow assignment operator results in this handle referencing the same Implementation object as does the source. More...

	~AbstractMeasure ()
	Destructor decrements the Implementation's reference count and deletes the object if the count goes to zero. More...

AbstractMeasure &	shallowAssign (const AbstractMeasure &)
	Shallow assignment operator destructs the current Implementation object (meaning its reference count is decremented and the object actually deleted only if the count goes to zero), then copies the Implementation pointer from the source and bumps its reference count. More...

AbstractMeasure &	deepAssign (const AbstractMeasure &source)
	Deep assignment clones the Implementation object pointed to by the source handle, so that this handle ends up pointing to a new Measure object similar to the original but not yet contained in any Subsystem. More...

int	getNumTimeDerivatives () const
	Every Measure can produce a value, and some can provide one or more total derivatives with respect to time of that value. More...

Stage	getDependsOnStage (int derivOrder=0) const
	At what Stage can we expect the value of this AbstractMeasure or one of its time derivatives to be available? Users of Measures will typically impose restrictions on the levels they will accept. More...

bool	isSameMeasure (const AbstractMeasure &other) const
	There can be multiple handles on the same Measure. More...

bool	isEmptyHandle () const

bool	isInSubsystem () const
	Test whether this Measure object has been adopted by a Subsystem. More...

const Subsystem &	getSubsystem () const
	Return a reference to the Subsystem that owns this Measure. More...

MeasureIndex	getSubsystemMeasureIndex () const
	Return the MeasureIndex by which this Measure is known to the Subsystem that owns it. More...

const Implementation &	getImpl () const

Implementation &	updImpl ()

bool	hasImpl () const

int	getRefCount () const

Detailed Description

template<class T>
class SimTK::Measure_< T >::Result

This Measure holds the result of some externally-determined computation, and helps to coordinate the validity of that computation with respect to the state variables.

The value must be set manually and explicitly marked valid when it is complete. The value will be automatically invalidated after a state change at or below a specified Stage, and changing the value here will automatically invalidate a specified Stage and above.

In constrast to Measure::Variable, Measure::Result is not a state variable; it is a cache variable meaning that it works with a const State. It is expected that the result can be recalculated from the state variables when needed, or contains ephemeral information that can be discarded.

No provision for derivatives is made; there is only the one result.

Constructor & Destructor Documentation

template<class T>

SimTK::Measure_< T >::Result::Result	(	Subsystem &	sub,
		Stage	dependsOn,
		Stage	invalidated
	)

inline

Create a new Result measure and add it to the indicated subsystem.

The Result measure's value depends on earlier values calculated at dependsOn stage, so whenever that stage or earlier is invalidated, so is the value here. In addition, any change made to the value here will invalidate stage invalidated and all subsequent stages. The invalidated stage must be later than the dependsOn stage, and you cannot update the value here in a state that hasn't already been realized to the dependsOn stage. Set dependsOn = Stage::Empty if your value computation doesn't depend on anything else (that will be interpreted as Stage::Topology, however, since space for the value gets allocated then). Set invalidated = Stage::Infinity if you don't want anything invalidated when this value is changed.

Member Function Documentation

template<class T>

SimTK::Measure_< T >::Result::SimTK_MEASURE_HANDLE_PREAMBLE	(	Result	,
		Measure_< T >
	)

template<class T>

Stage SimTK::Measure_< T >::Result::getDependsOnStage ( ) const

inline

Get the dependsOn stage for this measure's value.

template<class T>

Stage SimTK::Measure_< T >::Result::getInvalidatedStage ( ) const

inline

Get the invalidated stage for this measure's value.

template<class T>

Result& SimTK::Measure_< T >::Result::setDependsOnStage ( Stage dependsOn )

inline

Change the dependsOn stage for this measure's value, which must be strictly less than the current setting for the invalidated stage.

If you set the dependsOn stage to Stage::Empty it will be interpreted as Stage::Topology since the value must always depend on at least topology. Setting the dependsOn stage is itself a topological change requiring reallocation of the value if it has already been allocated; you must call realizeTopology() again.

template<class T>

Result& SimTK::Measure_< T >::Result::setInvalidatedStage ( Stage invalidated )

inline

Change the invalidated stage for this measure's value, which must be strictly greater than the current setting for the dependsOn stage.

This is a topological change requiring reallocation of the value if it has already been allocated; you must call realizeTopology() again.

template<class T>

Result& SimTK::Measure_< T >::Result::setIsPresumedValidAtDependsOnStage ( bool presume )

inline

Normally a Result measure's value is not considered valid unless we are notified explicitly that it is, via a call to markAsValid() or setValue(); this method allows the value to be assumed valid after the dependsOn stage has been realized.

The reason this exists is that in some cases it is difficult to find a place from which to call markAsValid(). That means you must set the value during realization of the dependsOn stage, but there is no way for this to be checked automatically. Thus use of this feature can lead to very difficult-to-find bugs; you should try hard to find a place to call markAsValid() before resorting to this method. This is a topological change requiring reallocation of the value if it has already been allocated; you must call realizeTopology() again.

template<class T>

bool SimTK::Measure_< T >::Result::getIsPresumedValidAtDependsOnStage ( ) const

inline

Return the value of the "presumed valid at dependsOn stage" flag.

See also: setIsPresumedValidAtDependsOnStage() for a discussion.

template<class T>

T& SimTK::Measure_< T >::Result::updValue ( const State & state ) const

inline

Obtain write access to the Measure's value in order to modify it.

Calling this method marks the result invalid; you must explicitly validate it when you're done. Also, if this Measure was created with an invalidates stage, then that stage and all later stages in the given state are marked invalid also.

template<class T>

void SimTK::Measure_< T >::Result::markAsValid ( const State & state ) const

inline

Mark the current value as valid.

This is done automatically if you call setValue() but must be done manually if you use updValue() to access the value. Note that you cannot mark this valid if state hasn't been realized already to at least the stage prior to this measure's dependsOn stage; that is, you must at least be working on the dependsOn stage at the time this is called.

template<class T>

bool SimTK::Measure_< T >::Result::isValid ( const State & state ) const

inline

Check whether the value contained in this Measure is currently valid.

If true, you can call getValue() to obtain it. If false, calling getValue() will throw an exception.

template<class T>

void SimTK::Measure_< T >::Result::markAsNotValid ( const State & state ) const

inline

Manually mark the contained value as invalid.

This will also invalidate any stages in state that depend on this value. This is called automatically whenever the updValue() method is invoked, and the value starts out invalid. The value becomes valid either by calling markAsValid() explicitly or calling setValue().

Warning: If you have set this Result measure to be presumed valid at dependsOn stage, this method will have no effect.

template<class T>

void SimTK::Measure_< T >::Result::setValue	(	const State &	state,
		const T &	value
	)		const

inline

Set a new value and mark it as valid.

For more flexibility, use the updValue() method and markAsValid() manually when you are done with the new value.

template<class T>

SimTK::Measure_< T >::Result::SimTK_MEASURE_HANDLE_POSTSCRIPT	(	Result	,
		Measure_< T >
	)

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

Measure.h

Classes

Public Member Functions

Detailed Description

template<class T> class SimTK::Measure_< T >::Result

Constructor & Destructor Documentation

Member Function Documentation

template<class T>
class SimTK::Measure_< T >::Result