From Emergent

Contents 1 Startup and Shutdown 1.1 Compile-time and Run-time Modes 1.2 Startup Procedures 1.3 Shutdown Procedures 1.3.1 cssMisc::Preinitialize 1.3.2 cssMisc::Initialize 1.4 Shutdown Procedures 1.4.1 Qt Session Management 1.4.2 Shutdown and Window Closing Issues 1.4.3 Quitting States and Window Management

Startup and Shutdown

This page describes the main actions that happen during Emergent startup and shutdown.

Compile-time and Run-time Modes

Emergent/TEMT can be compiled in the following modes:

• GUI -- (TA_GUI flag) standard compile, with full gui support
• MPI -- (DMEM_COMPILE flag) all of GUI, plus support for distributed cluster execution via Message Passign Interface (MPI)
• NOGUI -- (NO_TA_GUI + no TA_GUI flag) -- no gui at all (this is currently not tested or likely to work for awhile)

Emergent can be run in following modes (see: [wiki:CommandlineSwitches]

• • gui -- (-gui cmdline switch) displays the normal graphical user interface
  • nogui -- (-nogui cmdline switch )works in a batch mode only, with no main window, etc.

The following runtime scenarios are possible, based on the compiled version and command line flag:

GUI

cmdline flag	run state
-gui or none	gui
-nogui	nogui

MPI

cmdline flag	proc=0, 1 MPI proc	proc=0, >1 MPI procs	proc>0, >1 MPI procs
-gui or none	std gui (no MPI)	gui, master proc	nogui, slave proc
-nogui	std nogui (no MPI)	nogui, master proc	nogui, slave proc

NOGUI

cmdline flag	run state
-gui	**not allowed** (program halts with error code)
-nogui or none	nogui

Startup Procedures

NOTE: this may be out of date: see src/ta/ta_project.h/cpp for the definitive list -- in Startup_Main (i think).

1. . css::PreInitialize -- CSS parses command line switches
2. . initialize MPI (MPI only)
3. . check for gui or nogui startup flag, else default
4. . create the QApplication or QCoreApplication object (also inits SoQt/Coin)
5. . process command line arguments
6. . initialize static (built-in) type system (ta_Init_pdp)
   1. . init ta guys
   2. . init startup folders, including app folder
   3. . load user options
   4. . make root
   5. . load root defaults/preferences
7. . enumerate plugins
8. . load and initialize enabled plugins
9. . init types (bidding, etc.)
10. . initialize CSS
11. . create taiMisc (gui) or taiMiscCore (nogui)
    1. . init default colorspecs
    2. . arbitrate console type
12. . make main window
13. . startup console
14. . process cmd line args
15. . main program loop startup (see following) -- only continues on exit

to be slotted:

1. . set application WaitProc (to pdpMisc::WaitProc)
2. . register signal cleanup funcs (Unix platforms only)
3. . compile/run .pdpinitrc (if exists)

Shutdown Procedures

1. . delete the type catalog
2. . do shutdown for Coin/Inventor (SoQt::done())
3. . do shutdown for MPI (MPI_Finalize)

Main Program Loop Startup (non-mpi, gui)

1. . make main app window
2. . if using gui shell, make console shell window
3. . cssMisc::TopShell->StartupShellInit(cin, cout, <console type option>)
4. . cssMisc::TopShell->Shell_Xxxx("emergent> ") (where Xxxx indicates a console option)

Main Program Loop Startup (MPI)

TBD

Main Program Loop Startup (NO_TA_GUI or nogui)

1. . cssMisc::TopShell->Shell_Xxxx("emergent> ") (where Xxxx is a system (nongui) shell)

cssMisc::Preinitialize

1. . set trace switches
2. . initialize SoQt/Inventor (GUI only)
3. . create a QApplication (GUI) or QCoreApplication (NOGUI) app object

cssMisc::Initialize

(note: this is in css_builtin.cpp)

1. . initialize css type system, global objects, etc.
2. . set default home directory for css purposes
3. . add css environment paths
4. . process command line switches (including gui/nogui logic)
5. . set taMisc::gui_active if in gui mode

Shutdown Procedures

There are several shutdown scenarios:

1. . user chooses File/Quit from the main app menu
2. . user issues the 'quit' command in a console
3. . a script executes a Quit command
4. . user closes the main app window
5. . the user environment session shuts down (ex. user logs out, OS shutting down, etc.)

Qt Session Management

see QApplication and QSessionManager

Qt interacts with the OS to detect external shutdown scenarios. Its default behavior is to send close events to all open windows, and stop the shutdown (if it is stoppable) if any window refuses the close event. The default implementation allows user interaction during this period, however most OS's will only permit a maximum delay on this process before arbitrarily shutting down the system (ex. by killing processes).

Qt notifies of session end via the QApplication::commitData virtual function; this function does not provide a signal, so a subclass of QApplication would be needed.

Shutdown and Window Closing Issues

Qt apparently closes all open windows in "random order" (see QApplication::closeAllWindows()); presumably, this applies to closeAllWindows() as well as session shutdown. One challenge for emergent is that the main application window needs to remain open, so it wouldn't be any good to have the app window close but then have the user cancel closing during the close event of a project window. (Unless we allowed the app window to close any time, and provided a main menu option for reopening it -- this seems very confusing.)

If the gui console is allowed to close, we must be able to reopen it. If it is not allowed to close, we must know on getting a closeEvent that it is the system shutting down. A better alternative is to disallow voluntary closing of any app-critical windows -- this would insure the win stayed open during app running, but we'd allow it to close if the user was quitting.

Quitting States and Window Management

We detect whether the Session itself is ending, by trapping the QApplication::commitData method.

Windows need to have a mechanism that lets us query their close status and possibly trigger save, either from an external source, or while the window is closing. If we externally query a window and the user hits "discard" we need to somehow mark the window as non-dirty.

||Window flag||Description|| ||is_root||on browser windows; 'true' for app window, false for all others|| ||DockWidgetClosable||feature on Dockwindows -- viewer of that win should leave it clear for app-critical wins, like the console||

Here are the quitting states:

||Quit State||Set If/When||Cleared If/When|| ||running||startupBRshutdown cancelled||a quit state is entered (even if tentatively)|| ||user-quit||user choses File/QuitBRuser accepts closing of app win||user cancels close of app win|| ||force-quit||Session endsBRapp win closes (however)||(never)||

Scenarios:

User clicks on app close window.

1. . app window tries to close
2. . will warn user this will quit application
3. . if user rejects, don't close, and do nothing
4. . if user accepts, set "user-quit" flag
5. . do the global taMiscCore::OnQuitting procedure; calls: !ResolveChanges procedure
6. . if cancelled, then set back to "running" and exit
7. . call taMisc::Core::Quit not cancellable (calls QApplication::closeAllWindows())
8. . (do common Quit Subprocessing below)

User chooses File/Quit from menuBR User issues 'quit' command in consoleBR Script runs the app Quit command (prob. root->Quit())

1. . set "user-quit" flag (cancellable)
2. . when the
3. . (do common Quit Subprocessing below)
4. . if user cancelled, exit

Session is closing

1. . QApplication::commitData is trapped -- we set "force-quit"
2. . Qt will basically send a closeAllWindows
3. . if a window is a project win, it sees "force-quit", checks dirty:
   1. . if dirty, offer: "Save", "Discard"
   2. . if Save, then save;
   3. . accept close event (always)
4. . (common processing below)

ResolveChanges Processing

This procedure is heavily nested and may be called at several different levels, and can sometimes be called more than once. It is passed a CancelOp flag -- if it is NOT_CANCELLABLE then the routine will not allow the user to cancel; if it is PROCEED then the user may cancel. If anything sets it to CANCEL then processing will soon stop. Note that it is up to every client routine to respect NOT_CANCELLABLE and not change it.

1. . Resolve all open edits -- this basically saves any pending changes
2. . Resolve all unsaved projects in open project viewers

Common Quit End to all scenarios -- if all windows close

1. . when all app windows have closed, and events processed, appAboutToQuit will signal
2. . this will exit us from event loop and return to main startup code
3. . startup code will delete root object
4. . delete the typedefs, before the global dtors