Application Lifecycle: Details

Application Startup

The lifecycle begins when the nlpd calls the main routine in an application library. An argv argument tells the application if it is to be the main window, or run in the background, or whether it was started to handle something specific. You can see the argv strings in the source at hiker/main/dist/include/hiker/appmgr.h or in the doxygen documentation (once you build it). Here are some of the strings, and their effects on the application.

#define ALP_APP_PRIMARY "alpprimary"
// The application becomes the new "primary" UI app.
// Shut down the current app and run this app instead
#define ALP_APP_BACKGROUNDED "alpbackgrounded"
// The application is no longer the primary UI app,
// but let it continue in the background with no GUI visible
#define ALP_APP_NOTIFY "alpnotify"
// The application is being launched or relaunched
// to handle a notification.
#define ALP_APP_EXCHANGE "alpexchange"
// The application is being launched or relaunched
// to run an exchange handler.
#define ALP_APP_ALARM "alpalarm"
// The application is being launched because one
// of its alarms went off.

The most common launch argument is ALP_APP_PRIMARY. An application is typically launched with ALP_APP_PRIMARY, and will continue execution until a new primary application is launched. For the most simple applications, nothing beyond basic GTK (or other GUI toolkit) infrastructure may be needed. More complex applications, however, need some extra work beyond the basic GTK code, and this is where the other launch arguments come into play.

Application Execution

Applications generally run like any GUI application. They use a toolkit like GTK to
display some UI, and run a window main loop until it is time for them to quit.

Application Re-execution

The major departure from the usual desktop environment is that we only permit running a single instance of any given application. If a running application is launched again, it keeps running but the new launch arguments are delivered to it and the application is expected to update its state accordingly.

Applications receive new launch arguments through a callback that is termed a "relaunch handler", which is put in place by calling alp_app_set_relaunch_handler(). This handler will then be called later by the appserver clientside library in response to a launch request for the already-running application. It gives the application the opportunity to examine the new launch arguments, and update its state. This might mean handling an exchange request, showing or hiding UI, etc.

In other words, if the application is already running, the framework can tell it of a new task that must be done. And if an application is not running, the framework can start the application to ask it to handle a particular task. In this case, the application generally runs in the background with no GUI displayed.

Applications which might be relaunched include those that support/require both primary and background execution, register for system notifications, or register with Exchange Manager to handle some particular content types.

It's worth noting that unless the application goes out of its way to use Framework-specific facilities (by specifying an ALP_APP_BACKGROUND_* property in its Manifest.xml file, registering for notifications or alarms, registering with the ExchangeMgr, etc), then it will probably never be launched while it is already running, and thus there is no need for it to register a relaunch handler. This provides an easier transition for developers or software porters familiar with the GUI toolkit but not Hiker.

The app server will shut down and restart an app, if it gets a launch request for an app that is already running but which does not have a relaunch handler.

Application Shutdown

We maintain the traditional ACCESS Garnet OS model of having the system tell the application when to exit. While an application may exit at any time of its own accord, it should also be sure to always honor an exit request from the appserver.
Applications which need to perform cleanup before exiting will register callback handlers to receive the exit request, and should respond by performing any necessary cleanup, and returning from main(). The application may add (and remove) multiple callbacks in order to associate different types of cleanup with the current program state (for example, if the application displays a dialog, it can also register an exit handler to dismiss that dialog).

Exit handlers are always executed in order, starting with the most recently added.
If the application does not register any exit handlers, then the appserver clientside
library will raise a SIGTERM signal instead. This provides a familiar (to Linux developers) mechanism for exit notification. For most applications, the programmer doesn't need to write a SIGTERM handler and can just let Linux end the process.
If the application does not cease execution within a short timeframe (a few seconds), then the application server will send a SIGKILL, and a warning dialog may be displayed to the user (as much to encourage developers to handle the notification as to warn users). There will not be an API available to applications for resetting this timer. Applications with a genuine need for a lengthy exit procedure should instead specify ALP_APP_BACKGROUND_REQUIRED in their manifest file, and register a relaunch handler. When the app server relaunches the app in the background, it can run its lengthy exit procedure and return from main() to terminate.

Back to "Application Lifecycle "