API Reference: Future

future = new Future([func],[arguments],[scopeThis],[callback]);

Creates a new future. Futures are used to suspend execution until they are fulfilled. Futures can be containers for a single value that will be provided at a later time. If a function is provided, the function will be executed as a new thread/fiber. If the called function or any of the calls that it makes, suspends execution, (by calling future.result() on a future that has not been fulfilled), the constructor function will return without waiting for execution to be resumed. If the called function(s) do not suspend, it will return when finished, returning a fulfilled future object. This behaves the same as calling (except that it is executed as a new thread):

	func.apply(scopeThis,arguments);

If no parameters are provided the future will not be fulfilled until fulfill is called.

parameters:
func - (optional) the function to execute
arguments - (optional) The arguments to provide the executing function as an array.
scopeThis - (optional) the "this" for the calling function.
callback - (optional) If a callback is provided it will be executed on completion of the function's execution

returns: Returns a future that will be fulfilled by the execution (with the return value) of the provided function call.

future.fulfill([value])

Sets the value for this future and resumes any execution that is waiting on this future.

parameters:
the value for this future.

future.result([timeout])

Returns the value for this future. If the future has not been fulfilled yet, it blocks (suspends execution) until the value is provided. If the future has been fulfilled, it immediately returns the future's value.

examples:

parameters:
timeout — (optional) the number of milliseconds before Future.TimeoutException is thrown. If not specified, result() will wait forever for the future to be fulfilled.

example:

// example 1: an example of waiting for the user to respond
function waitForUser(userControl) { // wait for a the user to fire an event on a control
	var future = new Future();
	userControl.onFire = future.fulfill; // The event onFire should execute fulfill
	future.result(10000); // wait for the event to happen and then continue, if it doesn't happen in 10 secs then fail
}

// example 2: an example of spawning a new fiber
function spawnedFunc(futureB) {
	print("2. start spawned fiber");
	var result = futureB.result(); // should wait and then return 10
	print("4. finished spawned fiber with a value of " + result);
	return result + 5; // when this finishes it fulfills futureA that started it
}
function coroutineDemo() { // demonstration of starting a future and waiting for a future to be fulfilled
	print("1. start demo");
	var futureB = new Future();
	var futureA = new Future(spawnedFunc,[futureB]);
	print("3. function has been spawned, but is not done: isDone = " + futureA.isDone());
	futureB.fulfill(10);
	print("5. spawned function has finished and thus fulfilled futureA");
	var finalResult = futureA.result(); // This future has already been fulfilled and should provide a value of 15
	print("6. demo finished with a result from futureA of " + finalResult);

}
The output should be in the order of the numbers (1-6).

future.isDone()

Returns true if the future has been fulfilled.

future.interrupt([exception])

This will throw an exception in the all threads/fibers that are waiting on this future.

parameters:
exception - (optional) The exception to throw. Future.InterruptedException will be thrown if no parameter is provided.

future.addListener([callback])

When the future is fulfilled (if it has not already been), the given callback function will be executed when the future is completed. If the future has already been completed, this function will have no effect.

parameters:
callback - The function to execute when the future is fulfilled

sleep(milliseconds)

Pauses execution for the given number of milliseconds

parameters:
milliseconds - Time to pause in milliseconds

Extra capabilities

These functions are included in strands-ext.js

strands.request(url,method,postData)

Makes an XHR (Ajax) request using the given url, method, and post data (for POST requests) and returns contents that came from the server.

parameters:
url - the url to request
method - GET,POST, or other method to use
postData - if a POST is used, this is the post data

returns: The contents returned from the server

strands.synchronize(lockObject,func,notExclusive)

This function will can be used to synchronize access to a critical section of code. If there is other code with a lock on the lock object, than the code will be executed once the lock is released

parameters:
lockObject - This is the object to use lock. Two competing threads can use a single lock object to safeguard a critical section
func - This is the function to execute while locking out other execution of this function
notExclusive - Setting this to true will cause the function to be executed even if other code is using the lock object. The lock will be incremented so that synchronize will still block for calls that don't use this parameter

strands.rerunLater()

This can be used by idempotent functions that are written in native code that make calls to compiled code