lava.util
Class SpeedometerModel

java.lang.Object
  |
  +--lava.mv.MvModel
        |
        +--lava.util.SpeedometerModel

public class SpeedometerModel

extends MvModel

Measures progress rate.

Details: SpeedometerModel is a tool for estimating realtime processing rates. Applications which need to perform long operations (such as file transfers), while displaying instantaneous progress rates, can benefit from this class.

To use this class, instantiate a new instance before each long operation, and then report intermediate progress data to the instance, using the recordProgress method, after each processing step. Your progress display should then call getRate as often as convenient (once every second, for example), in order to obtain an estimate of the current, instantaneous processing rate.

SpeedometerModel divides time into user-specified intervals, creating an accumulator for each interval. When the application calls recordProgress with an amount corresponding to each completed processing step, that amount is added to the accumulator for the current interval. Whenever getRate is called, a weighted average based on the most recently passed intervals is computed and returned.

The formula for computing the instantaneous progress rate is designed to generate a stable result when the data amounts reported by the client arrive with relatively stable frequency and quantity. The formula is based on a weighted average that is biased towards the most recently measured time intervals.

Although it is not strictly necessary, you can use SpeedometerModel as a model in programs that use the model-view design pattern. Views for SpeedometerModel implement the IMvView interface and receive periodic instantaneous processing rate updates via IMvView's updateView method. When updateView is called, the ipModelId parameter is a pointer to this instance and the ipModelData parameter is an MvModelEvent. If the event's getType method returns CURRENT_RATE, then getParam (0) will return an Integer representing the new instantaneous rate. (See sample code below.)

SpeedometerModel is thread-safe.

Test application:

import java.awt.Frame; import java.awt.Label; import java.io.IOException; import lava.io.ConsoleDialog; import lava.mv.IMvView; import lava.mv.MvModelEvent; import sharky.util.SpeedometerModel; class RateLabel extends Label implements IMvView { public static void main (String[] isArgs) throws IOException { ConsoleDialog vpDialog = new ConsoleDialog (); SpeedometerModel vpMeter = new SpeedometerModel ( vpDialog . queryInt ("How many metering intervals should I track? "), vpDialog . queryInt ("How long should each interval be (in milliseconds)? ") ); Frame vpFrame = new Frame ("SpeedometerModel test"); RateLabel vpLabel = new RateLabel (); vpLabel . setText ("data rate"); vpFrame . add (vpLabel); vpFrame . pack (); vpFrame . setVisible (true); vpMeter . registerView (vpLabel); while (true) vpMeter . recordProgress (vpDialog . queryInt ("Enter 1000s to vpMeter: ") * 1000); } public void updateView (Object ipModelId, Object ipModelData) { MvModelEvent vpEvent = (MvModelEvent) ipModelData; if (vpEvent . getType () == SpeedometerModel.CURRENT_RATE) setText (((Integer) vpEvent . getParam (0)) . intValue () + " units/sec"); } }

Since:

1999.03.27

Version:

2001.04.17

Author:

Sharky

Field Summary

static int	CURRENT_RATE Indicates rate change.
protected int	mnInterval Duration of metering period.
protected int	mnPeriods History size.

Constructor Summary

SpeedometerModel(int inPeriods, int inInterval)
Sets number and length of metering intervals.

Method Summary

void	dispose() Kills internal metering thread.
protected void	finalize() Prepares for destruction.
int	getRate() Returns current progress rate.
void	recordProgress(int inAmount) Records progress.

Methods inherited from class lava.mv.MvModel

getEventDispatcher, notifyViews, notifyViews, registerView, setEventDispatcher, unregisterView

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CURRENT_RATE

public static final int CURRENT_RATE

Indicates rate change.

Details: CURRENT_RATE indicates that a new instantaneous rate has been computed. This value is returned by MvModelEvents getType method in views that subscribe to this model. If this model is expanded to generates other types of events, new type constants will be defined.

Since:

2001.04.17

mnPeriods

protected int mnPeriods

History size.

Details: mnPeriods is the number previously completed metering periods used to determine the instantaneous data rate.

mnInterval

protected int mnInterval

Duration of metering period.

Details: mnInterval is the length, in milliseconds, of each metering period.

Constructor Detail

SpeedometerModel

public SpeedometerModel(int inPeriods,
                        int inInterval)

Sets number and length of metering intervals.

Details: This constructor sets the number of intervals to track and the duration of each interval. Refer to the class introduction for details.

Parameters:

mnPeriods - number of mnPeriods (buckets)

mnInterval - duration of each period

Method Detail

recordProgress

public void recordProgress(int inAmount)

Records progress.

Details: Called by the client, this method reports an amount of progress to be recorded. The client should call this method as often as it completes processing steps.

Parameters:

inAmount - the amount of data processed

getRate

public final int getRate()

Returns current progress rate.

Details: getRate returns an estimate of the current, instantaneous progress rate.

Returns:

the average data rate

dispose

public void dispose()

Kills internal metering thread.

Details: dispose causes the graceful death of this instance's internal metering thread. This method should only be called when this instance is no longer needed, in preparation for garbage collection.

finalize

protected void finalize()

Prepares for destruction.

Details: finalize prepares this instance for destruction by calling dispose.

Overrides:

finalize in class java.lang.Object