From 72e55e891758db0552b7ddaeff87bf5208bc639c Mon Sep 17 00:00:00 2001 From: Anna Schumaker Date: Sat, 8 Nov 2014 11:55:22 -0500 Subject: [PATCH] idle: Add more detailed documentation Also remove the idle queue section from the DESIGN file. Signed-off-by: Anna Schumaker --- DESIGN | 64 ------------------------------------- include/core/idle.h | 74 ++++++++++++++++++++++--------------------- include/core/idle.hpp | 6 ++-- 3 files changed, 41 insertions(+), 103 deletions(-) diff --git a/DESIGN b/DESIGN index 7881a81d..9cff98cf 100644 --- a/DESIGN +++ b/DESIGN @@ -66,70 +66,6 @@ Callbacks: -Idle queue: - The idle queue is used to schedule function calls that run at a later - time. - - A single queue instance needs to be able to run functions that take - different types of arguments. This is done by creating an IdleBase - base class that the templated IdleTask class inherits from. - -- IdleBase: - class IdleBase { - private: - schedule(); - - public: - IdleBase(); - ~IdleBase(); - virtual void run() = 0; - }; - -- IdleTask: - template - class IdleTask : IdleBase { - private: - void (*func)(T &); - T &data; - - public: - IdleTask(void (*)(T &), T); - void run(); - }; - -- Queue: - queue idle_queue; - float queued = 0.0 - float serviced = 0.0 - -- API: - void IdleBase :: schedule(); - Add the idle task to the idle queue. This should be called - by the IdleTask constructor. - queued++; - - template - static inline void idle :: schedule(void (*)(T &), T); - Create a new IdleTask to run the function later. - - bool idle :: run_task(); - If there are tasks on the queue: - run the next task - scheduled++ - If there are still tasks on the queue: - 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 (and - to avoid a divide-by-zero error). - - - Tag Database: The tag database is actually several databases that describe every track added by the user. I do not expect the artist_db, album_db, diff --git a/include/core/idle.h b/include/core/idle.h index 7067d971..49079cfc 100644 --- a/include/core/idle.h +++ b/include/core/idle.h @@ -6,88 +6,90 @@ #define OCARINA_CORE_IDLE_H /** - * Namespace for controlling idle tasks. + * The idle queue is used to schedule function calls to run at a + * later time. It is expected that a higher layer can determine + * when the application is idle and call idle::run_task() accordingly. + * + * The idle layer keeps a count of the number of tasks added to the queue + * since the last time the queue was empty. Whenever a task is scheduled, + * the "queued" count is incremented by 1. When tasks are run, the "serviced" + * count is incremented by 1. These counters are reset to 0 once the queue + * is empty. */ namespace idle { /** - * Base class for creating new IdleTasks. + * Base class used by the templated IdleTask class. This lets + * us create an idle queue storing IdleBase pointers to get + * around potential templating issues. */ class IdleBase { protected: /** - * Add the IdleBase to the idle queue. + * Adds the IdleBase to the idle queue and increments + * the "queued" counter by 1. */ void schedule(); public: - /** - * Constructor for the IdleBase class. - */ - IdleBase(); - - /** - * IdleBase destructor. - */ - virtual ~IdleBase(); - - /** - * Run the idle task. - */ - virtual void run() = 0; + IdleBase(); /**< IdleBase constructor. */ + virtual ~IdleBase(); /**< IdleBase destructor. */ + virtual void run() = 0; /**< Run the idle task. */ }; /** - * Generic IdleTask class. + * Generic IdleTask class. This class is templated to allow + * for scheduling functions that take different types of data + * parameters. */ template class IdleTask : public IdleBase { private: - void (*func)(T &); - T data; + void (*_func)(T &); /**< Function to call when run. */ + T _data; /**< Data to pass to the function. */ public: /** * IdleTask constructor. + * * @param func Function to call when running this task. * @param data Data to pass to the function. */ IdleTask(void (*)(T &), T); - /** - * IdleTask destructor. - */ - ~IdleTask(); - - /** - * Run the IdleTask. - */ - void run(); + ~IdleTask(); /**< IdleTask destructor. */ + void run(); /**< Call func(), passing data as the argument. */ }; /** - * Create a new IdleTask and add it to the queue. + * Creates a new IdleTask and adds it to the queue. + * * @param func Function to call when running the new task. * @param data Data to pass to the function. */ template - static inline void schedule(void (*func)(T &), T param) + static inline void schedule(void (*func)(T &), T data) { - new IdleTask(func, param); + new IdleTask(func, data); } /** - * Run the next task on the idle queue. - * @return True if there are still tracks on the queue, false otherwise. + * Run the next task on the idle queue and increment the "serviced" + * counter. If this was the last task then the "queued" and + * "serviced" values are reset to 0. + * + * @return True if there are still tasks on the queue, false otherwise. */ bool run_task(); /** - * Call to find the progress of the idle queue. - * @return A fraction representing the idle queue progress. + * Use the values of the queued and serviced counters to find the + * overall process of the idle queue (serviced / queued). + * + * @return The percentage of IdleTasks that have been run. */ float get_progress(); diff --git a/include/core/idle.hpp b/include/core/idle.hpp index 5fc466eb..59cc2f61 100644 --- a/include/core/idle.hpp +++ b/include/core/idle.hpp @@ -9,8 +9,8 @@ #define OCARINA_IDLE_HPP template -idle :: IdleTask :: IdleTask(void (*fn)(T &), T param) - : func(fn), data(param) +idle :: IdleTask :: IdleTask(void (*func)(T &), T data) + : _func(func), _data(data) { IdleBase :: schedule(); } @@ -23,7 +23,7 @@ idle :: IdleTask :: ~IdleTask() template void idle :: IdleTask :: run() { - func(data); + _func(_data); } #endif /* OCARINA_IDLE_HPP */