NAME

       md_src_plugins_dbus_READMEREADME
        -

       • infos = Information about the dbus plugin is in keys below

       • infos/author = Markus Raab elektra@libelektra.org

       • infos/licence = BSD

       • infos/needs =

       • infos/provides = notification

       • infos/placements = postgetstorage postcommit

       • infos/description = Sends DBus signals when a method is called

       This plugin is a notification plugin which sends a signal to dbus when a method is called.
       This plugin allows external programs to take action when dbus notifies the program that a
       certain method has taken place with Elektra.

   Dependencies
       • libdbus-1-dev

   Dbus
       A preferred way to interconnect desktop applications and even embedded system applications
       on mobile devices running Linux is D-Bus. The idea of D-Bus accords to that of Elektra: to
       provide standards to let software work together more tightly. D-Bus provides a simple and
       lightweight IPC (Inter-Process Communication= system to be used within desktop systems.
       Next to RPC (Remote Procedure Call), which is not used in this plugin, it supports signals
       which can notify an arbitrary number of other applications about changes. Given software
       like a D-Bus library, notification itself is a rather easy task, but it involves
       additional library dependences. So it is the perfect task to be implemented as a plugin.
       The information about the channels to be used can be stored in the global key database.

       D-Bus supports a system-wide bus and a session bus. The system configuration can be
       accessed by each user and the user configuration is limited to a single user. Both buses
       can immediately be used for the system and user configuration notification updates to get
       pleasing results. But, there is a problem with the session bus: It is possible within D-
       Bus that a user starts several sessions. The user configuration should be global to the
       user and is not aware of these sessions. So if several sessions are started, some of the
       user's processes will miss notification updates.

       The namespaces are mapped to the buses the following way:

       • system: system-wide bus

       • user: session bus

       Following signal names are used to notify about changes in the elektra KeySet:

       • KeyAdded: a key has been added

       • KeyChanged: a key has been changed

       • KeyDeleted: a key has been deleted

   Usage
       Mount the plugin additionally to a storage plugin, e.g.

           kdb mount file.dump / dump dbus

       then we can receive the notification events using:

           dbus-monitor type='signal',interface='org.libelektra',path='/org/libelektra/configuration'

   Python
       In Python the DBus notifications can be used as follows

       import dbus
       import gobject
       gobject.threads_init()  # important: initialize threads if gobject main loop is used
       from dbus.mainloop.glib import DBusGMainLoop

       class DBusTest():
           def __init__(self):
               DBusGMainLoop(set_as_default=True)
               bus = dbus.SystemBus()  # may use session bus for user db
               bus.add_signal_receiver(self.elektra_dbus_key_changed_cb,
                   signal_name="KeyChanged",
                   dbus_interface="org.libelektra",
                   path="/org/libelektra/configuration")

           def elektra_dbus_key_changed_cb(self, key):
               print('key changed %s' % key)

       test = DBusTest()
       loop = gobject.MainLoop()
       try:
           loop.run()
       except KeyboardInterrupt:
           loop.quit()

   Background
       Today, programs are often interconnected in a dense way. Such applications should always
       be informed when something in their environment changes. For user interactive software,
       notification about configuration changes is expected. The only alternative is polling,
       which wastes resources. It additionally is no option, because for interactive software the
       latency needs to be low. Instead, the software which changes the configuration has to
       notify all other interested applications that can reread their configuration without
       significant delay. In Elektra, a notification plugin ensures that a notification is
       actually sent on each change.

       Applications can wait for such a notification with hand-written code. Bindings, however,
       allow for better integration. It is a common approach for toolkits to provide a main loop.
       Applications using such toolkits can integrate notification services into this main loop.

       The actions that occur in such events are application or toolkit specific because of the
       non-invasive nature of Elektra. Software reacts in many different ways to update events.
       Hence, the frequency of update events should be kept at a minimum. Changes are kept atomic
       with a single attempt to write out configuration. Notification callbacks shall not change
       configuration because this can lead to a longer chain of unwanted modifications. That
       might not be true, however, if a programmer of the whole system knows that a chain of
       reactions will terminate. When doing such event-driven programming, care is needed to
       avoid infinite loops. Elektra guarantees consistency of the key database even in such
       cases.