From 5d996e5d420e69f6f4016de78598c287db708b5f Mon Sep 17 00:00:00 2001
From: "Alex A. Naanou" <alex.nanou@gmail.com>
Date: Thu, 11 Jul 2013 03:55:53 +0400
Subject: [PATCH] makeDeferredQ(...) now done, tested and documented...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
---
 ui/compatibility.js | 54 +++++++++++----------------------------------
 ui/lib/jli.js       | 44 +++++++++++++++++++++++++++++++-----
 2 files changed, 52 insertions(+), 46 deletions(-)

diff --git a/ui/compatibility.js b/ui/compatibility.js
index e5f8cd95..6ef19ac3 100755
--- a/ui/compatibility.js
+++ b/ui/compatibility.js
@@ -364,56 +364,28 @@ if(window.CEF_dumpJSON != null){
 	window._PREVIW_CREATE_QUEUE = null
 	// Queued version of makeImagesPreviews(...)
 	//
-	// XXX make a generic deferred queue...
-	// XXX is this robust enough???
-	// 		of one deferred hangs or breaks without finalizing this will 
-	// 		stall the whole queue...
-	// 		...need a way to jumpstart it again...
 	// XXX check if we are leaking the tail...
-	// XXX test progress...
-	// 		...gets collected but the structure is a tad too complex...
-	// 		- should we make it flat???
-	//		- do we need all that data????
 	// NOTE: this will remove the old deferred if it us resolved, thus
 	// 		clearing the "log" of previous operations, unless keep_log
 	// 		is set to true...
-	// XXX need a way to cancel this...
-	window.makeImagesPreviewsQ = function(gids, sizes, mode, keep_log){
+	window.makeImagesPreviewsQ = function(gids, sizes, mode){
 		gids = gids == null ? getClosestGIDs() : gids
-		var previews = []
 
-		$.each(gids, function(i, e){
-			var deferred = $.Deferred()
+		// attach the the previous queue...
+		if(_PREVIW_CREATE_QUEUE == null){
+			var queue = makeDeferredsQ()
+			_PREVIW_CREATE_QUEUE = queue.start()
+		} else {
+			var queue = _PREVIW_CREATE_QUEUE
+		}
 
-			var last = previews[previews.length-1]
-
-			// first in this set -- attach to the queue...
-			if(last == null){
-				if(_PREVIW_CREATE_QUEUE == null
-						|| (!keep_log && _PREVIW_CREATE_QUEUE.state() == 'resolved')){
-					// if nothing in queue, start at once...
-					last = $.Deferred().resolve()
-				} else {
-					last = _PREVIW_CREATE_QUEUE
-				}
-			}
-
-			// append to deffered queue...
-			last.always(function(){
-				makeImagePreviews(e, sizes, mode)
-					.progress(function(state){
-						deferred.notify(state)
-					})
-					.always(function(){
-						deferred.resolve()
-					})
-			})
-
-			previews.push(deferred)
+		$.each(gids, function(_, gid){
+			queue.enqueue(makeImagePreviews, gid, sizes, mode)
+				//.progress(function(state){ queue.notify(state) })
+				.always(function(){ queue.notify(gid, 'done') })
 		})
 
-		_PREVIW_CREATE_QUEUE = $.when.apply(null, previews)
-		return _PREVIW_CREATE_QUEUE
+		return queue
 	}
 
 	window.makeImageGID = function(source, make_text_gid){
diff --git a/ui/lib/jli.js b/ui/lib/jli.js
index a50ad1b5..1c1aca5b 100755
--- a/ui/lib/jli.js
+++ b/ui/lib/jli.js
@@ -678,11 +678,38 @@ function assyncCall(func){
 }
 
 
-// XXX needs more docs...
-// XXX needs a better public inteface...
-function makeDeferredsQ(){
+// Deferred worker queue
+//
+// This will either create a new queue or attach to the tail of an 
+// existing queue (deferred) if given.
+//
+// This will return a deferred object with several extensions:
+//
+// 		.enqueue(worker, ...)
+// 			Add a worker to the queue.
+// 			A worker is executed when the previous worker is resolved.
+// 			A worker must return a deferred.
+//
+// 		.start()
+// 			Start the first worker.
+//
+// 		.kill()
+// 			Stop the queue, preventing any new workers from starting.
+// 			NOTE: this will not kill the currently running worker.
+//
+// 		.isWorking()
+// 			will return true if there is at least one worker still not
+// 			resolved, false otherwise.
+// 			NOTE: if the queue is killed, this will always return false.
+//
+//
+// NOTE: one queue is guaranteed to work in a sequence, to run several 
+// 		pipelines in parallel use two or more queues.
+// NOTE: running queues in parallel depends on the actual context in
+// 		use (browser/node.js/...).
+function makeDeferredsQ(first){
+	first = first == null ? $.Deferred() : first
 
-	var first = $.Deferred()
 	var last = first
 
 	// this is used for two things:
@@ -735,7 +762,14 @@ function makeDeferredsQ(){
 		this.resolve()
 		return this
 	}
-
+	// XXX make this a propper state, or integrate into the deferred in 
+	// 		a more natural way...
+	monitor.isWorking = function(){
+		if(monitor.state() != 'resolved' && last.state() != 'resolved'){
+			return true
+		}
+		return false
+	}
 
 	return monitor
 }