IMcUserMeasureUserIsValueStale Method

Parameters

MeasurementObject

Type: MediaCy.IQL.FeaturesIMcMeasure
The McMeasure object for which the measurement is to be computed.

Return Value

Type: Boolean
Return True if the measurement is stale, False otherwise.

The McMeasure.Value for all measurements is cached after a McMeasure.Compute call. It can then be accessed without having to be recomputed for derivation of other measurements or further analysis. But the value needs to be recomputed if any data on which it depends changes; that is, when the current value bcomes "stale". The McMeasures collection will automatically set McMeasure.IsValueStale True when any of the data sources identified by a McMeasure.Attributes(mcmaidDependencies) call change. This automatic mechanism handles the data dependencies for most situations, so normally the measurement does not need to process the UserIsValueStale call (and in fact it will never be called). However, under some circumstances the standard dependencies may not capture all situations that cause the measurement to go stale. These cases are very rare, but they do exist. An example might be a case where a measurement uses the maRgnRadii measurement for its computation. The maRgnRadii measurement can go stale if its NumAngles property is assigned and this property change is not captured by any of the standard dependencies. In cases like this, the McUserMeasure developer has two options: 1) they can ensure that they are polled to be given a chance to determine if their measurement is stale before any use is made of the cached value, or 2) they can asynchronously set the measurement stale based on some event. The first of these approaches is supported by calls to the UserIsValueStale method. For polled setting of the underlying McMeasure.IsValueStale property, the UserAttributes method must handle the mcmaidDependencies AttributeId argument, and it must include mcmdfOther among the mcMeasurementDependencyFlags returned. Subsequently on every McMeasure.Value access, UserIsValueStale will be called. The method must determine if the measurement is stale and return True if so or False otherwise. Note that you do not need to check for staleness due to any standard dependencies that you have OR'ed with the mcmdfOther flag in your return from the UserAttributes(mcmaidDependencies), because these are still handled in the usual way to set the value stale automatically. For asynchronous setting of the underlying McMeasure.IsValueStale property, you just need to call the McMeasure.SetValueStale method in response to an event that detects a change in a non-standard dependency of a McMeasure being serviced by this McUserMeasure. In order to capture such events you need to associate an event handler with each serviced McMeasure. The best place to do this (and other per-McMeasure initialization) is int eh UserAttributes(mcmaidDependencies), call. This call is made only once for each serviced McMeasure instance. The choice between asynchronous and polling value cache invalidation depends on a number of trade-offs. The asynchronous method is a little more work in that you need to track your special dependencies using some sort of event handlers. The polling method may or may not be efficient depending on how complex are the dependency tests to be performed and on how frequently the McMeasure.Value or statistical properties are accessed.