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         <surname>Wheeler</surname>
  26       </author>
  27     </authorgroup>
  28   </articleinfo>
  29
  30   <qandaset id="faq">
  31
  32     <qandaentry>
  33       <question>
  34         <para>
  35           What is D-BUS?
  36         </para>
  37       </question>
  38       <answer>
  39         <para>
  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.
  44         </para>
  45       </answer>
  46     </qandaentry>
  47
  48     <qandaentry>
  49       <question>
  50         <para>
  51           Is D-BUS stable/finished?
  52         </para>
  53       </question>
  54       <answer>
  55         <para>
  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.
  62         </para>
  63       </answer>
  64     </qandaentry>
  65
  66     <qandaentry>
  67       <question>
  68         <para>
  69           How is the reference implementation licensed? Can I use it in
  70           proprietary applications?
  71         </para>
  72       </question>
  73       <answer>
  74         <para>
  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.
  86         </para>
  87       </answer>
  88     </qandaentry>
  89
  90     <qandaentry>
  91       <question>
  92         <para>
  93           What is the difference between a bus name, and object path,
  94           and an interface?
  95         </para>
  96       </question>
  97       <answer>
  98         <para>
  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).
 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>), 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>.
 128         </para>
 129       </answer>
 130     </qandaentry>
 131
 132
 133     <qandaentry id="service">
 134       <question>
 135         <para>
 136           What is a "service"?
 137         </para>
 138       </question>
 139       <answer>
 140         <para>
 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
 144           have.
 145         </para>
 146       </answer>
 147     </qandaentry>
 148
 149     <qandaentry id="components">
 150       <question>
 151         <para>
 152           Is D-BUS a "component system"?
 153         </para>
 154       </question>
 155       <answer>
 156         <para>
 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.
 165         </para>
 166         <para>
 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
 172           can be embedded.
 173         </para>
 174         <para>
 175           The word "component" just means "object with some fancy features" and
 176           in modern languages all objects are effectively "components."
 177         </para>
 178         <para>
 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.
 186         </para>
 187         <para>
 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.
 190         </para>
 191         <para>
 192           Summarizing, there are three orthogonal things:
 193           <orderedlist>
 194             <listitem>
 195               <para>
 196                 Object/component system
 197               </para>
 198             </listitem>
 199             <listitem>
 200               <para>
 201                 Control embedding interfaces
 202               </para>
 203             </listitem>
 204             <listitem>
 205               <para>
 206                 Interprocess communication system or wire protocol
 207               </para>
 208             </listitem>
 209           </orderedlist>
 210         </para>
 211         <para>
 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.
 218         </para>
 219       </answer>
 220     </qandaentry>
 221
 222     <qandaentry id="speed">
 223       <question>
 224         <para>
 225           How fast is the D-BUS reference implementation?
 226         </para>
 227       </question>
 228       <answer>
 229         <para>
 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.
 237         </para>
 238         <para>
 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.
 243         </para>
 244         <para>
 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.
 252         </para>
 253         <para>
 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
 257           than throughput.
 258         </para>
 259       </answer>
 260     </qandaentry>
 261
 262
 263     <qandaentry id="size">
 264       <question>
 265         <para>
 266           How large is the D-BUS reference implementation?
 267         </para>
 268       </question>
 269       <answer>
 270         <para>
 271           A production build (with assertions, unit tests, and verbose logging
 272           disabled) is on the order of a 150K shared library.
 273         </para>
 274         <para>
 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.
 278         </para>
 279       </answer>
 280     </qandaentry>
 281
 282     <qandaentry id="other-ipc">
 283       <question>
 284         <para>
 285           How does D-BUS differ from other interprocess communication
 286           or networking protocols?
 287         </para>
 288       </question>
 289       <answer>
 290         <para>
 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.
 296         </para>
 297         <para>
 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.
 303         </para>
 304         <para>
 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.
 311         </para>
 312         <para>
 313           It should be possible to bridge D-BUS to other IPC systems,
 314           just as D-BUS can be bridged to object systems.
 315         </para>
 316         <para>
 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.
 320         </para>
 321       </answer>
 322     </qandaentry>
 323
 324
 325     <qandaentry id="corba">
 326       <question>
 327         <para>
 328           How does D-BUS differ from CORBA?
 329         </para>
 330       </question>
 331       <answer>
 332         <para>
 333           Start by reading <xref linkend="other-ipc"/>.
 334         </para>
 335         <para>
 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.
 348         </para>
 349         <para>
 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.
 355         </para>
 356         <para>
 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.
 360         </para>
 361         <para>
 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).
 366         </para>
 367         <para>
 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.
 371         </para>
 372         <para>
 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.
 382         </para>
 383         <para>
 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.
 390         </para>
 391         <para>
 392           On a more trivial note, D-BUS involves substantially fewer acronyms
 393           than CORBA.
 394         </para>
 395       </answer>
 396     </qandaentry>
 397
 398
 399     <qandaentry id="xmlrpcsoap">
 400       <question>
 401         <para>
 402           How does D-BUS differ from XML-RPC and SOAP?
 403         </para>
 404       </question>
 405       <answer>
 406         <para>
 407           Start by reading <xref linkend="other-ipc"/>.
 408         </para>
 409         <para>
 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.
 416         </para>
 417         <para>
 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.
 421         </para>
 422         <para>
 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.
 427         </para>
 428       </answer>
 429     </qandaentry>
 430
 431     <qandaentry id="dce">
 432       <question>
 433         <para>
 434           How does D-BUS differ from DCE?
 435         </para>
 436       </question>
 437       <answer>
 438         <para>
 439           Start by reading <xref linkend="other-ipc"/>.
 440         </para>
 441         <para>
 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.
 451         </para>
 452       </answer>
 453     </qandaentry>
 454
 455
 456     <qandaentry id="dcom">
 457       <question>
 458         <para>
 459           How does D-BUS differ from DCOM and COM?
 460         </para>
 461       </question>
 462       <answer>
 463         <para>
 464           Start by reading <xref linkend="other-ipc"/>.
 465         </para>
 466         <para>
 467           Comparing D-BUS to COM is apples and oranges;
 468           see <xref linkend="components"/>.
 469         </para>
 470         <para>
 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.
 473         </para>
 474       </answer>
 475     </qandaentry>
 476
 477     <qandaentry id="internet-communications-engine">
 478       <question>
 479         <para>
 480           How does D-BUS differ from ZeroC's Internet Communications Engine (Ice)
 481         </para>
 482       </question>
 483       <answer>
 484         <para>
 485           Start by reading <xref linkend="other-ipc"/>.
 486         </para>
 487         <para>
 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
 492           proprietary license.
 493         </para>
 494       </answer>
 495     </qandaentry>
 496
 497     <qandaentry id="inter-client-exchange">
 498       <question>
 499         <para>
 500           How does D-BUS differ from Inter-Client Exchange (ICE)?
 501         </para>
 502       </question>
 503       <answer>
 504         <para>
 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.
 509         </para>
 510         <para>
 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).
 517         </para>
 518         <para>
 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.)
 522         </para>
 523       </answer>
 524     </qandaentry>
 525
 526
 527
 528     <qandaentry id="dcop">
 529       <question>
 530         <para>
 531           How does D-BUS differ from DCOP?
 532         </para>
 533       </question>
 534       <answer>
 535         <para>
 536           Start by reading <xref linkend="other-ipc"/>.
 537         </para>
 538         <para>
 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.
 543         </para>
 544         <para>
 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.
 553         </para>
 554         <para>
 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.
 558         </para>
 559         <para>
 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.
 565         </para>
 566       </answer>
 567     </qandaentry>
 568
 569
 570     <qandaentry id="yet-more-ipc">
 571       <question>
 572         <para>
 573           How does D-BUS differ from [yet more IPC mechanisms]?
 574         </para>
 575       </question>
 576       <answer>
 577         <para>
 578           Start by reading <xref linkend="other-ipc"/>.
 579         </para>
 580         <para>
 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.
 584         </para>
 585       </answer>
 586     </qandaentry>
 587
 588
 589     <qandaentry id="which-ipc">
 590       <question>
 591         <para>
 592           Which IPC mechanism should I use?
 593         </para>
 594       </question>
 595       <answer>
 596         <para>
 597           Start by reading <xref linkend="other-ipc"/>.
 598         </para>
 599         <para>
 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.
 603         </para>
 604         <para>
 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.)
 610         </para>
 611         <para>
 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.
 616         </para>
 617         <para>
 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.
 626         </para>
 627       </answer>
 628     </qandaentry>
 629
 630
 631     <qandaentry>
 632       <question>
 633         <para>
 634           How can I submit a bug or patch?
 635         </para>
 636       </question>
 637       <answer>
 638         <para>
 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.
 643         </para>
 644       </answer>
 645     </qandaentry>
 646
 647   </qandaset>
 648
 649 </article>