# SoftBank Robotics documentation What's new in NAOqi 2.8?

# 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`.

## Summary

Global Classes

- class qi::PeriodicTask

  Functions (class qi::PeriodicTask)

  qi::PeriodicTask::compensateCallbackTime

  qi::PeriodicTask::~PeriodicTask

  qi::PeriodicTask::PeriodicTask

  qi::PeriodicTask::trigger

  qi::PeriodicTask::setPeriod

  qi::PeriodicTask::setUsPeriod

  qi::PeriodicTask::stop

  qi::PeriodicTask::asyncStop

  qi::PeriodicTask::isRunning

  qi::PeriodicTask::setName

  qi::PeriodicTask::isStopping

  qi::PeriodicTask::setStrand

  qi::PeriodicTask::start

  qi::PeriodicTask::setCallback

## 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

template<typename T>
auto ``setCallback``(T&& cb)
template<typename T>
auto ``setCallback``(T&& cb)
template<typename AF, typename ARG0, typename... ARGS>
````()
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.

#### Detailed Description

Control a task executed periodically and asynchronously. .

#### Function Documentation

template<typename T>
auto `qi::PeriodicTask::``setCallback`(T&& cb)

template<typename T>
auto `qi::PeriodicTask::``setCallback`(T&& cb)

`()`

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. If you call this function from within the callback, it will be taken into account 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.

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.

Glossary Site map Index Support Contact Legal Notices