libqi-api  2.8.7.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Member Functions | Static Public Member Functions | List of all members
qi::Application Class Reference

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

#include <application.hpp>

Public Member Functions

 Application (int &argc, char **&argv, const std::string &name="", const std::string &path="")
 Application constructor. Must be the first thing called by main(). More...
 
 Application (const std::string &name, int &argc, char **&argv)
 Application constructor. Must be the first thing called by main(). More...
 
 ~Application ()
 Application destructor. It executes atExit() callbacks. More...
 
 Application (const Application &)=delete
 
Applicationoperator= (const Application &)=delete
 

Static Public Member Functions

static void run ()
 Wait until the end of the program. More...
 
static void stop ()
 Stop the application. Call all atStop handlers. More...
 
static const std::vector
< std::string > & 
arguments ()
 Get arguments of the program as an std::vector of std::string. More...
 
static int argc ()
 Get argument counter of the program. More...
 
static const char ** argv ()
 Get string arguments of the program (including program name). More...
 
static void setName (const std::string &name)
 Set application name. More...
 
static std::string name ()
 Get application name. More...
 
static void setArguments (int argc, char **argv)
 Set arguments of the program with argc as argument counter and argv as argument values. More...
 
static void setArguments (const std::vector< std::string > &arguments)
 Set arguments ot the program as an std::vector of std::string. More...
 
static void * loadModule (const std::string &name, int flags=-1)
 Load a module into the current process. More...
 
static void unloadModule (void *handle)
 Unload a module from the current process. More...
 
static bool terminated ()
 Check whether the Application instance is terminated or not. More...
 
static bool initialized ()
 Check whether the Application instance was initialized or not. More...
 
static const char * program ()
 Return the current program full path according to argv[0]. More...
 
static const char * realProgram ()
 Return the current program full path. More...
 
static const char * _suggestedSdkPath ()
 Return the SDK path given through –qi-sdk-prefix or QI_SDK_PREFIX. More...
 
static bool atEnter (std::function< void()> func)
 Register a function to be executed at Application creation. More...
 
static bool atExit (std::function< void()> func)
 Register a function to be executed at Application destruction. More...
 
static bool atRun (std::function< void()> func)
 Register a function to be executed when run() is called. The functions are executed sequentially at the beginning of run(). More...
 
static bool atStop (std::function< void()> func)
 Register a function to be executed when stop() is called. The functions are executed sequentially before run() returns. More...
 
static bool atSignal (std::function< void(int)> func, int signal)
 Register a function to be executed when a signal occurs. More...
 
static
boost::program_options::options_description & 
options ()
 Get the registered global program options. More...
 
static std::string helpText ()
 

Detailed Description

Class handling startup and teardown of an application.

* The :cpp:class:`qi::Application` class is designed to ease
* startup and teardown of an executable.
*
* All executables using qi classes should create an instance of
* :cpp:class:`qi::Application` on the stack of the main() function.
* 

Definition at line 31 of file application.hpp.

Constructor & Destructor Documentation

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

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

Parameters
argcArgument counter of the program.
argvArguments of the program (given to main).
nameThe name of the program. It will be returned by name().
pathThe full path to the program if you wish to override it. It will be returned by program() but not realProgram().
Exceptions
std::logic_errorWhen the constructor is called twice.
qi::Application::Application ( const std::string &  name,
int &  argc,
char **&  argv 
)

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

Parameters
nameName of the application.
argcArgument counter of the program.
argvArguments of the program (given to main).
Exceptions
std::logic_errorWhen the constructor is called twice.
Deprecated:
Use Application(int&, char**&, const std::string&, const std::string&)
qi::Application::~Application ( )

Application destructor. It executes atExit() callbacks.

See Also
qi:Application::atExit
QI_AT_EXIT
qi::Application::Application ( const Application )
delete

Member Function Documentation

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

Return the SDK path given through –qi-sdk-prefix or QI_SDK_PREFIX.

Used internally, you should not need this.

static int qi::Application::argc ( )
static

Get argument counter of the program.

Returns
Argument counter of the program if Application was initialized, -1 otherwise.
static const std::vector<std::string>& qi::Application::arguments ( )
static

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

Returns
List of arguments of the program.
static const char** qi::Application::argv ( )
static

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

Returns
Arguments of the program if Application was initialized, 0 otherwise.
static bool qi::Application::atEnter ( std::function< void()>  func)
static

Register a function to be executed at Application creation.

Parameters
funcCallback function at Application creation.
Returns
True if registering succeeded, false otherwise.
static bool qi::Application::atExit ( std::function< void()>  func)
static

Register a function to be executed at Application destruction.

Parameters
funcCallback function called at Application destruction.
Returns
True if registering succeeded, false otherwise.
static bool qi::Application::atRun ( std::function< void()>  func)
static

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

Parameters
funcCallback 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 
)
static

Register a function to be executed when a signal occurs.

Parameters
funcCallback function called on signal.
signalSignal 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 bool qi::Application::atStop ( std::function< void()>  func)
static

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

Parameters
funcCallback function called when stop() is called.
Returns
True if registering succeeded, false otherwise.
static std::string qi::Application::helpText ( )
static
Returns
Get the help text displayed when the --help option is used.
static bool qi::Application::initialized ( )
static

Check whether the Application instance was initialized or not.

Returns
True if it was initialized, false otherwise.
static void* qi::Application::loadModule ( const std::string &  name,
int  flags = -1 
)
static

Load a module into the current process.

Parameters
nameThe module path and name. If no extension is used, the correct extension for a library on the current platform is used.
flagsExtra 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 :cpp:macro:`QI_AT_ENTER`.
* 
static std::string qi::Application::name ( )
static

Get application name.

Returns
A string with the application name, empty string if setName isn't call.
Application& qi::Application::operator= ( const Application )
delete
static boost::program_options::options_description& qi::Application::options ( )
static

Get the registered global program options.

Returns
The options_description of the currently added program options.
static const char* qi::Application::program ( )
static

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

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

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 :cpp:func:`qi::Application(int&, char**&)` should
* have been called in your main().
* 
static void qi::Application::run ( )
static

Wait until the end of the program.

* Wait until one of those conditions becomes true:
* - stop() is called.
* - TERM or INT 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::setArguments ( int  argc,
char **  argv 
)
static

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

Parameters
argcArgument counter of the program.
argvArguments of the program (given to main).
static void qi::Application::setArguments ( const std::vector< std::string > &  arguments)
static

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

Parameters
argumentsSets arguments with a vector of strings.
static void qi::Application::setName ( const std::string &  name)
static

Set application name.

Parameters
nameThe application's name.
static void qi::Application::stop ( )
static

Stop the application. Call all atStop handlers.

static bool qi::Application::terminated ( )
static

Check whether the Application instance is terminated or not.

Returns
True if it is stop, false otherwise.
static void qi::Application::unloadModule ( void *  handle)
static

Unload a module from the current process.

Parameters
handleHandle on the loaded module.

The documentation for this class was generated from the following file: