[telepathy-spec/master] Observer.ObserveChannels::DispatchOperation: note the possibility for deadlock

[Simon McVittie]

---
 spec/Client_Observer.xml |   31 ++++++++++++++++++++-----------
 1 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml
index 52d7edb..da59cb6 100644
--- a/spec/Client_Observer.xml
+++ b/spec/Client_Observer.xml
@@ -242,19 +242,28 @@ org.freedesktop.Telepathy.Channel.Requested b=true
         </tp:docstring>
       </arg>
 
-      <arg name="DispatchOperation" type="o" direction="in">
-        <tp:docstring>
-          The path to the <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT</tp:dbus-ref>
-          for these channels, or the special value '/' if there is no
-          ChannelDispatchOperation (because the channels were requested, not incoming).
+      <arg name="Dispatch_Operation" type="o" direction="in">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The path to the <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT</tp:dbus-ref>
+            for these channels, or the special value '/' if there is no
+            ChannelDispatchOperation (because the channels were requested, not
+            incoming).</p>
 
-          <tp:rationale>
-            This allows an Observer to <tp:dbus-ref
+          <p>If the Observer calls <tp:dbus-ref
               namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Claim</tp:dbus-ref>
-            a set of channels without having to match up calls to this method
-            with calls to <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy.Client.Approver.DRAFT">AddDispatchOperation</tp:dbus-ref>.
+            or <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">HandleWith</tp:dbus-ref>
+            on the dispatch operation, it MUST be careful to avoid deadlock,
+            since these methods cannot return until the Observer has returned
+            from <tp:member-ref>ObserveChannels</tp:member-ref>.</p>
+
+          <tp:rationale>
+            <p>This allows an Observer to <tp:dbus-ref
+                namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Claim</tp:dbus-ref>
+              a set of channels without having to match up calls to this method
+              with calls to <tp:dbus-ref
+                namespace="org.freedesktop.Telepathy.Client.Approver.DRAFT">AddDispatchOperation</tp:dbus-ref>.</p>
           </tp:rationale>
         </tp:docstring>
       </arg>
-- 
1.5.6.5