UDisks modular approach

UDisks functionality can be extended by modules. It's not that traditional fully pluggable system as we all know it, modules are essentially just carved-out parts of the daemon code and are free to access whatever internal daemon objects they need. There's no universal module API other than a couple of module initialization functions and a stateful module object. Out-of-tree modules are not supported either and no ABI guarantee exists at all.

This fact allows us to stay code-wise simple and transparent. It's also easier to adapt modules for any change done to the core daemon. As a design decision and leading from GType system limitation modules can't be unloaded once initialized. This may be a subject to change in the future, though unlikely.

The primary motivation for introducing the modular system was to keep the daemon low on resource footprint for basic usage (typically desktop environments) and activating extended functionality only as needed (e.g. enterprise storage applications). As the extra information comes in form of additional D-Bus objects and interfaces, no difference should be observed by ordinary clients.

Modules activation

The UDisks daemon constructs a UDisksModuleManager singleton acting as a module manager. This object tracks module usage and takes care of their activation.

By default UDisksModuleManager is constructed on daemon startup with module loading delayed until requested. This can be overriden by the --force-load-modules and --disable-modules commandline switches that makes modules loaded right on startup or never loaded respectively.

Clients are supposed to call the org.freedesktop.UDisks2.Manager.EnableModule() D-Bus method as a "greeter" call for each module requested. Proper error is reported should the module initialization fail or the module is not available. Clients are supposed to act accordingly and make sure that all requested modules are available and loaded prior to using any of the extra API.

Upon successful activation, a modules-activated signal is emitted internally on the UDisksModuleManager object. Any daemon objects connected to this signal are responsible for performing "coldplug" on exported objects to assure modules would pick up the devices they're interested in.

D-Bus interface extensibility

The modular approach is fairly simple, there are basically three primary ways of extending the D-Bus API:

All these ways of extensibility are implemented as UDisksModule methods and it is a UDisksModuleManager task to provide interconnection between UDisksModule instances and daemon objects representing drives and block devices.

udisks_module_manager_new ()

UDisksModuleManager *
udisks_module_manager_new (UDisksDaemon *daemon);

Creates a new UDisksModuleManager object.

udisks_module_manager_new_uninstalled ()

UDisksModuleManager *
udisks_module_manager_new_uninstalled (UDisksDaemon *daemon);

Creates a new UDisksModuleManager object with indication that the daemon runs from a source tree.

udisks_module_manager_load_single_module ()

gboolean
udisks_module_manager_load_single_module
                               (UDisksModuleManager *manager,
                                const gchar *name,
                                GError **error);

Loads single module and emits the modules-activated signal in case the module activation was successful. Already active module is not being reinitialized on subsequent calls to this method and TRUE is returned immediately.

udisks_module_manager_load_modules ()

void
udisks_module_manager_load_modules (UDisksModuleManager *manager);

Loads all modules at a time and emits the modules-activated signal in case any new module has been activated. Modules that are already loaded are skipped on subsequent calls to this method.

udisks_module_manager_unload_modules ()

void
udisks_module_manager_unload_modules (UDisksModuleManager *manager);

Unloads all modules at a time. A modules-activated signal is emitted if there are any modules staged for unload to give listeners room to unexport all module interfaces and objects. The udisks_module_manager_get_modules() would return NULL at that time. Note that proper module unload is not fully supported, this is just a convenience call for cleanup.

udisks_module_manager_get_modules ()

GList *
udisks_module_manager_get_modules (UDisksModuleManager *manager);

Gets list of active modules. Can be called from different threads.

udisks_module_manager_get_daemon ()

UDisksDaemon *
udisks_module_manager_get_daemon (UDisksModuleManager *manager);

Gets the daemon used by manager .

udisks_module_manager_get_uninstalled ()

gboolean
udisks_module_manager_get_uninstalled (UDisksModuleManager *manager);

Indicates whether the udisks daemon runs from a source tree rather than being a regular system instance.

UDisksModuleManager

typedef struct _UDisksModuleManager UDisksModuleManager;

The UDisksModuleManager structure contains only private data and should only be accessed using the provided API.