[mutter/wayland] Discourage server grabs

[Daniel Drake <dsd src gnome org>]

commit becbad56ef8e3621f451bf9def42c7de0c9d0bf0
Author: Daniel Drake <drake endlessm com>
Date:   Mon Dec 30 16:52:14 2013 -0600

    Discourage server grabs
    
    Server grabs are not as evil as you might expect, but there is agreement
    in that their usage should be limited.
    
    Server grabs can cause things to go rather wrong when mutter emits
    a signal while it has grabbed the server. If the receiver of that signal
    waits for a synchronous action performed by another client, then you
    have a deadlock. This happens with Mali binary GLESv2 drivers :(
    
    https://bugzilla.gnome.org/show_bug.cgi?id=721345

 src/core/display.c |   13 ++++++++++++-
 1 files changed, 12 insertions(+), 1 deletions(-)
---
diff --git a/src/core/display.c b/src/core/display.c
index ce33923..eced287 100644
--- a/src/core/display.c
+++ b/src/core/display.c
@@ -1155,7 +1155,18 @@ meta_display_screen_for_x_screen (MetaDisplay *display,
   return NULL;
 }
 
-/* Grab/ungrab routines taken from fvwm */
+/* Grab/ungrab routines taken from fvwm.
+ * Calling this function will cause X to ignore all other clients until
+ * you ungrab. This may not be quite as bad as it sounds, yet there is
+ * agreement that avoiding server grabs except when they are clearly needed
+ * is a good thing.
+ *
+ * If you do use such grabs, please clearly explain the necessity for their
+ * usage in a comment. Try to keep their scope extremely limited. In
+ * particular, try to avoid emitting any signals or notifications while
+ * a grab is active (if the signal receiver tries to block on an X request
+ * from another client at this point, you will have a deadlock).
+ */
 void
 meta_display_grab (MetaDisplay *display)
 {