[glib/mcatanzaro/#2211: 3/6] gsocketclient: document Happy Eyeballs

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 023ae2590d9775a586767273dd544000de364ccb
Author: Michael Catanzaro <mcatanzaro gnome org>
Date:   Thu Oct 8 19:08:34 2020 -0500

    gsocketclient: document Happy Eyeballs
    
    This isn't an API guarantee, but it's a potentially-surprising
    behavior difference between the sync and async functions that is good
    to know about, especially because our sync and async functions are
    normally identical.

 gio/gsocketclient.c | 8 ++++++++
 1 file changed, 8 insertions(+)
---
diff --git a/gio/gsocketclient.c b/gio/gsocketclient.c
index 24505c882..24c5100bd 100644
--- a/gio/gsocketclient.c
+++ b/gio/gsocketclient.c
@@ -1927,6 +1927,14 @@ g_socket_client_enumerator_callback (GObject      *object,
  *
  * This is the asynchronous version of g_socket_client_connect().
  *
+ * You may wish to prefer the asynchronous version even in synchronous
+ * command line programs because, since 2.60, it implements RFC 6555
+ * "Happy Eyeballs" recommendations to work around long connection
+ * timeouts in networks where IPv6 is broken by performing an IPv4
+ * connection simultaneously without waiting for IPv6 to time out,
+ * which is not supported by the synchronous call. (This is not an API
+ * guarantee, and may be removed in the future.)
+ *
  * When the operation is finished @callback will be
  * called. You can then call g_socket_client_connect_finish() to get
  * the result of the operation.