[tracker/wip/carlosg/doc-improvements: 3/5] libtracker-sparql: Add some documentation about allowed multi-thread usage

[Carlos Garnacho <carlosg src gnome org>]

commit 54730d1ab727081d32315c7c34f93ef324dcb68d
Author: Carlos Garnacho <carlosg gnome org>
Date:   Wed Sep 15 21:00:58 2021 +0200

    libtracker-sparql: Add some documentation about allowed multi-thread usage
    
    Spell these a bit louder out for the main library objects.

 src/libtracker-sparql/tracker-connection.c    | 4 ++++
 src/libtracker-sparql/tracker-cursor.c        | 4 ++++
 src/libtracker-sparql/tracker-endpoint-dbus.c | 3 +++
 src/libtracker-sparql/tracker-endpoint-http.c | 3 +++
 src/libtracker-sparql/tracker-statement.c     | 4 +++-
 5 files changed, 17 insertions(+), 1 deletion(-)
---
diff --git a/src/libtracker-sparql/tracker-connection.c b/src/libtracker-sparql/tracker-connection.c
index 9584a057b..adc9b3d92 100644
--- a/src/libtracker-sparql/tracker-connection.c
+++ b/src/libtracker-sparql/tracker-connection.c
@@ -51,6 +51,10 @@
  *
  * After use, a #TrackerSparqlConnection should be closed. See
  * tracker_sparql_connection_close() and tracker_sparql_connection_close_async().
+ *
+ * A #TrackerSparqlConnection may be used from multiple threads, asynchronous
+ * database updates are executed sequentially on arrival order, asynchronous
+ * queries are executed in a thread pool.
  */
 #include "config.h"
 
diff --git a/src/libtracker-sparql/tracker-cursor.c b/src/libtracker-sparql/tracker-cursor.c
index 3b7d9da09..ae871b790 100644
--- a/src/libtracker-sparql/tracker-cursor.c
+++ b/src/libtracker-sparql/tracker-cursor.c
@@ -25,6 +25,10 @@
  *
  * #TrackerSparqlCursor is an object which provides methods to iterate the
  * results of a query to the Tracker Store.
+ *
+ * It is possible to use a given #TrackerSparqlCursor in other threads than
+ * the one it was created from. It must be however used from just one thread
+ * at any given time.
  */
 #include "config.h"
 
diff --git a/src/libtracker-sparql/tracker-endpoint-dbus.c b/src/libtracker-sparql/tracker-endpoint-dbus.c
index 602614f58..527e3f33a 100644
--- a/src/libtracker-sparql/tracker-endpoint-dbus.c
+++ b/src/libtracker-sparql/tracker-endpoint-dbus.c
@@ -34,6 +34,9 @@
  * the Tracker portal service for applications sandboxed via Flatpak, and
  * access to data constrained to the graphs defined in the applications
  * manifest.
+ *
+ * A #TrackerEndpointDBus may be created on a different thread/main
+ * context than the one creating the #TrackerSparqlConnection.
  */
 
 #include "config.h"
diff --git a/src/libtracker-sparql/tracker-endpoint-http.c b/src/libtracker-sparql/tracker-endpoint-http.c
index e4b6a9ec9..4ff89d6f9 100644
--- a/src/libtracker-sparql/tracker-endpoint-http.c
+++ b/src/libtracker-sparql/tracker-endpoint-http.c
@@ -34,6 +34,9 @@
  * #TrackerEndpointHttp::block-remote-address signal, the boolean
  * return value expressing whether the connection is blocked or not.
  * Inspection of the requester address is left up to the user.
+ *
+ * A #TrackerEndpointHttp may be created on a different thread/main
+ * context than the one creating the #TrackerSparqlConnection.
  */
 
 #include "config.h"
diff --git a/src/libtracker-sparql/tracker-statement.c b/src/libtracker-sparql/tracker-statement.c
index c3d0ce30b..261265197 100644
--- a/src/libtracker-sparql/tracker-statement.c
+++ b/src/libtracker-sparql/tracker-statement.c
@@ -38,7 +38,9 @@
  * Once all arguments have a value, the query may be executed through
  * tracker_sparql_statement_execute() or tracker_sparql_statement_execute_async().
  *
- * This object was added in Tracker 2.2.
+ * It is possible to use a given #TrackerSparqlStatement in other threads than
+ * the one it was created from. It must be however used from just one thread
+ * at any given time.
  */
 #include "config.h"