idle: Add more detailed documentation
Also remove the idle queue section from the DESIGN file. Signed-off-by: Anna Schumaker <Anna@OcarinaProject.net>
This commit is contained in:
parent
2a65fe8db0
commit
72e55e8917
64
DESIGN
64
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 T>
|
|
||||||
class IdleTask : IdleBase {
|
|
||||||
private:
|
|
||||||
void (*func)(T &);
|
|
||||||
T &data;
|
|
||||||
|
|
||||||
public:
|
|
||||||
IdleTask(void (*)(T &), T);
|
|
||||||
void run();
|
|
||||||
};
|
|
||||||
|
|
||||||
- Queue:
|
|
||||||
queue<IdleBase *> 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 <class T>
|
|
||||||
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:
|
Tag Database:
|
||||||
The tag database is actually several databases that describe every
|
The tag database is actually several databases that describe every
|
||||||
track added by the user. I do not expect the artist_db, album_db,
|
track added by the user. I do not expect the artist_db, album_db,
|
||||||
|
|
|
@ -6,88 +6,90 @@
|
||||||
#define OCARINA_CORE_IDLE_H
|
#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
|
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 {
|
class IdleBase {
|
||||||
protected:
|
protected:
|
||||||
/**
|
/**
|
||||||
* Add the IdleBase to the idle queue.
|
* Adds the IdleBase to the idle queue and increments
|
||||||
|
* the "queued" counter by 1.
|
||||||
*/
|
*/
|
||||||
void schedule();
|
void schedule();
|
||||||
|
|
||||||
public:
|
public:
|
||||||
/**
|
IdleBase(); /**< IdleBase constructor. */
|
||||||
* Constructor for the IdleBase class.
|
virtual ~IdleBase(); /**< IdleBase destructor. */
|
||||||
*/
|
virtual void run() = 0; /**< Run the idle task. */
|
||||||
IdleBase();
|
|
||||||
|
|
||||||
/**
|
|
||||||
* IdleBase destructor.
|
|
||||||
*/
|
|
||||||
virtual ~IdleBase();
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Run the idle task.
|
|
||||||
*/
|
|
||||||
virtual void run() = 0;
|
|
||||||
};
|
};
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Generic IdleTask class.
|
* Generic IdleTask class. This class is templated to allow
|
||||||
|
* for scheduling functions that take different types of data
|
||||||
|
* parameters.
|
||||||
*/
|
*/
|
||||||
template <class T>
|
template <class T>
|
||||||
class IdleTask : public IdleBase {
|
class IdleTask : public IdleBase {
|
||||||
private:
|
private:
|
||||||
void (*func)(T &);
|
void (*_func)(T &); /**< Function to call when run. */
|
||||||
T data;
|
T _data; /**< Data to pass to the function. */
|
||||||
|
|
||||||
public:
|
public:
|
||||||
/**
|
/**
|
||||||
* IdleTask constructor.
|
* IdleTask constructor.
|
||||||
|
*
|
||||||
* @param func Function to call when running this task.
|
* @param func Function to call when running this task.
|
||||||
* @param data Data to pass to the function.
|
* @param data Data to pass to the function.
|
||||||
*/
|
*/
|
||||||
IdleTask(void (*)(T &), T);
|
IdleTask(void (*)(T &), T);
|
||||||
|
|
||||||
/**
|
~IdleTask(); /**< IdleTask destructor. */
|
||||||
* IdleTask destructor.
|
void run(); /**< Call func(), passing data as the argument. */
|
||||||
*/
|
|
||||||
~IdleTask();
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Run the IdleTask.
|
|
||||||
*/
|
|
||||||
void run();
|
|
||||||
};
|
};
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 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 func Function to call when running the new task.
|
||||||
* @param data Data to pass to the function.
|
* @param data Data to pass to the function.
|
||||||
*/
|
*/
|
||||||
template <class T>
|
template <class T>
|
||||||
static inline void schedule(void (*func)(T &), T param)
|
static inline void schedule(void (*func)(T &), T data)
|
||||||
{
|
{
|
||||||
new IdleTask<T>(func, param);
|
new IdleTask<T>(func, data);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Run the next task on the idle queue.
|
* Run the next task on the idle queue and increment the "serviced"
|
||||||
* @return True if there are still tracks on the queue, false otherwise.
|
* 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();
|
bool run_task();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Call to find the progress of the idle queue.
|
* Use the values of the queued and serviced counters to find the
|
||||||
* @return A fraction representing the idle queue progress.
|
* overall process of the idle queue (serviced / queued).
|
||||||
|
*
|
||||||
|
* @return The percentage of IdleTasks that have been run.
|
||||||
*/
|
*/
|
||||||
float get_progress();
|
float get_progress();
|
||||||
|
|
||||||
|
|
|
@ -9,8 +9,8 @@
|
||||||
#define OCARINA_IDLE_HPP
|
#define OCARINA_IDLE_HPP
|
||||||
|
|
||||||
template <class T>
|
template <class T>
|
||||||
idle :: IdleTask<T> :: IdleTask(void (*fn)(T &), T param)
|
idle :: IdleTask<T> :: IdleTask(void (*func)(T &), T data)
|
||||||
: func(fn), data(param)
|
: _func(func), _data(data)
|
||||||
{
|
{
|
||||||
IdleBase :: schedule();
|
IdleBase :: schedule();
|
||||||
}
|
}
|
||||||
|
@ -23,7 +23,7 @@ idle :: IdleTask<T> :: ~IdleTask()
|
||||||
template <class T>
|
template <class T>
|
||||||
void idle :: IdleTask<T> :: run()
|
void idle :: IdleTask<T> :: run()
|
||||||
{
|
{
|
||||||
func(data);
|
_func(_data);
|
||||||
}
|
}
|
||||||
|
|
||||||
#endif /* OCARINA_IDLE_HPP */
|
#endif /* OCARINA_IDLE_HPP */
|
||||||
|
|
Loading…
Reference in New Issue