doc/dbus-faq.xml

   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"
   4 [
   5 ]>
   6
   7 <article id="index">
   8   <articleinfo>
   9     <title>D-Bus FAQ</title>
  10     <releaseinfo>Version 0.1</releaseinfo>
  11     <date>22 January 2005</date>
  12     <authorgroup>
  13       <author>
  14         <firstname>Havoc</firstname>
  15         <surname>Pennington</surname>
  16         <affiliation>
  17           <orgname>Red Hat, Inc.</orgname>
  18           <address>
  19             <email>hp@pobox.com</email>
  20           </address>
  21         </affiliation>
  22       </author>
  23       <author>
  24         <firstname>David</firstname>
  25         <othername role="mi">A</othername>
  26         <surname>Wheeler</surname>
  27       </author>
  28     </authorgroup>
  29   </articleinfo>
  30
  31   <qandaset id="faq">
  32
  33     <qandaentry>
  34       <question>
  35         <para>
  36           What is D-Bus?
  37         </para>
  38       </question>
  39       <answer>
  40         <para>
  41           This is probably best answered by reading the D-Bus <ulink url="dbus-tutorial.html">tutorial</ulink>. In
  42           short, it is a system consisting of 1) a wire protocol for exposing a
  43           typical object-oriented language/framework to other applications; and
  44           2) a bus daemon that allows applications to find and monitor one another.
  45         </para>
  46       </answer>
  47     </qandaentry>
  48
  49     <qandaentry>
  50       <question>
  51         <para>
  52           Is D-Bus stable/finished?
  53         </para>
  54       </question>
  55       <answer>
  56         <para>
  57           D-Bus has not yet reached 1.0. The <ulink url="README">README</ulink>
  58           file has a discussion of the API/ABI stability guarantees before and
  59           after 1.0. In short, there are no guarantees before 1.0, and stability
  60           of both protocol and reference library will be maintained after 1.0.
  61           As of January 2005 we don't expect major protocol or API changes prior
  62           to the 1.0 release, but anything is possible.
  63         </para>
  64       </answer>
  65     </qandaentry>
  66
  67     <qandaentry>
  68       <question>
  69         <para>
  70           How is the reference implementation licensed? Can I use it in
  71           proprietary applications?
  72         </para>
  73       </question>
  74       <answer>
  75         <para>
  76           The short answer is yes, you can use it in proprietary applications.
  77           You should read the <ulink url="COPYING">COPYING</ulink> file, which
  78           offers you the choice of two licenses. These are the GPL and the
  79           AFL. The GPL requires that your application be licensed under the GPL
  80           as well. The AFL is an "X-style" or "BSD-style" license compatible
  81           with proprietary licensing, but it does have some requirements; in
  82           particular it prohibits you from filing a lawsuit alleging that the
  83           D-Bus software infringes your patents <emphasis>while you continue to
  84           use D-Bus</emphasis>.  If you're going to sue, you have to stop using
  85           the software. Read the licenses to determine their meaning, this FAQ
  86           entry is not intended to change the meaning or terms of the licenses.
  87         </para>
  88       </answer>
  89     </qandaentry>
  90
  91     <qandaentry>
  92       <question>
  93         <para>
  94           What is the difference between a bus name, and object path,
  95           and an interface?
  96         </para>
  97       </question>
  98       <answer>
  99         <para>
 100           If you imagine a C++ program that implements a network service, then
 101           the bus name is the hostname of the computer running this C++ program,
 102           the object path is a C++ object instance pointer, and an interface is
 103           a C++ class (a pure virtual or abstract class, to be exact).
 104         </para>
 105         <para>
 106           In Java terms, the object path is an object reference,
 107           and an interface is a Java interface.
 108         </para>
 109         <para>
 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>.
 119         </para>
 120         <para>
 121           However, a text editor application could as easily own multiple bus
 122           names (for example, <literal>org.kde.KWrite</literal> in addition to
 123           generic <literal>TextEditor</literal>), have multiple objects (maybe
 124           <literal>/org/kde/documents/4352</literal> where the number changes
 125           according to the document), and each object could implement multiple
 126           interfaces, such as <literal>org.freedesktop.DBus.Introspectable</literal>,
 127           <literal>org.freedesktop.BasicTextField</literal>,
 128           <literal>org.kde.RichTextDocument</literal>.
 129         </para>
 130       </answer>
 131     </qandaentry>
 132
 133
 134     <qandaentry id="service">
 135       <question>
 136         <para>
 137           What is a "service"?
 138         </para>
 139       </question>
 140       <answer>
 141         <para>
 142           A service is a program that can be launched by the bus daemon
 143           to provide some functionality to other programs. Services
 144           are normally launched according to the bus name they will
 145           have.
 146         </para>
 147       </answer>
 148     </qandaentry>
 149
 150     <qandaentry id="components">
 151       <question>
 152         <para>
 153           Is D-Bus a "component system"?
 154         </para>
 155       </question>
 156       <answer>
 157         <para>
 158           It helps to keep these concepts separate in your mind:
 159           <orderedlist>
 160             <listitem>
 161               <para>
 162                 Object/component system
 163               </para>
 164             </listitem>
 165             <listitem>
 166               <para>
 167                 GUI control/widget embedding interfaces
 168               </para>
 169             </listitem>
 170             <listitem>
 171               <para>
 172                 Interprocess communication system or wire protocol
 173               </para>
 174             </listitem>
 175           </orderedlist>
 176         </para>
 177         <para>
 178           D-Bus is not a component system. "Component system" was originally
 179           defined by COM, and was essentially a workaround for the limitations
 180           of the C++ object system (adding introspection, runtime location of
 181           objects, ABI guarantees, and so forth). With the C# language and CLR,
 182           Microsoft added these features to the primary object system, leaving
 183           COM obsolete. Similarly, Java has much less need for something like
 184           COM than C++ did. Even QObject (from Qt) and GObject (from GLib) offer
 185           some of the same features found in COM.
 186         </para>
 187         <para>
 188           Component systems are not about GUI control embedding. Embedding
 189           a spreadsheet in a word processor document is a matter of defining
 190           some specific <emphasis>interfaces</emphasis> that objects
 191           can implement. These interfaces provide methods related to
 192           GUI controls. So an object implementing those interfaces
 193           can be embedded.
 194         </para>
 195         <para>
 196           The word "component" just means "object with some fancy features" and
 197           in modern languages all objects are effectively "components."
 198         </para>
 199         <para>
 200           So components are fancy objects, and some objects are GUI controls.
 201         </para>
 202         <para>
 203           A third, unrelated feature is interprocess communication or IPC.
 204           D-Bus is an IPC system. Given an object (or "component" if you must),
 205           you can expose the functionality of that object over an IPC system.
 206           Examples of IPC systems are DCOM, CORBA, SOAP, XML-RPC, and D-Bus.
 207           You can use any of these IPC systems with any object/component system,
 208           though some of them are "tuned" for specific object systems.
 209           You can think of an IPC system primarily as a wire protocol.
 210         </para>
 211         <para>
 212           If you combine an IPC system with a set of GUI control interfaces,
 213           then you can have an out-of-process or dynamically-loaded GUI control.
 214         </para>
 215         <para>
 216           Another related concept is the <firstterm>plugin</firstterm> or
 217           <firstterm>extension</firstterm>.  Generic plugin systems such as the
 218           <ulink url="http://eclipse.org">Eclipse</ulink> system are not so different
 219           from component/object systems, though perhaps a "plugin" tends to be a
 220           bundle of objects with a user-visible name and can be
 221           downloaded/packaged as a unit.
 222         </para>
 223       </answer>
 224     </qandaentry>
 225
 226     <qandaentry id="speed">
 227       <question>
 228         <para>
 229           How fast is the D-Bus reference implementation?
 230         </para>
 231       </question>
 232       <answer>
 233         <para>
 234           Of course it depends a bit on what you're doing.
 235           <ulink url="http://lists.freedesktop.org/pipermail/dbus/2004-November/001779.html">
 236             This mail</ulink> contains some benchmarking.  At the time of that
 237           benchmark, D-Bus one-to-one communication was about 2.5x slower than
 238           simply pushing the data raw over a socket. After the recent rewrite of
 239           the marshaling code, D-Bus is slower than that because a lot of
 240           optimization work was lost. But it can probably be sped up again.
 241         </para>
 242         <para>
 243           D-Bus communication with the intermediate bus daemon should be
 244           (and as last profiled, was) about twice as slow as one-to-one
 245           mode, because a round trip involves four socket reads/writes rather
 246           than two socket reads/writes.
 247         </para>
 248         <para>
 249           The overhead comes from a couple of places; part of it is simply
 250           "abstraction penalty" (there are layers of code to support
 251           multiple main loops, multiple transport types, security, etc.).
 252           Probably the largest part comes from data validation
 253           (because the reference implementation does not trust incoming data).
 254           It would be simple to add a "no validation" mode, but probably
 255           not a good idea all things considered.
 256         </para>
 257         <para>
 258           Raw bandwidth isn't the only concern; D-Bus is designed to
 259           enable asynchronous communication and avoid round trips.
 260           This is frequently a more important performance issue
 261           than throughput.
 262         </para>
 263       </answer>
 264     </qandaentry>
 265
 266
 267     <qandaentry id="size">
 268       <question>
 269         <para>
 270           How large is the D-Bus reference implementation?
 271         </para>
 272       </question>
 273       <answer>
 274         <para>
 275           A production build (with assertions, unit tests, and verbose logging
 276           disabled) is on the order of a 150K shared library.
 277         </para>
 278         <para>
 279           A much, much smaller implementation would be possible by omitting out
 280           of memory handling, hardcoding a main loop (or always using blocking
 281           I/O), skipping validation, and otherwise simplifying things.
 282         </para>
 283       </answer>
 284     </qandaentry>
 285
 286     <qandaentry id="other-ipc">
 287       <question>
 288         <para>
 289           How does D-Bus differ from other interprocess communication
 290           or networking protocols?
 291         </para>
 292       </question>
 293       <answer>
 294         <para>
 295           The best place to start is to read the D-Bus <ulink url="dbus-tutorial.html">tutorial</ulink>, so
 296           you have a concrete idea what D-Bus actually is. If you
 297           understand other protocols on a wire format level, you
 298           may also want to read the D-Bus <ulink url="dbus-specification.html">specification</ulink> to see what
 299           D-Bus looks like on a low level.
 300         </para>
 301         <para>
 302           As the <ulink url="dbus-tutorial.html">tutorial</ulink> and <ulink url="dbus-specification.html">specification</ulink> both explain, D-Bus is tuned
 303           for some specific use cases. Thus, it probably isn't tuned
 304           for what you want to do, unless you are doing the things
 305           D-Bus was designed for. Don't make the mistake of thinking
 306           that any system labeled "IPC" is the same thing.
 307         </para>
 308         <para>
 309           The D-Bus authors would not recommend using D-Bus
 310           for applications where it doesn't make sense.
 311           The following questions compare D-Bus to some other
 312           protocols primarily to help you understand D-Bus
 313           and decide whether it's appropriate; D-Bus is neither intended
 314           nor claimed to be the right choice for every application.
 315         </para>
 316         <para>
 317           It should be possible to bridge D-Bus to other IPC systems,
 318           just as D-Bus can be bridged to object systems.
 319         </para>
 320         <para>
 321           Note: the D-Bus mailing list subscribers are <emphasis>very much not
 322           interested</emphasis> in debating which IPC system is the One True
 323           System. So if you want to discuss that, please use another forum.
 324         </para>
 325       </answer>
 326     </qandaentry>
 327
 328
 329     <qandaentry id="corba">
 330       <question>
 331         <para>
 332           How does D-Bus differ from CORBA?
 333         </para>
 334       </question>
 335       <answer>
 336         <para>
 337           Start by reading <xref linkend="other-ipc"/>.
 338         </para>
 339         <para>
 340           <ulink url="http://www.omg.org">CORBA</ulink> is designed to support
 341          object-oriented IPC between objects, automatically marshalling
 342          parameters as necessary. CORBA is strongly supported by the <ulink
 343          url="http://www.omg.org">Open Management Group (OMG)</ulink>, which
 344          produces various standards and supporting documents for CORBA and has
 345          the backing of many large organizations.  There are many CORBA ORBs
 346          available, both proprietary ORBs and free / open source software ORBs
 347          (the latter include <ulink
 348          url="http://orbit-resource.sourceforge.net/">ORBit</ulink>, <ulink
 349          url="http://www.mico.org/">MICO</ulink>, and <ulink
 350          url="http://www.theaceorb.com/">The ACE Orb (TAO)</ulink>).  Many
 351          organizations continue to use CORBA ORBs for various kinds of IPC.
 352         </para>
 353         <para>
 354           Both GNOME and KDE have used CORBA and then moved away from it.  KDE
 355           had more success with a system called DCOP, and GNOME layered a system
 356           called Bonobo on top of CORBA. Without custom extensions, CORBA does
 357           not support many of the things one wants to do in a desktop
 358           environment with the GNOME/KDE architecture.
 359         </para>
 360         <para>
 361           CORBA on the other hand has a number of features of interest for
 362           enterprise and web application development, though XML systems such as
 363           SOAP are the latest fad.
 364         </para>
 365         <para>
 366           Like D-Bus, CORBA uses a fast binary protocol (IIOP). Both systems
 367           work in terms of objects and methods, and have concepts such as
 368           "oneway" calls. Only D-Bus has direct support for "signals" as in
 369           GLib/Qt (or Java listeners, or C# delegates).
 370         </para>
 371         <para>
 372           D-Bus hardcodes and specifies a lot of things that CORBA leaves open-ended,
 373           because CORBA is more generic and D-Bus has two specific use-cases in mind.
 374           This makes D-Bus a bit simpler.
 375         </para>
 376         <para>
 377           However, unlike CORBA D-Bus does <emphasis>not</emphasis> specify the
 378           API for the language bindings. Instead, "native" bindings adapted
 379           specifically to the conventions of a framework such as QObject,
 380           GObject, C#, Java, Python, etc. are encouraged. The libdbus reference
 381           implementation is designed to be a backend for bindings of this
 382           nature, rather than to be used directly. The rationale is that an IPC
 383           system API should not "leak" all over a program; it should come into
 384           play only just before data goes over the wire. As an aside, OMG is
 385           apparently working on a simpler C++ binding for CORBA.
 386         </para>
 387         <para>
 388           Many CORBA implementations such as ORBit are faster than the libdbus
 389           reference implementation.  One reason is that D-Bus considers data
 390           from the other end of the connection to be untrusted and extensively
 391           validates it. But generally speaking other priorities were placed
 392           ahead of raw speed in the libdbus implementation. A fast D-Bus
 393           implementation along the lines of ORBit should be possible, of course.
 394         </para>
 395         <para>
 396           On a more trivial note, D-Bus involves substantially fewer acronyms
 397           than CORBA.
 398         </para>
 399       </answer>
 400     </qandaentry>
 401
 402
 403     <qandaentry id="xmlrpcsoap">
 404       <question>
 405         <para>
 406           How does D-Bus differ from XML-RPC and SOAP?
 407         </para>
 408       </question>
 409       <answer>
 410         <para>
 411           Start by reading <xref linkend="other-ipc"/>.
 412         </para>
 413         <para>
 414           In <ulink url="http://www.w3.org/TR/SOAP/">SOAP</ulink> and <ulink
 415             url="http://www.xmlrpc.com">XML-RPC</ulink>, RPC calls are transformed
 416           into an XML-based format, then sent over the wire (typically using the
 417           HTTP protocol), where they are processed and returned.  XML-RPC is the
 418           simple protocol (its spec is only a page or two), and SOAP is the
 419           full-featured protocol.
 420         </para>
 421         <para>
 422           XML-RPC and SOAP impose XML parsing overhead that is normally
 423           irrelevant in the context of the Internet, but significant for
 424           constant fine-grained IPC among applications in a desktop session.
 425         </para>
 426         <para>
 427           D-Bus offers persistent connections and with the bus daemon
 428           supports lifecycle tracking of other applications connected
 429           to the bus. With XML-RPC and SOAP, typically each method call
 430           exists in isolation and has its own HTTP connection.
 431         </para>
 432       </answer>
 433     </qandaentry>
 434
 435     <qandaentry id="dce">
 436       <question>
 437         <para>
 438           How does D-Bus differ from DCE?
 439         </para>
 440       </question>
 441       <answer>
 442         <para>
 443           Start by reading <xref linkend="other-ipc"/>.
 444         </para>
 445         <para>
 446           <ulink url="http://www.opengroup.org/dce/">Distributed Computing
 447           Environment (DCE)</ulink> is an industry-standard vendor-neutral
 448           standard that includes an IPC mechanism.  <ulink
 449           url="http://www.opengroup.org/comm/press/05-01-12.htm">The Open Group
 450           has released an implementation as open source software</ulink>.  DCE
 451           is quite capable, and includes a vast amount of functionality such as
 452           a distributed time service.  As the name implies, DCE is intended for
 453           use in a large, multi-computer distributed application. D-Bus would
 454           not be well-suited for this.
 455         </para>
 456       </answer>
 457     </qandaentry>
 458
 459
 460     <qandaentry id="dcom">
 461       <question>
 462         <para>
 463           How does D-Bus differ from DCOM and COM?
 464         </para>
 465       </question>
 466       <answer>
 467         <para>
 468           Start by reading <xref linkend="other-ipc"/>.
 469         </para>
 470         <para>
 471           Comparing D-Bus to COM is apples and oranges;
 472           see <xref linkend="components"/>.
 473         </para>
 474         <para>
 475           DCOM (distributed COM) is a Windows IPC system designed for use with
 476           the COM object system. It's similar in some ways to DCE and CORBA.
 477         </para>
 478       </answer>
 479     </qandaentry>
 480
 481     <qandaentry id="internet-communications-engine">
 482       <question>
 483         <para>
 484           How does D-Bus differ from ZeroC's Internet Communications Engine (Ice)
 485         </para>
 486       </question>
 487       <answer>
 488         <para>
 489           Start by reading <xref linkend="other-ipc"/>.
 490         </para>
 491         <para>
 492           The <ulink url="http://www.zeroc.com/ice.html"> Internet
 493           Communications Engine (Ice)</ulink> is a powerful IPC mechanism more
 494           on the level of SOAP or CORBA than D-Bus.  Ice has a "dual-license"
 495           business around it; i.e. you can use it under the GPL, or pay for a
 496           proprietary license.
 497         </para>
 498       </answer>
 499     </qandaentry>
 500
 501     <qandaentry id="inter-client-exchange">
 502       <question>
 503         <para>
 504           How does D-Bus differ from Inter-Client Exchange (ICE)?
 505         </para>
 506       </question>
 507       <answer>
 508         <para>
 509           <ulink url="http://www.x.org/X11R6.8.1/docs/ICE/ice.pdf">ICE</ulink>
 510           was developed for the X Session Management protocol (XSMP), as part of
 511           the X Window System (X11R6.1). The idea was to allow desktop sessions
 512           to contain nongraphical clients in addition to X clients.
 513         </para>
 514         <para>
 515           ICE is a binary protocol designed for desktop use, and KDE's DCOP
 516           builds on ICE.  ICE is substantially simpler than D-Bus (in contrast
 517           to most of the other IPC systems mentioned here, which are more
 518           complex). ICE doesn't really define a mapping to objects and methods
 519           (DCOP adds that layer).  The reference implementation of ICE (libICE)
 520           is often considered to be horrible (and horribly insecure).
 521         </para>
 522         <para>
 523           DCOP and XSMP are the only two widely-used applications of ICE,
 524           and both could in principle be replaced by D-Bus. (Though whether
 525           GNOME and KDE will bother is an open question.)
 526         </para>
 527       </answer>
 528     </qandaentry>
 529
 530
 531
 532     <qandaentry id="dcop">
 533       <question>
 534         <para>
 535           How does D-Bus differ from DCOP?
 536         </para>
 537       </question>
 538       <answer>
 539         <para>
 540           Start by reading <xref linkend="other-ipc"/>.
 541         </para>
 542         <para>
 543           D-Bus is intentionally pretty similar to <ulink
 544           url="http://developer.kde.org/documentation/library/kdeqt/dcop.html">DCOP</ulink>,
 545           and can be thought of as a "DCOP the next generation" suitable for
 546           sharing between the various open source desktop projects.
 547         </para>
 548         <para>
 549           D-Bus is a bit more complex than DCOP, though the Qt binding for D-Bus
 550           should not be more complex for programmers. The additional complexity
 551           of D-Bus arises from its separation of object references vs. bus names
 552           vs. interfaces as distinct concepts, and its support for one-to-one
 553           connections in addition to connections over the bus. The libdbus
 554           reference implementation has a lot of API to support multiple bindings
 555           and main loops, and performs data validation and out-of-memory handling
 556           in order to support secure applications such as the systemwide bus.
 557         </para>
 558         <para>
 559           D-Bus is probably somewhat slower than DCOP due to data validation
 560           and more "layers" in the reference implementation. A comparison
 561           hasn't been posted to the list though.
 562         </para>
 563         <para>
 564           At this time, KDE has not committed to using D-Bus, but there have
 565           been discussions of KDE bridging D-Bus and DCOP, or even changing
 566           DCOP's implementation to use D-Bus internally (so that GNOME and KDE
 567           would end up using exactly the same bus). See the KDE mailing list
 568           archives for some of these discussions.
 569         </para>
 570       </answer>
 571     </qandaentry>
 572
 573
 574     <qandaentry id="yet-more-ipc">
 575       <question>
 576         <para>
 577           How does D-Bus differ from [yet more IPC mechanisms]?
 578         </para>
 579       </question>
 580       <answer>
 581         <para>
 582           Start by reading <xref linkend="other-ipc"/>.
 583         </para>
 584         <para>
 585           There are countless uses of network sockets in the world.  <ulink
 586           url="http://www.mbus.org/">MBUS</ulink>, Sun ONC/RPC, Jabber/XMPP,
 587           SIP, are some we can think of quickly.
 588         </para>
 589       </answer>
 590     </qandaentry>
 591
 592
 593     <qandaentry id="which-ipc">
 594       <question>
 595         <para>
 596           Which IPC mechanism should I use?
 597         </para>
 598       </question>
 599       <answer>
 600         <para>
 601           Start by reading <xref linkend="other-ipc"/>.
 602         </para>
 603         <para>
 604           If you're writing an Internet or Intranet application, XML-RPC or SOAP
 605           work for many people. These are standard, available for most
 606           languages, simple to debug and easy to use.
 607         </para>
 608         <para>
 609           If you're writing a desktop application for UNIX,
 610           then D-Bus is of course our recommendation for
 611           talking to other parts of the desktop session.
 612           (With the caveat that you should use a stable release
 613           of D-Bus; until we reach 1.0, there isn't a stable release.)
 614         </para>
 615         <para>
 616           If you're doing something complicated such as clustering,
 617           distributed swarms, peer-to-peer, or whatever then
 618           the authors of this FAQ don't have expertise in these
 619           areas and you should ask someone else or try a search engine.
 620         </para>
 621         <para>
 622           Note: the D-Bus mailing list is probably not the place to
 623           discuss which system is appropriate for your application,
 624           though you are welcome to ask specific questions about
 625           D-Bus <emphasis>after reading this FAQ, the tutorial, and
 626             searching the list archives</emphasis>. The best way
 627           to search the list archives is probably to use
 628           an Internet engine such as Google. On Google,
 629           include "site:freedesktop.org" in your search.
 630         </para>
 631       </answer>
 632     </qandaentry>
 633
 634
 635     <qandaentry>
 636       <question>
 637         <para>
 638           How can I submit a bug or patch?
 639         </para>
 640       </question>
 641       <answer>
 642         <para>
 643           The D-Bus <ulink url="http://dbus.freedesktop.org">web site</ulink>
 644           has a link to the bug tracker, which is the best place to store
 645           patches.  You can also post them to the list, especially if you want
 646           to discuss the patch or get feedback.
 647         </para>
 648       </answer>
 649     </qandaentry>
 650
 651   </qandaset>
 652
 653 </article>