Feature - Table Lock Policy

[cnoon]

This PR adds a new TableLockPolicy enum to SQift to enable table lock error handling internally for execute, prepare, and step operations.

Problem Statement

Table lock errors are SQLITE_ERROR types thrown by execute, prepare, and step operations. These errors can occur when the database is configured with a WAL journal mode as well as a shared cache. When one connection has obtained a lock on a table, another connection running on a different thread will receive table lock errors until the previous lock is released. In these situations, there are a couple of ways to proceed. The error can either be immediately thrown and handled by the client, or the calling thread can poll the operation until the lock is released.

Solution

The TableLockPolicy defines two different ways to handle table lock errors. The first option is to poll on the calling thread at a specified interval until the lock is released. The other option is to immediately fast fail by throwing the table lock error as soon as it is encountered. Connection, ConnectionPool, and Database types are set to .fastFail by default.

In order to enable polling for table lock errors, all that needs to be done is to set the policy in the Connection or Database initializer.

let connection = try Connection(storageLocation: storageLocation, tableLockPolicy: .poll(0.01))
let database = try Database(storageLocation: .onDisk("path_to_db"), tableLockPolicy: .poll(0.01))

When using a WAL journal mode and a shared cache, it is recommended to use a .poll table lock policy with a poll interval of 10 ms.

Testing

I've added as many tests as possible that reproduce the table lock error behavior. We've also been shipping these changes at scale in NRC and NTC over the past couple of months to ensure the TableLockPolicy does catch all the potential edge cases for table lock errors. We have now eliminated all the table lock errors in both apps and feel these changes are ready for release.

[ejensen]

A few of the new tests are failing on certain platforms

[cnoon]

I just pushed 35dcf04 which should help stabilize the tests running on CI. If that doesn't work, then we'll probably have to disable the tests on CI since they're all timing based. These types of tests are extremely difficult to make pass locally and on CI in a consistent way.