soci/docs/multithreading.md

0001 # Multithreading
0002
0003 The general rule for multithreading is that SOCI classes are *not* thread-safe, meaning that their instances should not be used concurrently by multiple threads.
0004
0005 The simplest solution for multithreaded code is to set up a separate `session` object for each thread that needs to inteact with the database.
0006 Depending on the design of the client application this might be also the most straightforward approach.
0007
0008 For some applications, however, it might be preferable to decouple the set of threads from the set of sessions, so that they can be optimized separately with different resources in mind.
0009 The `connection_pool` class is provided for this purpose:
0010
0011 ```cpp
0012 // phase 1: preparation
0013
0014 const size_t poolSize = 10;
0015 connection_pool pool(poolSize);
0016
0017 for (size_t i = 0; i != poolSize; ++i)
0018 {
0019     session & sql = pool.at(i);
0020
0021     sql.open("postgresql://dbname=mydb");
0022 }
0023
0024 // phase 2: usage from working threads
0025
0026 {
0027     session sql(pool);
0028
0029     sql << "select something from somewhere...";
0030
0031 } // session is returned to the pool automatically
0032 ```
0033
0034 The `connection_pool`'s constructor expects the size of the pool and internally creates an array of `session`s in the disconnected state.
0035 Later, the `at` function provides *non-synchronized* access to each element of the array.
0036 Note that this function is *not* thread-safe and exists only to make it easier to set up the pool in the initialization phase.
0037
0038 Note that it is not obligatory to use the same connection parameters for all sessions in the pool, although this will be most likely the usual case.
0039
0040 The working threads that need to *lease* a single session from the pool use the dedicated constructor of the `session` class - this constructor blocks until some session object becomes available in the pool and attaches to it, so that all further uses will be forwarded to the `session` object managed by the pool.
0041 As long as the local `session` object exists, the associated session in the pool is *locked* and no other thread will gain access to it.
0042 When the local `session` variable goes out of scope, the related entry in the pool's internal array is released, so that it can be used by other threads.
0043 This way, the connection pool guarantees that its session objects are never used by more than one thread at a time.
0044
0045 Note that the above scheme is the simplest way to use the connection pool, but it is also constraining in the fact that the `session`'s constructor can *block* waiting for the availability of some entry in the pool.
0046 For more demanding users there are also low-level functions that allow to lease sessions from the pool with timeout on wait.
0047 Please consult the [reference](api/client.md) for details.