[PATCH] doc: be explicit about requests not returning a value

[Pekka Paalanen]

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

> From: Varad Gautam <varad.gautam at collabora.com>
> 
> document how the asynchronous model works for requests and events to avoid
> any confusion.
> 
> Signed-off-by: Varad Gautam <varad.gautam at collabora.com>
> Suggested-by: Pekka Paalanen <pekka.paalanen at 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20170516/06ebde81/attachment.sig>