1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
9 <title>D-BUS FAQ</title>
10 <releaseinfo>Version 0.1</releaseinfo>
11 <date>22 January 2005</date>
14 <firstname>Havoc</firstname>
15 <surname>Pennington</surname>
17 <orgname>Red Hat, Inc.</orgname>
19 <email>hp@pobox.com</email>
24 <firstname>David</firstname>
25 <surname>Wheeler</surname>
40 This is probably best answered by reading the D-BUS <ulink url="dbus-tutorial.html">tutorial</ulink>. In
41 short, it is a system consisting of 1) a wire protocol for exposing a
42 typical object-oriented language/framework to other applications; and
43 2) a bus daemon that allows applications to find and monitor one another.
51 Is D-BUS stable/finished?
56 D-BUS has not yet reached 1.0. The <ulink url="README">README</ulink>
57 file has a discussion of the API/ABI stability guarantees before and
58 after 1.0. In short, there are no guarantees before 1.0, and stability
59 of both protocol and reference library will be maintained after 1.0.
60 As of January 2005 we don't expect major protocol or API changes prior
61 to the 1.0 release, but anything is possible.
69 How is the reference implementation licensed? Can I use it in
70 proprietary applications?
75 The short answer is yes, you can use it in proprietary applications.
76 You should read the <ulink url="COPYING">COPYING</ulink> file, which
77 offers you the choice of two licenses. These are the GPL and the
78 AFL. The GPL requires that your application be licensed under the GPL
79 as well. The AFL is an "X-style" or "BSD-style" license compatible
80 with proprietary licensing, but it does have some requirements; in
81 particular it prohibits you from filing a lawsuit alleging that the
82 D-BUS software infringes your patents <emphasis>while you continue to
83 use D-BUS</emphasis>. If you're going to sue, you have to stop using
84 the software. Read the licenses to determine their meaning, this FAQ
85 entry is not intended to change the meaning or terms of the licenses.
93 What is the difference between a bus name, and object path,
99 If you imagine a C++ program that implements a network
100 service, then the bus name is the domain name
101 of the computer running this C++ program, the object path
102 is a C++ object instance pointer, and an interface is a C++
103 class (a pure virtual or abstract class, to be exact).
106 In Java terms, the object path is an object reference,
107 and an interface is a Java interface.
110 People get confused because if they write an application
111 with a single object instance and a single interface,
112 then the bus name, object path, and interface look
113 redundant. For example, you might have a text editor
114 that uses the bus name <literal>org.freedesktop.TextEditor</literal>,
115 has a global singleton object called
116 <literal>/org/freedesktop/TextEditor</literal>, and
117 that singleton object could implement the interface
118 <literal>org.freedesktop.TextEditor</literal>.
121 However, a text editor application could as easily own multiple bus
122 names (for example, <literal>org.kde.KWrite</literal>), have multiple
123 objects (maybe <literal>/org/kde/documents/4352</literal>),
124 and each object could implement multiple interfaces,
125 such as <literal>org.freedesktop.Introspectable</literal>,
126 <literal>org.freedesktop.BasicTextField</literal>,
127 <literal>org.kde.RichTextDocument</literal>.
133 <qandaentry id="service">
141 A service is a program that can be launched by the bus daemon
142 to provide some functionality to other programs. Services
143 are normally launched according to the bus name they will
149 <qandaentry id="components">
152 Is D-BUS a "component system"?
157 D-BUS is not a component system. "Component system" was originally
158 defined by COM, and was essentially a workaround for the limitations
159 of the C++ object system (adding introspection, runtime location of
160 objects, ABI guarantees, and so forth). With the C# language and CLR,
161 Microsoft added these features to the primary object system, leaving
162 COM obsolete. Similarly, Java has much less need for something like
163 COM than C++ did. Even QObject (from Qt) and GObject (from GLib) offer
164 some of the same features found in COM.
167 Component systems are not about GUI control embedding. Embedding
168 a spreadsheet in a word processor document is a matter of defining
169 some specific <emphasis>interfaces</emphasis> that objects
170 can implement. These interfaces provide methods related to
171 GUI controls. So an object implementing those interfaces
175 The word "component" just means "object with some fancy features" and
176 in modern languages all objects are effectively "components."
179 A third, orthogonal feature is interprocess communication or IPC.
180 D-BUS is an IPC system. Given an object (or "component" if you must),
181 you can expose the functionality of that object over an IPC system.
182 Examples of IPC systems are DCOM, CORBA, SOAP, XML-RPC, and D-BUS.
183 You can use any of these IPC systems with any object/component system,
184 though some of them are "tuned" for specific object systems.
185 You can think of an IPC system primarily as a wire protocol.
188 If you combine an IPC system with a set of GUI control interfaces,
189 then you can have an out-of-process or dynamically-loaded GUI control.
192 Summarizing, there are three orthogonal things:
196 Object/component system
201 Control embedding interfaces
206 Interprocess communication system or wire protocol
212 Another related concept is the <firstterm>plugin</firstterm> or
213 <firstterm>extension</firstterm>. Generic plugin systems such as the
214 <ulink url="http://eclipse.org">Eclipse</ulink> system are not so different
215 from component/object systems, though perhaps a "plugin" tends to be a
216 bundle of objects with a user-visible name and can be
217 downloaded/packaged as a unit.
222 <qandaentry id="speed">
225 How fast is the D-BUS reference implementation?
230 Of course it depends a bit on what you're doing.
231 <ulink url="http://lists.freedesktop.org/pipermail/dbus/2004-November/001779.html">
232 This mail</ulink> contains some benchmarking. At the time of that
233 benchmark, D-BUS one-to-one communication was about 2.5x slower than
234 simply pushing the data raw over a socket. After the recent rewrite of
235 the marshaling code, D-BUS is slower than that because a lot of
236 optimization work was lost. But it can probably be sped up again.
239 D-BUS communication with the intermediate bus daemon should be
240 (and as last profiled, was) about twice as slow as one-to-one
241 mode, because a round trip involves four socket reads/writes rather
242 than two socket reads/writes.
245 The overhead comes from a couple of places; part of it is simply
246 "abstraction penalty" (there are layers of code to support
247 multiple main loops, multiple transport types, security, etc.).
248 Probably the largest part comes from data validation
249 (because the reference implementation does not trust incoming data).
250 It would be simple to add a "no validation" mode, but probably
251 not a good idea all things considered.
254 Raw bandwidth isn't the only concern; D-BUS is designed to
255 enable asynchronous communication and avoid round trips.
256 This is frequently a more important performance issue
263 <qandaentry id="size">
266 How large is the D-BUS reference implementation?
271 A production build (with assertions, unit tests, and verbose logging
272 disabled) is on the order of a 150K shared library.
275 A much, much smaller implementation would be possible by omitting out
276 of memory handling, hardcoding a main loop (or always using blocking
277 I/O), skipping validation, and otherwise simplifying things.
282 <qandaentry id="other-ipc">
285 How does D-BUS differ from other interprocess communication
286 or networking protocols?
291 The best place to start is to read the D-BUS <ulink url="dbus-tutorial.html">tutorial</ulink>, so
292 you have a concrete idea what D-BUS actually is. If you
293 understand other protocols on a wire format level, you
294 may also want to read the D-BUS <ulink url="dbus-specification.html">specification</ulink> to see what
295 D-BUS looks like on a low level.
298 As the <ulink url="dbus-tutorial.html">tutorial</ulink> and <ulink url="dbus-specification.html">specification</ulink> both explain, D-BUS is tuned
299 for some specific use cases. Thus, it probably isn't tuned
300 for what you want to do, unless you are doing the things
301 D-BUS was designed for. Don't make the mistake of thinking
302 that any system labeled "IPC" is the same thing.
305 The D-BUS authors would not recommend using D-BUS
306 for applications where it doesn't make sense.
307 The following questions compare D-BUS to some other
308 protocols primarily to help you understand D-BUS
309 and decide whether it's appropriate; D-BUS is neither intended
310 nor claimed to be the right choice for every application.
313 It should be possible to bridge D-BUS to other IPC systems,
314 just as D-BUS can be bridged to object systems.
317 Note: the D-BUS mailing list subscribers are <emphasis>very much not
318 interested</emphasis> in debating which IPC system is the One True
319 System. So if you want to discuss that, please use another forum.
325 <qandaentry id="corba">
328 How does D-BUS differ from CORBA?
333 Start by reading <xref linkend="other-ipc"/>.
336 <ulink url="http://www.omg.org">CORBA</ulink> is designed to support
337 object-oriented IPC between objects, automatically marshalling
338 parameters as necessary. CORBA is strongly supported by the <ulink
339 url="http://www.omg.org">Open Management Group (OMG)</ulink>, which
340 produces various standards and supporting documents for CORBA and has
341 the backing of many large organizations. There are many CORBA ORBs
342 available, both proprietary ORBs and free / open source software ORBs
343 (the latter include <ulink
344 url="http://orbit-resource.sourceforge.net/">ORBit</ulink>, <ulink
345 url="http://www.mico.org/">MICO</ulink>, and <ulink
346 url="http://www.theaceorb.com/">The ACE Orb (TAO)</ulink>). Many
347 organizations continue to use CORBA ORBs for various kinds of IPC.
350 Both GNOME and KDE have used CORBA and then moved away from it. KDE
351 had more success with a system called DCOP, and GNOME layered a system
352 called Bonobo on top of CORBA. Without custom extensions, CORBA does
353 not support many of the things one wants to do in a desktop
354 environment with the GNOME/KDE architecture.
357 CORBA on the other hand has a number of features of interest for
358 enterprise and web application development, though XML systems such as
359 SOAP are the latest fad.
362 Like D-BUS, CORBA uses a fast binary protocol (IIOP). Both systems
363 work in terms of objects and methods, and have concepts such as
364 "oneway" calls. Only D-BUS has direct support for "signals" as in
365 GLib/Qt (or Java listeners, or C# delegates).
368 D-BUS hardcodes and specifies a lot of things that CORBA leaves open-ended,
369 because CORBA is more generic and D-BUS has two specific use-cases in mind.
370 This makes D-BUS a bit simpler.
373 However, unlike CORBA D-BUS does <emphasis>not</emphasis> specify the
374 API for the language bindings. Instead, "native" bindings adapted
375 specifically to the conventions of a framework such as QObject,
376 GObject, C#, Java, Python, etc. are encouraged. The libdbus reference
377 implementation is designed to be a backend for bindings of this
378 nature, rather than to be used directly. The rationale is that an IPC
379 system API should not "leak" all over a program; it should come into
380 play only just before data goes over the wire. As an aside, OMG is
381 apparently working on a simpler C++ binding for CORBA.
384 Many CORBA implementations such as ORBit are faster than the libdbus
385 reference implementation. One reason is that D-BUS considers data
386 from the other end of the connection to be untrusted and extensively
387 validates it. But generally speaking other priorities were placed
388 ahead of raw speed in the libdbus implementation. A fast D-BUS
389 implementation along the lines of ORBit should be possible, of course.
392 On a more trivial note, D-BUS involves substantially fewer acronyms
399 <qandaentry id="xmlrpcsoap">
402 How does D-BUS differ from XML-RPC and SOAP?
407 Start by reading <xref linkend="other-ipc"/>.
410 In <ulink url="http://www.w3.org/TR/SOAP/">SOAP</ulink> and <ulink
411 url="http://www.xmlrpc.com">XML-RPC</ulink>, RPC calls are transformed
412 into an XML-based format, then sent over the wire (typically using the
413 HTTP protocol), where they are processed and returned. XML-RPC is the
414 simple protocol (its spec is only a page or two), and SOAP is the
415 full-featured protocol.
418 XML-RPC and SOAP impose XML parsing overhead that is normally
419 irrelevant in the context of the Internet, but significant for
420 constant fine-grained IPC among applications in a desktop session.
423 D-BUS offers persistent connections and with the bus daemon
424 supports lifecycle tracking of other applications connected
425 to the bus. With XML-RPC and SOAP, typically each method call
426 exists in isolation and has its own HTTP connection.
431 <qandaentry id="dce">
434 How does D-BUS differ from DCE?
439 Start by reading <xref linkend="other-ipc"/>.
442 <ulink url="http://www.opengroup.org/dce/">Distributed Computing
443 Environment (DCE)</ulink> is an industry-standard vendor-neutral
444 standard that includes an IPC mechanism. <ulink
445 url="http://www.opengroup.org/comm/press/05-01-12.htm">The Open Group
446 has released an implementation as open source software</ulink>. DCE
447 is quite capable, and includes a vast amount of functionality such as
448 a distributed time service. As the name implies, DCE is intended for
449 use in a large, multi-computer distributed application. D-BUS would
450 not be well-suited for this.
456 <qandaentry id="dcom">
459 How does D-BUS differ from DCOM and COM?
464 Start by reading <xref linkend="other-ipc"/>.
467 Comparing D-BUS to COM is apples and oranges;
468 see <xref linkend="components"/>.
471 DCOM (distributed COM) is a Windows IPC system designed for use with
472 the COM object system. It's similar in some ways to DCE and CORBA.
477 <qandaentry id="internet-communications-engine">
480 How does D-BUS differ from ZeroC's Internet Communications Engine (Ice)
485 Start by reading <xref linkend="other-ipc"/>.
488 The <ulink url="http://www.zeroc.com/ice.html"> Internet
489 Communications Engine (Ice)</ulink> is a powerful IPC mechanism more
490 on the level of SOAP or CORBA than D-BUS. Ice has a "dual-license"
491 business around it; i.e. you can use it under the GPL, or pay for a
497 <qandaentry id="inter-client-exchange">
500 How does D-BUS differ from Inter-Client Exchange (ICE)?
505 <ulink url="http://www.x.org/X11R6.8.1/docs/ICE/ice.pdf">ICE</ulink>
506 was developed for the X Session Management protocol (XSMP), as part of
507 the X Window System (X11R6.1). The idea was to allow desktop sessions
508 to contain nongraphical clients in addition to X clients.
511 ICE is a binary protocol designed for desktop use, and KDE's DCOP
512 builds on ICE. ICE is substantially simpler than D-BUS (in contrast
513 to most of the other IPC systems mentioned here, which are more
514 complex). ICE doesn't really define a mapping to objects and methods
515 (DCOP adds that layer). The reference implementation of ICE (libICE)
516 is often considered to be horrible (and horribly insecure).
519 DCOP and XSMP are the only two widely-used applications of ICE,
520 and both could in principle be replaced by D-BUS. (Though whether
521 GNOME and KDE will bother is an open question.)
528 <qandaentry id="dcop">
531 How does D-BUS differ from DCOP?
536 Start by reading <xref linkend="other-ipc"/>.
539 D-BUS is intentionally pretty similar to <ulink
540 url="http://developer.kde.org/documentation/library/kdeqt/dcop.html">DCOP</ulink>,
541 and can be thought of as a "DCOP the next generation" suitable for
542 sharing between the various open source desktop projects.
545 D-BUS is a bit more complex than DCOP, though the Qt binding for D-BUS
546 should not be more complex for programmers. The additional complexity
547 of D-BUS arises from its separation of object references vs. bus names
548 vs. interfaces as distinct concepts, and its support for one-to-one
549 connections in addition to connections over the bus. The libdbus
550 reference implementation has a lot of API to support multiple bindings
551 and main loops, and performs data validation and out-of-memory handling
552 in order to support secure applications such as the systemwide bus.
555 D-BUS is probably somewhat slower than DCOP due to data validation
556 and more "layers" in the reference implementation. A comparison
557 hasn't been posted to the list though.
560 At this time, KDE has not committed to using D-BUS, but there have
561 been discussions of KDE bridging D-BUS and DCOP, or even changing
562 DCOP's implementation to use D-BUS internally (so that GNOME and KDE
563 would end up using exactly the same bus). See the KDE mailing list
564 archives for some of these discussions.
570 <qandaentry id="yet-more-ipc">
573 How does D-BUS differ from [yet more IPC mechanisms]?
578 Start by reading <xref linkend="other-ipc"/>.
581 There are countless uses of network sockets in the world. <ulink
582 url="http://www.mbus.org/">MBUS</ulink>, Sun ONC/RPC, Jabber/XMPP,
583 SIP, are some we can think of quickly.
589 <qandaentry id="which-ipc">
592 Which IPC mechanism should I use?
597 Start by reading <xref linkend="other-ipc"/>.
600 If you're writing an Internet or Intranet application, XML-RPC or SOAP
601 work for many people. These are standard, available for most
602 languages, simple to debug and easy to use.
605 If you're writing a desktop application for UNIX,
606 then D-BUS is of course our recommendation for
607 talking to other parts of the desktop session.
608 (With the caveat that you should use a stable release
609 of D-BUS; until we reach 1.0, there isn't a stable release.)
612 If you're doing something complicated such as clustering,
613 distributed swarms, peer-to-peer, or whatever then
614 the authors of this FAQ don't have expertise in these
615 areas and you should ask someone else or try a search engine.
618 Note: the D-BUS mailing list is probably not the place to
619 discuss which system is appropriate for your application,
620 though you are welcome to ask specific questions about
621 D-BUS <emphasis>after reading this FAQ, the tutorial, and
622 searching the list archives</emphasis>. The best way
623 to search the list archives is probably to use
624 an Internet engine such as Google. On Google,
625 include "site:freedesktop.org" in your search.
634 How can I submit a bug or patch?
639 The D-BUS <ulink url="http://dbus.freedesktop.org">web site</ulink>
640 has a link to the bug tracker, which is the best place to store
641 patches. You can also post them to the list, especially if you want
642 to discuss the patch or get feedback.