summaryrefslogtreecommitdiffstats
path: root/doc/dbus-faq.xml
blob: b197297edf4c551daae1cdcc8bc67775f57a26bc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
<?xml version="1.0" standalone="no"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
[
]>

<article id="index">
  <articleinfo>
    <title>D-BUS FAQ</title>
    <releaseinfo>Version 0.1</releaseinfo>
    <date>22 January 2005</date>
    <authorgroup>
      <author>
	<firstname>Havoc</firstname>
	<surname>Pennington</surname>
	<affiliation>
	  <orgname>Red Hat, Inc.</orgname>
	  <address>
	    <email>hp@pobox.com</email>
	  </address>
	</affiliation>
      </author>
      <author>
	<firstname>David</firstname>
        <othername role="mi">A</othername>
	<surname>Wheeler</surname>
      </author>
    </authorgroup>
  </articleinfo>

  <qandaset id="faq">

    <qandaentry>
      <question>
        <para>
          What is D-BUS?
        </para>
      </question>
      <answer>
        <para>
          This is probably best answered by reading the D-BUS <ulink url="dbus-tutorial.html">tutorial</ulink>. In
          short, it is a system consisting of 1) a wire protocol for exposing a
          typical object-oriented language/framework to other applications; and
          2) a bus daemon that allows applications to find and monitor one another.
        </para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
        <para>
          Is D-BUS stable/finished?
        </para>
      </question>
      <answer>
        <para>
          D-BUS has not yet reached 1.0. The <ulink url="README">README</ulink>
          file has a discussion of the API/ABI stability guarantees before and
          after 1.0. In short, there are no guarantees before 1.0, and stability
          of both protocol and reference library will be maintained after 1.0.
          As of January 2005 we don't expect major protocol or API changes prior
          to the 1.0 release, but anything is possible.
        </para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
        <para>
          How is the reference implementation licensed? Can I use it in 
          proprietary applications?
        </para>
      </question>
      <answer>
        <para>
          The short answer is yes, you can use it in proprietary applications.
          You should read the <ulink url="COPYING">COPYING</ulink> file, which
          offers you the choice of two licenses. These are the GPL and the
          AFL. The GPL requires that your application be licensed under the GPL
          as well. The AFL is an "X-style" or "BSD-style" license compatible
          with proprietary licensing, but it does have some requirements; in
          particular it prohibits you from filing a lawsuit alleging that the
          D-BUS software infringes your patents <emphasis>while you continue to
          use D-BUS</emphasis>.  If you're going to sue, you have to stop using
          the software. Read the licenses to determine their meaning, this FAQ
          entry is not intended to change the meaning or terms of the licenses.
        </para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
        <para>
          What is the difference between a bus name, and object path, 
          and an interface?
        </para>
      </question>
      <answer>
        <para>
          If you imagine a C++ program that implements a network service, then
          the bus name is the hostname of the computer running this C++ program,
          the object path is a C++ object instance pointer, and an interface is
          a C++ class (a pure virtual or abstract class, to be exact).
        </para>
        <para>
          In Java terms, the object path is an object reference, 
          and an interface is a Java interface.
        </para>
        <para>
          People get confused because if they write an application 
          with a single object instance and a single interface, 
          then the bus name, object path, and interface look 
          redundant. For example, you might have a text editor 
          that uses the bus name <literal>org.freedesktop.TextEditor</literal>,
          has a global singleton object called 
          <literal>/org/freedesktop/TextEditor</literal>, and 
          that singleton object could implement the interface 
          <literal>org.freedesktop.TextEditor</literal>.
        </para>
        <para>
          However, a text editor application could as easily own multiple bus
          names (for example, <literal>org.kde.KWrite</literal> in addition to
          generic <literal>TextEditor</literal>), have multiple objects (maybe
          <literal>/org/kde/documents/4352</literal> where the number changes
          according to the document), and each object could implement multiple
          interfaces, such as <literal>org.freedesktop.Introspectable</literal>,
          <literal>org.freedesktop.BasicTextField</literal>,
          <literal>org.kde.RichTextDocument</literal>.
        </para>
      </answer>
    </qandaentry>


    <qandaentry id="service">
      <question>
        <para>
          What is a "service"?
        </para>
      </question>
      <answer>
        <para>
          A service is a program that can be launched by the bus daemon 
          to provide some functionality to other programs. Services
          are normally launched according to the bus name they will 
          have.
        </para>
      </answer>
    </qandaentry>

    <qandaentry id="components">
      <question>
        <para>
          Is D-BUS a "component system"?
        </para>
      </question>
      <answer>
        <para>
          D-BUS is not a component system. "Component system" was originally
          defined by COM, and was essentially a workaround for the limitations
          of the C++ object system (adding introspection, runtime location of
          objects, ABI guarantees, and so forth). With the C# language and CLR,
          Microsoft added these features to the primary object system, leaving
          COM obsolete. Similarly, Java has much less need for something like
          COM than C++ did. Even QObject (from Qt) and GObject (from GLib) offer
          some of the same features found in COM.
        </para>
        <para>
          Component systems are not about GUI control embedding. Embedding
          a spreadsheet in a word processor document is a matter of defining
          some specific <emphasis>interfaces</emphasis> that objects
          can implement. These interfaces provide methods related to 
          GUI controls. So an object implementing those interfaces 
          can be embedded.
        </para>
        <para>
          The word "component" just means "object with some fancy features" and
          in modern languages all objects are effectively "components."
        </para>
        <para>
          A third, orthogonal feature is interprocess communication or IPC.
          D-BUS is an IPC system. Given an object (or "component" if you must), 
          you can expose the functionality of that object over an IPC system.
          Examples of IPC systems are DCOM, CORBA, SOAP, XML-RPC, and D-BUS.
          You can use any of these IPC systems with any object/component system,
          though some of them are "tuned" for specific object systems.
          You can think of an IPC system primarily as a wire protocol.
        </para>
        <para>
          If you combine an IPC system with a set of GUI control interfaces, 
          then you can have an out-of-process or dynamically-loaded GUI control.
        </para>
        <para>
          Summarizing, there are three orthogonal things:
          <orderedlist>
            <listitem>
              <para>
                Object/component system
              </para>
            </listitem>
            <listitem>
              <para>
                Control embedding interfaces
              </para>
            </listitem>
            <listitem>
              <para>
                Interprocess communication system or wire protocol
              </para>
            </listitem>
          </orderedlist>
        </para>
        <para>
          Another related concept is the <firstterm>plugin</firstterm> or
          <firstterm>extension</firstterm>.  Generic plugin systems such as the
          <ulink url="http://eclipse.org">Eclipse</ulink> system are not so different
          from component/object systems, though perhaps a "plugin" tends to be a
          bundle of objects with a user-visible name and can be
          downloaded/packaged as a unit.
        </para>
      </answer>
    </qandaentry>

    <qandaentry id="speed">
      <question>
        <para>
          How fast is the D-BUS reference implementation?
        </para>
      </question>
      <answer>
        <para>
          Of course it depends a bit on what you're doing. 
          <ulink url="http://lists.freedesktop.org/pipermail/dbus/2004-November/001779.html">
            This mail</ulink> contains some benchmarking.  At the time of that
          benchmark, D-BUS one-to-one communication was about 2.5x slower than
          simply pushing the data raw over a socket. After the recent rewrite of
          the marshaling code, D-BUS is slower than that because a lot of
          optimization work was lost. But it can probably be sped up again.
        </para>
        <para>
          D-BUS communication with the intermediate bus daemon should be 
          (and as last profiled, was) about twice as slow as one-to-one 
          mode, because a round trip involves four socket reads/writes rather 
          than two socket reads/writes.
        </para>
        <para>
          The overhead comes from a couple of places; part of it is simply 
          "abstraction penalty" (there are layers of code to support 
          multiple main loops, multiple transport types, security, etc.).
          Probably the largest part comes from data validation
          (because the reference implementation does not trust incoming data).
          It would be simple to add a "no validation" mode, but probably 
          not a good idea all things considered.
        </para>
        <para>
          Raw bandwidth isn't the only concern; D-BUS is designed to 
          enable asynchronous communication and avoid round trips.
          This is frequently a more important performance issue 
          than throughput.
        </para>
      </answer>
    </qandaentry>


    <qandaentry id="size">
      <question>
        <para>
          How large is the D-BUS reference implementation?
        </para>
      </question>
      <answer>
        <para>
          A production build (with assertions, unit tests, and verbose logging
          disabled) is on the order of a 150K shared library.
        </para>
        <para>
          A much, much smaller implementation would be possible by omitting out
          of memory handling, hardcoding a main loop (or always using blocking
          I/O), skipping validation, and otherwise simplifying things.
        </para>
      </answer>
    </qandaentry>
    
    <qandaentry id="other-ipc">
      <question>
        <para>
          How does D-BUS differ from other interprocess communication
          or networking protocols?
        </para>
      </question>
      <answer>
        <para>
          The best place to start is to read the D-BUS <ulink url="dbus-tutorial.html">tutorial</ulink>, so 
          you have a concrete idea what D-BUS actually is. If you 
          understand other protocols on a wire format level, you 
          may also want to read the D-BUS <ulink url="dbus-specification.html">specification</ulink> to see what 
          D-BUS looks like on a low level.
        </para>
        <para>
          As the <ulink url="dbus-tutorial.html">tutorial</ulink> and <ulink url="dbus-specification.html">specification</ulink> both explain, D-BUS is tuned 
          for some specific use cases. Thus, it probably isn't tuned 
          for what you want to do, unless you are doing the things 
          D-BUS was designed for. Don't make the mistake of thinking 
          that any system labeled "IPC" is the same thing.
        </para>
        <para>
          The D-BUS authors would not recommend using D-BUS 
          for applications where it doesn't make sense.
          The following questions compare D-BUS to some other 
          protocols primarily to help you understand D-BUS 
          and decide whether it's appropriate; D-BUS is neither intended
          nor claimed to be the right choice for every application.
        </para>
        <para>
          It should be possible to bridge D-BUS to other IPC systems, 
          just as D-BUS can be bridged to object systems.
        </para>
        <para>
          Note: the D-BUS mailing list subscribers are <emphasis>very much not
          interested</emphasis> in debating which IPC system is the One True
          System. So if you want to discuss that, please use another forum.
        </para>
      </answer>      
    </qandaentry>

    
    <qandaentry id="corba">
      <question>
        <para>
          How does D-BUS differ from CORBA?
        </para>
      </question>
      <answer>
        <para>
          Start by reading <xref linkend="other-ipc"/>.
        </para>
        <para>
          <ulink url="http://www.omg.org">CORBA</ulink> is designed to support
         object-oriented IPC between objects, automatically marshalling
         parameters as necessary. CORBA is strongly supported by the <ulink
         url="http://www.omg.org">Open Management Group (OMG)</ulink>, which
         produces various standards and supporting documents for CORBA and has
         the backing of many large organizations.  There are many CORBA ORBs
         available, both proprietary ORBs and free / open source software ORBs
         (the latter include <ulink
         url="http://orbit-resource.sourceforge.net/">ORBit</ulink>, <ulink
         url="http://www.mico.org/">MICO</ulink>, and <ulink
         url="http://www.theaceorb.com/">The ACE Orb (TAO)</ulink>).  Many
         organizations continue to use CORBA ORBs for various kinds of IPC.
        </para>
        <para>
          Both GNOME and KDE have used CORBA and then moved away from it.  KDE
          had more success with a system called DCOP, and GNOME layered a system
          called Bonobo on top of CORBA. Without custom extensions, CORBA does
          not support many of the things one wants to do in a desktop
          environment with the GNOME/KDE architecture.
        </para>
        <para>
          CORBA on the other hand has a number of features of interest for
          enterprise and web application development, though XML systems such as
          SOAP are the latest fad.
        </para>
        <para>
          Like D-BUS, CORBA uses a fast binary protocol (IIOP). Both systems
          work in terms of objects and methods, and have concepts such as
          "oneway" calls. Only D-BUS has direct support for "signals" as in
          GLib/Qt (or Java listeners, or C# delegates).
        </para>
        <para>
          D-BUS hardcodes and specifies a lot of things that CORBA leaves open-ended,
          because CORBA is more generic and D-BUS has two specific use-cases in mind.
          This makes D-BUS a bit simpler.
        </para>
        <para>
          However, unlike CORBA D-BUS does <emphasis>not</emphasis> specify the
          API for the language bindings. Instead, "native" bindings adapted
          specifically to the conventions of a framework such as QObject,
          GObject, C#, Java, Python, etc. are encouraged. The libdbus reference
          implementation is designed to be a backend for bindings of this
          nature, rather than to be used directly. The rationale is that an IPC
          system API should not "leak" all over a program; it should come into
          play only just before data goes over the wire. As an aside, OMG is
          apparently working on a simpler C++ binding for CORBA.
        </para>
        <para>
          Many CORBA implementations such as ORBit are faster than the libdbus
          reference implementation.  One reason is that D-BUS considers data
          from the other end of the connection to be untrusted and extensively
          validates it. But generally speaking other priorities were placed
          ahead of raw speed in the libdbus implementation. A fast D-BUS
          implementation along the lines of ORBit should be possible, of course.
        </para>
        <para>
          On a more trivial note, D-BUS involves substantially fewer acronyms
          than CORBA.
        </para>
      </answer>
    </qandaentry>


    <qandaentry id="xmlrpcsoap">
      <question>
        <para>
          How does D-BUS differ from XML-RPC and SOAP?
        </para>
      </question>
      <answer>
        <para>
          Start by reading <xref linkend="other-ipc"/>.
        </para>
        <para>
          In <ulink url="http://www.w3.org/TR/SOAP/">SOAP</ulink> and <ulink
            url="http://www.xmlrpc.com">XML-RPC</ulink>, RPC calls are transformed
          into an XML-based format, then sent over the wire (typically using the
          HTTP protocol), where they are processed and returned.  XML-RPC is the
          simple protocol (its spec is only a page or two), and SOAP is the
          full-featured protocol.
        </para>
        <para>
          XML-RPC and SOAP impose XML parsing overhead that is normally
          irrelevant in the context of the Internet, but significant for
          constant fine-grained IPC among applications in a desktop session.
        </para>
        <para>
          D-BUS offers persistent connections and with the bus daemon 
          supports lifecycle tracking of other applications connected
          to the bus. With XML-RPC and SOAP, typically each method call 
          exists in isolation and has its own HTTP connection.
        </para>
      </answer>
    </qandaentry>

    <qandaentry id="dce">
      <question>
        <para>
          How does D-BUS differ from DCE?
        </para>
      </question>
      <answer>
        <para>
          Start by reading <xref linkend="other-ipc"/>.
        </para>
        <para>
          <ulink url="http://www.opengroup.org/dce/">Distributed Computing
          Environment (DCE)</ulink> is an industry-standard vendor-neutral
          standard that includes an IPC mechanism.  <ulink
          url="http://www.opengroup.org/comm/press/05-01-12.htm">The Open Group
          has released an implementation as open source software</ulink>.  DCE
          is quite capable, and includes a vast amount of functionality such as
          a distributed time service.  As the name implies, DCE is intended for
          use in a large, multi-computer distributed application. D-BUS would
          not be well-suited for this.
        </para>
      </answer>
    </qandaentry>    


    <qandaentry id="dcom">
      <question>
        <para>
          How does D-BUS differ from DCOM and COM?
        </para>
      </question>
      <answer>
        <para>
          Start by reading <xref linkend="other-ipc"/>.
        </para>
        <para>
          Comparing D-BUS to COM is apples and oranges; 
          see <xref linkend="components"/>.
        </para>
        <para>
          DCOM (distributed COM) is a Windows IPC system designed for use with
          the COM object system. It's similar in some ways to DCE and CORBA.
        </para>
      </answer>
    </qandaentry>    

    <qandaentry id="internet-communications-engine">
      <question>
        <para>
          How does D-BUS differ from ZeroC's Internet Communications Engine (Ice)
        </para>
      </question>
      <answer>
        <para>
          Start by reading <xref linkend="other-ipc"/>.
        </para>
        <para>
          The <ulink url="http://www.zeroc.com/ice.html"> Internet
          Communications Engine (Ice)</ulink> is a powerful IPC mechanism more
          on the level of SOAP or CORBA than D-BUS.  Ice has a "dual-license"
          business around it; i.e. you can use it under the GPL, or pay for a
          proprietary license.
        </para>
      </answer>
    </qandaentry>    

    <qandaentry id="inter-client-exchange">
      <question>
        <para>
          How does D-BUS differ from Inter-Client Exchange (ICE)?
        </para>
      </question>
      <answer>
        <para>
          <ulink url="http://www.x.org/X11R6.8.1/docs/ICE/ice.pdf">ICE</ulink>
          was developed for the X Session Management protocol (XSMP), as part of
          the X Window System (X11R6.1). The idea was to allow desktop sessions
          to contain nongraphical clients in addition to X clients.
        </para>
        <para>
          ICE is a binary protocol designed for desktop use, and KDE's DCOP
          builds on ICE.  ICE is substantially simpler than D-BUS (in contrast
          to most of the other IPC systems mentioned here, which are more
          complex). ICE doesn't really define a mapping to objects and methods
          (DCOP adds that layer).  The reference implementation of ICE (libICE)
          is often considered to be horrible (and horribly insecure).
        </para>
        <para>
          DCOP and XSMP are the only two widely-used applications of ICE,
          and both could in principle be replaced by D-BUS. (Though whether 
          GNOME and KDE will bother is an open question.)
        </para>
      </answer>
    </qandaentry>

    

    <qandaentry id="dcop">
      <question>
        <para>
          How does D-BUS differ from DCOP?
        </para>
      </question>
      <answer>
        <para>
          Start by reading <xref linkend="other-ipc"/>.
        </para>
        <para>
          D-BUS is intentionally pretty similar to <ulink
          url="http://developer.kde.org/documentation/library/kdeqt/dcop.html">DCOP</ulink>,
          and can be thought of as a "DCOP the next generation" suitable for 
          sharing between the various open source desktop projects.
        </para>
        <para>
          D-BUS is a bit more complex than DCOP, though the Qt binding for D-BUS
          should not be more complex for programmers. The additional complexity
          of D-BUS arises from its separation of object references vs. bus names
          vs. interfaces as distinct concepts, and its support for one-to-one
          connections in addition to connections over the bus. The libdbus
          reference implementation has a lot of API to support multiple bindings
          and main loops, and performs data validation and out-of-memory handling 
          in order to support secure applications such as the systemwide bus.
        </para>
        <para>
          D-BUS is probably somewhat slower than DCOP due to data validation 
          and more "layers" in the reference implementation. A comparison 
          hasn't been posted to the list though.
        </para>
        <para>
          At this time, KDE has not committed to using D-BUS, but there have
          been discussions of KDE bridging D-BUS and DCOP, or even changing
          DCOP's implementation to use D-BUS internally (so that GNOME and KDE
          would end up using exactly the same bus). See the KDE mailing list 
          archives for some of these discussions.
        </para>
      </answer>
    </qandaentry>


    <qandaentry id="yet-more-ipc">
      <question>
        <para>
          How does D-BUS differ from [yet more IPC mechanisms]?
        </para>
      </question>
      <answer>
        <para>
          Start by reading <xref linkend="other-ipc"/>.
        </para>
        <para>
          There are countless uses of network sockets in the world.  <ulink
          url="http://www.mbus.org/">MBUS</ulink>, Sun ONC/RPC, Jabber/XMPP,
          SIP, are some we can think of quickly.
        </para>
      </answer>
    </qandaentry>


    <qandaentry id="which-ipc">
      <question>
        <para>
          Which IPC mechanism should I use?
        </para>
      </question>
      <answer>
        <para>
          Start by reading <xref linkend="other-ipc"/>.
        </para>
        <para>
          If you're writing an Internet or Intranet application, XML-RPC or SOAP
          work for many people. These are standard, available for most
          languages, simple to debug and easy to use.
        </para>
        <para>
          If you're writing a desktop application for UNIX, 
          then D-BUS is of course our recommendation for 
          talking to other parts of the desktop session.
          (With the caveat that you should use a stable release 
          of D-BUS; until we reach 1.0, there isn't a stable release.)
        </para>
        <para>
          If you're doing something complicated such as clustering, 
          distributed swarms, peer-to-peer, or whatever then 
          the authors of this FAQ don't have expertise in these
          areas and you should ask someone else or try a search engine.
        </para>
        <para>
          Note: the D-BUS mailing list is probably not the place to 
          discuss which system is appropriate for your application, 
          though you are welcome to ask specific questions about 
          D-BUS <emphasis>after reading this FAQ, the tutorial, and 
            searching the list archives</emphasis>. The best way 
          to search the list archives is probably to use 
          an Internet engine such as Google. On Google, 
          include "site:freedesktop.org" in your search.
        </para>
      </answer>
    </qandaentry>


    <qandaentry>
      <question>
        <para>
          How can I submit a bug or patch?
        </para>
      </question>
      <answer>
        <para>
          The D-BUS <ulink url="http://dbus.freedesktop.org">web site</ulink>
          has a link to the bug tracker, which is the best place to store
          patches.  You can also post them to the list, especially if you want
          to discuss the patch or get feedback.
        </para>
      </answer>
    </qandaentry>

  </qandaset>

</article>