PQRST  1.1
Priority Queue for Running Simple Tasks
Public Member Functions | Protected Member Functions | List of all members
LoopTask Class Referenceabstract

A Task which will automatically reschedule itself after it is run. More...

#include <pqrst.h>

Inheritance diagram for LoopTask:
Inheritance graph
[legend]
Collaboration diagram for LoopTask:
Collaboration graph
[legend]

Public Member Functions

 LoopTask (ms_t cadence, int repeats=-1)
 Construct a looping task. More...
 
ms_t set_cadence (ms_t)
 Set the scheduling cadence. More...
 
int set_repeats (int n)
 Set the repeat-count of the loop. More...
 
ms_t get_cadence (void) const
 Return the interval between loop runs. More...
 
int get_repeats (void) const
 Returns the number of repeats still to do. More...
 
virtual void run (ms_t)=0
 Run a single iteration of the loop. More...
 
- Public Member Functions inherited from Task
 Task ()
 Construct a task. More...
 
virtual ~Task ()
 
virtual void start (ms_t delay)
 Start the task. More...
 
virtual void start (void)
 Start the task immediately. More...
 
ms_t cancel (void)
 Cancel this task. More...
 
ms_t uncancel (void)
 Uncancel a task. More...
 
void run_at (ms_t t, Task *T=nullptr)
 Push a new task onto the queue, due at a given time. More...
 
void run_after (ms_t t, Task *T=nullptr)
 Push a new Task onto the queue, due some (non-negative) interval after the queue's current reference time. More...
 
void run_immediately (Task *T=nullptr)
 Push a task onto the queue, due immediately. More...
 
bool before (const Task *) const
 Impose an ordering on tasks. More...
 
bool set_task_slippy (bool)
 Set a task to be ‘slippy’. More...
 
bool get_task_slippy (void) const
 Determine whether a task is ‘slippy’. More...
 
bool is_enqueued_p (void) const
 Return true if the task is currently scheduled on a queue. More...
 
ms_t ready_after (void) const
 Return the interval until the Task is next ready, relative to the queue reference time. More...
 
void set_priority (unsigned char)
 Set the priority of the task. More...
 
unsigned char get_priority (void) const
 Return the priority of the task. More...
 
void set_duration (ms_t)
 Set the duration of the task. More...
 
ms_t get_duration (void) const
 Return the task's expected duration. More...
 
virtual bool user_task_p (void) const
 True if this is a ‘user task’, as opposed to a maintenance task. More...
 
void set_task_ident (const char *ident_string)
 Set the identification string for a task. More...
 
const char * get_task_ident (void) const
 Retrieve the identification string. More...
 

Protected Member Functions

void run_task (ms_t)
 Run the task, additionally rescheduling it. More...
 
- Protected Member Functions inherited from Task
virtual void signal (int signal, ms_t t)
 Receive a signal. More...
 

Additional Inherited Members

- Static Public Attributes inherited from Task
static const PROGMEM char *const pqrst_version
 Reports the PQRST version and compilation options. More...
 

Detailed Description

A Task which will automatically reschedule itself after it is run.

Constructor & Destructor Documentation

◆ LoopTask()

LoopTask::LoopTask ( ms_t  cadence,
int  repeats = -1 
)

Construct a looping task.

The task is rescheduled to run at the given cadence.

If repeats is positive, then the task is rescheduled only the given number of times; if it is negative, then it is rescheduled indefinitely; and if it is zero, it is never rescheduled, and thus acts the same as a simple Task.

If the cadence is zero, the task is never rescheduled, and thus acts the same as a simple Task.

The task is rescheduled the given interval after the due time; if there is any delay in running the task, then the gap between actual run times may slightly vary from this.

The task is not automatically scheduled. Once created, it must be initially scheduled with Task::start, and it will repeat at the given cadence thereafter.

Note: if the preprocessor constant PQRST_SELF_QUEUE is non-zero, then the constructor takes an additional first argument TaskQueue* (see Task).

Parameters
cadencethe interval in ms between repeats
repeatsthe number of repeats; if negative, repeat indefinitely

Member Function Documentation

◆ get_cadence()

ms_t LoopTask::get_cadence ( void  ) const
inline

Return the interval between loop runs.

Returns
an interval in ms
See also
set_cadence

◆ get_repeats()

int LoopTask::get_repeats ( void  ) const
inline

Returns the number of repeats still to do.

If this is negative, the task is to be repeated indefinitely.

Returns
repeat count
See also
set_repeats

◆ run()

virtual void LoopTask::run ( ms_t  )
pure virtual

Run a single iteration of the loop.

The run may schedule other tasks, but will typically not reschedule itself, since this is handled automatically. If, however, the task has a cadence or repeats of zero, so that it is not automatically rescheduled, then this method may need or want to do so as appropriate.

Implements Task.

Implemented in FunctionTask.

◆ run_task()

void LoopTask::run_task ( ms_t  t)
protectedvirtual

Run the task, additionally rescheduling it.

This method is public so that it can be overridden if necessary in some special circumstance; but that will be unusual, and should probably be done only after examination of the source code.

That said, the following shows how one might dynamically adjust the cadence of a loop task:

void MySpecialLoopTask::run_task(ms_t t)
{
    if (adjust_cadence_this_time()) {
        ms_t orig_cadence = set_cadence(2);
        LoopTask::run_task(t);
        set_cadence(orig_cadence);
    } else {
        LoopTask::run_task(t);
    }
}

Reimplemented from Task.

◆ set_cadence()

ms_t LoopTask::set_cadence ( ms_t  new_cadence)

Set the scheduling cadence.

Setting this to zero stops the loop from being re-scheduled (see also cancel).

Parameters
new_cadencethe new cadence
Returns
the previous cadence

◆ set_repeats()

int LoopTask::set_repeats ( int  new_n)

Set the repeat-count of the loop.

This resets the count; it does not take any account of the number of repeats already executed. The repeat count has the meanings described in the constructor.

Parameters
new_nthe new repeat count
Returns
the previous repeat count
See also
LoopTask::LoopTask

The documentation for this class was generated from the following files: