Warning, /plasma/plasma-desktop/design/dataengine is written in an unsupported language. File is not indexed.
0001 DataEngine 0002 ========== 0003 0004 Overview 0005 -------- 0006 A Plasma::DataEngine provides read access to data via a standardized API. DataEngine is design specifically with visualizations in mind: the data structure is simple, the data is implicitly shared amongst all visualizations and many requirements are provided by the infrastructure "for free" to a DataEngine to support this mission. 0007 0008 The data is exposed as a simple two level tree; the first level is made up of "sources", each of which contains a dictionary of key/value pairs. The model is purposefully simplified in this manner to prevent complicated arbitrary data structures from being exported in ways that would make it more difficult than necessary for writers of visualizations (e.g. Plasmoids). 0009 0010 Users of DataEngines are usually referred to as "visualizations" as they most often provide a user visible (or audible) representation of the data. 0011 0012 0013 Timeline 0014 -------- 0015 DataEngine was a part of the original libplasma release. 0016 0017 0018 Component Type 0019 -------------- 0020 DataEngines are plugins of ServiceType Plasma/DataEngine. 0021 0022 0023 Component Management 0024 -------------------- 0025 The Plasma::DataEngineManager class provides a loader for DataEngine plugins as well as handles reference counting of them. DataEngineManager follows the singleton pattern. 0026 0027 When a DataEngine's reference count becomes zero, the DataEngine is deleted by the DataEngineManager. Plasma::Applet uses the DataEngineManager internally to provide access to DataEngines for Plasmoids. DataEngines may also be loaded directly without using DataEngineManager, but then are not otherwise managed. 0028 0029 If an engine is requested of DataEngineManager that either does not exist or can not be loaded (e.g. due to a flaw in the plugin library), then a NullEngine is returned. In all cases, however, DataEngineManager will return a valid object. 0030 0031 0032 Sources 0033 ------- 0034 Each source is represented internally by a Plasma::DataContainer. The DataContainer does two things: it holds the key/value dictionary and it manages multiple connections drawing data at different points in time (See: Polling). Each source in a DataEngine must have a unique name. 0035 0036 Often a DataEngine implementation will not handle DataContainers directly, but let the DataEngine class manage them implicitly with calls to setData. However, a DataEngine can create it's own DataContainers; this is usually done when each DataContainer represents an asynchronous job, allowing for the job to be encapsulated. 0037 0038 A DataEngine may create as many (or as few) sources on its own as is reasonable. This is useful for DataEngines which represent sets of data such as hot-plugged devices which do not make sense as queryable items. 0039 0040 Engines may also place an upper limit on the number of sources that may be active at any time. When this limit is reached, the least recently used source is dropped in favour of newer sources. 0041 0042 0043 Visualizations 0044 -------------- 0045 Visualizations are notified via signals of new sources being added, existing sources being removed and the data in existing sources being changed. Visualizations may also query for the current state of a source without connecting to it. 0046 0047 When connecting to a source, the object passed to the connectSource method as the visualization will have its dataUpdated(const QString &sourceName, const Plasma::DataEngine::Data &data) slot called whenever the source changes or when the polling interval expires (whichever is later). 0048 0049 When a source that doesn't exist is requested, the DataEngine is prompted to create a matching source via a sourceRequestEvent. The DataEngine is not required to create a source, however. Sources created in response to a sourceRequestEvent are automatically discarded when the last visualization connected to it disconnects. 0050 0051 0052 Polling 0053 ------- 0054 DataEngine allows both engine-wide polling as well as per-source/visualization polling. This is handled completely internally and results in updateSourceEvent calls. A visualization may request to be updated every N milliseconds; this will be rounded to the nearest 50ms and matched with other similar calls. Additionally, a DataEngine may request an all-sources-update every N milliseconds. Multiple polling intervals on the same source are handled internally, and a minimum polling frequency may be set by the DataEngine to prevent too many calls to updateSourceEvent for the same source. 0055 0056 0057 Services 0058 -------- 0059 A Plasma::Service may be associated with any source. Visualizations can retrieve the Service by calling serviceForSource. The returned service should already be associated by the DataEngine with the source in question. Therefore a Service to post to an online blogging service that is requested using the source that represents the account would post to that account. This prevents visualizations from having to load Services themselves from plugins or pre-configure them. It also allows DataEngines a way to provide mutators for sources. 0060 0061 Unlike sources, Services are not shared. They are unique to the caller of serviceForSource and therefore do not need to be made multi-user safe. 0062