4.10 Multi-threaded Applications

Elephant is thread-safe by design. Users should not have to think about threading except to follow a couple of simple rules.

1. Do not perform transactions across multiple threads
2. Do not perform add/remove index operations on indexed-btrees in more than one thread.

This and common coding sense should be sufficient! Elephant's internal design for thread safety employs a number of policies to try to minimize using lisp locks and simplify analysis of multi threaded interactions:

1. Rely on the thread safety of the data store databases
2. Ensure transaction isolation
3. Minimize dependency on thread-local special variables
4. Protect shared resources for a given store controller.
5. A use policy for shared objects (above)

4.10.1 Shared Resources

Elephant has a few shared resources which are protected by standard locks. These are:

• The store controller connection table
• The instance cache
• The circularity buffer pool for the serializer
• The buffer-stream pool in memutils

In some cases, and on some lisp platforms, we try to use a fast lock strategy for frequently accessed items (the resource pools and instance cache especially).

4.10.2 Data Store Thread Safety and Transactions

Both CLSQL and Berkelely DB backends are thread safe. In CLSQL this is by ensuring that every thread has it's own handle into the SQL libraries or sockets. Berkeley DB is reentrant and handles locking internally.

Elephant depends on these guarantees especially for the isolation properties of transactions. All operations in the context of a given transaction should be isolated and atomic. It is important that a transaction not be shared across threads, however.

4.10.3 Minimize Dependency on Thread-Local Specials

Elephant uses several global variables as default arguments. Most of these were removed leaving only a couple to handle:

• *store-controller*. Store controller objects can be shared between threads and if a user resets this variable in a local thread to another controller, there is no problem with that either. Users of multiple concurrent stores can specify the store controller to all elephant API commands that don't get it from a persistent object implicitely. *current-transaction*. This is always set to the proper null value globally and should not be reset in local threads. Instead, transactions take place in a dynamic context that rebinds this variable as a special with the current transaction. This allows for a dynamic transaction stack for data stores that can nest transactions or when two datastores are both doing transactions concurrently.