doc: be explicit about requests not returning a value

Submitted by Varad Gautam on May 16, 2017, 5:53 a.m.

Details

Message ID 20170516055355.6466-1-varadgautam@gmail.com
State New
Headers show
Series "doc: be explicit about requests not returning a value" ( rev: 1 ) in Wayland

Not browsing as part of any series.

Commit Message

Varad Gautam May 16, 2017, 5:53 a.m.
From: Varad Gautam <varad.gautam@collabora.com>

document how the asynchronous model works for requests and events to avoid
any confusion.

Signed-off-by: Varad Gautam <varad.gautam@collabora.com>
Suggested-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
---
 doc/publican/sources/Protocol.xml | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

Patch hide | download patch | download mbox

diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
index ba6b5f1..b8c30fe 100644
--- a/doc/publican/sources/Protocol.xml
+++ b/doc/publican/sources/Protocol.xml
@@ -52,7 +52,12 @@ 
       object ID and the event opcode, from which the client can determine
       the type of event.  Events are generated both in response to requests
       (in which case the request and the event constitutes a round trip) or
-      spontaneously when the server state changes.
+      spontaneously when the server state changes.  As the Wayland protocol
+      follows an asynchronous request model, there is no concept of
+      'return value' for requests.  A client can only receive information from
+      the server in the form of events.  Hence, if a client cannot proceed
+      without getting some information from the server, it must invoke a
+      round trip by issuing a <function>wl_display_roundtrip</function> call.
     </para>
     <para>
       <itemizedlist>

Comments

On Tue, 16 May 2017 11:23:55 +0530
Varad Gautam <varadgautam@gmail.com> wrote:

> From: Varad Gautam <varad.gautam@collabora.com>
> 
> document how the asynchronous model works for requests and events to avoid
> any confusion.
> 
> Signed-off-by: Varad Gautam <varad.gautam@collabora.com>
> Suggested-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
> ---
>  doc/publican/sources/Protocol.xml | 7 ++++++-
>  1 file changed, 6 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
> index ba6b5f1..b8c30fe 100644
> --- a/doc/publican/sources/Protocol.xml
> +++ b/doc/publican/sources/Protocol.xml
> @@ -52,7 +52,12 @@
>        object ID and the event opcode, from which the client can determine
>        the type of event.  Events are generated both in response to requests
>        (in which case the request and the event constitutes a round trip) or
> -      spontaneously when the server state changes.
> +      spontaneously when the server state changes.  As the Wayland protocol
> +      follows an asynchronous request model, there is no concept of
> +      'return value' for requests.  A client can only receive information from
> +      the server in the form of events.  Hence, if a client cannot proceed
> +      without getting some information from the server, it must invoke a
> +      round trip by issuing a <function>wl_display_roundtrip</function> call.
>      </para>
>      <para>
>        <itemizedlist>

Hi Varad,

I had to read this a couple of times before I could understand what you
are after. That's probably not a good sign, considering I recently
explained the same thing on the mailing list. ;-)

How about a new paragraph instead, with a more verbose and explicit
description?

- there is no concept of return value; why; do not be fooled by the C
  API
- what do you need to do instead if you need one: explicitly define a
  reply event in the protocol
- if one needs to block waiting for the reply, how
- how to coalesce several request-reply pairs into one roundtrip
- prefer protocol designs where there is no need to block waiting
- the inverse: server needing info from client; the server must never
  block waiting

Maybe it'd need a sub-heading even?


Thanks,
pq