dconf & GSettings

This page is about dconf and GSettings.

dconf is a low-level configuration system.

GSettings is the settings-management interface that makes GObject programmers happy.

Both components are currently under heavy development. Code is available from http://git.desrt.ca/

dconf Overview

dconf is a simple key-based configuration system. Keys exist in an unstructured database (but it is intended that keys that logically belong together are grouped together).

Change notification is supported.

Stacking of multiple configuration sources is supported. Mandatory keys are supported.

The stacking can be done at "mount points". For example, the global system configuration can be mounted under /system inside of each user's configuration space. A single configuration source may appear at multiple points in the hierarchy. For example, in addition to stacking over the normal keys, the mandatory keys may also appear at /mandatory for inspection and modification by a system policy configuration utility.

PolicyKit integration is planned so that a normal user may temporarily gain the ability to, for example, write to the keys under /system (or /mandatory). This means that programs like the GDM configuration utility no longer have to be run as root.

Since a typical GNOME login consists of thousands of reads and 2 writes, dconf is optimised for reads. Typically, reading a key from dconf involves zero system calls and zero context switches. This is achieved with a simple file format that doubles both as the storage format for data in dconf and as an IPC mechanism between the clients and the server.

Avoiding round trips and context switches is nice in itself, but the real win comes from allowing the IO scheduler in the kernel to do a better job by saturating it with requests coming from all of the applications trying to read their keys (as opposed to a common configuration server serially requesting a single key at a time).

Having all of the keys in a single compact binary format also avoids the intense fragmentation problems currently experienced by the tree-of-directories-of-xml-files approach.

Writes are less optimised -- they traverse the bus and are handled by the server in the ordinary way. Change notification is handled by the server. The reason for having a server at all is that because getting the clients to synchronise on writing would be a nightmare.

The server doesn't even have to be activated until the first write operation is performed.

The server is completely stateless and can come and go as it pleases. The list of change notifications that an individual client is interested in is maintained by the bus daemon (as a dbus signal watch/match list).

dconf API

The application-facing side of dconf is very simple. There are two major API sets that are intended to be consumed:

• key get/set api
• schema api

Key Get/Set API

This is the main dconf API for accessing keys. It can be expressed as follows:

• Boolean Gettable (Key)

• Value Get (Key)

• Boolean Settable (Key)

• void Set (Key, Value)

• Value List (Path, Flags)

• plus a callback API for change notification

All of the calls can potentially generate exceptions. These are modelled by dbus errors.

In C, all calls return a status code to indicate success or exception and the actual results are returned through pass-by-reference parameters.

Schema API

Schemas in dconf exist only on the client-side and, even there, are very weak. The server has no concept of their existence. You can query any key using the API above and receive any possible value, or no value at all. Schemas do not in any way effect the normal Get/Set calls.

There is a separate API for schemas. A schema is a collection of relative key names, their types, and default values. You can use the schema API to query if a key name exists, what type it has and what its default value is.

If you use dconf directly then you are on your own with respect to using schemas to provide default values and type safety. This is perfect for applications that want to allow direct editing of the database (think dconf-editor type applications) but is not intended to be consumed by normal applications.

GSettings

GSettings is a nice API intended to be directly consumed by GNOME applications written in C (but possibly also other languages). It is extremely strict with respect to schemas:

• schemas are non-optional
• if the schema for your app is missing then it is a fatal error
• writing to a key name not in the schema is a fatal error
• reading from a key name not in the schema is a fatal error
• writing an incorrectly-typed value is a fatal error
• reading a key that has no value in the database results in the schema default being transparently returned.
• reading a key that has a value of the incorrect type in the database results in that value being ignored and the schema default being transparently returned.

In the above list, "fatal error" means "you get a nice message explaining to you why abort() is being called". These rules result in very strong type safety (for example, reading a setting with GSettings will always result in a value of the expected type being returned).

GSettings is a "thick interface". This means that GSettings is really a GObject interface that can be implemented by many different backends. Currently, the only backend that exists is one for dconf.

The "thick interface" contains nice functions for getting and setting relative keys. These functions have varargs bling to allow providing values of the correct type directly (rather than having to first put them in a special container type).

There is also support for "binding" settings keys to object properties (for example, binding a boolean setting in the database to a checkbox). If the object that is being bound happens to have a boolean property named "sensitive" and the key in the database is read-only then the "sensitive" property is set to false. This little piece of magic works nicely for GtkWidget and GtkAction.

  GtkWidget *toggle;
  int width, height;
  GSettings *gs;

  /* the location of the settings object in the database
     is part of the information contained in the schema.
   */
  gs = g_settings_new ("myschema", NULL);

  /* notice that the api is very similar to g_object_get.
     because of the strong type safety, we can give int
     pointers here without fear.
   */
  g_settings_get ("width", &width, "height", &height, NULL);

  /* "size" is a pair of integers */
  g_settings_set ("size", 800, 600, NULL);

  /* create a toggle to control the "mykey" setting */
  toggle = gtk_check_button_new_with_label ("check me");
  g_settings_bind (gs, "mykey", toggle, "active", 0);

Implementers of GSettings need provide only a few small functions for getting and setting keys using DValues.

Status

Much of the above is currently implemented.

Here is a list of functionality listed above that is not actually implemented yet:

• PolicyKit integration does not exist.

• The binary file backend is currently very fragile and requires the files to be manually created. A rewrite is planned.

• GSettings is not yet an interface, but rather just an object that is hard-wired to dconf.

• Configuration sources can not yet appear at multiple mount points.
• Currently watches are implemented very inefficiently (broadcast, basically: pending a more expressive match language in dbus).
• An awful lot of polish is still needed.
• probably other things that i missed.

dconf and GSettings are not yet free software. They are currently "all rights reserved". In the future they will be released under some form of (L)GPL 2/3.

API/ABI stability is not even close to being reached.

Documentation is sparse, but improving.

You probably don't want to use this yet.