From 164bad341512db9676fc66483688d9e92727dc2c Mon Sep 17 00:00:00 2001 From: Will Manley 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 @@ + + William + Manley + + YouView TV Ltd. +
+ william.manley@youview.com +
+
+
current commit log - - + willm + define RefCounted 0.17 @@ -3172,6 +3182,127 @@ + + + <literal>org.freedesktop.DBus.RefCounted</literal> + + 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. + + + A client should call DropRef on an object to + indicate that it is no longer interested in it and that it can + be destroyed: + + + + org.freedesktop.DBus.RefCounted.DropRef (in UINT32 refcount); + + + + DropRef will not return. + + + 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. + + + + 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. + + + + + Whenever the client receives an object path the reference count + in the client for that object is incremented. + + + + + Once the client is finished with this object it calls + org.freedesktop.DBus.RefCounted.DropRef on + that object giving the client reference count for that object. + The server should then decrement the server reference count by + that amount. + + + + + 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. + + + + + 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: + + + + org.freedesktop.DBus.AddMatch ("type='signal',name='org.freedesktop.DBus.NameOwnerChanged',arg0='client unique busname'"); + org.freedesktop.DBus.NameHasOwner ("client unique busname") + + + + and reset the server reference count for that client if + NameHasOwner returns false or a + NameOwnerChanged signal is received + indicating that the client has dropped its connection to the + bus. + + + + + Reference counts are not affected for DBus paths sent as a + signal payload as it is impossible to know who has received + these messages. + + + + + + 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: + + + + org.freedesktop.DBus.RefCounted.AddRef (); + + + + 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 DropRef on the object until + it has been confirmed that Client B has called AddRef + on the object to avoid race conditions. AddRef + will not return. + + + + The org.freedesktop.DBus.RefCounted + interface was added in version 0.18 of the D-Bus + specification. + + + -- 1.7.1