From 1cfd9588f94508ae211e0e4b97a7c661c7c4c60d Mon Sep 17 00:00:00 2001
From: Anna Schumaker <schumaker.anna@gmail.com>
Date: Wed, 7 Aug 2013 21:21:13 -0400
Subject: [PATCH] design: Update idle queue design

I need a way to return the progress of the idle queue and to indicate
when it is out of tasks so idle threads can stop running.

Signed-off-by: Anna Schumaker <schumaker.anna@gmail.com>
---
 design.txt      | 26 +++++++++++++++++++-------
 design/idle.txt | 26 +++++++++++++++++++-------
 2 files changed, 38 insertions(+), 14 deletions(-)

diff --git a/design.txt b/design.txt
index 5e7d396d..f0907a22 100644
--- a/design.txt
+++ b/design.txt
@@ -36,6 +36,7 @@ Files:
 		filter.h
 		groups.h
 		idle.h
+		idle.hpp
 		index.h
 		library.h
 		playlist.h
@@ -214,7 +215,7 @@ On-disk files: (lib/file.cpp)
 Idle queue: (lib/idle.cpp)
 	The idle queue is used to schedule tasks to run at a later time.  Idle
 	tasks must inherit from the IdleBase class so that multiple templated
-	types can be placed on the same idle queue.
+	IdleTask pointers can be placed on the same idle queue.
 
 - IdleBase:
 	class IdleBase {
@@ -236,19 +237,30 @@ Idle queue: (lib/idle.cpp)
 	};
 
 - Queue:
-	deque(IdleTask *> idle_queue;
+	deque(IdleBase *> idle_queue;
 	float queued = 0.0
 	float serviced = 0.0
 
 - API:
 	template <class T>
 	void idle :: schedule(void (*)(T *), T *);
-		Schedule a function to run later.
-		queued++
+		Schedule a function to run later (queued++).  This should
+		be written in the idle.hpp file since it is a function
+		template.
+
 	bool idle :: run_task()
-		Run the next task on the queue.  Return true if a task was
-		found, and false otherwise.
-		scheduled++, reset to zero if idle queue is empty.
+		If there are tasks on the queue:
+			run the next task
+			scheduled++
+			return true
+		else:
+			queued = 0
+			scheduled = 0
+			return false
+
+	float idle :: get_progress()
+		Return (serviced / queued) to the caller.  If there are no
+		tasks, return 1.0 to indicate that the queue is finished.
 
 
 
diff --git a/design/idle.txt b/design/idle.txt
index 8d4bad6a..33aceb34 100644
--- a/design/idle.txt
+++ b/design/idle.txt
@@ -1,6 +1,7 @@
 == Files ==
 	ocarina/include/
 		idle.h
+		idle.hpp
 	ocarina/lib/
 		idle.cpp
 
@@ -10,7 +11,7 @@ version print
 Idle queue: (lib/idle.cpp)
 	The idle queue is used to schedule tasks to run at a later time.  Idle
 	tasks must inherit from the IdleBase class so that multiple templated
-	types can be placed on the same idle queue.
+	IdleTask pointers can be placed on the same idle queue.
 
 - IdleBase:
 	class IdleBase {
@@ -32,16 +33,27 @@ Idle queue: (lib/idle.cpp)
 	};
 
 - Queue:
-	deque(IdleTask *> idle_queue;
+	deque(IdleBase *> idle_queue;
 	float queued = 0.0
 	float serviced = 0.0
 
 - API:
 	template <class T>
 	void idle :: schedule(void (*)(T *), T *);
-		Schedule a function to run later.
-		queued++
+		Schedule a function to run later (queued++).  This should
+		be written in the idle.hpp file since it is a function
+		template.
+
 	bool idle :: run_task()
-		Run the next task on the queue.  Return true if a task was
-		found, and false otherwise.
-		scheduled++, reset to zero if idle queue is empty.
+		If there are tasks on the queue:
+			run the next task
+			scheduled++
+			return true
+		else:
+			queued = 0
+			scheduled = 0
+			return false
+
+	float idle :: get_progress()
+		Return (serviced / queued) to the caller.  If there are no
+		tasks, return 1.0 to indicate that the queue is finished.