#################################################
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, SuperClassic, 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
===================


+------------+---------+-----------------+----------------+--------------------+
| 2.0/2.1.x  | 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                 |
+------------+---------+-----------------+----------------+--------------------+
| 2.5.x      | Windows | SuperServer     | Local          | Yes                |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | Classic         | Local          | Yes                |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | SuperClassic    | Local          | Yes                |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | Embedded        | Local          | Yes                |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | No such config.    |
|            +---------+-----------------+----------------+--------------------+
|            | Linux   | SuperServer     | Local          | No such config.    |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | Classic         | Local          | Yes                |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | SuperClassic    | Local          | Yes                |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | Yes                |
|            |         +-----------------+----------------+--------------------+
|            |         | Embedded        | Local          | Yes                |
|            |         |                 +----------------+--------------------+
|            |         |                 | Remote         | No such config.    |
+------------+---------+-----------------+----------------+--------------------+

