[libgda] Asynchronous execution: doc and example update

[Vivien Malerba <vivien src gnome org>]

commit dfd631932914248036c176d6c223a7270d5d1222
Author: Vivien Malerba <malerba gnome-db org>
Date:   Thu Jul 19 12:51:50 2012 +0200

    Asynchronous execution: doc and example update

 libgda/gda-connection.c     |    5 +++++
 samples/AsyncExec/example.c |    7 ++++++-
 2 files changed, 11 insertions(+), 1 deletions(-)
---
diff --git a/libgda/gda-connection.c b/libgda/gda-connection.c
index d2c195d..53dc248 100644
--- a/libgda/gda-connection.c
+++ b/libgda/gda-connection.c
@@ -3179,6 +3179,11 @@ async_stmt_exec_cb (G_GNUC_UNUSED GdaServerProvider *provider, GdaConnection *cn
  * the connection has a transaction started and the failure invalidates the transaction (as decided by the database
  * server).
  *
+ * Note that for asynchronous calls to succeed, it is gererally necessary to specify the
+ * %GDA_CONNECTION_OPTIONS_THREAD_ISOLATED flag when opening the connection to be sure it is opened in a separate thread
+ * in which asynchronous calls are made (failing to use this flag make the asynchronous call dependant on the database
+ * provider implementation and at the moment none support this feature).
+ *
  * Returns: a task ID, or 0 if an error occurred (not an error regarding @stmt itself as its execution has not yet started
  * but any other error)
  *
diff --git a/samples/AsyncExec/example.c b/samples/AsyncExec/example.c
index 86eab7b..2f7f641 100644
--- a/samples/AsyncExec/example.c
+++ b/samples/AsyncExec/example.c
@@ -34,7 +34,12 @@ main (int argc, char** argv)
 
 	gda_init ();
 
-	cnc = gda_connection_open_from_dsn ("SalesTest", NULL, GDA_CONNECTION_OPTIONS_THREAD_SAFE, NULL);
+	/* REM: the GDA_CONNECTION_OPTIONS_THREAD_ISOLATED flag is necessary
+	 * to make sure the connection is opened in a separate thread from the main thread in order
+	 * for the asynchronous method to work. Failing to do so will generally (depending on the
+	 * database provider's implementation) lead to asynchronous execution failure.
+	 */
+	cnc = gda_connection_open_from_dsn ("SalesTest", NULL, GDA_CONNECTION_OPTIONS_THREAD_ISOLATED, NULL);
 	if (!cnc) {
 		g_print ("Can't open connection: %s\n", error && error->message ? error->message : "No detail");
 		return 1;