issue #239 - documented flows.trampoline helper

lib/compiler/flows._js

@@ -272,6 +272,12 @@
 		return globals.context;
 	}
 
+	/// 
+	/// * result = flows.trampoline(_, fn, thisObj)`  
+	///   Executes `fn(_)` through a trampoline.  
+	///   Waits for `fn`'s result and returns it.  
+	///   This is equivalent to calling `fn.call(thisObj, _)` but the current stack is unwound
+	///   before calling `fn`.
 	exports.trampoline = _(function(cb, fn, thisObj) {
 		setImmediate(function() {
 			fn.call(thisObj, _ >> cb);
@@ -286,10 +292,13 @@
 		cb();
 	};
 
+	// document later
 	exports.nextTick =  function(_) {
 		nextTick(~_);
 	};
 
+	// document later
+	// should probably cap millis instead of trying to be too smart 
 	exports.setTimeout = function(fn, millis) {
 		// node's setTimeout notifies immediately if millis > max!! 
 		// So be safe and work around it. 
@@ -306,12 +315,16 @@
 		}
 	}
 
+	// document later
 	exports.setInterval = function(fn, millis) {
 		return setInterval(function() {
 			fn(!_);
 		}, millis)
 	}
 
+	/// 
+	/// * `flows.sleep(_, millis)`  
+	///   Sleeps `millis` ms.  
 	exports.sleep = function(_, millis) {
 		return setTimeout(~_, millis)
 	}
@@ -333,6 +346,10 @@
 		return fn.apply_(_, thisObj, args, index);
 	}
 
+	/// 
+	/// * `flows.callWithTimeout(_, fn, millis)`  
+	///   Calls `fn(_)` with a timeout guard.  
+	///   Throws a timeout exception if `fn` takes more than `millis` ms to complete.  
 	exports.callWithTimeout = _(function(cb, fn, millis) {
 			var tid = setTimeout(function() {
 				if (cb) {

lib/util/flows.md

@@ -49,6 +49,19 @@ won't be called, and no other operation will enter the funnel.
 * `results = flows.collect(_, futures)`  
   collects the results of an array of futures
 
+* result = flows.trampoline(_, fn, thisObj)`  
+  Executes `fn(_)` through a trampoline.  
+  Waits for `fn`'s result and returns it.  
+  This is equivalent to calling `fn.call(thisObj, _)` but the current stack is unwound
+  before calling `fn`.
+
 * `flows.nextTick(_)`  
   `nextTick` function for both browser and server.  
   Aliased to `process.nextTick` on the server side.
+
+* `flows.sleep(_, millis)`  
+  Sleeps `millis` ms.  
+
+* `flows.callWithTimeout(_, fn, millis)`  
+  Calls `fn(_)` with a timeout guard.  
+  Throws a timeout exception if `fn` takes more than `millis` ms to complete.