.TH "md_src_plugins_dbus_README" 3elektra "Sun May 29 2016" "Version 0.8.14" "Elektra" \" -*- nroff -*- .ad l .nh .SH NAME md_src_plugins_dbus_README \- README .IP "\(bu" 2 infos = Information about the dbus plugin is in keys below .IP "\(bu" 2 infos/author = Markus Raab elektra@libelektra.org .IP "\(bu" 2 infos/licence = BSD .IP "\(bu" 2 infos/needs = .IP "\(bu" 2 infos/provides = notification .IP "\(bu" 2 infos/placements = postgetstorage postcommit .IP "\(bu" 2 infos/description = Sends DBus signals when a method is called .PP .PP 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\&. .PP .SS "Dependencies" .PP .IP "\(bu" 2 \fClibdbus-1-dev\fP .PP .PP .SS "Dbus" .PP 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\&. .PP D-Bus supports a \fBsystem-wide bus\fP and a \fBsession bus\fP\&. 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\&. .PP The namespaces are mapped to the buses the following way: .PP .IP "\(bu" 2 system: system-wide bus .IP "\(bu" 2 user: session bus .PP .PP Following signal names are used to notify about changes in the elektra KeySet: .IP "\(bu" 2 KeyAdded: a key has been added .IP "\(bu" 2 KeyChanged: a key has been changed .IP "\(bu" 2 KeyDeleted: a key has been deleted .PP .PP .SS "Usage" .PP Mount the plugin additionally to a storage plugin, e\&.g\&. .PP .nf kdb mount file.dump / dump dbus .fi .PP .PP then we can receive the notification events using: .PP .nf dbus-monitor type='signal',interface='org.libelektra',path='/org/libelektra/configuration' .fi .PP .PP .SS "Python" .PP In Python the DBus notifications can be used as follows .PP .PP .nf 1 import dbus 2 import gobject 3 gobject\&.threads_init() # important: initialize threads if gobject main loop is used 4 from dbus\&.mainloop\&.glib import DBusGMainLoop 5 6 class DBusTest(): 7 def __init__(self): 8 DBusGMainLoop(set_as_default=True) 9 bus = dbus\&.SystemBus() # may use session bus for user db 10 bus\&.add_signal_receiver(self\&.elektra_dbus_key_changed_cb, 11 signal_name="KeyChanged", 12 dbus_interface="org\&.libelektra", 13 path="/org/libelektra/configuration") 14 15 def elektra_dbus_key_changed_cb(self, key): 16 print('key changed %s' % key) 17 18 test = DBusTest() 19 loop = gobject\&.MainLoop() 20 try: 21 loop\&.run() 22 except KeyboardInterrupt: 23 loop\&.quit() .fi .PP .PP .SS "Background" .PP 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\&. .PP 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\&. .PP 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\&.