GM_xmlhttpRequest - Asynchronous (queue method)

// ==UserScript==
// @name        GM_xmlhttpRequest - Asynchronous (queue method)
// @namespace   http://userscripts.org/users/23652
// @description Uses a queueing method to run multiple xml request on different urls
// @include     *
// @copyright   JoeSimmons
// @version     1.0.0
// @license     http://creativecommons.org/licenses/by-nc-nd/3.0/us/
// ==/UserScript==



/* --------------------------- INFORMATION ----------------------------------------------------------------------


    ## IMPORTANT INFORMATION ##

        - You may pass the arguments in any order

        - None of the arguments are strictly required

---------------------------------------------

    ## SYNTAX ##

        - If you pass it an array, it should contain a list of URLs
                - e.g., runQueue( ['url1', 'url2', 'url3' ] );
            If you do not pass it an array or the queue is empty, it will not run
            because there is nothing in the queue

        - If you pass it a function, it will run that function each time a URL in the queue completes
            loading, with the response as the first argument
            If you do not pass it a function, it will run an empty function and do nothing (besides load the url)

        - If you pass it a number, it will use that as the delay between requests
            If you do not, it will use 0 delay


-------------------------------------------------------------------------------------------------------------- */


// stack of requests
var $queue = [];

function xhr(func, url, delay) {
    if (typeof url !== 'string') { return; }

    GM_xmlhttpRequest({
        'url' : url,
        'method' : 'GET',
        'onload' : function (r) {
            func(r); // run callback
                window.setTimeout(function () {
                    runQueue(func, delay); // run the next in queue, if any
                }, delay);
        }
    });
}

// this takes any order of arguments and determines whether or not
// xhr() should be run
function runQueue() {
    var i, func = null, delay = 0, arg;

    for (i = 0; i < arguments.length; i += 1) {
        arg = arguments[i];
        if ( Array.isArray(arg) ) $queue = $queue.concat(arg);
            else if (typeof arg === 'function') func = arg;
            else if (typeof arg === 'number' && arg > 0) delay = Math.floor(arg);
    }

    if ($queue.length === 0) { return; }
    if (func === null) func = function () {};

    xhr(func, $queue.shift(), delay); // run an xml request with the first url in the queue, then remove it from the queue
}



// the handleRes function is an example.
// you may edit this function or specify a new function in runQueue()
function handleRes(res) {
    var rText = res.responseText,  // response text
        rStatus = res.status,      // response status
        rUrl = res.finalUrl;       // response url

    // do stuff here

    // debug snippet for showing each url as it's loaded
    alert('URL: ' + rUrl + '\n\nStatus: ' + rStatus + ($queue.length === 0 ? '\n\nEND OF QUEUE.' : ''));

    // debug snippet for showing when the queue is finished
    if ($queue.length === 0) alert('The queue is finished.');
}


// example function
// -----
// it requests an array of URLs individually, with a 250ms delay
// between each, and calls handleRes when each request is done (it doesn't check the status of the request)
runQueue(250, handleRes, [
    'http://www.google.com?num=1',
    'http://www.google.com?num=2',
    'http://www.google.com?num=3'
]);