From 76ee87af5b5007839012259304cce50a43e69638 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Sun, 23 Jan 2005 00:28:41 +0000 Subject: the new tutorial/FAQ --- doc/Makefile.am | 6 + doc/dbus-faq.xml | 649 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/dbus-tutorial.xml | 18 +- 3 files changed, 669 insertions(+), 4 deletions(-) create mode 100644 doc/dbus-faq.xml diff --git a/doc/Makefile.am b/doc/Makefile.am index 7df331c5..11f7db96 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,5 @@ EXTRA_DIST= \ + dbus-faq.xml \ dbus-specification.xml \ dbus-test-plan.xml \ dbus-tutorial.xml \ @@ -6,6 +7,7 @@ EXTRA_DIST= \ file-boilerplate.c HTML_FILES= \ + dbus-faq.html \ dbus-specification.html \ dbus-test-plan.html \ dbus-tutorial.html @@ -23,6 +25,10 @@ dbus-test-plan.html: dbus-test-plan.xml dbus-tutorial.html: dbus-tutorial.xml $(XMLTO) html-nochunks $< + +dbus-faq.html: dbus-faq.xml + $(XMLTO) html-nochunks $< + endif maintainer-clean-local: diff --git a/doc/dbus-faq.xml b/doc/dbus-faq.xml new file mode 100644 index 00000000..773acee7 --- /dev/null +++ b/doc/dbus-faq.xml @@ -0,0 +1,649 @@ + + + +
+ + D-BUS FAQ + Version 0.1 + 22 January 2005 + + + Havoc + Pennington + + Red Hat, Inc. +
+ hp@pobox.com +
+ + + + David + Wheeler + + + + + + + + + + What is D-BUS? + + + + + This is probably best answered by reading the D-BUS tutorial. 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. + + + + + + + + Is D-BUS stable/finished? + + + + + D-BUS has not yet reached 1.0. The README + 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. + + + + + + + + How is the reference implementation licensed? Can I use it in + proprietary applications? + + + + + The short answer is yes, you can use it in proprietary applications. + You should read the COPYING 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 while you continue to + use D-BUS. 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. + + + + + + + + What is the difference between a bus name, and object path, + and an interface? + + + + + If you imagine a C++ program that implements a network + service, then the bus name is the domain name + 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). + + + In Java terms, the object path is an object reference, + and an interface is a Java interface. + + + 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 org.freedesktop.TextEditor, + has a global singleton object called + /org/freedesktop/TextEditor, and + that singleton object could implement the interface + org.freedesktop.TextEditor. + + + However, a text editor application could as easily own multiple bus + names (for example, org.kde.KWrite), have multiple + objects (maybe /org/kde/documents/4352), + and each object could implement multiple interfaces, + such as org.freedesktop.Introspectable, + org.freedesktop.BasicTextField, + org.kde.RichTextDocument. + + + + + + + + + What is a "service"? + + + + + 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. + + + + + + + + Is D-BUS a "component system"? + + + + + 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. + + + Component systems are not about GUI control embedding. Embedding + a spreadsheet in a word processor document is a matter of defining + some specific interfaces that objects + can implement. These interfaces provide methods related to + GUI controls. So an object implementing those interfaces + can be embedded. + + + The word "component" just means "object with some fancy features" and + in modern languages all objects are effectively "components." + + + 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. + + + 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. + + + Summarizing, there are three orthogonal things: + + + + Object/component system + + + + + Control embedding interfaces + + + + + Interprocess communication system or wire protocol + + + + + + Another related concept is the plugin or + extension. Generic plugin systems such as the + Eclipse 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. + + + + + + + + How fast is the D-BUS reference implementation? + + + + + Of course it depends a bit on what you're doing. + + This mail 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. + + + 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. + + + 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. + + + 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. + + + + + + + + + How large is the D-BUS reference implementation? + + + + + A production build (with assertions, unit tests, and verbose logging + disabled) is on the order of a 150K shared library. + + + 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. + + + + + + + + How does D-BUS differ from other interprocess communication + or networking protocols? + + + + + The best place to start is to read the D-BUS tutorial, 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 specification to see what + D-BUS looks like on a low level. + + + As the tutorial and specification 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. + + + 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. + + + It should be possible to bridge D-BUS to other IPC systems, + just as D-BUS can be bridged to object systems. + + + Note: the D-BUS mailing list subscribers are very much not + interested in debating which IPC system is the One True + System. So if you want to discuss that, please use another forum. + + + + + + + + + How does D-BUS differ from CORBA? + + + + + Start by reading . + + + CORBA is designed to support + object-oriented IPC between objects, automatically marshalling + parameters as necessary. CORBA is strongly supported by the Open Management Group (OMG), 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 ORBit, MICO, and The ACE Orb (TAO)). Many + organizations continue to use CORBA ORBs for various kinds of IPC. + + + 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. + + + 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. + + + 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). + + + 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. + + + However, unlike CORBA D-BUS does not 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. + + + 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. + + + On a more trivial note, D-BUS involves substantially fewer acronyms + than CORBA. + + + + + + + + + How does D-BUS differ from XML-RPC and SOAP? + + + + + Start by reading . + + + In SOAP and XML-RPC, 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. + + + 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. + + + 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. + + + + + + + + How does D-BUS differ from DCE? + + + + + Start by reading . + + + Distributed Computing + Environment (DCE) is an industry-standard vendor-neutral + standard that includes an IPC mechanism. The Open Group + has released an implementation as open source software. 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. + + + + + + + + + How does D-BUS differ from DCOM and COM? + + + + + Start by reading . + + + Comparing D-BUS to COM is apples and oranges; + see . + + + 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. + + + + + + + + How does D-BUS differ from ZeroC's Internet Communications Engine (Ice) + + + + + Start by reading . + + + The Internet + Communications Engine (Ice) 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. + + + + + + + + How does D-BUS differ from Inter-Client Exchange (ICE)? + + + + + ICE + 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. + + + 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). + + + 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.) + + + + + + + + + + How does D-BUS differ from DCOP? + + + + + Start by reading . + + + D-BUS is intentionally pretty similar to DCOP, + and can be thought of as a "DCOP the next generation" suitable for + sharing between the various open source desktop projects. + + + 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. + + + 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. + + + 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. + + + + + + + + + How does D-BUS differ from [yet more IPC mechanisms]? + + + + + Start by reading . + + + There are countless uses of network sockets in the world. MBUS, Sun ONC/RPC, Jabber/XMPP, + SIP, are some we can think of quickly. + + + + + + + + + Which IPC mechanism should I use? + + + + + Start by reading . + + + 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. + + + 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.) + + + 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. + + + 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 after reading this FAQ, the tutorial, and + searching the list archives. 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. + + + + + + + + + How can I submit a bug or patch? + + + + + The D-BUS web site + 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. + + + + + + +
diff --git a/doc/dbus-tutorial.xml b/doc/dbus-tutorial.xml index ccb12d4c..6f5afc07 100644 --- a/doc/dbus-tutorial.xml +++ b/doc/dbus-tutorial.xml @@ -20,6 +20,10 @@ + + David + Wheeler + @@ -101,11 +105,16 @@ There are many, many technologies in the world that have "Inter-process communication" or "networking" in their stated purpose: MBUS, CORBA, DCE, COM/DCOM, DCOP, XML-RPC, SOAP, and probably hundreds - more. Each of these is tailored for particular kinds of application. + url="http://www.w3.org/TR/SOAP/">SOAP, MBUS, Internet Communications Engine (ICE), + and probably hundreds more. + Each of these is tailored for particular kinds of application. D-BUS is designed for two specific cases: @@ -130,7 +139,8 @@ have significant previous experience with different IPC solutions such as CORBA and DCOP. D-BUS is built on that experience and carefully tailored to meet the needs of these desktop projects - in particular. + in particular. D-BUS may or may not be appropriate for other + applications; the FAQ has some comparisons to other IPC systems. The problem solved by the systemwide or communication-with-the-OS case -- cgit