From 5c9307ca9e35ca8be036157989a29bb4d60fe5c2 Mon Sep 17 00:00:00 2001 From: William Manley Date: Wed, 10 Aug 2011 21:07:53 +0100 Subject: [PATCH] Add standard interface org.freedestop.DBus.RefCounted to spec. --- doc/dbus-specification.xml | 139 +++++++++++++++++++++++++++++++++++++++++++- 1 files changed, 137 insertions(+), 2 deletions(-) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 7280cf1..eda74fa 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.18 @@ -3190,6 +3200,131 @@ + + + <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. + + + 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. + + + 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 does not return a useful result, and + calling it with the NO_REPLY flag is suggested. + + + 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 + server. (In fact the server should keep a per client reference + count for each object). + + + + Every time a client calls a method that sends a RefCounted + object's path in its method reply message, the reference + count maintained on behalf of that 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 server 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 server + 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 + does not return a useful result, and calling it with NO_REPLY is + suggested. + + + + The org.freedesktop.DBus.RefCounted + interface was added in version UNRELEASED of the D-Bus + specification. + + + -- 1.7.1