Tuesday, November 22, 2005

Prototype.js : PeriodicalExecuter

In a previous entry I kicked off this series of posts on the Prototype JavaScript library, with this being the third in the series. In this entry I will cover the small but useful PeriodicalExecuter class.

The PeriodicalExecuter, as of the current release (1.4.0_rc2), allows you to start a task that should be repeated some number of seconds. It does allow you to pause and resume execution by modifying the currentlyExecuting property of the instance, but there is currently no way to stop the execution timer. It also ensures that the task is running in a sychronized manner, meaning it will never be executing more than once at any given time. If, for example, the executing task is still running the next time the task is triggered it will skip that execution time and not try again until the next trigger time.

API Summary

new PeriodicalExecuter(callback, seconds)
pe.callback
pe.frequency
pe.currentlyExecuting

API Details

new PeriodicalExecuter(callback, seconds)

Params:
callback - Function reference
seconds - Number of seconds between executions

Returns:
A new PeriodicalExecuter object.

Creates and starts a new periodically executing task. The callback passed to the constructor will be executed peridically based on the number of seconds passed to the constructor. The callback function is executed as if it was a method of the PeriodicalExecuter object that is returned, so you may set properties of the object to store data between executions.

function showAlert ()
{
this.counter = this.counter ? this.counter + 1 : 1;
alert(this.counter);
}
var pe = new PeriodicalExecuter(showAlert, 10);

pe.callback

A reference to the callback function passed to the constructor. Changing this property after constructing the object WILL change the method that gets executed.

pe.callback = function () { ...do something else... }

pe.frequency

The frequency in seconds that the callback is executed. Changing this value will not alter the rate of execution.

pe.currentlyExecuting

A boolean flag indicating if the callback is currently being executed. Setting this value to true will cause the execution of the callback to temporarily stop until it is set back to false.

6 comments:

peter said...

In your example you incorrectly have it spelt PeriodicalExecutOr, instead of PeriodicalExecutEr. Other than that these articles are quite helpful.

Robert Hanson said...

I'll make the change, and I'm glad it was helpful. Looking at my traffic, this seems to be my most popular article to date, yet I feel that PE is a little underpowered. I will probably write a followup that adds some additional features to the class.

James Gregory said...

I've been having similar thoughts regarding the underpowered nature of the PeriodicalExecuter, especially when it's based around the setInterval function built into most browsers.

With that in mind I created a little extension with a stop function:
Prototype PeriodicalExecuter.stop() javascript function

Casey said...

Using the following statement to pause the periodical executer seems kind of hackish to me.

pe.currentlyExecuting = true;

Perhaps a pe.pause() would be a better interface that would isolate the user from the internals a bit more.

Felix said...

Just to let you know you have task mispelt as 'tast' in this article

Robert Hanson said...

Thanks Felix, it is fixed.