From 164bad341512db9676fc66483688d9e92727dc2c Mon Sep 17 00:00:00 2001
From: Will Manley <william.manley@bbc.co.uk>
Date: Wed, 29 Jun 2011 22:20:00 +0100
Subject: [PATCH] Add standard interface org.freedestop.DBus.RefCounted to spec.

---
 doc/dbus-specification.xml |  135 +++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 133 insertions(+), 2 deletions(-)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 4bd0cb3..bb18476 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -69,13 +69,23 @@
           </address>
         </affiliation>
       </author>
+      <author>
+        <firstname>William</firstname>
+        <surname>Manley</surname>
+        <affiliation>
+          <orgname>YouView TV Ltd.</orgname>
+          <address>
+            <email>william.manley@youview.com</email>
+          </address>
+        </affiliation>
+      </author>
     </authorgroup>
    <revhistory>
      <revision>
        <revnumber>current</revnumber>
        <date><ulink url='http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml'>commit log</ulink></date>
-       <authorinitials></authorinitials>
-       <revremark></revremark>
+       <authorinitials>willm</authorinitials>
+       <revremark>define RefCounted</revremark>
      </revision>
      <revision>
        <revnumber>0.17</revnumber>
@@ -3172,6 +3182,127 @@
         </emphasis>
       </para>
     </sect2>
+
+    <sect2 id="standard-interfaces-refcounted">
+      <title><literal>org.freedesktop.DBus.RefCounted</literal></title>
+      <para>
+        The intent of this interface is to allow DBus clients to own (be
+        responsible for the lifetime of) objects in remote applications
+        in a way which is robust and non-racy in the presence of
+        asynchronous method calls that might return this object path.
+        An object can optionally make use of this interface.
+      </para>
+      <para>
+        A client should call <literal>DropRef</literal> on an object to
+        indicate that it is no longer interested in it and that it can
+        be destroyed:
+      </para>
+      <para>
+        <programlisting>
+          org.freedesktop.DBus.RefCounted.DropRef (in UINT32 refcount);
+        </programlisting>
+      </para>
+      <para>
+        <literal>DropRef</literal> will not return.
+      </para>
+      <para>
+        Implementations of this interface should use distributed
+        reference counting to ensure a non-racy implementation in the
+        presence of pending asynchronous calls which may return this
+        object.  This means that there are two reference counts for
+        every RefCounted object.  One is in the client and one is in the
+        remote application.  (In fact the remote application has a
+        per client reference count for each object).  In the discussion
+        below "server" refers to the process within which the actual
+        object lives and "client" refers to another process that has a
+        handle to one of these objects.
+        <itemizedlist>
+          <listitem>
+            <para>
+              Every time an object is returned to a client from a remote
+              application the reference count in the server for that
+              object/client is incremented.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              Whenever the client receives an object path the reference count
+              in the client for that object is incremented.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              Once the client is finished with this object it calls
+              <literal>org.freedesktop.DBus.RefCounted.DropRef</literal> on
+              that object giving the client reference count for that object.
+              The server should then decrement the server reference count by
+              that amount.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              If the server finds that all server reference counts on an
+              object have dropped to zero the server can choose to remove the
+              object from the bus and delete it.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              In addition, to cope with unclean client exits, the server
+              should reset the reference count for those clients that drop off
+              the bus.  To do this without races the application should call:
+            </para>
+            <para>
+              <programlisting>
+                org.freedesktop.DBus.AddMatch ("type='signal',name='org.freedesktop.DBus.NameOwnerChanged',arg0='client unique busname'");
+                org.freedesktop.DBus.NameHasOwner ("client unique busname")
+              </programlisting>
+            </para>
+            <para>
+              and reset the server reference count for that client if
+              <literal>NameHasOwner</literal> returns false or a
+              <literal>NameOwnerChanged</literal> signal is received
+              indicating that the client has dropped its connection to the
+              bus.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              Reference counts are not affected for DBus paths sent as a
+              signal payload as it is impossible to know who has received
+              these messages.
+            </para>
+          </listitem>
+        </itemizedlist>
+      </para>
+      <para>
+        An object in a remote process may be "owned" by multiple client
+        applications and adjustments to one client's reference count
+        should not affect any other client's reference counts.  To
+        facilitate passing RefCounted objects between clients the remote
+        application should also present the method:
+      </para>
+      <para>
+        <programlisting>
+          org.freedesktop.DBus.RefCounted.AddRef ();
+        </programlisting>
+      </para>
+      <para>
+        which should increment the server reference count for the
+        calling client.  If Client A is passing an object to Client B it
+        should not call <literal>DropRef</literal> on the object until
+        it has been confirmed that Client B has called <literal>AddRef</literal>
+        on the object to avoid race conditions.  <literal>AddRef</literal>
+        will not return.
+      </para>
+      <para>
+        <emphasis>
+          The <literal>org.freedesktop.DBus.RefCounted</literal>
+          interface was added in version 0.18 of the D-Bus
+          specification.
+        </emphasis>
+      </para>
+    </sect2>
   </sect1>
 
   <sect1 id="introspection-format">
-- 
1.7.1