diff options
Diffstat (limited to 'src/3rd_party/dbus-1.7.8/doc/dbus-faq.xml')
| -rw-r--r-- | src/3rd_party/dbus-1.7.8/doc/dbus-faq.xml | 674 |
1 files changed, 0 insertions, 674 deletions
diff --git a/src/3rd_party/dbus-1.7.8/doc/dbus-faq.xml b/src/3rd_party/dbus-1.7.8/doc/dbus-faq.xml deleted file mode 100644 index 0d296d9266..0000000000 --- a/src/3rd_party/dbus-1.7.8/doc/dbus-faq.xml +++ /dev/null @@ -1,674 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" -"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" -[ -]> - -<article id="index"> - <articleinfo> - <title>D-Bus FAQ</title> - <releaseinfo>Version 0.3</releaseinfo> - <date>17 November 2006</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> or - the introduction to the <ulink url="dbus-specification.html">specification</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. - Phrased differently, D-Bus is 1) an interprocess communication (IPC) system and 2) some higher-level - structure (lifecycle tracking, service activation, security policy) provided by two bus daemons, - one systemwide and one per-user-session. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para> - Is D-Bus stable/finished? - </para> - </question> - <answer> - <para> - The low-level library "libdbus" and the protocol specification are considered - ABI stable. The <ulink url="README">README</ulink> - file has a discussion of the API/ABI stability guarantees. - Higher-level bindings (such as those for Qt, GLib, Python, Java, C#) each - have their own release schedules and degree of maturity, not linked to - the low-level library and bus daemon release. Check the project page for - the binding you're considering to understand that project's policies. - </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.DBus.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> - <para> - People often misuse the word "service" for any - bus name, but this tends to be ambiguous and confusing so is discouraged. - In the D-Bus docs we try to use "service" only when talking about - programs the bus knows how to launch, i.e. a service always has a - .service file. - </para> - </answer> - </qandaentry> - - <qandaentry id="components"> - <question> - <para> - Is D-Bus a "component system"? - </para> - </question> - <answer> - <para> - It helps to keep these concepts separate in your mind: - <orderedlist> - <listitem> - <para> - Object/component system - </para> - </listitem> - <listitem> - <para> - GUI control/widget embedding interfaces - </para> - </listitem> - <listitem> - <para> - Interprocess communication system or wire protocol - </para> - </listitem> - </orderedlist> - </para> - <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> - So components are fancy objects, and some objects are GUI controls. - </para> - <para> - A third, unrelated 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> - 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> - Keep in mind, it is not only an IPC system; it also includes - lifecycle tracking, service activation, security policy, and other - higher-level structure and assumptions. - </para> - <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 involving "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. - </para> - <para> - D-Bus is also designed for communications between system daemons and - communications between the desktop and system daemons. - </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. - D-Bus is most likely a poor choice but could be appropriate - for some things. - </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> |