qi::Application

On this page

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 )
boost::program_options::options_description& options ( )
std::string helpText ( )

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.

static boost::program_options::options_description& qi::Application:: options ( )

Brief: Get the registered global program options.

Returns: The options_description of the currently added program options.
static std::string qi::Application:: helpText ( )

Brief:

Returns: Get the help text displayed when the –help option is used.
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.