[gtk/ebassi/run-dialog-run: 22/22] docs: Mention blocking functions in the migration guide

[Emmanuele Bassi <ebassi src gnome org>]

commit 1b49f6c49a51c72542baf98ebe4371557ff1273d
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Apr 30 16:08:37 2020 +0100

    docs: Mention blocking functions in the migration guide
    
    Link to how to make a dialog modal, and to the response signal.

 docs/reference/gtk/migrating-3to4.xml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
---
diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml
index 53c1b67ef1..4676ce01d3 100644
--- a/docs/reference/gtk/migrating-3to4.xml
+++ b/docs/reference/gtk/migrating-3to4.xml
@@ -1157,5 +1157,24 @@
         emitted.
       </para>
     </section>
+
+    <section>
+      <title>Stop using blocking dialog functions</title>
+      <para>
+        GtkDialog, GtkNativeDialog, and GtkPrintOperation removed their
+        blocking API using nested main loops. Nested main loops present
+        re-entrancy issues and other hard to debug issues when coupled
+        with other event sources (IPC, accessibility, network operations)
+        that are not under the toolkit or the application developer's
+        control. Additionally, "stop-the-world" functions do not fit
+        the event-driven programming model of GTK.
+      </para>
+      <para>
+        You can replace calls to <function>gtk_dialog_run()</function>
+        by specifying that the #GtkDialog must be modal using
+        gtk_window_set_modal() or the %GTK_DIALOG_MODAL flag, and
+        connecting to the #GtkDialog::response signal.
+      </para>
+    </section>
   </section>
 </chapter>