From f7ea9a3f27790345e9535ebe0ca01092b5be63b8 Mon Sep 17 00:00:00 2001
From: Aris Adamantiadis <aris@0xbadc0de.be>
Date: Sun, 12 Sep 2010 22:34:38 +0200
Subject: [PATCH] Added documentation for threading

---
 doc/introduction.dox |  2 ++
 doc/tbd.dox          |  1 -
 doc/threading.dox    | 65 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 67 insertions(+), 1 deletion(-)
 create mode 100644 doc/threading.dox

diff --git a/doc/introduction.dox b/doc/introduction.dox
index 20894821..9aca63e1 100644
--- a/doc/introduction.dox
+++ b/doc/introduction.dox
@@ -43,6 +43,8 @@ Table of contents:
 
 @subpage forwarding
 
+@subpage threads
+
 @subpage tbd
 
 */
diff --git a/doc/tbd.dox b/doc/tbd.dox
index 1e256fdb..e1ba046d 100644
--- a/doc/tbd.dox
+++ b/doc/tbd.dox
@@ -1,6 +1,5 @@
 /**
 @page tbd To be done
-@section threads Working with threads
 
 *** To be written ***
 
diff --git a/doc/threading.dox b/doc/threading.dox
new file mode 100644
index 00000000..4a45cfa4
--- /dev/null
+++ b/doc/threading.dox
@@ -0,0 +1,65 @@
+/**
+@page threads Chapter 8: Threads with libssh
+@section threads_with_libssh How to use libssh with threads
+
+libssh may be used in multithreaded applications, but under several conditions :
+ - Threading must be initialized during the initialization of libssh. This 
+   initialization must be done outside of any threading context.
+ - If pthreads is being used by your application (or your framework's backend),
+   you must link with libssh_threads_pthread dynamic library and initialize 
+   threading with the ssh_threads_pthreads threading object.
+ - If an other threading library is being used by your application, you must 
+   implement all the methods of the ssh_threads_callbacks_struct structure
+   and initialize libssh with it.
+ - At all times, you may use different sessions inside threads, make parallel
+   connections, read/write on different sessions and so on. You can use a
+   single session in several channels at the same time. This will lead to
+   internal state corruption. This limitation is being worked out and will
+   maybe disappear later.
+   
+@subsection threads_init Initialization of threads
+
+To initialize threading, you must first select the threading model you want to
+use, using ssh_threads_set_callbacks(), then call ssh_init().
+
+@code 
+#include <libssh/callbacks.h>
+...
+ssh_threads_set_callbacks(ssh_threads_noop);
+ssh_init();
+@endcode
+
+ssh_threads_noop is the threading structure that does nothing. It's the
+threading callbacks being used by default when you're not using threading.
+
+@subsection threads_pthread Using libpthread with libssh
+
+If your application is using libpthread, you may simply use the libpthread
+threading backend:
+
+@code
+#include <libssh/callbacks.h>
+...
+ssh_threads_set_callbacks(ssh_threads_pthread);
+ssh_init();
+@endcode
+
+However, you must be sure to link with the library ssh_threads_pthread. If 
+you're using gcc, you must use the commandline
+@code
+gcc -o output input.c -lssh -lssh_threads_pthread
+@endcode 
+
+
+@subsection threads_other Using another threading library
+
+You must find your way in the ssh_threads_callbacks_struct structure. You must
+implement the following methods :
+- mutex_lock
+- mutex_unlock
+- mutex_init
+- mutex_destroy
+- thread_id
+
+Good luck !
+*/