From 855e4eac4ff9ef779a715c49d972bb6b4f8098fe Mon Sep 17 00:00:00 2001
From: Eike Ziller <eike.ziller@nokia.com>
Date: Mon, 28 Nov 2011 08:27:50 +0100
Subject: [PATCH] Add document on plugin life cycle.
Change-Id: Iec868cdb8158726d91bcece935a9d6269219c056
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@nokia.com>
---
doc/api/plugin-lifecycle.qdoc | 122 +++++++++++++++++++++++++++++
doc/api/plugin-specifications.qdoc | 3 +-
doc/doc.pri | 1 +
3 files changed, 125 insertions(+), 1 deletion(-)
create mode 100644 doc/api/plugin-lifecycle.qdoc
diff --git a/doc/api/plugin-lifecycle.qdoc b/doc/api/plugin-lifecycle.qdoc
new file mode 100644
index 00000000000..afaf055e9c4
--- /dev/null
+++ b/doc/api/plugin-lifecycle.qdoc
@@ -0,0 +1,122 @@
+/****************************************************************************
+**
+** This file is part of Qt Creator
+**
+** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
+**
+** Contact: Nokia Corporation (info@qt.nokia.com)
+**
+**
+** GNU Free Documentation License
+**
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at info@qt.nokia.com.
+**
+****************************************************************************/
+
+/*!
+ \page plugin-lifecycle.html
+ \title Plugin Life Cycle
+
+ To be able to write \QC plugins, you must understand the steps that the plugin
+ manager takes when you start or shut down \QC. This section describes
+ the process and the state that plugins go through in detail.
+
+ When you start \QC, the plugin manager does the following:
+
+ \list 1
+ \o Looks in its search paths for
+ all .pluginspec files, and reads them. This is the first point where
+ loading a plugin can fail in the worst case of a malformed plugin spec.
+
+ \o Creates an instance of the \l{ExtensionSystem::PluginSpec} class for
+ each plugin. This class is a container for
+ all the information from the plugin specification, and additionally
+ tracks the state of the plugin.
+ You can get the \l{ExtensionSystem::PluginSpec} instances via the
+ plugin manager's \l{ExtensionSystem::PluginManager::plugins()}{plugins()}
+ method, or, after a plugin is loaded, through the plugin's
+ \l{ExtensionSystem::IPlugin::pluginSpec()}{pluginSpec()} method.
+
+ \o Sets the plugins to \c Read state.
+
+ \o Verifies that the dependencies of each plugin
+ exist and are compatible. For more information about plugin dependencies,
+ see \l{Plugin Specifications}.
+
+ \o Sets the plugins to \c Resolved state.
+
+ \o Sorts all plugins into a list that we call the \e{load queue}, where the
+ dependencies of a plugin are positioned after the plugin
+ (but not necessarily \e directly after the plugin).
+ It will make sure that we load
+ and initialize the plugins in proper order.
+
+ \o Loads the plugins' libraries, and creates their IPlugin instances
+ in the order of the load queue. At this point the
+ plugin constructors are called. Plugins that other plugins depend on
+ are created first.
+
+ \o Sets the plugins to \c Loaded state.
+
+ \o Calls the \l{ExtensionSystem::IPlugin::initialize()}{initialize()} methods of
+ all plugins in the order of the load queue. In the initialize method,
+ a plugin should make sure that all exported interfaces are set up and available
+ to other plugins. A plugin can assume that plugins they depend on have set up
+ their exported interfaces. For example, the \c Core plugin sets up the
+ \l{Core::ActionManager}, \l{Core::EditorManager} and all other publicly available
+ interfaces, so other plugins can request and use them.
+
+ The \l{ExtensionSystem::IPlugin::initialize()}{initialize()} method of a plugin
+ is a good place for
+ \list
+ \o registering objects in the plugin manager's object pool
+ (see \l{The Plugin Manager, the Object Pool, and Registered Objects})
+ \o loading settings
+ \o adding new menus, and new actions to menus
+ \o connecting to other plugin's signals.
+ \endlist
+
+ \o Sets the plugins to \c Initialized state.
+
+ \o Calls the \l{ExtensionSystem::IPlugin::extensionsInitialized()}{extensionsInitialized()}
+ methods of all plugins in \e reverse order of the load queue. After
+ the extensionsInitialized method, a plugin should be fully initialized, set up
+ and running. A plugin can assume that plugins that depend on it are fully set up,
+ and can finish the initialization of parts that can be extended by other plugins.
+ For example, the \c Core plugin assumes that all plugins have registered
+ their actions, and finishes initialization of the action manager.
+
+ \o Sets the plugins to \c Running state.
+ \endlist
+
+ At the end of startup, the \c Core plugin's \l{Core::ICore} sends two signals.
+ Before the \QC UI is shown it sends \l{Core::ICore::coreAboutToOpen()}{coreAboutToOpen()},
+ and afterwards \l{Core::ICore::coreOpened()}{coreOpened()}.
+
+ Before shutdown, the \c Core plugin's \l{Core::ICore} sends the
+ \l{Core::ICore::coreAboutToClose()}{coreAboutToClose()} signal. After that, the
+ plugin manager starts its shutdown sequence:
+
+ \list 1
+ \o Calls the \l{ExtensionSystem::IPlugin::aboutToShutdown()}{aboutToShutdown()} methods of
+ all plugins in the order of the load queue. Plugins should perform measures
+ for speeding up the actual shutdown here, like disconnecting signals that
+ would otherwise needlessly be called.
+ If a plugin needs to delay the real shutdown for a while, for example if
+ it needs to wait for external processes to finish for a clean shutdown,
+ the plugin can return \l{ExtensionSystem::IPlugin::AsynchronousShutdown} from this
+ method. This will make the plugin manager wait with the next step, and keep the main
+ event loop running, until all plugins requesting AsynchronousShutdown have sent
+ the asynchronousShutdownFinished() signal.
+
+ \o Destroys all plugins by deleting their \l{ExtensionSystem::IPlugin}
+ instances in \e reverse order of the load queue. At this point the plugin destructors
+ are called. Plugins should clean up after themselves by freeing memory and other resources.
+ \endlist
+*/
diff --git a/doc/api/plugin-specifications.qdoc b/doc/api/plugin-specifications.qdoc
index 6469dff998c..f38d9d39eff 100644
--- a/doc/api/plugin-specifications.qdoc
+++ b/doc/api/plugin-specifications.qdoc
@@ -180,7 +180,8 @@
the \c{-help} command line argument, and the plugin manager does its command
line parsing and sanity checks based on that information.
If the plugin manager finds matching command line arguments for a plugin,
- it passes them on to the plugin's \l{IPlugin::initialize} method.
+ it passes them on to the plugin's
+ \l{ExtensionSystem::IPlugin::initialize()}{initialize()} method.
All command line argument definitions are enclosed by a single \c argumentList
tag. The individual command line arguments are defined by the \c argument tag,
diff --git a/doc/doc.pri b/doc/doc.pri
index be1c1dcf0bb..a5e39f4e5e3 100644
--- a/doc/doc.pri
+++ b/doc/doc.pri
@@ -55,6 +55,7 @@ DEV_HELP_DEP_FILES = \
$$PWD/api/getting-and-building.qdoc \
$$PWD/api/first-plugin.qdoc \
$$PWD/api/plugin-specifications.qdoc \
+ $$PWD/api/plugin-lifecycle.qdoc \
$$PWD/api/qtcreator-dev.qdocconf
dev_html_docs.commands = $$qdoc($$OUT_PWD/doc/html-dev) $$PWD/api/qtcreator-dev.qdocconf
--
GitLab