KSycoca (KDE3 Architecture)

This page contains information relevant to KDE 3.x or older versions.

This page contains archived content from various sources pertaining to KDE 3.x (maybe outdated and/or partly useful) which should probably be updated. Please regard information in this page with extra caution.

Sycoca - Introduction

Sycoca stands for System Configuration Cache and is nominated to be the successor of kregistry. It is a light weight database optimized for looking up static system configuration information fast and with minimal memory usage.

The database will offer read-only access to many clients at once. The database is read-only which means that looking up can be very fast since no locking or transaction operations need to be performed. The database is created/updated by kbuildsycoca from human readable configuration files. kded monitors these configuration files and will call kbuildsycoca to update the database when a change in any of the configuration files is detected.

Updating the database will mean that the database is replaced as a whole by a more up to date version. This approach allows a very straight forward database implementation. With Sycoca it will not be necessary any more to parse multiple files when looking for static system information. Instead Sycoca can return the requested information with a performance near to O(1). Examples of static system information are mimetype bindings and .desktop information (servicetypes). Application specific configuration information will _NOT_ be stored in Sycoca since this information is usually subject to regular change.

Using Sycoca in your application

Applications never use sycoca directly but always through classes provided by the KDE framework. The following classes use sycoca to obtain their information:

KImageIOFormat: Class that provides information about an image format that is supported by KDE. The correct way to access this information is through the KImageIO class.

KProtocolInfo: Class that provides information about a protocol supported by KDE. These protocols can be used in a URL and will map to an IO-slave that supports the protocol. Examples of protocols supported by KDE are "http", "ftp" and "pop3". The KProtocolInfo class provides information about the capabilities of a protocol. An example of a capability is whether the protocol can provide a list of entries similar to the contents of a directory.

KServiceGroup: Class that provides a (possibly nested) listing of services. Used for things like a hierarchy of applications (K-menu), hierarchy of settings (Control Center) or list of screensavers (screensaver setup in control center)

KService: Class that provides information about a service (or more specific about "applications"). A service is always described by a .desktop file. Such a file contains information like which icon to use for the service, how to start the service, the (translated) name of the service and (translated) comment which describes the service. See the Desktop Entry Standard for a description of .desktop files.

KServiceType: Mostly known due to one of its subclasses KMimeType. KServiceType describes a certain type of service that can be offered by a service. In the case of KMimeType the type of service is the ability to open a file of a specific format. A typical sequence of events, implemented by KRun, is to determine the mimetype of a file and then to search for a service that supports this mimetype. E.g. a file is examined and identified as a HTML file (mimetype text/html) based on this information, one or more services can be found that are able to open this file (for example konqueror, netscape and kwrite)

Sycoca class & responsibilities overview

KSycoca

Responsible for building Sycoca database. Factories need to register themselves to KSycoca.
Tells factories where to store their information.
Builds factory index.

KSycocaEntry

Abstract Base Class (ABC) for all information stored in Sycoca.
Has an id which is unique in the whole database.
Each subclass has a unique type-key which identifies the subclass.
Creates itself based on information from human readable config file.
Creates itself based on information stored in database.
Can find itself in the database based on its id. (because Id == offset)
Stores its information content in database.
Has static factory lookup-methods which dispatch to the responsible factory.

KSycocaFactory

Each factory has a unique type-key which identifies the factory.
Finds its own information in the database using the factory index.
Maintains a specific number of information types in the Sycoca database.
Identifies which human readable configuration files to use for creating which kind of KSycocaEntry's.
Builds fast lookup indices inside the database for the KSycocaEntry's managed by it.
Stores the KSycocaEntry's it maintains in the database.
Looks up information in the Sycoca database and recreates KSycocaEntry's to represent this information.

KSycocaDict

KSycocaDict offers a fast lookup-index based on string keys. Creation of the index is reasonably slow, but once the index has been created information can be found with a small number of steps nearly independent from the data size.

During creation KSycocaDict creates a hash-function and a hash-index which is populated for approximately 20% and which has a typical hash collision chance of 10%.

This means that existing objects can be found at once in 90% of the time. In the other 10% the collision list has to be searched. A collision list typically contains 2 entries.

Not existing objects have a chance of 20% to give a false hit. A hit should therefore always be verified by loading the actual object.

KSycocaDict is used by the KSycocaFactories to be able to create fast lookup functions for the objects it maintains.

Users of the Sycoca database

KServiceTypeFactory (subclass of KSycocaFactory)

Offers KServiceType lookup on name.
Offers KMimeType lookup on name (name == mimetype).
Offers KMimeType lookup on filetype (regexp match).
Offers KFolderType lookup (one instance only).
Offers KDEDesktopMimeType lookup (one instance only).
Offers KExecMimeType lookup (one instance only).

KServiceFactory (subclass of KSycocaFactory)

Offers KService lookup on name.

KProtocolInfoFactory (subclass of KSycocaFactory)

Offers KProtocolInfo lookup on name (name == protocol).

KImageIOFactory (subclass of KSycocaFactory)

Registers image-IO plugins and loads image-IO plugins when needed.

KServiceGroupFactory (subclass of KSycocaFactory)

Offers KServiceGroup lookup on path.

KServiceTypeFactory is repsonsible for the following classes:

KServiceType (subclass of KSycocaEntry)
KMimeType (subclass of KServiceType)
KFolderType (subclass of KMimeType)
KDEDesktopMimeType (subclass of KMimeType)
KExecMimeType (subclass of KMimeType)

KServiceFactory is responsible for the following classes:

KService (subclass of KSycocaEntry)

Implementation notes:

To speed up the dereferencing of relations between KSycocaEntries of various kinds, the id of the KSycocaEntry should be used to store these references.
When e.g. KMimeType creates itself based on the database and its Id it should check that the information labeled with this Id in the database, does indeed belong to a KMimeType type of object. (Watch out with multiple inheritance!)

Initial Author: Waldo Bastian bastian@kde.org