Qt5的插件机制（2）--QxxxFactory类与QFactoryLoader类
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
QxxxFactory类：插件生产者
在Qt的插件加载机制的概述中，我已经提到过，一个Q
在Qt中，为了区分不同类别、不同功能的插件，应该为每一类插件设置一个独特的 IID 值，这个IID值通常
是一个长字符串。属于同一类的插件应该具有相同的IDD值。比如，所有平台类QPA插件，包括LinuxFB插件(QLinuxFbIntegration)、
XCB插件（QXcbIntegration）等，他们的IDD都应是 org.qt-project.Qt.QPA.QPlatformIntegrationFactoryInterface.5.2 ，
而所有的输入法类插件，如Qt的ibus插件、fcitx插件等，他们的IDD都应该是 org.qt-project.Qt.QPlatformInputContextFactoryInterface。
另外我提到过，Qt还会为每个Q
这个QFactoryLoader 对象中也记录了这一类插件的IID的值，专门负责加载这一类别的插件。
接下来，就分别研究一下这两个类。先看 QxxxFactory。这里为了具体一点，我们拿QPlatformInputContextFactory类来讲，其他的QxxxFactory
类也都是类似的。
class Q_GUI_EXPORT QPlatformInputContextFactory
{
public:
static QStringList keys(); // 只有几个静态的成员函数
static QPlatformInputContext *create(const QString &key);
static QPlatformInputContext *create();
};
其中，keys() 方法用于获得所有同类插件的关键字。对于QPlatformInputContextFactory类，它的keys()方法自然就是获得所有输入法类插件，比如ibus\fcitx等插件的关键字。
QStringList QPlatformInputContextFactory::keys()
{
#if !defined(QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)
return loader()->keyMap().values();
#else
return QStringList();
#endif
}
获取关键字的这段代码很短，但我们马上就有个疑问，代码中出现的 loader() 是哪儿来的？它的返回值是什么？
我最初读到这段代码时也一致纠结于此，因为哪里都找不到这个 loader() 的定义，后来才注意到，在这个源文件的
开头，有一句
#if !defined(QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)
Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader, // <--- loader就在这里定义
(QPlatformInputContextFactoryInterface_iid, QLatin1String("/platforminputcontexts"), Qt::CaseInsensitive))
#endif
这才有点眉目，而且在Qt Assistanct中也找到了 Q_GLOBAL_STATIC_WITH_ARGS 这个宏的说明，这个宏专门用于定义全局的静态变量，
Q_GLOBAL_STATIC_WITH_ARGS( Type, VariableName, Arguments)
其中Type是要定义的静态全局变量的类型，VariableName是变量的名字，Arguments是构造参数。使用这个宏，可以定义一个变量为
VariableName、类型为 QGlobalStatic 的对象。而 QGlobalStatic 类重载了括号运算符 '()'，通过VariableName()可以得到一个
Type类型的指针，他指向的就是我们所需要的那个静态全局变量。Arguments就是在构造这个Type类型的静态全局对象时传给构造函数
的参数。
因此上面那句代码，就是定义了一个 QFactoryLoader 类的静态全局对象，这样在之后的代码中，就可以通过 loader() 访问这个对象了。
loader()->keyMap().values() 这一行，就把这个 QFactoryLoader 对象对应的所有插件的关键字获取到组成一个列表，本文后面会介绍QFactoryLoader类。
QPlatformInputContextFactory 有两个 create 方法，其中一个是指定了关键字，另一个则自己搜索关键字。
QPlatformInputContext *QPlatformInputContextFactory::create(const QString& key)
{
// 指定了关键字 key
QStringList paramList = key.split(QLatin1Char(':')); // 将关键字按分隔符分离成一个或多个参数，分隔符是冒号
const QString platform = paramList.takeFirst().toLower(); // 获取key中分离的第一个参数，作为加载插件时用的关键字
#if !defined(QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)
if (QPlatformInputContext *ret = qLoadPlugin1(loader(), platform, paramList))
return ret;
#endif
return 0;
}
QPlatformInputContext *QPlatformInputContextFactory::create()
{
// 未指定关键字，则自己搜索关键字。
QPlatformInputContext *ic = 0;
// 先从环境变量中搜索关键字
QString icString = QString::fromLatin1(qgetenv("QT_IM_MODULE"));
if (icString == QLatin1String("none"))
return 0;
ic = create(icString);
if (ic && ic->isValid())
return ic;
delete ic;
ic = 0;
// 如果环境变量中找不到合适的关键字，则从 keys() 返回的关键字列表中一个一个试
QStringList k = keys();
for (int i = 0; i < k.size(); ++i) {
if (k.at(i) == icString)
continue;
ic = create(k.at(i));
if (ic && ic->isValid())
return ic;
delete ic;
ic = 0;
}
return 0;
}
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
QFactoryLoader 类：插件加载者
如前所说，一个 QFactoryLoader 对象用于加载某一类别的插件。QFactoryLoader 类中维护了一个
插件/库列表（列表中的元素都是QLibraryPrivate类型），这个列表中的插件/库都是属于同一类别的插件，
他们的 IID 都是一样的（一个插件/库的IID值存储在其QLibraryPrivate对象的元信息metaData中）。
除了这个插件/库列表，QFactoryLoader 类中还维护了一个从关键字到插件/库的映射表，通过这个映射表
可以快速的通过关键字来找到对应的库。
这里我们先来看下QFactoryLoaderPrivate的定义：
class QFactoryLoaderPrivate : public QObjectPrivate
{
Q_DECLARE_PUBLIC(QFactoryLoader)
public:
QFactoryLoaderPrivate(){} // 构造函数什么也不做
~QFactoryLoaderPrivate(); // 析构函数中卸载并释放插件/库列表中所有的库
/* QFactoryLoaderPrivate::~QFactoryLoaderPrivate()
{
for (int i = 0; i < libraryList.count(); ++i) {
QLibraryPrivate *library = libraryList.at(i);
library->unload();
library->release();
}
} */
mutable QMutex mutex;
QByteArray iid; // 当前对象对应的插件集的 IID
QList libraryList; // 插件/库 列表
QMap keyMap; // 插件/库 到 关键字的映射表
QString suffix; // 当前对象对应的插件集中所有插件/库对应的库文件(.so文件)路径的后缀（最低一级目录的名字）
Qt::CaseSensitivity cs; // 匹配关键字的策略，是精确匹配还是粗略匹配，一般都选粗略匹配
QStringList loadedPaths; // 所有已经加载过的库路径
void unloadPath(const QString &path);
};
QFactoryLoaderPrivate类的iid、suffix和cs成员，实在QFactoryLoader类的构造函数中初始化的，下面马上会看到。
QFactoryLoader类的定义如下。
class Q_CORE_EXPORT QFactoryLoader : public QObject
{
Q_OBJECT
Q_DECLARE_PRIVATE(QFactoryLoader)
public:
explicit QFactoryLoader(const char *iid,
const QString &suffix = QString(),
Qt::CaseSensitivity = Qt::CaseSensitive);
// 构造函数，先设置插件集的 IID、插件路径后缀和关键字匹配策略，
// 再调用update()生成插件列表和插件到关键字的映射表，并将当前的
// QFactoryLoader对象添加到全局的loader列表qt_factory_loaders中 。
~QFactoryLoader(); // 析构，将当前的QFactoryLoader对象从全局的loader列表qt_factory_loaders中移除
QList metaData() const; // 返回d->libraryList(库列表)中每个库的元信息组成的列表（列表的还加上了静态库的元信息）
QObject *instance(int index) const; // 返回d->libraryList(库列表)第index个插件的实例
#if defined(Q_OS_UNIX) && !defined (Q_OS_MAC)
QLibraryPrivate *library(const QString &key) const; // 返回映射表中关键字key对应的库
#endif
QMultiMap keyMap() const; // 返回d->libraryList(库列表)中所有库的关键字映射表：每个库有
// 一个int型索引（就是该库在库列表中的索引）和若干个QString
// 类型的关键字，这个函数的返回值是QMultiMap类型的一个“一对多”的映射表，一个
// 库(索引)对应若干个关键字。
int indexOf(const QString &needle) const; // 返回关键字needle对应的库在库列表中的索引
void update(); // 主要功能就是更新 库列表（d->libraryList） 和 关键字到库的映射表（d->keyMap）， 一般在应用程序的库加载路径发生变化时才需调用
static void refreshAll(); // 这是一个静态函数，用于将全局loader列表(qt_factory_loaders)中的所有QFactoryLoader对象都update() 一下
};
通过上面的注释我们已经知道，库列表（d->libraryList） 和 关键字到库的映射表（d->keyMap）都是在构造函数中通过调用update()生成的，
这两个表几乎就是这个类的核心，下面我们就看看这两个表是如何生成的。
void QFactoryLoader::update()
{
#ifdef QT_SHARED
Q_D(QFactoryLoader);
QStringList paths = QCoreApplication::libraryPaths(); // 获取应用程序的库加载路径
// 第一层循环， 开始遍历所有的库路径
for (int i = 0; i < paths.count(); ++i) {
const QString &pluginDir = paths.at(i); // 获取第 i 个库路径
// Already loaded, skip it... 如果当前库路径已经记录在了 d->loadedPaths 中，则跳过这个库路径。
if (d->loadedPaths.contains(pluginDir))
continue;
d->loadedPaths << pluginDir; // 将当前库路径添加到 d->loadedPaths 中。这样可以防止重复加载一个库路径
QString path = pluginDir + d->suffix; // 这个库路径加上当前QFactoryLoader对象对应的插件集的路径后缀，得到插件集的路径path（如果存在）
if (qt_debug_component())
qDebug() << "QFactoryLoader::QFactoryLoader() checking directory path" << path << "...";
if (!QDir(path).exists(QLatin1String("."))) // 检测插件集路径path是否存在，不存在则跳过当前的库路径
continue;
// 如果插件集路径path存在，接着往下运行
QStringList plugins = QDir(path).entryList(QDir::Files); // 列出当前插件集路径path中的所有文件名，存入plugins列表中
QLibraryPrivate *library = 0;
#ifdef Q_OS_MAC
// Loading both the debug and release version of the cocoa plugins causes the objective-c runtime
// to print "duplicate class definitions" warnings. Detect if QFactoryLoader is about to load both,
// skip one of them (below).
//
// ### FIXME find a proper solution
//
const bool isLoadingDebugAndReleaseCocoa = plugins.contains(QStringLiteral("libqcocoa_debug.dylib"))
&& plugins.contains(QStringLiteral("libqcocoa.dylib"));
#endif
// 第二层循环，开始遍历插件集路径path中的所有文件
for (int j = 0; j < plugins.count(); ++j) {
QString fileName = QDir::cleanPath(path + QLatin1Char('/') + plugins.at(j)); // 获取第 j 个文件的文件名
#ifdef Q_OS_MAC
if (isLoadingDebugAndReleaseCocoa) {
#ifdef QT_DEBUG
if (fileName.contains(QStringLiteral("libqcocoa.dylib")))
continue; // Skip release plugin in debug mode
#else
if (fileName.contains(QStringLiteral("libqcocoa_debug.dylib")))
continue; // Skip debug plugin in release mode
#endif
}
#endif
if (qt_debug_component()) {
qDebug() << "QFactoryLoader::QFactoryLoader() looking at" << fileName;
}
// 尝试根据文件名fileName创建库library (库用QLibraryPrivate类的对象表示)
// 疑问： 如果插件集路径中包含有非库的普通文件（比如文本文件、图片），也要为他们生成一个 library ? 所以不应该在插件集路径中放非库的文件？
library = QLibraryPrivate::findOrCreate(QFileInfo(fileName).canonicalFilePath());
if (!library->isPlugin()) {
// 判断该库(library)是不是插件，如果不是插件，则跳过当前的库
if (qt_debug_component()) {
qDebug() << library->errorString;
qDebug() << " not a plugin";
}
library->release();// 释放该库
continue;
}
// 如果该库(library)是插件，则继续往下运行
QStringList keys;
bool metaDataOk = false;
QString iid = library->metaData.value(QLatin1String("IID")).toString();
if (iid == QLatin1String(d->iid.constData(), d->iid.size())) {
// 如果插件library的IID与当前QFactoryLoader对象对应的插件集的IID相同，则设置metaDataOk标志，并
// 读取该插件library的元信息中的 MetaData:Keys 字段，这个字段是个JSON数组类型，
// 存储了若干字符串类型的关键字，将这些关键字天价到字符串列表 keys 中。
QJsonObject object = library->metaData.value(QLatin1String("MetaData")).toObject();
metaDataOk = true; // 设置metaDataOk标志
QJsonArray k = object.value(QLatin1String("Keys")).toArray();
for (int i = 0; i < k.size(); ++i)
keys += d->cs ? k.at(i).toString() : k.at(i).toString().toLower();
}
if (qt_debug_component())
qDebug() << "Got keys from plugin meta data" << keys;
if (!metaDataOk) { // 如果metaDataOk标志未被设置，说明IID不匹配，跳过library这个插件
library->release();
continue;
}
int keyUsageCount = 0; // 映射计数，对映射到 library 上的关键字计数
// 第三层小循环，遍历library元信息中Keys字段存储的所有关键字
// 这个循环建立了 库到关键字的映射表（的一部分）
for (int k = 0; k < keys.count(); ++k) {
// first come first serve, unless the first
// library was built with a future Qt version,
// whereas the new one has a Qt version that fits
// better
const QString &key = keys.at(k); // 获取第k个关键字key
// 如果映射表已经映射过 key 了，则获取其之前映射的那个库previous及其所用的Qt版本号prev_qt_version，
// 跟当前库library的Qt版本号qt_version进行比较，如果prev_qt_version高于当前的QT版本号并且qt_version
// 不大于当前的QT版本号，则将关键字 key 重新映射到 library 。
// 如果映射表中还未映射过关键字key，则直接将其映射到 library
QLibraryPrivate *previous = d->keyMap.value(key);
int prev_qt_version = 0;
if (previous) {
prev_qt_version = (int)previous->metaData.value(QLatin1String("version")).toDouble();
}
int qt_version = (int)library->metaData.value(QLatin1String("version")).toDouble();
if (!previous || (prev_qt_version > QT_VERSION && qt_version <= QT_VERSION)) {
// 如果映射表中还未映射过关键字key（!previous）, 或者之前映射到key的库的Qt版本号不合适时，
// 都讲 key 映射到 library 。
d->keyMap[key] = library;
++keyUsageCount; // 映射计数加1
}
}
// 如果映射计数大于0或者库library的元信息中的MetaData:Keys 字段为空(没有关键字)，则将库library添加到库列表d->libraryList 中
if (keyUsageCount || keys.isEmpty())
d->libraryList += library; // 这里建立了 库列表（的一部分）
else
library->release();
}
}
#else
Q_D(QFactoryLoader);
if (qt_debug_component()) {
qDebug() << "QFactoryLoader::QFactoryLoader() ignoring" << d->iid
<< "since plugins are disabled in static builds";
}
#endif
}