#################################################
Overview of Firebird Client Library Thread-Safety
#################################################


The thread-safety properties of the standard Firebird client library
vary according to the following:


+ Firebird version
+ operating system
+ Firebird server architecture (SuperServer, Classic, Embedded)
+ underlying connection protocol (embedded vs. local vs. IPC vs.
  remote)


Determining whether the client library you're using is thread-safe can
be quite confusing. This document aims to reduce that confusion by
defining what thread-safety means in the context of the Firebird
client library, then presenting a table that specifies which client
library configurations are thread-safe.

Note that this document deals only with the *standard* Firebird client
library that underlies the Firebird C API. It has *no relevance* to
the clean-slate reimplementations in access libraries such as Jaybird.


Definition of "Thread-Safety"
=============================

Currently, the highest level of concurrency supported by any version
of the Firebird client library is *thread-safety at the connection
level*.

When we say that the Firebird client library is *thread-safe at the
connection level*, we mean that it is safe to use a particular
connection in only one thread at a time, although the same connection
can be manipulated by different threads in a serial fashion, and
different connections can be manipulated by different threads in
parallel.

For example, in a multithreaded application server, it is safe for a
particular connection to be leased from a connection pool by Thread A,
used, and returned to the pool for later lease by Thread B. It is not
safe for Thread A and Thread B to use the same connection at the same
time.


Thread-Safety Table
===================


+------------+---------+-----------------+----------------+--------------------+
| FB Version | OS      | FB Architecture | Remote / Local | Thread-Safe?       |
+============+=========+=================+================+====================+
| 1.0.3      | Windows | SuperServer     | Local          | No                 |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | Classic         | Local          | No such config.    |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | No such config.    |
|            |         +-----------------+----------------+--------------------+
|            |         | Embedded        | Local          | No such config.    |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | No such config.    |
|            +---------+-----------------+----------------+--------------------+
|            | Linux   | SuperServer     | Local          | No such config.    |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | No                 |
|            |         +-----------------+----------------+--------------------+
|            |         | Classic         | Local          | No                 |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | No                 |
+------------+---------+-----------------+----------------+--------------------+
| 1.5        | Windows | SuperServer     | Local          | No                 |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | Classic         | Local          | No such config.    |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | Embedded        | Local          | Yes                |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | No such config.    |
|            +---------+-----------------+----------------+--------------------+
|            | Linux   | SuperServer     | Local          | No such config.    |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | Classic         | Local          | No                 |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | No                 |
+------------+---------+-----------------+----------------+--------------------+
| 2.0/2.1    | Windows | SuperServer     | Local          | Yes                |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | Classic         | Local          | Yes                |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | Embedded        | Local          | Yes                |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | No such config.    |
|            +---------+-----------------+----------------+--------------------+
|            | Linux   | SuperServer     | Local          | No such config.    |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | Classic         | Local          | No                 |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | No                 |
+------------+---------+-----------------+----------------+--------------------+

This document was written by David Rushby, with assistance from Dmitry
Yemanov. Errors are attributable to Rushby rather than Yemanov.