SoftBank Robotics documentation What's new in NAOqi 2.5?

qi::EventLoop

Provide an eventloop based on boost::asio.

Detailed Description

This eventloop consists of a threadpool of boost::asio threads waiting for work. You can schedule work using async or using the io_service directly (to do asynchronous operations on sockets for example). Most basic usages are described in asynchronous operations.

Good use of a threadpool

It is often needed to schedule asynchronous work so that multiple work can be done in parallel. One way to do such a thing is to spawn a thread for the task and have the thread quit when the task is finished. It is bad practice to do such things. Spawning and exiting threads is costly in performance and must be avoided.

A threadpool starts a bunch of threads at its initialization and allows one to schedule short tasks on it, this avoids thread creations/destructions.

Blocking threads

It is not recommended to schedule large tasks in the threadpool (like image or sound processing) since it will block a thread and be unfair to other users. Such tasks should be scheduled on separate threads (which should of course not be created/destroyed each time there is work to do) synchronized with mutexes and condition variables.

Additionally, an asynchronous task should not lock long-held mutexes or do blocking calls. Every time a task does that, a thread of the threadpool is blocked an no more work can be scheduled on it until the task finishes.

Threadpool Monitoring

The threadpool is constantly monitored by an external thread to check if it is full (or deadlocked). The thread schedules a “ping” every 0.5 second and waits for the “pong” for 0.5 second. If it times out, a new thread is spawned until the maximum is reached. If 20 timeouts happen in a row, the emergency callback is called (which may abort execution since a deadlock is likely to have occurred).

Customizing the Threadpool Behavior

You can control how the threadpool behaves through environment variables.

  • QI_EVENTLOOP_THREAD_COUNT: number of threads the eventloop should start with. By default, it will start with one thread per CPU. This is overridden by calling qi::startEventLoop explicitly.
  • QI_EVENTLOOP_MAX_THREADS: maximum number of threads that the threadpool can have.
  • QI_EVENTLOOP_GRACE_PERIOD: time in ms to wait after a failed ping, defaults to 0.
  • QI_EVENTLOOP_PING_TIMEOUT: time in ms to wait for a ping response before considering it failed, defaults to 500.
  • QI_EVENTLOOP_MAX_TIMEOUTS: number of timeouts before calling the emergency callback, defaults to 20.

Reference

qi::EventLoop Class Reference

Introduction

Class to handle eventloop. . More...

#include <qi/eventloop.hpp>
  • Inherits: qi::ExecutionContext

Public Functions

template<typename R>
Future<R> async(const boost::function<R()>& callback, uint64_t usDelay)
Future<void> async(const boost::function<void()>& callback, uint64_t usDelay)
Future<void> async(const boost::function<void()>& callback, qi::Duration delay)
Future<void> async(const boost::function<void()>& callback, qi::SteadyClockTimePoint timepoint)
EventLoop(const std::string& name)
~EventLoop()
bool isInThisContext()
void start(int nthreads)
void join()
void stop()
void setEmergencyCallback(boost::function<void()> cb)
void setMaxThreads(unsigned int max)
void* nativeHandle()
void post(const boost::function<void()>& callback, uint64_t usDelay)
void post(const boost::function<void()>& callback, qi::Duration delay)
void post(const boost::function<void()>& callback, qi::SteadyClockTimePoint timepoint)
Future<void> monitorEventLoop(EventLoop* helper, uint64_t maxUsDelay)

Detailed Description

Class to handle eventloop. .

Function Documentation

template<typename R>

Brief: Call given function once after given delay in microseconds.

Parameters:
  • callback -- Callback to be called.
  • usDelay -- Delay before call the callback in microsecond.
Returns:

A canceleable future.

Future<R> qi::EventLoop::async(const boost::function<R()>& callback, uint64_t usDelay)

Deprecateduse qi::async with qi::Duration

Future<void> qi::EventLoop::async(const boost::function<void()>& callback, uint64_t usDelay)
Future<void> qi::EventLoop::async(const boost::function<void()>& callback, qi::Duration delay)

call a callback asynchronously to be executed in delay Deprecatedsince 2.5

Future<void> qi::EventLoop::async(const boost::function<void()>& callback, qi::SteadyClockTimePoint timepoint)

call a callback asynchronously to be executed on tp Deprecatedsince 2.5

qi::EventLoop::EventLoop(const std::string& name = "eventloop")

Brief: Create a new eventLoop.

Parameters:
  • name – Name of the event loop created.

You must then call either start(), run() or startThreadPool() to start event processing.

qi::EventLoop::~EventLoop()

Default destructor.

bool qi::EventLoop::isInThisContext()

Brief: Check if current thread is the event loop thread.

Returns:true if current thread is the event loop thread.
void qi::EventLoop::start(int nthreads = 0)

Brief: Start the eventloop in threaded mode.

Parameters:
  • nthreads – Numbers of threads.
void qi::EventLoop::join()

Wait for run thread to terminate.

void qi::EventLoop::stop()

Ask main loop to terminate.

void qi::EventLoop::setEmergencyCallback(boost::function<void()> cb)

Brief: Set callback to be called in case of a deadlock detection.

Parameters:
  • cb – Callback to be called.
void qi::EventLoop::setMaxThreads(unsigned int max)

Brief: Set the maximum number of threads in the pool.

Parameters:
  • max – Maximum number of threads.
void* qi::EventLoop::nativeHandle()

Internal function.

void qi::EventLoop::post(const boost::function<void()>& callback, uint64_t usDelay)

Brief: Similar to async() but without cancelation or notification.

Parameters:
  • callback – Callback to be called.
  • usDelay – Delay before call the callback in microsecond.
void qi::EventLoop::post(const boost::function<void()>& callback, qi::Duration delay)
void qi::EventLoop::post(const boost::function<void()>& callback, qi::SteadyClockTimePoint timepoint)
Future<void> qi::EventLoop::monitorEventLoop(EventLoop* helper, uint64_t maxUsDelay)

Brief: Monitor event loop to detect deadlocks.

Parameters:
  • helper – an other event loop used for monitoring.
  • maxUsDelay – maximum expected delay between an async() and its execution.
Returns:

A canceleable future. Invoke cancel() to terminate monitoring. In case an async() call does not execute in time, the future’s error will be set.

EventLoop* qi::getEventLoop()

Return the global eventloop, created on demand on first call.

void qi::startEventLoop(int nthread)

Brief: Start the eventloop with nthread threads. No-op if already started.

Parameters:
  • nthread – Set the minimum number of worker threads in the pool.
boost::asio::io_service& qi::getIoService()

Brief: Get the io_service used by the global event loop.

Returns:io_service used by the global event loop.
template<typename R>
Future<R> qi::async(boost::function<R()> callback, uint64_t usDelay)

Deprecateduse qi::async with qi::Duration

template<typename R>
Future<R> qi::async(boost::function<R()> callback, qi::Duration delay)
template<typename R>
Future<R> qi::async(boost::function<R()> callback, qi::SteadyClockTimePoint timepoint)