Documentation | Source

NAME

Wait - A missing shortcuts in JavaScript language.

SYNOPSIS

  JSAN.use('Wait');

  wait(
     // Wait for this function to return true
     function() {
         return (v1 == 100);
     },
     // ... and then do this
     function() {
         v2 = true;
     },
     // ... unless the waiting is so long
     function() {
         v3 = false;
     },
     // ... as 10000 ms.
     10000
  );

DESCRIPTION

This library exports a function called 'wait'. It aims to simplify the standard setInterval-clearInterval pattern which is used to ensure the synchronous of data.

One basic problem programming in javascript is about asynchrounous, especially when you're dealing with cross browser issue. Sometimes the returned object of document.createElement('div') may not have it's .style property ready when you want to use it.

So here's what 'wait' does: It keeps checking whether a given etst passed or not periodically. Once the test passed, call the callabck. If the waiting time is too long, longer then the maximum, another failure callback is called.

The 'wait' function can be used in two form: either with 3 arguments or 4 arguments. The semantic of its 3-argument form is:

  wait(test, callback, max_wait)

And for its 4-argument form, it would be:

  wait(test, callback, failure_callback, max_wait)

It handles setInterval() and calls clearInterval() once the test passed, or elapsed over max waiting time. You may omit the last max_wait argument, in such case it never ends waiting, which means the failure_callback would never be called even if it's given. So you might just use this form for convienence:

  wait(test, callback)

Waiting indefinitely might not be the best behaviour, but long as you can ensure that the test would be passing, it's golden.

AUTHOR

Kang-min Liu <gugod@gugod.org>.

COPYRIGHT

Copyright 2006 by Kang-min Liu <gugod@gugod.org>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See <http://www.perl.com/perl/misc/Artistic.html>

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 62:

=back without =over

/**

*/



if ( typeof Wait == 'undefined' ) {
    Wait = {}
}

Wait.VERSION = 0.02;
Wait.EXPORT  = [ 'wait' ];
Wait.EXPORT_TAGS = { ':all': Wait.EXPORT };

Wait.interval = 100;

Wait.wait = function(arg1, arg2, arg3, arg4) {
    if (   typeof arg1 == 'function'
        && typeof arg2 == 'function'
        && typeof arg3 == 'function'
        ) {
            return Wait._wait3(arg1, arg2, arg3, arg4);
        }

    if (   typeof arg1 == 'function'
        && typeof arg2 == 'function'
        ) {
            return Wait._wait2(arg1, arg2, arg3);
        }
}

Wait._wait2 = function(test, callback, max) {
    Wait._wait3(test, callback, function(){}, max);
}

Wait._wait3 = function(test, callback, failed_callback ,max) {
    var func = function() {
        var interval = Wait.interval;
        var time_elapsed = 0;
        var intervalId;
        var check_and_callback = function () {
            if ( test() ) {
                callback();
                clearInterval(intervalId);
            }
            time_elapsed += interval;
            if ( typeof max == 'number' ) {
                if ( time_elapsed >= max ) {
                    if ( typeof failed_callback == 'function')
                        failed_callback();
                    clearInterval(intervalId);
                }
            }
        }
        intervalId = setInterval(check_and_callback, interval );
    }
    func();
    
}

/**

*/