[aravis] documentation: add some words regarding thread safety

[Emmanuel Pacaud <emmanuel src gnome org>]

commit a832bf15113bc370f94680c8576ed67a22c389f5
Author: Emmanuel Pacaud <emmanuel gnome org>
Date:   Mon Sep 8 15:47:12 2014 +0200

    documentation: add some words regarding thread safety

 docs/reference/aravis/aravis-overview.xml |   22 +++++++++++++++++++++-
 src/arvstream.c                           |    8 ++++++++
 2 files changed, 29 insertions(+), 1 deletions(-)
---
diff --git a/docs/reference/aravis/aravis-overview.xml b/docs/reference/aravis/aravis-overview.xml
index 28ae79b..219aaf6 100644
--- a/docs/reference/aravis/aravis-overview.xml
+++ b/docs/reference/aravis/aravis-overview.xml
@@ -34,8 +34,28 @@
                </para>
        </chapter>
 
+       <chapter id="thread-safety">
+               <title>Thread Safety</title>
+
+               <para>
+                       Aravis is not thread safe, which means one can not use the same object
+                       simultaneously from different threads, without using mutexes. But it is
+                       perfectly fine to use different aravis objects in different threads.
+               </para>
+
+               <para>
+                       A possible trap is that glib signal callbacks are called from the thread that
+                       emitted the corresponding signal. For example, the "new-buffer" callback is
+                       emitted from the stream packet receiving thread, which is an internal thread
+                       created by ArvGvStream. It is not safe to use ArvDevice and some ArvStream
+                       functions from this callback without using mutexes. The exceptions are
+                       #arv_stream_push_buffer, #arv_stream_pop_buffer, #arv_stream_try_pop_buffer and
+                       #arv_stream_timeout_pop_buffer.
+               </para>
+       </chapter>
+
        <chapter id="aravis-building">
-               <title>Building and debugging Aravis</title>
+               <title>Building and Debugging Aravis</title>
 
                <para>
                        On UNIX, Aravis uses the standard GNU build system, using
diff --git a/src/arvstream.c b/src/arvstream.c
index 573edc2..0afc8d4 100644
--- a/src/arvstream.c
+++ b/src/arvstream.c
@@ -64,6 +64,8 @@ struct _ArvStreamPrivate {
  * Pushes a #ArvBuffer to the @stream thread. The @stream takes ownership of @buffer,
  * and will free all the buffers still in its queues when destroyed.
  *
+ * This method is thread safe.
+ *
  * Since: 0.2.0
  */
 
@@ -84,6 +86,8 @@ arv_stream_push_buffer (ArvStream *stream, ArvBuffer *buffer)
  * may contain an invalid image. Caller should check the buffer status before using it.
  * This function blocks until a buffer is available.
  *
+ * This method is thread safe.
+ *
  * Returns: (transfer full): a #ArvBuffer
  *
  * Since: 0.2.0
@@ -105,6 +109,8 @@ arv_stream_pop_buffer (ArvStream *stream)
  * may contain an invalid image. Caller should check the buffer status before using it.
  * This is the non blocking version of pop_buffer.
  *
+ * This method is thread safe.
+ *
  * Returns: (transfer full): a #ArvBuffer, NULL if no buffer is available.
  *
  * Since: 0.2.0
@@ -126,6 +132,8 @@ arv_stream_try_pop_buffer (ArvStream *stream)
  * Pops a buffer from the output queue of @stream, waiting no more than @timeout. The retrieved buffer
  * may contain an invalid image. Caller should check the buffer status before using it.
  *
+ * This method is thread safe.
+ *
  * Returns: (transfer full): a #ArvBuffer, NULL if no buffer is available until the timeout occurs.
  *
  * Since: 0.2.0