qmachine.js

//- JavaScript source code

//- qmachine.js ~~
//                                                      ~~ (c) SRW, 15 Nov 2012
//                                                  ~~ last updated 08 Feb 2015

(function (global, sandbox) {
    'use strict';

 // Pragmas

    /*jshint maxparams: 5, quotmark: single, strict: true */

    /*jslint indent: 4, maxlen: 80 */

    /*properties
        a, ActiveXObject, addEventListener, anon, appendChild, apply, ass,
        atob, attachEvent, avar, b, bitwise, body, box, browser, btoa, by,
        call, can_run_remotely, charAt, charCodeAt, clearTimeout, closure,
        CoffeeScript, comm, configurable, console, constructor, contentWindow,
        continue, createElement, data, debug, def, '__defineGetter__',
        defineProperty, '__defineSetter__', detachEvent, devel, diagnostics,
        display, document, done, enable_volunteer, enumerable, env, epitaph,
        eqeq, error, errors, es5, eval, evil, exemptions, exit, f, fail, floor,
        forin, fromCharCode, get, getElementsByTagName, global, hasOwnProperty,
        head, host, ignoreCase, importScripts, indexOf, join, JSLINT, key,
        length, lib, load_data, load_script, location, log, map, mapreduce,
        method, multiline, navigator, newcap, node, nomen, now, on, onLine,
        onload, onreadystatechange, open, parentElement, parse, passfail,
        plusplus, ply, postMessage, predef, properties, protocol, prototype,
        push, puts, Q, QM, QUANAH, query, random, readyState, reason, recent,
        reduce, regexp, removeChild, removeEventListener, replace,
        responseText, result, results, revive, rhino, run_remotely, send, set,
        setRequestHeader, setTimeout, shelf, shift, slice, sloppy, source, src,
        start, status, stay, stringify, stop, stupid, style, sub, submit, sync,
        test, time, timer, toJSON, toSource, toString, todo, unparam, url, val,
        value, valueOf, vars, via, visibility, volunteer, white, window,
        withCredentials, writable, x, XDomainRequest, XMLHttpRequest, y
    */

 // Prerequisites

    if (global.hasOwnProperty('QM')) {
     // Exit early if QMachine is already present.
        return;
    }

    if (global.hasOwnProperty('QUANAH') === false) {
     // This checks to make sure that Quanah 0.2.0 or later has been loaded.
        throw new Error('Quanah is missing.');
    }

 // Declarations

    var ajax, atob, AVar, avar, btoa, can_run_remotely, convert_to_js, copy,
        deserialize, defineProperty, get_avar, get_list, in_a_browser,
        in_a_WebWorker, is_closed, is_Function, is_RegExp, is_String, lib,
        load_data, load_script, map, mapreduce, mothership, origin, ply, puts,
        recent, reduce, revive, run_remotely, serialize, set_avar, start,
        state, stop, submit, sync, uuid, update_local, update_remote,
        volunteer;

 // Definitions

    ajax = function (method, url, body) {
     // This function returns an avar.
        var y = avar();
        y.Q(function (evt) {
         // This function needs documentation of a more general form ...
            if ((body !== undefined) && (body.length > 65536)) {
             // If it's likely to fail (because the default "max_body_size" is
             // 64 KB), why not just fail preemptively?
                return evt.fail('Upload size is too large.');
            }
            if (recent(method, url)) {
             // If we have already issued this request recently, we need to
             // wait a minute before doing it again to avoid hammering the
             // server needlessly.
                return evt.stay('Enforcing refractory period ...');
            }
            var request;
         // As of Chrome 21 (and maybe sooner than that), Web Workers do have
         // the `XMLHttpRequest` constructor, but it isn't one of `global`'s
         // own properties as it is in Firefox 15.01 or Safari 6. In Safari 6,
         // however, `XMLHttpRequest` has type 'object' rather than 'function',
         // which makes _zero_ sense to me right now. Thus, my test is _not_
         // intuitive in the slightest ...
            if (global.XMLHttpRequest instanceof Object) {
                request = new global.XMLHttpRequest();
                if (origin() !== mothership) {
                 // This is a slightly weaker test than using `hasOwnProperty`,
                 // but it may work better with Firefox. I'll test in a minute.
                    if (request.withCredentials === undefined) {
                        if (global.hasOwnProperty('XDomainRequest')) {
                            request = new global.XDomainRequest();
                        } else {
                            return evt.fail('Browser does not support CORS.');
                        }
                    }
                }
            } else if (global.hasOwnProperty('ActiveXObject')) {
                request = new global.ActiveXObject('Microsoft.XMLHTTP');
            } else {
                return evt.fail('Browser does not support AJAX.');
            }
            request.onreadystatechange = function () {
             // This function needs documentation.
                if (request.readyState === 4) {
                    if (request.status >= 500) {
                     // These are internal server errors that were occurring
                     // in early "full-stack" versions of QMachine due to a
                     // small error in a Monit script. I've left this arm in
                     // here just in case something silly like that happens
                     // again so that the client keeps trying to connect if
                     // the error is due to a temporary snag on the server.
                        return evt.stay('Internal server error?');
                    }
                    y.val = request.responseText;
                    if (((method === 'GET') && (request.status !== 200)) ||
                            ((method === 'POST') && (request.status !== 201))) {
                     // Something else went wrong, and we can't ignore it.
                        return evt.fail(request.status);
                    }
                    return evt.exit();
                }
             // NOTE: Should we `revive` here?
                return;
            };
            request.open(method, url, true);
            if (method === 'POST') {
             // This code only ever runs as part of an API call. As of v1.1.14,
             // neither the Node.js nor Ruby servers check for this header, but
             // frameworks like Express (http://expressjs.com) that parse the
             // body of the incoming request automatically *do* care.
                request.setRequestHeader('Content-Type', 'application/json');
            }
            request.send(body);
            return;
        });
        return y;
    };

    atob = function (x) {
     // This function redefines itself during its first invocation.
        if (is_Function(global.atob)) {
            atob = global.atob;
        } else {
            atob = function (x) {
             // This function decodes a string which has been encoded using
             // base64 encoding. It isn't part of JavaScript or any standard,
             // but it _is_ a DOM Level 0 method, and it is extremely useful
             // to have around. Unfortunately, it isn't available in Node.js,
             // the Web Worker contexts of Chrome 21 or Safari 6, or common
             // server-side developer shells like Spidermonkey, D8 / V8, or
             // JavaScriptCore.
                /*jslint bitwise: true */
                var a, ch1, ch2, ch3, en1, en2, en3, en4, i, n, y;
                n = x.length;
                y = '';
                if (n > 0) {
                    a = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefg' +
                        'hijklmnopqrstuvwxyz0123456789+/=';
                 // NOTE: This `for` loop may actually require sequentiality
                 // as currently written. I converted it from a `do..while`
                 // implementation, but I will write it as a `map` soon :-)
                    for (i = 0; i < n; i += 4) {
                     // Surprisingly, my own tests have shown that it is faster
                     // to use the `charAt` method than to use array indices,
                     // as of 19 Aug 2012. I _do_ know that `charAt` has better
                     // support in old browsers, but the speed surprised me.
                        en1 = a.indexOf(x.charAt(i));
                        en2 = a.indexOf(x.charAt(i + 1));
                        en3 = a.indexOf(x.charAt(i + 2));
                        en4 = a.indexOf(x.charAt(i + 3));
                        if ((en1 < 0) || (en2 < 0) || (en3 < 0) || (en4 < 0)) {
                         // It also surprised me to find out that testing for
                         // invalid characters inside the loop is faster than
                         // validating with a regular expression beforehand.
                            throw new Error('Invalid base64 characters: ' + x);
                        }
                        ch1 = ((en1 << 2) | (en2 >> 4));
                        ch2 = (((en2 & 15) << 4) | (en3 >> 2));
                        ch3 = (((en3 & 3) << 6) | en4);
                        y += String.fromCharCode(ch1);
                        if (en3 !== 64) {
                            y += String.fromCharCode(ch2);
                        }
                        if (en4 !== 64) {
                            y += String.fromCharCode(ch3);
                        }
                    }
                }
                return y;
            };
        }
        return atob(x);
    };

    AVar = global.QUANAH.avar().constructor;

    avar = global.QUANAH.avar;

    btoa = function (x) {
     // This function redefines itself during its first invocation.
        if (is_Function(global.btoa)) {
            btoa = global.btoa;
        } else {
            btoa = function (x) {
             // This function encodes binary data into a base64 string. It
             // isn't part of JavaScript or any standard, but it _is_ a DOM
             // Level 0 method, and it is extremely useful to have around.
             // Unfortunately, it isn't available in Node.js, the Web Worker
             // contexts of Chrome 21 or Safari 6, or common server-side
             // developer shells like Spidermonkey, D8 / V8, or JavaScriptCore.
             // Also, it throws an error in most (?) browsers if you feed it
             // Unicode (see http://goo.gl/3fLFs).
                /*jslint bitwise: true */
                var a, ch1, ch2, ch3, en1, en2, en3, en4, i, n, y;
                n = x.length;
                y = '';
                if (n > 0) {
                    a = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefg' +
                        'hijklmnopqrstuvwxyz0123456789+/=';
                 // NOTE: This `for` loop may actually require sequentiality
                 // as currently written. I converted it from a `do..while`
                 // implementation, but I will write it as a `map` soon :-)
                    for (i = 0; i < n; i += 3) {
                        ch1 = x.charCodeAt(i);
                        ch2 = x.charCodeAt(i + 1);
                        ch3 = x.charCodeAt(i + 2);
                        en1 = (ch1 >> 2);
                        en2 = (((ch1 & 3) << 4) | (ch2 >> 4));
                        en3 = (((ch2 & 15) << 2) | (ch3 >> 6));
                        en4 = (ch3 & 63);
                        if (isNaN(ch2)) {
                            en3 = en4 = 64;
                        } else if (isNaN(ch3)) {
                            en4 = 64;
                        }
                        y += (a.charAt(en1) + a.charAt(en2) + a.charAt(en3) +
                            a.charAt(en4));
                    }
                }
                return y;
            };
        }
        return btoa(x);
    };

    can_run_remotely = function (task) {
     // This function returns a boolean.
        return ((global.hasOwnProperty('JSON'))     &&
                (global.hasOwnProperty('JSLINT'))   &&
                (task instanceof Object)            &&
                (task.hasOwnProperty('f'))          &&
                (task.hasOwnProperty('x'))          &&
                (is_Function(task.f))               &&
                (task.x instanceof AVar)            &&
             // (is_online())                       &&
                (is_closed(task, state.exemptions[task.x.key]) === false));
    };

    convert_to_js = function (x) {
     // This function converts a function or string into an avar with a `val`
     // property that is a JavaScript function. This isn't quite the same as an
     // `eval`, however, because the string is expected to be used only when it
     // represents CoffeeScript code. Unfortunately, the mere use of the word
     // so irritates JSLint that I must designate this function "evil" just to
     // suppress its scary messages.
        /*jslint evil: true */
        var y = avar();
        y.Q(function (evt) {
         // This function needs documentation.
            if (is_Function(x)) {
                y.val = x;
                return evt.exit();
            }
            if (is_String(x) === false) {
                return evt.fail('Cannot convert argument to a function');
            }
            if (global.hasOwnProperty('CoffeeScript')) {
                y.val = global.CoffeeScript['eval'](x);
                return evt.exit();
            }
            lib('//cdnjs.cloudflare.com/ajax/libs/coffee-script' +
                    '/1.6.3/coffee-script.min.js').Q(function (lib_evt) {
             // This function needs documentation.
                y.val = global.CoffeeScript['eval'](x);
                lib_evt.exit();
                return evt.exit();
            }).on('error', evt.fail);
            return;
        });
        return y;
    };

    copy = function (x, y) {
     // This function copies the properties of `x` to `y`, specifying `y` as
     // object literal if it was not provided as an input argument. It does
     // not perform a "deep copy", which means that properties whose values
     // are objects will be "copied by reference" rather than by value. Right
     // now, I see no reason to worry about deep copies or getters / setters.
     // Because the current version of Quanah no longer uses ECMAScript 5.1
     // features to make the `comm` method non-enumerable, however, we do have
     // to be careful not to overwrite the `y.comm` method if `y` is an avar.
        if (y === undefined) {
         // At one point, I used a test here that `arguments.length === 1`,
         // but it offended JSLint:
         //     "Do not mutate parameter 'y' when using 'arguments'."
            y = {};
        }
        var comm, key;
        if (y instanceof AVar) {
            comm = y.comm;
        }
        for (key in x) {
            if (x.hasOwnProperty(key)) {
                y[key] = x[key];
            }
        }
        if (is_Function(comm)) {
            y.comm = comm;
        }
        return y;
    };

    defineProperty = function (obj, name, params) {
     // This function wraps the ES5 `Object.defineProperty` function so that
     // it degrades gracefully in crusty old browsers. I would like to improve
     // my implementation eventually so that the fallback definition will more
     // closely simulate the ES5 specification, but for now, this works well.
     // For more information, see the documentation at http://goo.gl/xXHKr.
        if (Object.hasOwnProperty('defineProperty')) {
            defineProperty = Object.defineProperty;
        } else if (Object.prototype.hasOwnProperty('__defineGetter__')) {
            defineProperty = function (obj, name, params) {
             // This function needs documentation.
                /*jslint nomen: true */
                params = (params instanceof Object) ? params : {};
                ply(params).by(function (key, val) {
                 // This has a "forEach" pattern ==> `ply` is justified.
                    if (key === 'get') {
                        obj.__defineGetter__(name, val);
                    } else if (key === 'set') {
                        obj.__defineSetter__(name, val);
                    } else if (key === 'value') {
                     // NOTE: This may fail if the property's `configurable`
                     // attribute was set to `false`, but if such an error
                     // could occur, that JS implementation would have had a
                     // native `Object.defineProperty` method anyway :-P
                        delete obj[name];
                        obj[name] = val;
                    }
                    return;
                });
                return obj;
            };
        } else {
            throw new Error('Platform lacks support for getters and setters.');
        }
        return defineProperty(obj, name, params);
    };

    deserialize = function ($x) {
     // This function is a JSON-based deserialization utility that can invert
     // the `serialize` function provided herein. Unfortunately, no `fromJSON`
     // equivalent exists for obvious reasons -- it would have to be a String
     // prototype method, and it would have to be extensible for all types.
     // NOTE: This definition could stand to be optimized, but I recommend
     // leaving it as-is until improving performance is absolutely critical.
        /*jslint unparam: true */
        return JSON.parse($x, function reviver(key, val) {
         // This function is provided to `JSON.parse` as the optional second
         // parameter that its documentation refers to as a `reviver` function.
         // NOTE: This is _not_ the same as Quanah's `revive`!
            var f, re;
            re = /^\[(FUNCTION|REGEXP) ([A-z0-9\+\/\=]+) ([A-z0-9\+\/\=]+)\]$/;
         // Is the second condition even reachable in the line below?
            if (is_String(val)) {
                if (re.test(val)) {
                    val.replace(re, function ($0, type, code, props) {
                     // This function is provided to the String prototype's
                     // `replace` method and uses references to the enclosing
                     // scope to return results. I wrote things this way in
                     // order to avoid changing the type of `val` and thereby
                     // confusing the JIT compilers, but I'm not certain that
                     // using nested closures is any faster anyway. For that
                     // matter, calling the regular expression twice may be
                     // slower than calling it once and processing its output
                     // conditionally, and that way might be clearer, too ...
                        f = sandbox(atob(code));
                        copy(deserialize(atob(props)), f);
                        return;
                    });
                }
            }
            return (f !== undefined) ? f : val;
        });
    };

    get_avar = function (x) {
     // This function needs documentation.
        var y = ajax('GET', mothership + '/box/' + x.box + '?key=' + x.key);
        return y.Q(function (evt) {
         // This function deserializes the string returned as the `val` of
         // `y` into a temporary variable and then copies its property values
         // back onto `y`.
            copy(deserialize(y.val), y);
            return evt.exit();
        });
    };

    get_list = function (box) {
     // This function retrieves a list of tasks that need to be executed.
        var y = ajax('GET', mothership + '/box/' + box + '?status=waiting');
        return y.Q(function (evt) {
         // This function needs documentation.
            y.val = JSON.parse(y.val);
            return evt.exit();
        });
    };

    in_a_browser = function () {
     // This function returns a boolean.
        return ((global.hasOwnProperty('location'))             &&
                (global.hasOwnProperty('navigator'))            &&
                (global.hasOwnProperty('phantom') === false)    &&
                (global.hasOwnProperty('system') === false));
    };

    in_a_WebWorker = function () {
     // This function returns a boolean.
        return ((is_Function(global.importScripts))             &&
                (global.location instanceof Object)             &&
                (global.navigator instanceof Object)            &&
                (global.hasOwnProperty('phantom') === false)    &&
                (global.hasOwnProperty('system') === false));
    };

    is_closed = function (x, options) {
     // This function tests an input argument `x` for references that "close"
     // over external references from another scope. This function solves a
     // very important problem in JavaScript because function serialization is
     // extremely difficult to perform rigorously. Most programmers consider a
     // function only as its source code representation, but because it is also
     // a closure and JavaScript has lexical scope, the exact "place" in the
     // code where the code existed is important, too. A third consideration is
     // that a function is also an object which can have methods and properties
     // of its own, and these need to be included in the serializated form. I
     // puzzled over this problem and eventually concluded that because I may
     // not be able to serialize an entire scope (I haven't solved that yet), I
     // _can_ get the source code representation of a function from within most
     // JavaScript implementations even though it isn't part of the ECMAScript
     // standard (June 2011). Thus, if a static analysis tool were able to
     // parse the source code representation to confirm that the function did
     // not depend on its scope, then I might be able to serialize it, provided
     // that it did not contain any methods that depended on their scopes. Of
     // course, writing such a tool is a huge undertaking, so instead I just
     // used a fantastic program by Douglas Crockford, JSLINT, which contains
     // an expertly-written parser with configurable parameters. A bonus here
     // is that JSLINT allows me to avoid a number of other unsavory problems,
     // such as functions that log messages to a console -- such functions may
     // or may not be serializable, but their executions should definitely
     // occur on the same machines that invoked them! Anyway, this function is
     // only one solution to the serialization problem, and I welcome feedback
     // from others who may have battled the same problems :-)
        /*jslint unparam: true */
        if ((options instanceof Object) === false) {
            options = {};
        }
        var comm, $f, flag, left, right;
        if (x instanceof AVar) {
         // We'll put this back later.
            comm = x.comm;
            delete x.comm;
        }
        flag = false;
        left = '(function () {\nreturn ';
        right = ';\n}());';
        if (x instanceof Object) {
            if (is_Function(x)) {
                if (is_Function(x.toJSON)) {
                    $f = x.toJSON();
                } else if (is_Function(x.toSource)) {
                    $f = x.toSource();
                } else if (is_Function(x.toString)) {
                    $f = x.toString();
                } else {
                 // If we fall this far, we're probably in trouble anyway, but
                 // we aren't out of options yet. We could try to coerce to a
                 // string by adding an empty string or calling the String
                 // constructor without the `new` keyword, but I'm not sure if
                 // either would cause Quanah itself to fail JSLINT. Of course,
                 // we can always just play it safe and return `true` early to
                 // induce local execution of the function -- let's do that!
                    return true;
                }
             // By this point, `$f` must be defined, and it must be a string
             // or else the next line will fail when we try to remove leading
             // and trailing parentheses in order to appease JSLINT.
                $f = left + $f.replace(/^[(]|[)]$/g, '') + right;
             // Now, we send our function's serialized form `$f` into JSLINT
             // for analysis, taking care to disable all options that are not
             // directly relevant to determining if the function is suitable
             // for running in some remote JavaScript environment. If JSLINT
             // returns `false` because the scan fails for some reason, the
             // answer to our question would be `true`, which is why we have
             // to negate JSLINT's output.
                flag = (false === global.JSLINT($f, copy(options, {
                 // JSLINT configuration options, as of version 2013.05.31:
                    'ass':      true,   //- allow assignment expressions?
                    'bitwise':  true,   //- allow use of bitwise operators?
                    'browser':  false,  //- assume browser as JS environment?
                    'closure':  true,   //- tolerate Google Closure idioms?
                    'continue': true,   //- allow continuation statement?
                    'debug':    false,  //- allow debugger statements?
                    'devel':    false,  //- allow output logging?
                    'eqeq':     true,   //- allow `==` instead of `===`?
                    'es5':      true,   //- allow ECMAScript 5 syntax?
                    'evil':     false,  //- allow the `eval` statement?
                    'forin':    true,   //- allow unfiltered `for..in`?
                    //'indent': 4,
                    //'maxerr': 50,
                    //'maxlen': 80,
                    'newcap':   true,   //- constructors must be capitalized?
                    'node':     false,  //- assume Node.js as JS environment?
                    'nomen':    true,   //- allow names' dangling underscores?
                    'passfail': true,   //- halt the scan on the first error?
                    'plusplus': true,   //- allow `++` and `--` usage?
                    'predef':   {},     //- predefined global variables
                    'properties': false,//- require JSLINT /*properties */?
                    'regexp':   true,   //- allow `.` in regexp literals?
                    'rhino':    false,  //- assume Rhino as JS environment?
                    'sloppy':   true,   //- ES5 strict mode pragma is optional?
                    'stupid':   true,   //- allow `*Sync` calls in Node.js?
                    'sub':      true,   //- allow all forms of subset notation?
                    'todo':     true,   //- allow comments that start with TODO
                    'unparam':  true,   //- allow unused parameters?
                    'vars':     true,   //- allow multiple `var` statements?
                    'white':    true    //- allow sloppy whitespace?
                })));
            }
            ply(x).by(function (key, val) {
             // This function examines all methods and properties of `x`
             // recursively to make sure none of those are closed, either.
             // Because order isn't important, use of `ply` is justified.
                if (flag === false) {
                    flag = is_closed(val, options);
                }
                return;
            });
        }
        if (is_Function(comm)) {
            x.comm = comm;
        }
        return flag;
    };

    is_Function = function (f) {
     // This function returns `true` if and only if input argument `f` is a
     // function. The second condition is necessary to avoid a false positive
     // in a pre-ES5 environment when `f` is a regular expression.
        return ((typeof f === 'function') && (f instanceof Function));
    };

    is_RegExp = function (x) {
     // This function returns `true` if its input argument `x` is a RegExp. It
     // is known to work in ES5, but if there is a way to "defeat" this test in
     // pre-ES5 environments, please let me know!
        return (Object.prototype.toString.call(x) === '[object RegExp]');
    };

    is_String = function (x) {
     // This function returns a boolean that indicates whether the given
     // argument `x` can be safely assumed to have `String.prototype` methods.
        return ((typeof x === 'string') || (x instanceof String));
    };

 /*
    is_online = function () {
     // This function returns a boolean. It is not currently necessary, but I
     // have future plans that will require this function, so I have already
     // generalized QM in preparation.
        return (mothership === 'LOCAL_ADDR') || global.navigator.onLine;
    };
 */

    lib = function (url) {
     // This function returns an avar.
        var y = avar();
        if (in_a_WebWorker()) {
            y.Q(function (evt) {
             // This function needs documentation.
                global.importScripts(url);
                return evt.exit();
            });
        } else if (in_a_browser()) {
            y.Q(function (evt) {
             // This function use the conventional "script tag loading"
             // technique to import external libraries. Ideally, it would try
             // to avoid loading libraries it has already loaded, but it turns
             // out that this is a very difficult once JSONP becomes involved
             // because those scripts _do_ need to reload every time. Thus, I
             // will need to start documenting best practices to teach others
             // how to construct idempotent scripts that won't leak memory and
             // plan to begin using "disposable execution contexts" like Web
             // Workers again soon.
             //
             // See also: http://goo.gl/byXCA and http://goo.gl/fUCXa .
             //
                /*jslint browser: true, unparam: true */
                var current, script;
                current = global.document.getElementsByTagName('script');
                script = global.document.createElement('script');
                if (is_Function(script.attachEvent)) {
                    script.attachEvent('onload', function onload() {
                     // This function needs documentation.
                        script.detachEvent('onload', onload);
                        if (script.parentElement === global.document.head) {
                            global.document.head.removeChild(script);
                        } else {
                            global.document.body.removeChild(script);
                        }
                        script = null;
                        return evt.exit();
                    });
                } else {
                    script.addEventListener('load', function onload() {
                     // This function needs documentation.
                        script.removeEventListener('load', onload, false);
                        if (script.parentElement === global.document.head) {
                            global.document.head.removeChild(script);
                        } else {
                            global.document.body.removeChild(script);
                        }
                        script = null;
                        return evt.exit();
                    }, false);
                }
                script.src = url;
                ply(current).by(function (key, val) {
                 // This function needs documentation.
                    if (script.src === val.src) {
                     // Aha! At long last, I have found a practical use for
                     // Cantor's Diagonalization argument :-P
                        script.src += '?';
                    }
                    return;
                });
                if ((global.document.body instanceof Object) === false) {
                    global.document.head.appendChild(script);
                } else {
                    global.document.body.appendChild(script);
                }
                current = null;
                return;
            });
        } else {
            y.Q(function (evt) {
             // This function needs documentation.
                return evt.fail('Missing `lib` definition');
            });
        }
        return y;
    };

    load_data = function (x, callback) {
     // This function is an incredibly rare one in the sense that it accepts
     // `x` which can be either an object literal or a string. Typically, I am
     // too "purist" to write such a _convenient_ function :-P
        var xdm, y, yql;
        xdm = function (evt) {
         // This function needs documentation.
            var proxy, request;
            proxy = global.document.createElement('iframe');
            request = this;
            proxy.src = request.val.via;
            proxy.display = 'none';
            proxy.style.visibility = 'hidden';
            proxy.onload = function () {
             // This function runs when the iframe loads.
                proxy.contentWindow.postMessage(JSON.stringify({
                    x: request.val.url
                }), proxy.src);
                return;
            };
            global.window.addEventListener('message', function cb(dom_evt) {
             // This function needs documentation.
                var temp = JSON.parse(dom_evt.data);
                if (temp.x === request.val.url) {
                    request.val = temp.y;
                    global.window.removeEventListener('message', cb, false);
                    global.document.body.removeChild(proxy);
                    proxy = null;
                    return evt.exit();
                }
                return;
            }, false);
            global.document.body.appendChild(proxy);
            return;
        };
        y = (x instanceof AVar) ? copy(x, avar(x.val)) : avar(x);
        yql = function (evt) {
         // This function uses Yahoo Query Language (YQL) as a cross-domain
         // proxy for retrieving text files. Binary file types probably won't
         // work very well at the moment, but I'll tweak the Open Data Table
         // I created soon to see what can be done toward that end.
            var base, callback, diag, format, query, temp;
            global.QM.shelf['temp' + y.key] = function (obj) {
             // This function needs documentation.
                if (obj.query.results === null) {
                    return evt.fail(obj.query.diagnostics);
                }
                y.val = obj.query.results.result;
                delete global.QM.shelf['temp' + y.key];
                return evt.exit();
            };
            base = '//query.yahooapis.com/v1/public/yql?';
            diag = 'diagnostics=true';
            callback = 'callback=QM.shelf.temp' + y.key;
            format = 'format=json';
            query = 'q=' +
                'USE "https://wilkinson.github.io/qmachine/qm.proxy.xml";' +
                'SELECT * FROM qm.proxy WHERE url="' + y.val.url + '";';
            temp = lib(base + [callback, diag, format, query].join('&'));
            temp.on('error', evt.fail);
            return;
        };
        y.on('error', function (message) {
         // This function needs documentation.
            if (is_Function(callback)) {
                y.val = callback(message, y.val);
            }
            return;
        }).Q(function (evt) {
         // This function needs documentation.
            var flag;
            flag = ((y.val instanceof Object)       &&
                    (y.val.hasOwnProperty('url'))   &&
                    (y.val.hasOwnProperty('via'))   &&
                    (in_a_browser() === true)       &&
                    (is_Function(global.window.postMessage)));
            return (flag === true) ? xdm.call(y, evt) : yql.call(y, evt);
        }).Q(function (evt) {
         // This function needs documentation.
            if (is_Function(callback)) {
                y.val = callback(null, y.val);
            }
            return evt.exit();
        });
        return y;
    };

    load_script = function (url, callback) {
     // This function loads external JavaScript files using the usual callback
     // idioms to which most JavaScripters are accustomed / addicted ;-)
        return lib(url).Q(function (evt) {
         // This function only runs if the script loaded successfully.
            if (is_Function(callback)) {
                callback(null);
            }
            return evt.exit();
        }).on('error', function (message) {
         // This function only runs if the script fails to load.
            if (is_Function(callback)) {
                callback(message);
            }
            return;
        });
    };

    map = function (x, f, box, env) {
     // This function needs documentation.
        var y = ((x instanceof AVar) ? x : avar(x)).Q(function (evt) {
         // This function needs documentation.
            var i, n, temp;
            n = this.val.length;
            temp = [];
            for (i = 0; i < n; i += 1) {
                temp[i] = submit(this.val[i], f, box, env);
                temp[i].on('error', evt.fail);
            }
            sync.apply(this, temp).Q(function (temp_evt) {
             // This function needs documentation.
                var i, n;
                n = temp.length;
                y.val = [];
                for (i = 0; i < n; i += 1) {
                    y.val[i] = temp[i].val;
                }
                temp_evt.exit();
                return evt.exit();
            });
            return;
        });
        return y;
    };

    mapreduce = function (x, mapf, redf, box, env) {
     // This function needs documentation.
        var y = avar();
        y.Q(function (evt) {
         // This function needs documentation.
            map(x, mapf, box, env).Q(function (temp_evt) {
             // This function needs documentation.
                y.val = this.val;
                temp_evt.exit();
                return evt.exit();
            }).on('error', evt.fail);
            return;
        }).Q(function (evt) {
         // This function needs documentation.
            reduce(y.val, redf, box, env).Q(function (temp_evt) {
             // This function needs documentation.
                y.val = this.val;
                temp_evt.exit();
                return evt.exit();
            }).on('error', evt.fail);
            return;
        });
        return y;
    };

    mothership = 'https://api.qmachine.org';

    origin = function () {
     // This function needs documentation.
        return global.location.protocol + '//' + global.location.host;
    };

    ply = function () {
     // This function has been condensed from its previous forms because
     // changes in Quanah 0.2.x made its support of dual asynchronous and
     // synchronous idioms both unnecessary and obsolete.
        var args = Array.prototype.slice.call(arguments);
        return {
            by: function (f) {
             // This function is a general-purpose iterator for key-value
             // pairs, and it works exceptionally well in JavaScript because
             // hash-like objects are so common in this language. This
             // definition itself is a little slower than previous versions
             // because they were optimized for internal use. In
             // performance-critical sections of Quanah that run often but
             // rarely change, I have inlined loops as appropriate. It is
             // difficult to optimize code for use with modern JIT compilers,
             // and my own recommendation is to hand-optimize with loops only
             // if you're truly obsessed with performance -- it's a lot of
             // work, and the auto-detecting and delegating dynamically in
             // order to use the fastest possible loop pattern adds overhead
             // that can be difficult to optimize for use in real-world
             // applications. That said, if you have ideas for how to make
             // `ply..by` run more efficiently, by all means drop me a line :-)
                if (is_Function(f) === false) {
                    throw new TypeError('`ply..by` expects a function.');
                }
                var i, key, obj, n, toc, x;
                n = args.length;
                toc = {};
                x = [];
                for (i = 0; i < n; i += 1) {
                    if ((args[i] !== null) && (args[i] !== undefined)) {
                        obj = args[i].valueOf();
                        for (key in obj) {
                            if (obj.hasOwnProperty(key)) {
                                if (toc.hasOwnProperty(key) === false) {
                                    toc[key] = x.push([key]) - 1;
                                }
                                x[toc[key]][i + 1] = obj[key];
                            }
                        }
                    }
                }
                n = x.length;
                for (i = 0; i < n; i += 1) {
                    f.apply(this, x[i]);
                }
                return;
            }
        };
    };

    puts = function () {
     // This function needs documentation.
        var args = Array.prototype.slice.call(arguments);
        return sync.apply(this, args).Q(function (evt) {
         // This function needs documentation.
            if ((global.console instanceof Object) &&
                    (is_Function(global.console.log))) {
                global.console.log(args.join(' '));
                return evt.exit();
            }
            return evt.fail('The `console.log` method is not available.');
        }).on('error', function (message) {
         // This function needs documentation.
            if ((global.console instanceof Object) &&
                    (is_Function(global.console.error))) {
                global.console.error('Error:', message);
            }
            return;
        });
    };

    recent = function (method, url) {
     // This function helps keep clients from polling too rapidly when they are
     // waiting for a remote task to finish. It keeps track of HTTP requests
     // made within the last 1000 milliseconds in order to prevent repeat calls
     // that use the same method and URL. This doesn't affect task execution by
     // volunteers, however, because those alternate between GETs and POSTs.
        var dt, flag, key, time;
        dt = 1000;
        time = Date.now();
        for (key in state.recent) {
            if (state.recent.hasOwnProperty(key)) {
                if ((time - state.recent[key].time) > dt) {
                    delete state.recent[key];
                }
            }
        }
        flag = ((state.recent.hasOwnProperty(url)) &&
                (state.recent[url].method === method));
        if (flag === false) {
            state.recent[url] = {
                method: method,
                time:   time
            };
            revive(dt + 1);
        }
        return flag;
    };

    reduce = function (x, redf, box, env) {
     // This function needs documentation.
        var f, y;
        f = convert_to_js(redf);
        y = ((x instanceof AVar) ? x : avar(x)).Q(function (evt) {
         // This function needs documentation.
            if (is_Function(f.val) === false) {
                f.on('error', evt.fail);
                return evt.stay('Awaiting function translation ...');
            }
            if (this.val.length < 2) {
                this.val = this.val[0];
                return evt.exit();
            }
            var g, i, n, obj, temp, that, x;
            g = function (obj) {
             // This function needs documentation.
                return obj.f(obj.a, obj.b);
            };
            temp = [];
            that = this;
            x = that.val;
         // This line is easier to read than modulo junk ...
            n = 2 * Math.floor(x.length / 2);
            for (i = 0; i < n; i += 2) {
                obj = {f: f.val, a: x[i], b: x[i + 1]};
                temp.push(submit(obj, g, box, env).on('error', evt.fail));
            }
            if (n !== x.length) {
                temp.push(avar(x[x.length - 1]).on('error', evt.fail));
            }
            sync.apply(this, temp).Q(function (temp_evt) {
             // This function needs documentation.
                var i, n, x;
                n = temp.length;
                x = [];
                for (i = 0; i < n; i += 1) {
                    x[i] = temp[i].val;
                }
                that.val = x;
                temp_evt.exit();
                return evt.stay('asynchronous loop');
            }).on('error', evt.fail);
            return;
        });
        return y;
    };

    revive = function (ms) {
     // This function restarting Quanah's event loop asynchronously using the
     // browser's own event loop if possible. It accepts an optional argument
     // specifying the number of milliseconds to wait before restarting.
        var dt = parseInt(ms, 10);
        if (is_Function(global.setTimeout)) {
            global.setTimeout(AVar.prototype.revive, isNaN(dt) ? 0 : dt);
        } else {
            AVar.prototype.revive();
        }
        return;
    };

    run_remotely = function (obj) {
     // This function distributes computations to remote execution nodes by
     // constructing a task that represents the computation, writing it to a
     // shared storage, polling for changes to its status, and then reading
     // the new values back into the local variables. My strategy is to use
     // a bunch of temporary avars that only execute locally -- on this part
     // I must be very careful, because remote calls should be able to make
     // remote calls of their own, but execution of a remote call should not
     // require remote calls of its own! A publication is forthcoming, and at
     // that point I'll simply use a self-citation as an explanation :-)
        var f, first, handler, x;
     // Step 1: copy the computation's function and data into fresh instances,
     // define some error handlers, and write the copies to the "filesystem".
     // If special property values have been added to `x`, they will be copied
     // onto `f` and `x` via the "copy constructor" idiom. Note that special
     // properties defined for `f` will be overwritten ...
        f = copy({box: obj.x.box, key: uuid()}, avar(obj.f));
        first = true;
        handler = function (message) {
         // This function tells the original `x` that something has gone awry.
            if (first === true) {
                first = false;
                obj.x.comm({fail: message});
            }
            return;
        };
        x = copy({box: obj.x.box, key: obj.x.key}, avar(obj.x.val));
        f.on('error', handler).Q(update_remote);
        x.on('error', handler).Q(update_remote);
     // Step 2: Use a `sync` statement to represent the remote computation and
     // track its execution status on whatever system is using Quanah.
        sync(f, x).Q(function (evt) {
         // This function creates a `task` object to represent the computation
         // and monitors its status by "polling" the "filesystem" for changes.
         // It initializes using `avar`'s "copy constructor" idiom to enable
         // `task` to "inherit" system-specific properties such as QMachine's
         // `box` property automatically. My design here reflects the idea that
         // the execution should follow the data.
            var task = avar({f: f.key, x: x.key});
            task.box = obj.x.box;
            task.key = uuid();
            task.status = 'waiting';
            task.on('error', function (message) {
             // This function alerts `f` and `x` that something has gone awry.
                return evt.fail(message);
            }).Q(update_remote).Q(function (evt) {
             // This function polls for changes in the `status` property using
             // a variation on the `update_local` function as a non-blocking
             // `while` loop -- hooray for disposable avars!
                var temp = get_avar(task);
                temp.on('error', function (message) {
                 // This alerts `task` that something has gone awry.
                    return evt.fail(message);
                }).Q(function (temp_evt) {
                 // This function analyzes the results of the `read` operation
                 // to determine if the `task` computation is ready to proceed.
                    switch (temp.status) {
                    case 'done':
                        task.val = temp.val;
                        evt.exit();
                        break;
                    case 'failed':
                        evt.fail(temp.val.epitaph);
                        break;
                    default:
                        evt.stay('Waiting for results ...');
                    }
                    return temp_evt.exit();
                });
                return;
            }).Q(function (task_evt) {
             // This function ends the enclosing `sync` statement.
                task_evt.exit();
                return evt.exit();
            });
            return;
        });
     // Step 3: Update the local instances of `f` and `x` by retrieving the
     // remote versions' representations. If possible, these operations will
     // run concurrently.
        f.Q(update_local);
        x.Q(update_local);
     // Step 4: Use a `sync` statement to wait for the updates in Step 3 to
     // finish before copying the new values into the original `obj` argument.
        sync(f, x).Q(function (evt) {
         // This function copies the new values into the old object. Please
         // note that we cannot simply write `obj.foo = foo` because we would
         // lose the original avar's internal state!
            obj.f = f.val;
            obj.x.val = x.val;
            obj.x.comm({done: []});
            return evt.exit();
        });
        return;
    };

    serialize = function (x) {
     // This function extends the standard `JSON.stringify` function with
     // support for functions and regular expressions. One of the problems I
     // address here is that the ES5.1 standard doesn't dictate a format for
     // representing functions as strings (see section 15.3.4.2). Another
     // problem is that the standard dictates that _no_ representation be given
     // at all in certain situations (see section 15.3.4.5). Fortunately, we
     // can avoid a lot of these situations entirely by using JSLint prior to
     // invoking the `serialize` function, but it isn't a perfect solution,
     // since users can currently invoke this function indirectly by calling
     // `JSON.stringify`. Also, this function depends on `btoa`, which may or
     // may not have issues with UTF-8 strings in different browsers. I have
     // not found a test case yet that proves I need to work around the issue,
     // but if I do, I will follow advice given at http://goo.gl/cciXV.
        /*jslint unparam: true */
        return JSON.stringify(x, function replacer(key, val) {
         // For more information on the use of `replacer` functions with the
         // `JSON.stringify` method, read the [inline] documentation for the
         // reference implementation, "json2.js", available online at
         // https://raw.github.com/douglascrockford/JSON-js/master/json2.js.
            var obj, $val;
            if (is_Function(val)) {
             // If the input argument `x` was actually a function, we have to
             // perform two steps to serialize the function because functions
             // are objects in JavaScript. The first step is to consider the
             // function as only its "action", represented as the source code
             // of the original function. The second step is to consider the
             // function as only an object with its own methods and properties
             // that must be preserved as source code also. (We can assume that
             // scope need not be preserved because `serialize` is only called
             // when `is_closed` returns `false`.)
                obj = {};
                $val = '[FUNCTION ';
                if (is_Function(val.toJSON)) {
                    $val += btoa(val.toJSON());
                } else if (is_Function(val.toSource)) {
                    $val += btoa(val.toSource());
                } else if (is_Function(val.toString)) {
                    $val += btoa(val.toString());
                } else {
                 // Here, we just hope for the best. This arm shouldn't ever
                 // run, actually, since we've likely already caught problems
                 // that would land here in the `is_closed` function.
                    $val += btoa(val);
                }
                ply(val).by(function f(key, val) {
                 // This function copies methods and properties from the
                 // function stored in `val` onto an object `obj` so they can
                 // be serialized separately from the function itself, but it
                 // only transfers the ones a function wouldn't normally have,
                 // using this function (`f`) itself as a reference. Because
                 // order isn't important, the use of `ply` is justified here.
                    if (f.hasOwnProperty(key) === false) {
                        obj[key] = val;
                    }
                    return;
                });
             // Now, we use recursion to serialize the methods and properties.
                $val += (' ' + btoa(serialize(obj)) + ']');
            } else if (is_RegExp(val)) {
             // Using a similar approach as for functions for almost exactly
             // the same reasons as for functions, we will now try to serialize
             // regular expressions.
                obj = {};
                $val = '[REGEXP ';
                if (val.hasOwnProperty('source')) {
                    $val += btoa([
                     // For now, I am ignoring the non-standard `y` ("sticky")
                     // flag until I confirm that it won't confuse browsers
                     // that don't support it.
                        '/', val.source, '/',
                        ((val.global === true) ? 'g' : ''),
                        ((val.ignoreCase === true) ? 'i' : ''),
                        ((val.multiline === true) ? 'm' : '')
                    ].join(''));
                } else if (is_Function(val.toJSON)) {
                    $val += btoa(val.toJSON());
                } else if (is_Function(val.toSource)) {
                    $val += btoa(val.toSource());
                } else if (is_Function(val.toString)) {
                    $val += btoa(val.toString());
                } else {
                 // Here, we just hope for the best. This arm shouldn't ever
                 // run, actually, since we've likely already caught problems
                 // that would land here in the `is_closed` function.
                    $val += btoa(val);
                }
                ply(val, /^$/).by(function f(key, val, standard) {
                 // This function copies methods and properties from the
                 // regular expression stored in the outer `val` onto an object
                 // `obj` so they can be serialized separately from the regular
                 // expression itself, but it only transfers the ones a regular
                 // expression wouldn't normally have. Because order isn't
                 // important, the use of `ply` is justified here.
                    if ((standard === undefined) && (val !== undefined)) {
                        obj[key] = val;
                    }
                    return;
                });
             // Now, we use recursion to serialize the methods and properties.
                $val += (' ' + btoa(serialize(obj)) + ']');
            }
            return ($val === undefined) ? val : $val;
        });
    };

    set_avar = function (x) {
     // This function sends an HTTP POST to QMachine. It doesn't worry
     // about the return data because QMachine isn't going to return
     // any data -- the request will either succeed or fail, as
     // indicated by the HTTP status code returned. It returns an avar.
        var url = mothership + '/box/' + x.box + '?key=' + x.key;
        return ajax('POST', url, JSON.stringify(x));
    };

    start = function () {
     // This function enables volunteering inside the background event loop
     // contained in this giant anonymous closure. This pairs with the `stop`
     // function to provide convenience, as this functionality and background
     // event loop were previously required to be provided as part of the app
     // that leverages this library.
        state.enable_volunteer = true;
        revive();
        return;
    };

    state = {
        box: 'ooga',
        enable_volunteer: false,
        exemptions: {},
        recent: {}
    };

    stop = function () {
     // This function pairs with `start`; see explanation there.
        state.enable_volunteer = false;
        revive();
        return;
    };

    submit = function (x, f, box, env) {
     // This function needs documentation.
        var arg_box, arg_env, arg_f, arg_x, y;
        if (arguments.length === 1) {
         // Assume here that the input argument is an object with properties
         // corresponding to the four variables. Although this is my preferred
         // syntax, it is not the default because the `submit` function is not
         // intended for advanced users anyway -- it's the "training wheels"
         // version of QM.
            arg_box = x.box;
            arg_env = x.env;
            arg_f = x.f;
            arg_x = x.x;
        } else {
            arg_box = box;
            arg_env = env;
            arg_f = f;
            arg_x = x;
        }
        y = avar();
        y.on('error', function (message) {
         // This function _can_ be overridden if the user specifies his or her
         // own handler. Otherwise, this function ensures that errors cause the
         // computation to self-destruct in a really ugly horrible way :-P
            throw message;
        });
        sync(arg_box, arg_env, arg_f, arg_x, y).Q(function (evt) {
         // This function runs locally.
            var box, env, f, x;
            box = (arg_box instanceof AVar) ? arg_box.val : arg_box;
            env = (arg_env instanceof AVar) ? arg_env.val : arg_env;
            f = (arg_f instanceof AVar) ? arg_f.val : arg_f;
            x = (arg_x instanceof AVar) ? arg_x.val : arg_x;
            if (is_String(box)) {
                y.box = box;
            }
            convert_to_js(f).Q(function (f_evt) {
             // This function needs documentation.
                y.val = {
                    env: ((env instanceof Object) ? env : {}),
                    f: this.val,
                    x: x
                };
                f_evt.exit();
                return evt.exit();
            }).on('error', evt.fail);
            return;
        });
        y.Q(function (evt) {
         // This function runs locally.
            var key, options, task, temp;
            options = {
                predef: {
                    'QM': false
                }
            };
            task = {
                f: y.val.f,
                x: y.val.x
            };
            for (key in y.val.env) {
                if (y.val.env.hasOwnProperty(key)) {
                    options.predef[key] = false;
                }
            }
            if (is_closed(task, options)) {
                return evt.fail(global.JSLINT.errors[0].reason);
            }
            temp = copy({box: y.box}, avar(y.val));
            state.exemptions[temp.key] = options;
            temp.on('error', function (message) {
             // This function needs documentation.
                delete state.exemptions[temp.key];
                return evt.fail(message);
            });
            temp.Q(function (evt) {
             // This function runs remotely on a volunteer machine.
                /*global QM: false */
                var env, f, temp, x;
                env = QM.avar(this.val.env);
                f = this.val.f;
                temp = this;
                x = QM.avar(this.val.x);
                env.on('error', evt.fail);
                x.on('error', evt.fail);
                QM.sync(env, x).Q(function (evt) {
                 // This function ensures that the task will not execute until
                 // the prerequisite scripts have finished loading.
                    var prereqs = [];
                    QM.ply(env.val).by(function (key, val) {
                     // This function needs documentation.
                        var libs = QM.avar(val.slice());
                        libs.on('error', function (message) {
                         // This function needs documentation.
                            return evt.fail(message);
                        }).Q(function (evt) {
                         // This function needs documentation.
                            if (libs.val.length === 0) {
                                return evt.exit();
                            }
                            var v = libs.val;
                            QM.load_script(v.shift()).Q(function (v_evt) {
                             // This function needs documentation.
                                v_evt.exit();
                                if (v.length === 0) {
                                 // This shaves off an extra step, but I'm not
                                 // sure if it's worth the extra lines ...
                                    return evt.exit();
                                }
                                return evt.stay('Recursing ... (' + key + ')');
                            }).on('error', function (message) {
                             // This function needs documentation.
                                return evt.fail(message);
                            });
                            return;
                        });
                        prereqs.push(libs);
                        return;
                    });
                    if (prereqs.length === 0) {
                        return evt.exit();
                    }
                    QM.sync.apply(null, prereqs).Q(function (w_evt) {
                     // This function needs documentation.
                        w_evt.exit();
                        return evt.exit();
                    });
                    return;
                });
                x.Q(function (evt) {
                 // This function is crucial for enabling synchronous syntax in
                 // the asynchronous world of the web.
                    var temp = f(this.val);
                    if (temp instanceof QM.avar().constructor) {
                        temp.Q(function (temp_evt) {
                         // This function needs documentation.
                            x.val = temp.val;
                            temp_evt.exit();
                            return evt.exit();
                        }).on('error', function (message) {
                         // This function needs documentation.
                            return evt.fail(message);
                        });
                        return;
                    }
                    this.val = temp;
                    return evt.exit();
                }).Q(function (x_evt) {
                 // This function needs documentation.
                    temp.val = x.val;
                    x_evt.exit();
                    return evt.exit();
                });
                return;
            }).Q(function (temp_evt) {
             // This function runs locally.
                delete state.exemptions[temp.key];
                y.val = temp.val;
                temp_evt.exit();
                return evt.exit();
            });
            return;
        });
        return y;
    };

    sync = global.QUANAH.sync;

    uuid = function () {
     // This function generates random hexadecimal strings of length 32. These
     // strings don't satisfy RFC 4122 or anything, but they're conceptually
     // the same as UUIDs. This version of the function generates characters by
     // sampling uniformly from [0, 16] and flooring, which generates an index
     // that maps to a character. This definition works in old browsers as well
     // as Adobe/Mozilla Tamarin and PhantomJS, the last of which has an open
     // issue regarding number-to-string conversion (http://goo.gl/8r4C40) that
     // caused the previous definition to generate invalid characters. As a
     // bonus, this version also generates a more uniform range of hexadecimal
     // strings than the previous one, in which zeroes were underrepresented.
     // An even faster version is shown in the comments, but it infuriates
     // JSLint because it uses the `|` operator instead of `Math.floor` :-P
        var c, i, y;
        c = [
            '0', '1', '2', '3', '4', '5', '6', '7',
            '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
        ];
        //y = c[(Math.random() * 16) | 0];
        y = c[Math.floor(Math.random() * 16)];
        for (i = 1; i < 32; i += 1) {
            //y += c[(Math.random() * 16) | 0];
            y += c[Math.floor(Math.random() * 16)];
        }
        return y;
    };

    update_local = function (evt) {
     // This function is used in the `run_remotely` and `volunteer` functions
     // to update the local copy of an avar so that its `val` property matches
     // the one from its remote representation. It is written as a function of
     // `evt` because it is intended to be used as an argument to Method Q.
        var local = this;
        get_avar(local).Q(function (temp_evt) {
         // This function copies the remote representation's property values
         // onto `local`. Note that the `copy` function does not copy `comm`
         // from `this` to `local` because `evt.exit` wouldn't work anymore.
            copy(this, local);
            temp_evt.exit();
            return evt.exit();
        }).on('error', function (message) {
         // This function tells `local` that something has gone awry.
            return evt.fail(message);
        });
        return;
    };

    update_remote = function (evt) {
     // This function is used in the `remote_call` and `volunteer` functions
     // to update the remote copy of an avar so that its `val` property matches
     // the one from its local representation. It is written as a function of
     // `evt` because it is intended to be used as an argument to Method Q.
        set_avar(this).Q(function (temp_evt) {
         // This function just releases execution for the local avar (`this`).
            temp_evt.exit();
            return evt.exit();
        }).on('error', function (message) {
         // This function tells the local avar that something has gone awry.
            return evt.fail(message);
        });
        return;
    };

    volunteer = function (box) {
     // This function, combined with `run_remotely`, provides the remote code
     // execution mechanism in Quanah. When `run_remotely` on one machine sends
     // a serialized task to another machine, that other machine runs it with
     // the `volunteer` function. This function outputs the avar representing
     // the task so that the underlying system (QM, in this case) can control
     // system resources itself. Examples will be included in the distribution
     // that will accompany the upcoming publication(s).
        if (is_String(box) === false) {
            box = global.QM.box;
        }
        var task = copy({box: box}, avar());
        task.Q(function (evt) {
         // This function retrieves the key of a task from the queue so we
         // can retrieve that task's full description. If no tasks are found,
         // we will simply check back later :-)
            var temp = get_list(box);
            temp.on('error', function (message) {
             // This function notifies `task` that something has gone wrong
             // during retrieval and interpretation of its description.
                return evt.fail(message);
            }).Q(function (temp_evt) {
             // This function chooses a task from the queue and runs it.
                var queue = temp.val;
                if ((queue instanceof Array) === false) {
                 // This seems like a common problem that will occur whenever
                 // users begin implementing custom storage mechanisms.
                    return temp_evt.fail('`get_list` should return an array');
                }
                if (queue.length === 0) {
                 // Here, we choose to `fail` not because this is a dreadful
                 // occurrence or something, but because this decision allows
                 // us to avoid running subsequent functions whose assumptions
                 // depend precisely on having found a task to run. If we were
                 // instead to `stay` and wait for something to do, it would
                 // be much harder to tune Quanah externally.
                    return temp_evt.fail('Nothing to do ...');
                }
             // Here, we grab a random entry from the queue, rather than the
             // first element in the queue. Why? Well, recall that tasks cannot
             // enter the "global" queue until the avars they will transform
             // are ready; this immediately implies that no task in the remote
             // queue can ever run out of order anyway. Unfortunately, without
             // fancy server-side transactional logic, workers can potentially
             // execute the same job redundantly, especially when there are a
             // large number of workers and a small number of jobs. This isn't
             // a big deal for an opportunistic system, and it may even be a
             // desirable "inefficiency" because it means the invoking machine
             // will get an answer faster. In some cases, though, such as for
             // batch jobs that take roughly the same amount of time to run, we
             // need to "jitter" the queue a little to avoid deadlock.
                task.key = queue[Math.floor(Math.random() * queue.length)];
                temp_evt.exit();
                return evt.exit();
            });
            return;
        }).Q(function (evt) {
         // This is just for debugging purposes ...
            update_local.call(this, evt);
            return;
        }).Q(function (evt) {
         // This function changes the `status` property of the local `task`
         // object we just synced from remote; the next step, obviously, is
         // to sync back to remote so that the abstract task will disappear
         // from the "waiting" queue.
            task.status = 'running';
            return evt.exit();
        }).Q(update_remote).Q(function (evt) {
         // This function executes the abstract task by recreating `f` and `x`
         // and running them in the local environment. Since we know `task` is
         // serializable, we cannot simply add its deserialized form to the
         // local machine's queue (`queue`), because `revive` would just send
         // it back out for remote execution again. Thus, we deliberately close
         // over local variables like `avar` in order to restrict execution to
         // the current environment. The transform defined in `task.val.f` is
         // still able to distribute its own sub-tasks for remote execution.
            var f, first, handler, x;
            f = copy({box: box, key: task.val.f}, avar());
            first = true;
            handler = function (message) {
             // This function runs if execution of the abstract task fails.
             // The use of a `first` value prevents this function from running
             // more than once, because aside from annoying the programmer by
             // returning lots of error messages on his or her screen, such a
             // situation can also wreak all kinds of havoc for reentrancy.
                var temp_f, temp_x;
                if (message === 409) {
                 // If we get `409` as an error message, it is most likely to
                 // be because the server has already received a result for
                 // this task from some other volunteer and thus that we have
                 // received a `409` HTTP status code for an update conflict.
                    return evt.fail('Results were already submitted.');
                }
                if (first) {
                    first = false;
                    task.val.epitaph = message;
                    task.status = 'failed';
                    temp_f = copy(f, avar()).Q(update_remote);
                    temp_x = copy(x, avar()).Q(update_remote);
                    sync(temp_f, temp_x).Q(function (temp_evt) {
                     // This function runs only when the error messages have
                     // finished syncing to remote storage successfully.
                        temp_evt.exit();
                        return evt.exit();
                    });
                }
                return;
            };
            x = copy({box: box, key: task.val.x}, avar());
            f.Q(update_local).on('error', handler);
            x.Q(update_local).on('error', handler);
            sync(f, x).Q(function (evt) {
             // This function contains the _actual_ execution. (Boring, huh?)
                f.val.call(x, evt);
                return;
            });
         //
         // Here, I would like to have a function that checks `f` and `x` to
         // using `is_closed` to ensure that the results it returns to the
         // invoking machine are the same as the results it computed, because
         // it _is_ actually possible to write a serializable function which
         // renders itself unserializable during its evaluation. Specifically,
         // if the results are not serializable and we are therefore unable to
         // return an accurate representation of the results, then I want to
         // send a special signal to the invoking machine to let it know that,
         // although no error has occurred, results will not be returned; the
         // invoking machine would then execute the "offending" task itself.
         // I have included a simple outline of such a function:
         //
         //     sync(f, x).Q(function (evt) {
         //         if (is_closed(f.val) || is_closed(x.val)) {
         //             return evt.abort('Results will not be returned.');
         //         }
         //         return evt.exit();
         //     });
         //
            f.Q(update_remote);
            x.Q(update_remote);
            sync(f, x).Q(function (temp_evt) {
             // This function only executes when the task has successfully
             // executed and the transformed values of `f` and `x` are synced
             // back to remote storage. Thus, we are now free to send the
             // signal for successful completion to the invoking machine by
             // updating the `status` property locally and syncing to remote.
                task.status = 'done';
                temp_evt.exit();
                return evt.exit();
            });
            return;
        }).Q(update_remote);
        return task;
    };

 // Prototype definitions

    defineProperty(AVar.prototype, 'box', {
     // This definition adds a `box` property to Quanah's avars as a means to
     // enable QMachine's per-instance queueing system. The other necessary
     // component is the `QM.box` definition a little further down.
        configurable: true,
        enumerable: false,
        get: function () {
         // This function needs documentation.
            return state.box;
        },
        set: function (x) {
         // This function needs documentation.
            if (is_String(x) === false) {
                throw new TypeError('`box` property must be a string.');
            }
            if ((/^[\w\-]+$/).test(x) === false) {
                throw new Error('Invalid assignment to `box`: "' + x + '"');
            }
            defineProperty(this, 'box', {
                configurable: true,
                enumerable: true,
                writable: true,
                value: x
            });
            return;
        }
    });

    defineProperty(AVar.prototype, 'key', {
     // This definition adds a `key` property to Quanah's avars as a means to
     // enable QMachine's per-instance queueing system. The other necessary
     // component is the `QM.box` definition a little further down.
        configurable: true,
        enumerable: false,
        get: function () {
         // This function needs documentation.
            var key = uuid();
            this.key = key;
            return key;
        },
        set: function (x) {
         // This function needs documentation.
            if (is_String(x) === false) {
                throw new TypeError('`key` property must be a string.');
            }
            if ((/^[\w\-]+$/).test(x) === false) {
                throw new Error('Invalid assignment to `key`: "' + x + '"');
            }
            defineProperty(this, 'key', {
                configurable: true,
                enumerable: true,
                writable: true,
                value: x
            });
            return;
        }
    });

    defineProperty(AVar.prototype, 'print', {
     // NOTE: I commented two of the next three lines out because their values
     // are the default ones specified by the ES5.1 standard.
        //configurable: false,
        enumerable: true,
        //writable: false,
        value: function () {
         // This function is syntactic sugar for logging output. I honestly
         // cannot remember why I used `QM.puts` here instead of just `puts`,
         // because this is a function that should *not* run remotely ...
            QM.puts(this);
            return this;
        }
    });

    defineProperty(AVar.prototype, 'toJSON', {
     // NOTE: I commented two of the next three lines out because their values
     // are the default ones specified by the ES5.1 standard.
        //configurable: false,
        enumerable: true,
        //writable: false,
        value: function () {
         // This function exists as a way to ensure that `JSON.stringify` can
         // serialize avars correctly, because that function will delegate to
         // an input argument's `toJSON` prototype method if one is available.
            var comm, y;
            comm = this.comm;
            delete this.comm;
            y = JSON.parse(serialize(copy(this)));
            this.comm = comm;
            return y;
        }
    });

    defineProperty(AVar.prototype, 'toString', {
     // NOTE: I commented two of the next three lines out because their values
     // are the default ones specified by the ES5.1 standard.
        //configurable: false,
        enumerable: true,
        //writable: false,
        value: function () {
         // This function delegates to the avar's `val` property if possible.
         // The code here differs from the code for `AVar.prototype.valueOf`
         // because it assumes that the returned value should have a particular
         // type (string). The reasoning here is that, if the returned value
         // were not a string, the JS engine would *probably* coerce it to a
         // string, but why worry? Specifying the behavior explicitly is cheap
         // and easy to understand :-)
            if (this.val === null) {
                return 'null';
            }
            if (this.val === undefined) {
                return 'undefined';
            }
            return this.val.toString.apply(this.val, arguments);
        }
    });

    defineProperty(AVar.prototype, 'valueOf', {
     // NOTE: I commented two of the next three lines out because their values
     // are the default ones specified by the ES5.1 standard.
        //configurable: false,
        enumerable: true,
        //writable: false,
        value: function () {
         // This function delegates to the avar's `val` property. It would be
         // easy simply to return the value of the avar's `val` and let the JS
         // engine decide what to do with it, but that approach assumes that no
         // value's `valueOf` method ever uses input arguments. That assumption
         // could be supported by a careful reading of the ES5.1 standard (June
         // 2011), but the priority here is correctness -- not performance --
         // and therefore this method has been designed for generic use.
            if ((this.val === null) || (this.val === undefined)) {
                return this.val;
            }
            return this.val.valueOf.apply(this.val, arguments);
        }
    });

 // Out-of-scope definitions

    defineProperty(global, 'QM', {
     // This creates the "namespace" for QMachine as a global `QM` object.
     // NOTE: I commented out two of the next three lines because their values
     // match the ES5.1 default values.
        //configurable: false,
        enumerable: true,
        //writable: false,
        value: {}
    });

    defineProperty(global.QM, 'box', {
     // Here, we enable users to send jobs to different "boxes" by labeling
     // the avars on a per-case basis, rather than on a session-level basis.
     // More explanation will be included in the upcoming paper :-)
        configurable: false,
        enumerable: true,
        get: function () {
         // This function needs documentation.
            return state.box;
        },
        set: function (x) {
         // This function needs documentation.
            if (is_String(x) === false) {
                throw new TypeError('`QM.box` must be a string.');
            }
            if ((/^[\w\-]+$/).test(x) === false) {
                throw new Error('Invalid assignment to `QM.box`: "' + x + '"');
            }
            state.box = x;
            global.QM.revive();
            return;
        }
    });

    (function () {
     // Here, we add some static methods to `QM` that make QMachine a little
     // more convenient to use ...
        var template;
        template = {
            avar:           avar,
            lib:            lib,
            load_data:      load_data,
            load_script:    load_script,
            map:            map,
            mapreduce:      mapreduce,
            ply:            ply,
            puts:           puts,
            reduce:         reduce,
            revive:         revive,
            shelf:          {},
            start:          start,
            stop:           stop,
            submit:         submit,
            sync:           sync,
            volunteer:      volunteer
        };
        ply(template).by(function (key, val) {
         // This function needs documentation.
            if (global.QM.hasOwnProperty(key) === false) {
                defineProperty(global.QM, key, {
                 // NOTE: I commented out two of the next three lines
                 // because their values match the ES5.1 default values.
                    //configurable: false,
                    enumerable: true,
                    //writable: false,
                    value: val
                });
            }
            return;
        });
        return;
    }());

 // Invocations

    (function loop() {
     // Here, we start a simple event loop that runs in the background. It
     // enables the process of scripting volunteers significantly easier, too,
     // because that responsibility was formerly placed on the app code that
     // uses this library.
        if (is_Function(global.clearTimeout)) {
            global.clearTimeout(loop.timer);
        }
        if (state.enable_volunteer === true) {
            volunteer(state.box).on('error', function (message) {
             // This function redirects error messages appropriately.
                if (message === 'Nothing to do ...') {
                    puts(message);
                } else if ((global.console instanceof Object) &&
                        (is_Function(global.console.error))) {
                    global.console.error('Error:', message);
                } else {
                    puts('Error:', message);
                }
                if (is_Function(global.setTimeout)) {
                    loop.timer = global.setTimeout(loop, 1000);
                }
                return;
            }).Q(function (evt) {
             // This function provides visual feedback for debugging as soon as
             // the volunteer finishes executing a task.
                puts('Done:', this.key);
                if (is_Function(global.setTimeout)) {
                    loop.timer = global.setTimeout(loop, 1000);
                }
                return evt.exit();
            });
        } else if (is_Function(global.setTimeout)) {
            loop.timer = global.setTimeout(loop, 1000);
        }
        revive();
        return;
    }());

    state.box = uuid();

    global.QUANAH.def({
        can_run_remotely:   can_run_remotely,
        run_remotely:       run_remotely
    });

 // That's all, folks!

    return;

}(Function.prototype.call.call(function (that) {
    'use strict';

 // This strict anonymous closure encapsulates the logic for detecting which
 // object in the environment should be treated as _the_ global object. It's
 // not as easy as you may think -- strict mode disables the `call` method's
 // default behavior of replacing `null` with the global object. Luckily, we
 // can work around that by passing a reference to the enclosing scope as an
 // argument at the same time and testing to see if strict mode has done its
 // deed. This task is not hard in the usual browser context because we know
 // that the global object is `window`, but CommonJS implementations such as
 // RingoJS confound the issue by modifying the scope chain, running scripts
 // in sandboxed contexts, and using identifiers like `global` carelessly ...

    /*global global: false */
    /*jslint indent: 4, maxlen: 80 */
    /*properties global */

    if (this === null) {

     // Strict mode has captured us, but we already passed a reference :-)

        return (typeof global === 'object') ? global : that;

    }

 // Strict mode isn't supported in this environment, but we need to make sure
 // we don't get fooled by Rhino's `global` function.

    return (typeof this.global === 'object') ? this.global : this;

}, null, this), function ($f) {
    'use strict';

 // This is a sandbox for resuscitating function code safely. I will explain
 // more later ...

    /*jslint evil: true, indent: 4, maxlen: 80 */

    return (new Function('return ' + $f))();

}));

//- vim:set syntax=javascript: