feat(google-cloud-spanner): Implement "Inline Begin Transaction"

[SandeepTuniki]

Implements "Inline Begin Transaction" optimisation for Ruby Spanner.

Overview

Cloud Spanner allows users to query the data in several ways, including transactions. A transaction allows users to execute a series of statements as a single atomic unit, and allows them to rollback the changes in case of errors.

Most Cloud Spanner *Request APIs include a TransactionSelector field for queries. The TransactionSelector field can be used within queries to specify an existing transaction ID or start a new transaction.

Currently, we make an explicit BeginTransaction rpc to create a transaction in the backend, and get the transaction ID as the response. We pass the ID in the TransactionSelector field in the subsequent operations within the transaction.

This process has the following drawbacks:

• Startup overhead - The client sets up the environment for transactions at the start of the client instantiation. This incurs an overhead in the instantiation time.

• Prepared transactions - As we cannot predict in advance how many transactions the user will need, we must prepare several transactions during client instantiation. This is done by maintaining two separate session pools in a specific ratio, one for read-only transactions and the other for read-write transactions. As the user accesses this pool of sessions, the client must rebalance the ratio of the two stacks.

• Transaction latency - The client makes an additional RPC to create a transaction. When the session pool runs out of available transactions, the client has to create more transactions. Both these factors increase the latency.

To address these drawbacks, we can defer the creation of transactions until the user executes the first query within the transaction. This is known as inlining the “begin transaction” call.

Implementation details

Below are the the high-level list of changes done throughout the codebase:

Pool class:

• Stop creating transactions in advance, and instead only maintain sessions in the pool.
• Remove the write_ratio field and the corresponding code that maintains transactions through write_ratio.
• Simplified maintenance:
  • Introduce new fields sessions_available and sessions_in_use to simplify the maintenance of session pool.
  • The new fields replace the previous fields all_sessions, session_stack and transaction_stack.

Transaction class:

• Inline the transaction creation to the first operation within the transaction.
• Add thread safety mechanisms to ensure that the transaction creation isn't initiated multiple times by concurrent operations.
• Add some helper methods (ex: existing_transaction?, safe_begin_transaction, safe_execute etc).

Client class:

• Refactor the .transaction method to handle inlining of transaction creation.
• Introduce helper methods (ex: check_and_propagate_err()) to reduce code complexity issues identified by Rubocop.

BatchUpdateResults class:

• New class introduced to facilitate easier handling of tx.batch_update() API's response.

Project class:

• Mark the write_ratio field as deprecated during client initialisation.

Results class:

• Add a helper method transaction to facilitate extraction of a transaction from the results metadata.

Session class:

• Add a helper method to create an empty transaction object (i.e; without gapic object), to facilitate ILB of a transaction.

Service class:

• Refactor some code & move the processing logic (ex: batch update) to other classes.

Tests

Unit tests

• Several unit tests are added to test the inlining of transactions.
• Many existing unit tests are modified to handle ILB.
• All the obsolete unit tests in the session pool which are related to write_ratio & transaction_stack are removed, and some are modified to fit the new mechanism of the session pool.

Acceptance tets

• All existing acceptance should pass, since ILB is an internal optimisation.
• Some existing acceptance tests are modified for easier testing.
• Few tests are added to handle edge cases.

[SandeepTuniki]

Below are the benchmarking results after inlining the "begin transaction" rpc.

[dazuma]

I think the logic looks good now. I have a few more recommendations on internal documentation, just to help with maintainability of the concurrency and synchronization.