Aldebaran documentation What's new in NAOqi 2.4.3?

qi::PeriodicTask

qimessaging provides numerous ways of doing async operations, but sometimes you need an async operation which repeats itself. This is what you can do with qi::PeriodicTask.

Detailed Description

Using a periodic task

#include <qi/periodictask.hpp>

void printDate();

qi::PeriodicTask task;
task.setName("print date");
task.setUsPeriod(1000*1000);
task.setCallback(printDate);
task.start();

// and at the end
task.stop();

This will create a task which will call printDate every second. The name of the task is not used yet, but may be useful to provide debug information later. start() will call the task immediately (unless given false as argument) and call it again every second.

In all cases, PeriodicTask never gives hard time guaranties (like realtime). If there is a lot of work in the event loop, your task may be called later than expected.

However, PeriodicTask guaranties you that it will never call your callback twice at the same time, even if it missed it’s deadline. Also, when you call stop, it will block until the callback is finished if it’s currently running.

About scheduling and callback time compensation

Sometime, your callback may be slow and you may wonder what happens in these cases.

Here is a simple task with a 5s period and a 3s callback:

v                                v
+-----------+                    +-----------
+  Task 3s  +      wait 5s       +  Task 3s  ...
+-----------+--------------------+-----------

Same thing with callback compensation enabled:

v                     v
+-----------+         +-----------
+  Task 3s  + wait 2s +  Task 3s  ...
+-----------+---------+-----------

Same thing again with a slower task:

v                            v
+----------------------------+---------------------------+----
+         Task 7s            +         Task 7s           +  ...
+----------------------------+---------------------------+----

The task will never be called twice even if it takes longer than the period.

Note that it is not recommended to use a periodic task with slow tasks (as other qimessaging’s async methods).

Reference

qi::PeriodicTask Class Reference

Introduction

Control a task executed periodically and asynchronously. . More...

#include <qi/periodictask.hpp>
  • Inherits: noncopyable

Public Functions

void setCallback(const Callback& cb)
template<typename T, typename ARG0>
PeriodicTask& setCallback(const T& callable, ARG0 tracked, ...)
void setStrand(qi::Strand* strand)
void setUsPeriod(qi::int64_t usPeriod)
void setPeriod(qi::Duration period)
void start(bool immediate)
void trigger()
void stop()
void asyncStop()
void compensateCallbackTime(bool compensate)
void setName(const std::string& name)
bool isRunning() const
bool isStopping() const
PeriodicTask()
~PeriodicTask()

Types

typedef boost::function< void()> Callback
Callback is a boost::function.
typedef boost::function< qi::Future< void > const Callback &, qi::Duration delay)> ScheduleCallback

Detailed Description

Control a task executed periodically and asynchronously. .

Function Documentation

void qi::PeriodicTask::setCallback(const Callback& cb)

One of the setCallback() functions below must be called before any other operation. Once set the callback cannot be changed. If the callback throws, async task will be stopped

template<typename T, typename ARG0>
PeriodicTask& qi::PeriodicTask::setCallback(const T& callable, ARG0 tracked, ...)
void qi::PeriodicTask::setStrand(qi::Strand* strand)

Set the strand on which to schedule the calls

void qi::PeriodicTask::setUsPeriod(qi::int64_t usPeriod)

Deprecatedsince 2.3. Use setPeriod.

void qi::PeriodicTask::setPeriod(qi::Duration period)

Brief: Set the call interval.

Parameters:
  • period – the PeriodicTask period
This call will wait until next callback invocation to apply the change. Use: task.stop(); task.setPeriod(qi::MilliSeconds(10)) task.start() to apply the change immediately.
void qi::PeriodicTask::start(bool immediate = true)

Brief: Start the periodic task at specified period.

Parameters:
  • immediate – if true, first schedule of the task will happen with no delay.

No effect if already running. No effect if called from within the callback.

void qi::PeriodicTask::trigger()

Trigger a started periodic task to run right now. Does nothing if the periodic task just ran, is running, starting, stopping or stopped. This function is lockfree.

void qi::PeriodicTask::stop()

When this function returns, the callback will not be called anymore. Can be called from within the callback function.

void qi::PeriodicTask::asyncStop()

Request for periodic task to stop asynchronously. Can be safely called from within the callback.

void qi::PeriodicTask::compensateCallbackTime(bool compensate)

If argument is true, call interval will take into account call duration to maintain the period.

void qi::PeriodicTask::setName(const std::string& name)

Brief: Set name for debugging and tracking purpose.

Parameters:
  • name – Name of the periodic task.
bool qi::PeriodicTask::isRunning() const

Brief:

Returns:true if task is running
bool qi::PeriodicTask::isStopping() const

Brief:

Returns:whether state is stopping or stopped

Can be called from within the callback to know if stop() or asyncStop() was called.

qi::PeriodicTask::PeriodicTask()

Default constructor.

qi::PeriodicTask::~PeriodicTask()

Default destructor.