libssh 0.7.5

Chapter 8: 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 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 cannot use a 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 being worked out and will maybe disappear later.

## 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().

#include <libssh/callbacks.h>
...
ssh_threads_set_callbacks(ssh_threads_get_noop());
ssh_init();

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.

## Using libpthread with libssh

If your application is using libpthread, you may simply use the libpthread threading backend:

#include <libssh/callbacks.h>
...
ssh_threads_set_callbacks(ssh_threads_get_pthread());
ssh_init();

However, you must be sure to link with the library ssh_threads. If you're using gcc, you must use the commandline

gcc -o output input.c -lssh -lssh_threads

## 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

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 !