lib/libssh
1
0
Fork 0
mirror of https://git.libssh.org/projects/libssh.git synced 2025-07-31 00:03:07 +03:00
Code Activity

docs: Update threading documentation

Browse Source 
Updated threading documentation mentioning changes in the requirements
to use libssh in multithread scenarios.

Signed-off-by: Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
Reviewed-by: Andreas Schneider <asn@cryptomilk.org>
This commit is contained in:
Anderson Toshiyuki Sasaki
2018-08-24 14:24:12 +02:00
committed by Andreas Schneider
parent a97e227a9d
commit d0f3cdfa10
1 changed files with 28 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
doc/threading.dox
View File

@ -3,64 +3,50 @@
@section threads_with_libssh How to use libssh with threads @section threads_with_libssh How to use libssh with threads
libssh may be used in multithreaded applications, but under several conditions : libssh may be used in multithreaded applications, but under several conditions :
- Threading must be initialized during the initialization of libssh. This - Your system must support libpthread or, in Windows environment,
initialization must be done outside of any threading context. CriticalSection based mutex control.
- If pthreads is being used by your application (or your framework's backend), - Since version 0.8.0, threads initialization is called automatically in the
you must link with libssh_threads dynamic library and initialize library constructor if libssh is dynamically linked. This means it is no
threading with the ssh_threads_pthreads threading object. longer necessary to call ssh_init()/ssh_finalize().
- If an other threading library is being used by your application, you must - If libssh is statically linked, threading must be initialized by calling
implement all the methods of the ssh_threads_callbacks_struct structure ssh_init() before using any of libssh provided functions. This initialization
and initialize libssh with it. must be done outside of any threading context. Don't forget to call
ssh_finalize() to avoid memory leak
- At all times, you may use different sessions inside threads, make parallel - At all times, you may use different sessions inside threads, make parallel
connections, read/write on different sessions and so on. You *cannot* use a connections, read/write on different sessions and so on. You *cannot* use a
single session (or channels for a single session) in several threads at the same single session (or channels for a single session) in several threads at the same
time. This will most likely lead to internal state corruption. This limitation is time. This will most likely lead to internal state corruption. This limitation is
being worked out and will maybe disappear later. being worked out and will maybe disappear later.
@subsection threads_init Initialization of threads @subsection threads_init Initialization of threads
To initialize threading, you must first select the threading model you want to Since version 0.8.0, it is no longer necessary to call ssh_init()/ssh_finalize()
use, using ssh_threads_set_callbacks(), then call ssh_init(). if libssh is dynamically linked.
@code If libssh is statically linked, call ssh_init() before using any of libssh
#include <libssh/callbacks.h> provided functions.
...
ssh_threads_set_callbacks(ssh_threads_get_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 @subsection threads_pthread Using libpthread with libssh
If your application is using libpthread, you may simply use the libpthread Since version 0.8.0, libpthread is the default threads library used by libssh.
threading backend:
@code To use libpthread, simply link it to you application.
#include <libssh/callbacks.h>
...
ssh_threads_set_callbacks(ssh_threads_get_pthread());
ssh_init();
@endcode
However, you must be sure to link with the library ssh_threads. If
you're using gcc, you must use the commandline
@code
gcc -o output input.c -lssh -lssh_threads
@endcode
If you are using libssh statically linked, don't forget to call ssh_init()
before using any of libssh provided functions (and ssh_finalize() in the end).
@subsection threads_other Using another threading library @subsection threads_other Using another threading library
You must find your way in the ssh_threads_callbacks_struct structure. You must Since version 0.8.0, libssh does not support custom threading libraries.
implement the following methods : The change makes sense since the newer versions for libcrypto (OpenSSL) and
- mutex_lock libgcrypt don't support custom threading libraries.
- mutex_unlock
- mutex_init The default used threading library is libpthread.
- mutex_destroy Alternatively, in Windows environment, CriticalSection based mutex control can
- thread_id be used.
If your system does not support libpthread nor CriticalSection based mutex
control, unfortunately, you cannot use libssh in multithreaded scenarios.
libgcrypt 1.6 and bigger backend does not support custom callback. Using anything else than pthreads (ssh_threads_get_pthread()) here will fail.
Good luck ! Good luck !
*/ */