google-cloud-spanner 2.27.0 → 2.29.0

data/lib/google/cloud/spanner/transaction.rb

@@ -76,19 +76,40 @@ module Google
       #   end
       #
       class Transaction
-        # @private The `Google::Cloud::Spanner::V1::Transaction` object.
+        # The underlying `V1::Transaction` protobuf object.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::Transaction]
         attr_reader :grpc
 
-        # @private The Session object.
+        # The `Spanner::Session` session for this transaction.
+        # @private
+        # @return [::Google::Cloud::Spanner::Session]
         attr_accessor :session
 
-        # @private Transaction tag for statistics collection.
+        # Transaction tag for statistics collection.
+        # Example: `"update_user_profile"`.
+        # @private
+        # @return [::String, nil]
         attr_accessor :transaction_tag
 
-        # @private Whether to exclude from change streams.
+        # Whether to exclude this transaction from change streams.
+        # @private
+        # @return [::Boolean]
         attr_accessor :exclude_txn_from_change_streams
 
-        def initialize
+        # Creates a new `Spanner::Transaction` instance from a `V1::Transaction` object.
+        # @param grpc [::Google::Cloud::Spanner::V1::Transaction] Underlying `V1::Transaction` object.
+        # @param session [::Google::Cloud::Spanner::Session] The session this transaction is running in.
+        # @param exclude_txn_from_change_streams [::Boolean]
+        #   When `exclude_txn_from_change_streams` is set to `true`, it prevents read
+        #   or write transactions from being tracked in change streams.
+        # @private
+        # @return [::Google::Cloud::Spanner::Transaction]
+        def initialize grpc, session, exclude_txn_from_change_streams
+          @grpc = grpc
+          @session = session
+          @exclude_txn_from_change_streams = exclude_txn_from_change_streams
+
           @commit = Commit.new
           @seqno = 0
           @exclude_txn_from_change_streams = false
@@ -116,7 +137,7 @@ module Google
         # @return [String] The transaction id.
         def transaction_id
           return @grpc.id if existing_transaction?
-          safe_begin_transaction
+          safe_begin_transaction!
           @grpc.id
         end
 
@@ -1153,15 +1174,16 @@ module Google
           @commit.mutations
         end
 
-        ##
-        # @private Creates a new Transaction instance from a
-        # `Google::Cloud::Spanner::V1::Transaction`.
+        # Creates a new `Spanner::Transaction` instance from a `V1::Transaction` object.
+        # @param grpc [::Google::Cloud::Spanner::V1::Transaction] Underlying `V1::Transaction` object.
+        # @param session [::Google::Cloud::Spanner::Session] The session this transaction is running in.
+        # @param exclude_txn_from_change_streams [::Boolean] Optional. Defaults to `false`.
+        #   When `exclude_txn_from_change_streams` is set to `true`, it prevents read
+        #   or write transactions from being tracked in change streams.
+        # @private
+        # @return [::Google::Cloud::Spanner::Transaction]
         def self.from_grpc grpc, session, exclude_txn_from_change_streams: false
-          new.tap do |s|
-            s.instance_variable_set :@grpc,    grpc
-            s.instance_variable_set :@session, session
-            s.exclude_txn_from_change_streams = exclude_txn_from_change_streams
-          end
+          new grpc, session, exclude_txn_from_change_streams
         end
 
         ##
@@ -1176,6 +1198,33 @@ module Google
           @grpc.nil?
         end
 
+        # Begins a new transaction in a thread-safe manner if one does not already exist.
+        #
+        # @param exclude_from_change_streams [::Boolean] Optional. Defaults to `false`.
+        #   When `exclude_from_change_streams` is set to `true`, it prevents read
+        #   or write transactions from being tracked in change streams.
+        # @param request_options [::Hash, nil] Optional. Common request options.
+        #   Example option: `:priority`.
+        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   call options. Example option `:timeout`.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::Transaction, nil] The new transaction
+        #   object, or `nil` if a transaction already exists.
+        def safe_begin_transaction! exclude_from_change_streams: false, request_options: nil, call_options: nil
+          @mutex.synchronize do
+            return if existing_transaction?
+            ensure_session!
+            route_to_leader = LARHeaders.begin_transaction true
+            @grpc = service.begin_transaction(
+              session.path,
+              exclude_txn_from_change_streams: exclude_from_change_streams,
+              request_options: request_options,
+              call_options: call_options,
+              route_to_leader: route_to_leader
+            )
+          end
+        end
+
         protected
 
         ##
@@ -1203,24 +1252,18 @@ module Google
           end
         end
 
-        ##
-        # Create a new transaction in a thread-safe manner.
-        def safe_begin_transaction
-          @mutex.synchronize do
-            return if existing_transaction?
-            ensure_session!
-            route_to_leader = LARHeaders.begin_transaction true
-            @grpc = service.begin_transaction session.path, route_to_leader: route_to_leader
-          end
-        end
-
-        ##
-        # @private The TransactionSelector to be used for queries. This method must
-        #   be called from within a synchronized block, since the value returned
-        #   depends on the state of @grpc field.
+        # The TransactionSelector to be used for queries. This method must
+        # be called from within a synchronized block, since the value returned
+        # depends on the state of @grpc field.
         #
-        #   This method is expected to be called from within `safe_execute()` method's block,
-        #   since it provides synchronization and gurantees thread safety.
+        # This method is expected to be called from within `safe_execute()` method's block,
+        # since it provides synchronization and gurantees thread safety.
+        #
+        # @param exclude_txn_from_change_streams [::Boolean] Optional. Defaults to `false`.
+        #   When `exclude_txn_from_change_streams` is set to `true`, it prevents read
+        #   or write transactions from being tracked in change streams.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::TransactionSelector]
         def tx_selector exclude_txn_from_change_streams: false
           return V1::TransactionSelector.new id: transaction_id if existing_transaction?
           V1::TransactionSelector.new(
@@ -1261,6 +1304,9 @@ module Google
           raise "Must have active connection to service" unless session
         end
 
+        # The `Spanner::Service` object used by this transaction.
+        # @private
+        # @return [::Google::Cloud::Spanner::Service]
         def service
           session.service
         end

data/lib/google/cloud/spanner/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.27.0".freeze
+      VERSION = "2.29.0".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-spanner
 version: !ruby/object:Gem::Version
-  version: 2.27.0
+  version: 2.29.0
 platform: ruby
 authors:
 - Mike Moore