Thread model | Tarantool
Concepts Transactions Thread model

Thread model

The thread model assumes that a query received by Tarantool via network is processed with three operating system threads:

  1. The network thread (or threads) on the server side receives the query, parses the statement, checks if it is correct, and then transforms it into a special structure – a message containing an executable statement and its options.

  2. The network thread sends this message to the instance’s transaction processor thread (TX thread) via a lock-free message bus. Lua programs are executed directly in the transaction processor thread, and do not need to be parsed and prepared.

    The TX thread either uses a space index to find and update the tuple, or executes a stored function that performs a data operation.

  3. The execution of the operation results in a message to the write-ahead logging (WAL) thread used to commit the transaction and the fiber executing the transaction is suspended. When the transaction results in a COMMIT or ROLLBACK, the following actions are taken:

    • The WAL thread responds with a message to the TX thread.
    • The fiber executing the transaction is resumed to process the result of the transaction.
    • The result of the fiber execution is passed to the network thread, and the network thread returns the result to the client.


There is only one TX thread in Tarantool. Some users are used to the idea that there can be multiple threads working on the database. For example, thread #1 reads a row #x while thread #2 writes a row #y. With Tarantool this does not happen. Only the TX thread can access the database, and there is only one TX thread for each Tarantool instance.

The TX thread can handle many fibers – a set of computer instructions that can contain “yield” signals. The TX thread executes all computer instructions up to a yield signal, and then switches to execute the instructions of another fiber.

Yields must happen, otherwise the TX thread would be permanently stuck on the same fiber.

There are also several supplementary threads that serve additional capabilities:

  • For replication, Tarantool creates a separate thread for each connected replica. This thread reads a write-ahead log and sends it to the replica, following its position in the log. Separate threads are required because each replica can point to a different position in the log and can run at different speeds.

  • There is a thread pool for ad hoc asynchronous tasks, such as a DNS resolver or fsync.

  • There are OpenMP threads used to parallelize sorting (hence, to parallelize building indexes). For example, this is applicable when Tarantool is restoring from a snapshot with a large amount of data and needs to sort a secondary index if it is ordered by something other than the primary order.


    The maximum number of OpenMP threads can be controlled by the OMP_NUM_THREADS environment variable.

Found what you were looking for?