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