Attachment 88632 Details for Bug 69430 – [04/12] ObserveChannel: be singular

[patch] [04/12] ObserveChannel: be singular

0004-ObserveChannel-be-singular.patch (text/plain), 11.43 KB, created by Simon McVittie on 2013-11-04 18:24:28 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2013-11-04 18:24:28 UTC

Size: 11.43 KB

patch

obsolete

>From 592dc2fe3045501bb23a6b2c5c141d8a0f4eeeb8 Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Date: Mon, 4 Nov 2013 15:28:24 +0000
>Subject: [PATCH 04/12] ObserveChannel: be singular
>
>---
> spec/Channel.xml | 2 +-
> spec/Client_Observer.xml | 63 ++++++++++++++++++++++++++----------------------
> 2 files changed, 35 insertions(+), 30 deletions(-)
>
>diff --git a/spec/Channel.xml b/spec/Channel.xml
>index f93043d..0646f29 100644
>--- a/spec/Channel.xml
>+++ b/spec/Channel.xml
>@@ -325,7 +325,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
> after the channel has been announced with <tp:dbus-ref
> namespace='imt1.Connection'>NewChannel</tp:dbus-ref>),
> provided to clients in the
>- <tp:dbus-ref namespace='imt1.Client.Observer'>ObserveChannels</tp:dbus-ref>,
>+ <tp:dbus-ref namespace='imt1.Client.Observer'>ObserveChannel</tp:dbus-ref>,
> <tp:dbus-ref namespace='imt1.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and
> <tp:dbus-ref namespace='imt1.Client.Handler'>HandleChannels</tp:dbus-ref>
> methods to permit immediate identification of the channel. This interface
>diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml
>index a21078f..b899742 100644
>--- a/spec/Client_Observer.xml
>+++ b/spec/Client_Observer.xml
>@@ -64,11 +64,11 @@
> to the Observer.
> </tp:rationale>
> 
>- Whenever a collection of new channels is signalled, the channel
>+ Whenever a new channel is signalled, the channel
> dispatcher will notify all running or activatable observers whose
> <tp:member-ref>ObserverChannelFilter</tp:member-ref> property
> (possibly as cached in the .client file) indicates that they are
>- interested in some of the channels.
>+ interested in that channel.
> 
> Observers are activated for all channels in which they have
> registered an interest - incoming, outgoing or automatically created -
>@@ -82,7 +82,7 @@
> instance, a Text logger needs to wait until pending messages have been
> downloaded), the channel dispatcher must wait (up to some timeout) for
> all observers to return from
>- <tp:member-ref>ObserveChannels</tp:member-ref> before letting anything
>+ <tp:member-ref>ObserveChannel</tp:member-ref> before letting anything
> destructive happen. Destructive things (e.g. acknowledging messages)
> are defined to be done by handlers, therefore HandleWith and Claim
> aren't allowed to succeed until all observers are ready.
>@@ -93,13 +93,13 @@
> be implemented as observers by following these steps:
> 
> <ol>
>- <li><tp:member-ref>ObserveChannels</tp:member-ref>() is called
>+ <li><tp:member-ref>ObserveChannel</tp:member-ref>() is called
> on the observer.</li>
> <li>The observer calls <tp:dbus-ref
> namespace="imt1.ChannelDispatchOperation">Claim</tp:dbus-ref>()
> on the CDO.</li>
> <li>The observer then returns from
>- <tp:member-ref>ObserveChannels</tp:member-ref>().</li>
>+ <tp:member-ref>ObserveChannel</tp:member-ref>().</li>
> <li><tp:dbus-ref
> namespace="imt1.ChannelDispatchOperation">Claim</tp:dbus-ref>
> will return successfully if the channels were successfully
>@@ -109,7 +109,7 @@
> Non-interactive approvers implemented as observers SHOULD
> also set <tp:member-ref>DelayApprovers</tp:member-ref> to TRUE
> so that other Approvers are not called on until all observers
>- return from <tp:member-ref>ObserveChannels</tp:member-ref>.
>+ return from <tp:member-ref>ObserveChannel</tp:member-ref>.
> This gives non-interactive approvers a chance to claim the
> channels before Approvers are called.
> </tp:docstring>
>@@ -119,7 +119,7 @@
> type="aa{sv}" access="read" tp:type="Channel_Class[]">
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> A specification of the channels in which this observer is
>- interested. The <tp:member-ref>ObserveChannels</tp:member-ref> method
>+ interested. The <tp:member-ref>ObserveChannel</tp:member-ref> method
> should be called by the channel dispatcher whenever the new
> channel in a <tp:dbus-ref
> namespace="im.telepathy.v1.Connection">NewChannel</tp:dbus-ref>
>@@ -215,14 +215,14 @@ im.telepathy.v1.Channel.Requested b=true
> 
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> If true, upon the startup of this observer, <tp:dbus-ref
>- namespace="im.telepathy.v1.Client.Observer">ObserveChannels</tp:dbus-ref>
>+ namespace="im.telepathy.v1.Client.Observer">ObserveChannel</tp:dbus-ref>
> will be called for every already existing channel matching
> its <tp:dbus-ref
> namespace="im.telepathy.v1.Client.Observer">ObserverChannelFilter</tp:dbus-ref>
> 
> When an activatable client having this property disappears from the
> bus and there are channels matching its ObserverChannelFilter,
>- ObserveChannels will be called immediately to reactivate it
>+ ObserveChannel will be called immediately to reactivate it
> again. Such clients should specify this property in their
> <tt>.client</tt> file as follows:
> 
>@@ -245,13 +245,13 @@ Recover=true
> currently active at the time that it starts up.
> </tp:rationale>
> 
>- When the ObserveChannels method is called due to observer recovery,
>+ When the ObserveChannel method is called due to observer recovery,
> the <var>Observer_Info</var> dictionary will contain one extra item
> mapping the key <code>"recovering"</code> to <code>True</code>.
> </tp:docstring>
> </property>
> 
>- <method name="ObserveChannels" tp:name-for-bindings="Observe_Channels">
>+ <method name="ObserveChannel" tp:name-for-bindings="Observe_Channel">
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> Called by the channel dispatcher when a channel in which the
> observer has registered an interest are announced in a <tp:dbus-ref
>@@ -265,7 +265,7 @@ Recover=true
> <tp:rationale>
> The channel dispatcher must wait for observers to start up,
> to avoid the following race: text channel logger (observer) gets
>- ObserveChannels, text channel handler gets
>+ ObserveChannel, text channel handler gets
> <tp:dbus-ref
> namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref>
> channel handler starts up faster and acknowledges messages,
>@@ -288,7 +288,7 @@ Recover=true
> <tp:docstring>
> The
> <tp:dbus-ref namespace="im.telepathy.v1">Account</tp:dbus-ref>
>- with which the channels are associated. The
>+ with which the channel is associated. The
> well-known bus name to use is that of the
> <tp:dbus-ref namespace="im.telepathy.v1">AccountManager</tp:dbus-ref>.
> </tp:docstring>
>@@ -298,20 +298,25 @@ Recover=true
> <tp:docstring>
> The
> <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref>
>- with which the channels are associated. The
>+ with which the channel is associated. The
> well-known bus name to use can be derived from this object
> path by removing the leading '/' and replacing all subsequent
> '/' by '.'.
> </tp:docstring>
> </arg>
> 
>- <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]"
>- direction="in">
>- <tp:docstring>
>- The <tp:dbus-ref
>- namespace="im.telepathy.v1">Channel</tp:dbus-ref>s
>- and their properties. Their well-known bus names are all the same as
>- that of the Connection.
>+ <arg name="Channel" direction="in" type="o">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ The Channel object. Its well-known bus name is the same
>+ as that of the Connection.
>+ </tp:docstring>
>+ </arg>
>+
>+ <arg name="Channel_Properties" direction="in" type="a{sv}"
>+ tp:type="Qualified_Property_Value_Map">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ Properties of the channel, equivalent to
>+ the properties in <tp:type>Channel_Details</tp:type>.
> </tp:docstring>
> </arg>
> 
>@@ -319,8 +324,8 @@ Recover=true
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> The path to the <tp:dbus-ref
> namespace="im.telepathy.v1">ChannelDispatchOperation</tp:dbus-ref>
>- for these channels, or the special value '/' if there is no
>- ChannelDispatchOperation (because the channels were requested, not
>+ for this channel, or the special value '/' if there is no
>+ ChannelDispatchOperation (because the channel was requested, not
> incoming).
> 
> If the Observer calls <tp:dbus-ref
>@@ -329,12 +334,12 @@ Recover=true
> namespace="im.telepathy.v1.ChannelDispatchOperation">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>.
>+ from <tp:member-ref>ObserveChannel</tp:member-ref>.
> 
> <tp:rationale>
> This allows an Observer to <tp:dbus-ref
> namespace="im.telepathy.v1.ChannelDispatchOperation">Claim</tp:dbus-ref>
>- a set of channels without having to match up calls to this method
>+ a channel without having to match up calls to this method
> with calls to <tp:dbus-ref
> namespace="im.telepathy.v1.Client.Approver">AddDispatchOperation</tp:dbus-ref>.
> </tp:rationale>
>@@ -345,7 +350,7 @@ Recover=true
> <tp:docstring>
> The <tp:dbus-ref
> namespace="im.telepathy.v1">ChannelRequest</tp:dbus-ref>s
>- satisfied by these channels.
>+ satisfied by this channel.
> 
> <tp:rationale>
> If the same process is an Observer and a Handler, it can be useful
>@@ -358,12 +363,12 @@ Recover=true
> 
> <arg name="Observer_Info" type="a{sv}" direction="in">
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>- Additional information about these channels. Currently defined
>+ Additional information about this channel. Currently defined
> keys are:
> 
> <dl>
> <dt><code>recovering</code> - b</dt>
>- <dd><code>True</code> if ObserveChannels was called for an existing
>+ <dd><code>True</code> if ObserveChannel was called for an existing
> channel (due to the <tp:member-ref>Recover</tp:member-ref>
> property being <code>True</code>); <code>False</code> or omitted
> otherwise.
>@@ -396,7 +401,7 @@ Recover=true
> <tp:added version="0.21.11"/>
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> If true, the channel dispatcher will wait for
>- <tp:member-ref>ObserveChannels</tp:member-ref> to return
>+ <tp:member-ref>ObserveChannel</tp:member-ref> to return
> before calling <tp:dbus-ref
> namespace="imt1.Client">Approver.AddDispatchOperation</tp:dbus-ref>
> on appropriate Approvers.
>-- 
>1.8.4.2
>

Actions: View | Splinter Review

Attachments on bug 69430: 88629 | 88630 | 88631 | 88632 | 88633 | 88634 | 88635 | 88636 | 88637 | 88638 | 88639 | 88640 | 92141

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.