Narrative JavaScript

API Reference: functions

spawn->([call])

Launches a new thread of execution, returning a future (see ResultNotifier) representing its result. Use spawn() to kick of the execution of a method containing the yielding operator.

parameters: call — the result of a method call. If the method call is yielding, it returns a special value that spawn recognizes and converts into a future. If the method call is not yielding, the value is simply used to fulfill the returned ResultNotifier.

returns: A ResultNotifier that is (eventually) fulfilled with the return value of the launched thread.

example: display a new value every second for 10 seconds:

    function update(n) {
        for(var i = 0; i < n; i++) {
            document.getElementById("counter").innerHTML = i;
            sleep->(1000);
        }
        return n;
    }
    
    var future = spawn(update(10));

sleep->([milliseconds])

Yields execution for the specified number of milliseconds.

parameters: milliseconds — the number of milleseconds to wait before resuming execution.

example:

    while (!checkState()) {
        sleep->(100);
    }

fetch->([url], [timeout])

Uses XmlHttp to retrieve a URL and yields execution until the document has been loaded.

parameters: url — the URL to fetch.
timeout — the amount of time (in milliseconds) to wait before returning null.

returns: a string containing the document contents, or null if an error occurs.

example:

    var document = fetch->("http://www.google.com/");

API Reference: EventNotifier

callback = new EventNotifier([id]);

Creates a new event notifier. An event notifier is a function that can be used as a callback for any JavaScript event.

parameters: id — (optional) a value that is returned from wait->() when an event is fired for this notifier. See the wait->() method for more information.

example:

    var elem = document.getElementById("myButton");
    elem.onclick = new EventNotifier();
    elem.onclick.wait->();

notifier.wait->([timeout])

Yields execution until the notifier is called. In environments that implement the setTimeout() method, the optional timeout parameter may be specified to indicate that the call should unblock if the notifier hasn't been called within the specified time period.

parameters: timeout — (optional) the number of milliseconds before NJS_TIMEOUT is thrown. If not specified, wait->() will wait forever for an event to fire.

returns: If an id was provided when the notifier was constructed, returns that id. Otherwise, returns the value that is passed into the notifier when it is fired. If no value is provided when the notifier is fired, wait->() will return the global event object if it exists, or finally null if none of the previous values exists.

throws: NJS_TIMEOUT if the specified time period has passed before the notifier is called

NJS_INTERRUPT if the interrupt() method is called on the identifier.

(If exception support is turned off when compiling, exceptions will be returned rather than thrown.)

example: The most common, simple usage:

    // do some work
    notifier.wait->();
    // do more work

More advanced usage:

    // do some work
    try {
        var args = notifier.wait->(3000);
    } catch(e if e == NJS_TIMEOUT) {
        // handle timeout
    } catch(e if e == NJS_INTERRUPT) {
        // handle interrupt
    }
    // do more work

API Reference: ResultNotifier

var promise = new ResultNotifier();

Creates a new result notifier. Result notifiers are containers for a single value that will be provided at a later time. As such, they can be used as promises or futures.

notifier.fulfill->([value])

Sets the value for this notifier. If value is in turn a notifier, this notifier automatically chains the return of value->() to the result of the parameter notifier.

parameters: the value for this notifier.

throws: an exception if a value has already by provided for this notifier.

notifier.hasValue()

Returns true if the notifier has a value, false otherwise.

notifier.value->([timeout])

Returns the value for this notifier. If called with the yielding operator, blocks until the value is provided. If called without the yielding operator, returns the notifier's value if one has already has already been provided, otherwise throws an exception.

parameters: timeout — (optional) the number of milliseconds before NJS_TIMEOUT is thrown. If not specified, wait->() will wait forever for an event to fire.

example: with yielding:

    var n = spawn(asynchOperation());
    var value = n.value->();

without yielding:

	if (n.hasValue()) {
		var value = n.value();
	}

API Reference: QueueNotifier

var mailbox = new QueueNotifier

Creates a new queue notifier. QueueNotifiers are useful for producer/consumer relationships, where there are one or more producers that push() values into the notifier, and one or more consumers that shift->() values out of the notifier.

example: Using the notifier chaining properties (see below), we can spawn multiple threads and wait for the first one that finishes:

    var n = new QueueNotifier();
    n.push( spawn(thread(1)) );
    n.push( spawn(thread(2)) );
    n.push( spawn(thread(3)) );

    var value = n.shift->();
    // value is from whichever thread finished first.

n.push([value])

Puts a value into the queue. If value is a notifier, placement in the queue is deferred until the notifier yields a value.

n.shift->([timeout])

Pulls a value off of the queue. If no value is currently available, blocks until a value becomes available.

parameters: timeout — (optional) the number of milliseconds before NJS_TIMEOUT is thrown. If not specified, wait->() will wait forever for an event to fire.

n.size()

Returns the number of elements currently in the queue.