Subject: MirWaitHandle and client guarantees

From: Cemil Azizoglu <[email-masked]>
Date: Thu, 11 Feb 2016 15:20:01 -0600

Hi,

We've had extensive discussions on this topic recently in a (seemingly
harmless) MP [1]. Just wanted to compile the key points and actions that (I
think) came out of that discussion :

   - MirWaitHandle could potentially give clients the (false) impression
   that their request has been fulfilled, when, in fact for a number of
   reasons, it may not have been (e.g. MirWaitHandle returns after IPC but the
   server might still be working on it, or shell may have overridden client's
   request due to policy, etc).
   - We do not want a mechanism that synchronously serializes client
   requests, as some requests might be slow, and others fast.
   - Clients must not assume anything about the outcome of an operation
   (like a state change) - they should rather listen and react to
   (asynchronous) events coming from the server.
   - That said, MirWaitHandle could be useful for our tests which we have
   control over and can force the server to honor requests in a predictable
   manner, and with no interference from a (human) user, in order to create a
   certain scenario being tested.

Some actions we need to take :

   - Deprecate (and eventually privatize on the next ABI break)
   mir_wait_for() to prevent misuse/abuse.
   - Extend use of a MirSurfaceSpec-like api to make atomic changes. For
   everything else, clients should rely on an event-driven mechanism.
   - Review tests to make sure that MirWaitHandles are not being
   misused/abused/used unnecessarily.
   - Update documentation to emphasize what a MirWaitHandle does and how it
   should not be relied upon for request sequencing by the clients.
   - Perhaps we could write a simple, but nontrivial app as an example, to
   drive home the key points and avoid pitfalls.

Let me know if I've skipped anything. Otherwise, I'll create a card for
these.

[1]
https://code.launchpad.net/~alan-griffiths/mir/discussion-point/+merge/284935

Cemil Azizoglu
Mir Display Server - Team Lead
Canonical USA