Attachment 48571 Details for Bug 38784 – Patch to DBus specification describing interface RefCounted

[patch] Patch to DBus specification describing interface RefCounted

0001-Add-standard-interface-org.freedestop.DBus.RefCounte.patch (text/plain), 6.66 KB, created by Will Manley on 2011-06-29 14:34:24 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Will Manley

Created: 2011-06-29 14:34:24 UTC

Size: 6.66 KB

patch

obsolete

>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
>

Actions: View | Splinter Review

Attachments on bug 38784: 48571 | 50102

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.