SoftBank Robotics documentation What's new in NAOqi 2.5?

qi::Application

Application takes care of the initialisation and termination of the program.

Detailed Description

Application is meant to be instantiated in the main function. It provides a run function that keeps the application running until the user asks for termination (usually through CTRL-C), which is useful when implementing a service.

Application‘s destructor blocks until there is no more work scheduled in the eventloop and all sockets are closed.

It also parses arguments, see qi application arguments.

See also

You rarely need to use this class, see ApplicationSession.

Usage Example

#include <qi/application.hpp>

int main(int argc, char* argv[])
{
  qi::Application app(argc, argv);

  // do things

  app.run();
}

Reference

qi::Application Class Reference

Introduction

Class handling startup and teardown of an application. More...

#include <qi/application.hpp>

Public Functions

Application(int& argc, char**& argv, const std::string& name, const std::string& path)
Application(const std::string& name, int& argc, char**& argv)
~Application()

Public Static Functions

void run()
void stop()
const std::vector<std::string>& arguments()
int argc()
const char** argv()
void setName(const std::string& name)
std::string name()
void setArguments(int argc, char** argv)
void setArguments(const std::vector<std::string>& arguments)
void* loadModule(const std::string& name, int flags)
void unloadModule(void* handle)
bool terminated()
bool initialized()
const char* program()
const char* realProgram()
const char* _suggestedSdkPath()
bool atEnter(std::function<void()> func)
bool atExit(std::function<void()> func)
bool atRun(std::function<void()> func)
bool atStop(std::function<void()> func)
bool atSignal(std::function<void(int)> func, int signal)

Detailed Description

The qi::Application class is designed to ease startup and teardown of an executable.

All executables using qi classes should create an instance of qi::Application on the stack of the main() function.

Function Documentation

static void qi::Application::run()

Wait until one of those conditions becomes true: - stop() is called. - TERM or QUIT signal is received. - the Application instance is destroyed, which means main() is exiting.

Run can be called by multiple threads simultaneously.

static void qi::Application::stop()

Stop the application. Call all atStop handlers.

static const std::vector<std::string>& qi::Application::arguments()

Brief: Get arguments of the program as an std::vector of std::string.

Returns:List of arguments of the program.
static int qi::Application::argc()

Brief: Get argument counter of the program.

Returns:Argument counter of the program if Application was initialized, -1 otherwise.
static const char** qi::Application::argv()

Brief: Get string arguments of the program (including program name).

Returns:Arguments of the program if Application was initialized, 0 otherwise.
static void qi::Application::setName(const std::string& name)

Brief: Set application name.

Parameters:
  • name – The application’s name.
static std::string qi::Application::name()

Brief: Get application name.

Returns:A string with the application name, empty string if setName isn’t call.
static void qi::Application::setArguments(int argc, char** argv)

Brief: Set arguments of the program with argc as argument counter and argv as argument values.

Parameters:
  • argc – Argument counter of the program.
  • argv – Arguments of the program (given to main).
static void qi::Application::setArguments(const std::vector<std::string>& arguments)

Brief: Set arguments ot the program as an std::vector of std::string.

Parameters:
  • arguments – Sets arguments with a vector of strings.
static void* qi::Application::loadModule(const std::string& name, int flags = -1)

Brief: Load a module into the current process.

Parameters:
  • name – The module path and name. If no extension is used, the correct extension for a library on the current platform is used.
  • flags – Extra flags to pass to the dlopen function.
Returns:

A handle, to be used by qi::os::dlsym() or unloadModule().

The module can execute code when loaded by using QI_AT_ENTER.

static void qi::Application::unloadModule(void* handle)

Brief: Unload a module from the current process.

Parameters:
  • handle – Handle on the loaded module.
static bool qi::Application::terminated()

Brief: Check whether the Application instance is terminated or not.

Returns:True if it is stop, false otherwise.
static bool qi::Application::initialized()

Brief: Check whether the Application instance was initialized or not.

Returns:True if it was initialized, false otherwise.
static const char* qi::Application::program()

Brief: Return the current program full path according to argv[0].

Returns:full path to the current running program, symbolic links are not resolved.
static const char* qi::Application::realProgram()

Brief: Return the current program full path.

Returns:full path to the current running program, symbolic links are resolved.

When using this function from a Python application for example on gentoo, it will return something like /usr/bin/python2.7 (because python is a symlink to python-wrapper which will exec() /usr/bin/python2.7). On the other hand, program() will return the full path to the script run by the Python interpreter.

Computed using specific OS API:

  • Apple : _NSGetExecutablePath
  • Linux : reading “/proc/self/exe”
  • Windows: GetModuleFileName

If the former API fail it will try to guess the value from argv[0]. For this method to work qi::Application(int&, char**&) should have been called in your main().

static const char* qi::Application::_suggestedSdkPath()

Used internally, you should not need this.

static bool qi::Application::atEnter(std::function<void()> func)

Brief: Register a function to be executed at Application creation.

Parameters:
  • func – Callback function at Application creation.
Returns:

True if registering succeeded, false otherwise.

static bool qi::Application::atExit(std::function<void()> func)

Brief: Register a function to be executed at Application destruction.

Parameters:
  • func – Callback function called at Application destruction.
Returns:

True if registering succeeded, false otherwise.

static bool qi::Application::atRun(std::function<void()> func)

Brief: Register a function to be executed when run() is called. The functions are executed sequentially at the beginning of run().

Parameters:
  • func – Callback function called when stop() is called.
Returns:

True if registering succeeded, false otherwise.

static bool qi::Application::atStop(std::function<void()> func)

Brief: Register a function to be executed when stop() is called. The functions are executed sequentially before run() returns.

Parameters:
  • func – Callback function called when stop() is called.
Returns:

True if registering succeeded, false otherwise.

static bool qi::Application::atSignal(std::function<void(int)> func, int signal)

Brief: Register a function to be executed when a signal occurs.

Parameters:
  • func – Callback function called on signal.
  • signal – Signal number.
Returns:

True if registering succeeded, false otherwise.

The handler is executed in a thread, not from within the signal handler, so there is no restriction on what can be done by your handler function, except that it should return reasonably quickly.

qi::Application::Application(int& argc, char**& argv, const std::string& name = "", const std::string& path = "")

Brief: Application constructor. Must be the first thing called by main().

Parameters:
  • argc – Argument counter of the program.
  • argv – Arguments of the program (given to main).
  • name – The name of the program. It will be returned by name().
  • path – The full path to the program if you wish to override it. It will be returned by program() but not realProgram().
qi::Application::Application(const std::string& name, int& argc, char**& argv)

Brief: Application constructor. Must be the first thing called by main().

Parameters:
  • name – Name of the application.
  • argc – Argument counter of the program.
  • argv – Arguments of the program (given to main).

DeprecatedUse Application(int&, char**&, const std::string&, const std::string&)

qi::Application::~Application()
QI_AT_ENTER(func)

func

The handler that must be called at enter.

QI_AT_EXIT(func)

func

The handler that must be called at exit.