Class: Mongo::Session
- Inherits:
-
Object
- Object
- Mongo::Session
- Extended by:
- Forwardable
- Includes:
- ClusterTime::Consumer, Loggable, Retryable
- Defined in:
- lib/mongo/session.rb,
lib/mongo/session/session_pool.rb,
lib/mongo/session/server_session.rb,
lib/mongo/session/server_session/dirtyable.rb
Overview
Session objects are not thread-safe. An application may use a session from only one thread or process at a time.
A logical session representing a set of sequential operations executed by an application that are related in some way.
Defined Under Namespace
Classes: ServerSession, SessionPool
Constant Summary collapse
- MISMATCHED_CLUSTER_ERROR_MSG =
Error message indicating that the session was retrieved from a client with a different cluster than that of the client through which it is currently being used.
'The configuration of the client used to create this session does not match that ' + 'of the client owning this operation. Please only use this session for operations through its parent ' + 'client.'.freeze
- SESSION_ENDED_ERROR_MSG =
Error message describing that the session cannot be used because it has already been ended.
'This session has ended and cannot be used. Please create a new one.'.freeze
- SESSIONS_NOT_SUPPORTED =
Deprecated.
Error message describing that sessions are not supported by the server version.
'Sessions are not supported by the connected servers.'.freeze
- NO_TRANSACTION_STATE =
The state of a session in which the last operation was not related to any transaction or no operations have yet occurred.
:no_transaction
- STARTING_TRANSACTION_STATE =
The state of a session in which a user has initiated a transaction but no operations within the transactions have occurred yet.
:starting_transaction
- TRANSACTION_IN_PROGRESS_STATE =
The state of a session in which a transaction has been started and at least one operation has occurred, but the transaction has not yet been committed or aborted.
:transaction_in_progress
- TRANSACTION_COMMITTED_STATE =
The state of a session in which the last operation executed was a transaction commit.
:transaction_committed
- TRANSACTION_ABORTED_STATE =
The state of a session in which the last operation executed was a transaction abort.
:transaction_aborted
- UNLABELED_WRITE_CONCERN_CODES =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
[ 79, # UnknownReplWriteConcern 100, # CannotSatisfyWriteConcern, ].freeze
Constants included from Loggable
Instance Attribute Summary collapse
-
#client ⇒ Client
readonly
The client through which this session was created.
-
#operation_time ⇒ BSON::Timestamp
readonly
The latest seen operation time for this session.
-
#options ⇒ Hash
readonly
The options for this session.
-
#pinned_connection_global_id ⇒ Integer | nil
readonly
private
The connection global id that this session is pinned to, if any.
-
#pinned_server ⇒ Server | nil
readonly
private
The server (which should be a mongos) that this session is pinned to, if any.
-
#recovery_token ⇒ BSON::Document | nil
private
Recovery token for the sharded transaction being executed on this session, if any.
- #snapshot_timestamp ⇒ Object private
Attributes included from ClusterTime::Consumer
Instance Method Summary collapse
-
#abort_transaction ⇒ Object
Abort the currently active transaction without making any changes to the database.
-
#aborting_transaction? ⇒ true | false
private
Whether the session is currently aborting a transaction.
-
#add_autocommit!(command) ⇒ Hash, BSON::Document
private
Add the autocommit field to a command document if applicable.
-
#add_start_transaction!(command) ⇒ Hash, BSON::Document
private
Add the startTransaction field to a command document if applicable.
-
#add_txn_num!(command) ⇒ Hash, BSON::Document
private
Add the transaction number to a command document if applicable.
-
#add_txn_opts!(command, read) ⇒ Hash, BSON::Document
private
Add the transactions options if applicable.
-
#advance_operation_time(new_operation_time) ⇒ BSON::Timestamp
Advance the cached operation time for this session.
- #cluster ⇒ Object
-
#commit_transaction(options = nil) ⇒ Object
Commit the currently active transaction on the session.
-
#committing_transaction? ⇒ true | false
private
Whether the session is currently committing a transaction.
-
#dirty!(mark = true) ⇒ Object
Sets the dirty state to the given value for the underlying server session.
-
#dirty? ⇒ true | false | nil
private
Whether the underlying server session is dirty.
-
#end_session ⇒ nil
End this session.
-
#ended? ⇒ true, false
Whether this session has ended.
-
#explicit? ⇒ true, false
Is this session an explicit one (i.e. user-created).
-
#implicit? ⇒ true, false
Is this session an implicit one (not user-created).
-
#in_transaction? ⇒ true | false
Whether or not the session is currently in a transaction.
-
#initialize(server_session, client, options = {}) ⇒ Session
constructor
private
Initialize a Session.
-
#inspect ⇒ String
Get a formatted string for use in inspection.
-
#materialize_if_needed ⇒ Session
private
If not already set, populate a session objects’s server_session by checking out a session from the session pool.
- #materialized? ⇒ Boolean private
-
#next_txn_num ⇒ Integer
private
Increment and return the next transaction number.
-
#pin_to_connection(connection_global_id) ⇒ Object
private
Pins this session to the specified connection.
-
#pin_to_server(server) ⇒ Object
private
Pins this session to the specified server, which should be a mongos.
-
#process(result) ⇒ Operation::Result
private
Process a response from the server that used this session.
-
#retry_reads? ⇒ Boolean
private
Whether reads executed with this session can be retried according to the modern retryable reads specification.
-
#retry_writes? ⇒ true, false
Will writes executed with this session be retried.
-
#session_id ⇒ BSON::Document
Get the server session id of this session, if the session has not been ended.
-
#snapshot? ⇒ true | false
Whether the session is configured for snapshot reads.
-
#start_transaction(options = nil) ⇒ Object
Places subsequent operations in this session into a new transaction.
- #starting_transaction? ⇒ Boolean private
-
#suppress_read_write_concern!(command) ⇒ Hash, BSON::Document
private
Remove the read concern and/or write concern from the command if not applicable.
-
#txn_num ⇒ Integer
Get the current transaction number.
-
#txn_options ⇒ Hash
on this session.
-
#txn_read_preference ⇒ Hash
Get the read preference the session will use in the currently active transaction.
-
#unpin(connection = nil) ⇒ Object
private
Unpins this session from the pinned server or connection, if the session was pinned.
-
#unpin_maybe(error, connection = nil) ⇒ Object
private
Unpins this session from the pinned server or connection, if the session was pinned and the specified exception instance and the session’s transaction state require it to be unpinned.
-
#update_state! ⇒ Object
private
Update the state of the session due to a (non-commit and non-abort) operation being run.
-
#validate!(client) ⇒ Session
private
Validate the session for use by the specified client.
-
#validate_read_preference!(command) ⇒ Object
private
Ensure that the read preference of a command primary.
-
#with_transaction(options = nil) ⇒ Object
Executes the provided block in a transaction, retrying as necessary.
Methods included from ClusterTime::Consumer
Methods included from Loggable
#log_debug, #log_error, #log_fatal, #log_info, #log_warn, #logger
Methods included from Retryable
#read_worker, #select_server, #write_worker
Constructor Details
#initialize(server_session, client, options = {}) ⇒ Session
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Applications should use Client#start_session to begin a session. This constructor is for internal driver use only.
Initialize a Session.
A session can be explicit or implicit. Lifetime of explicit sessions is managed by the application - applications explicitry create such sessions and explicitly end them. Implicit sessions are created automatically by the driver when sending operations to servers that support sessions (3.6+), and their lifetime is managed by the driver.
When an implicit session is created, it cannot have a server session associated with it. The server session will be checked out of the session pool when an operation using this session is actually executed. When an explicit session is created, it must reference a server session that is already allocated.
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 |
# File 'lib/mongo/session.rb', line 77 def initialize(server_session, client, = {}) if [:causal_consistency] && [:snapshot] raise ArgumentError, ':causal_consistency and :snapshot options cannot be both set on a session' end if [:implicit] unless server_session.nil? raise ArgumentError, 'Implicit session cannot reference server session during construction' end else if server_session.nil? raise ArgumentError, 'Explicit session must reference server session during construction' end end @server_session = server_session = .dup @client = client.use(:admin) @options = .dup.freeze @cluster_time = nil @state = NO_TRANSACTION_STATE end |
Instance Attribute Details
#client ⇒ Client (readonly)
Returns The client through which this session was created.
109 110 111 |
# File 'lib/mongo/session.rb', line 109 def client @client end |
#operation_time ⇒ BSON::Timestamp (readonly)
Returns The latest seen operation time for this session.
124 125 126 |
# File 'lib/mongo/session.rb', line 124 def operation_time @operation_time end |
#options ⇒ Hash (readonly)
Returns The options for this session.
104 105 106 |
# File 'lib/mongo/session.rb', line 104 def @options end |
#pinned_connection_global_id ⇒ Integer | nil (readonly)
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Returns The connection global id that this session is pinned to, if any.
277 278 279 |
# File 'lib/mongo/session.rb', line 277 def pinned_connection_global_id @pinned_connection_global_id end |
#pinned_server ⇒ Server | nil (readonly)
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Returns The server (which should be a mongos) that this session is pinned to, if any.
271 272 273 |
# File 'lib/mongo/session.rb', line 271 def pinned_server @pinned_server end |
#recovery_token ⇒ BSON::Document | nil
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Returns Recovery token for the sharded transaction being executed on this session, if any.
283 284 285 |
# File 'lib/mongo/session.rb', line 283 def recovery_token @recovery_token end |
#snapshot_timestamp ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
1139 1140 1141 |
# File 'lib/mongo/session.rb', line 1139 def @snapshot_timestamp end |
Instance Method Details
#abort_transaction ⇒ Object
Abort the currently active transaction without making any changes to the database.
691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 |
# File 'lib/mongo/session.rb', line 691 def abort_transaction QueryCache.clear check_if_ended! check_if_no_transaction! if within_states?(TRANSACTION_COMMITTED_STATE) raise Mongo::Error::InvalidTransactionOperation.new( Mongo::Error::InvalidTransactionOperation.cannot_call_after_msg( :commitTransaction, :abortTransaction)) end if within_states?(TRANSACTION_ABORTED_STATE) raise Mongo::Error::InvalidTransactionOperation.new( Mongo::Error::InvalidTransactionOperation.cannot_call_twice_msg(:abortTransaction)) end begin unless starting_transaction? @aborting_transaction = true context = Operation::Context.new(client: @client, session: self) write_with_retry([:write_concern], ending_transaction: true, context: context, ) do |connection, txn_num, context| begin Operation::Command.new( selector: { abortTransaction: 1 }, db_name: 'admin', session: self, txn_num: txn_num ).execute_with_connection(connection, context: context) ensure unpin end end end @state = TRANSACTION_ABORTED_STATE rescue Mongo::Error::InvalidTransactionOperation raise rescue Mongo::Error @state = TRANSACTION_ABORTED_STATE rescue Exception @state = TRANSACTION_ABORTED_STATE raise ensure @aborting_transaction = false end # No official return value, but return true so that in interactive # use the method hints that it succeeded. true end |
#aborting_transaction? ⇒ true | false
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Returns Whether the session is currently aborting a transaction.
774 775 776 |
# File 'lib/mongo/session.rb', line 774 def aborting_transaction? !!@aborting_transaction end |
#add_autocommit!(command) ⇒ Hash, BSON::Document
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Add the autocommit field to a command document if applicable.
854 855 856 857 858 |
# File 'lib/mongo/session.rb', line 854 def add_autocommit!(command) command.tap do |c| c[:autocommit] = false if in_transaction? end end |
#add_start_transaction!(command) ⇒ Hash, BSON::Document
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Add the startTransaction field to a command document if applicable.
869 870 871 872 873 874 875 |
# File 'lib/mongo/session.rb', line 869 def add_start_transaction!(command) command.tap do |c| if starting_transaction? c[:startTransaction] = true end end end |
#add_txn_num!(command) ⇒ Hash, BSON::Document
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Add the transaction number to a command document if applicable.
886 887 888 889 890 |
# File 'lib/mongo/session.rb', line 886 def add_txn_num!(command) command.tap do |c| c[:txnNumber] = BSON::Int64.new(@server_session.txn_num) if in_transaction? end end |
#add_txn_opts!(command, read) ⇒ Hash, BSON::Document
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Add the transactions options if applicable.
901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 |
# File 'lib/mongo/session.rb', line 901 def add_txn_opts!(command, read) command.tap do |c| # The read concern should be added to any command that starts a transaction. if starting_transaction? # https://jira.mongodb.org/browse/SPEC-1161: transaction's # read concern overrides collection/database/client read concerns, # even if transaction's read concern is not set. # Read concern here is the one sent to the server and may # include afterClusterTime. if rc = c[:readConcern] rc = rc.dup rc.delete(:level) end if txn_read_concern if rc rc.update(txn_read_concern) else rc = txn_read_concern.dup end end if rc.nil? || rc.empty? c.delete(:readConcern) else c[:readConcern ] = Options::Mapper.transform_values_to_strings(rc) end end # We need to send the read concern level as a string rather than a symbol. if c[:readConcern] c[:readConcern] = Options::Mapper.transform_values_to_strings(c[:readConcern]) end if c[:commitTransaction] if max_time_ms = [:max_commit_time_ms] c[:maxTimeMS] = max_time_ms end end # The write concern should be added to any abortTransaction or commitTransaction command. if (c[:abortTransaction] || c[:commitTransaction]) if @already_committed wc = BSON::Document.new(c[:writeConcern] || txn_write_concern || {}) wc.merge!(w: :majority) wc[:wtimeout] ||= 10000 c[:writeConcern] = wc elsif txn_write_concern c[:writeConcern] ||= txn_write_concern end end # A non-numeric write concern w value needs to be sent as a string rather than a symbol. if c[:writeConcern] && c[:writeConcern][:w] && c[:writeConcern][:w].is_a?(Symbol) c[:writeConcern][:w] = c[:writeConcern][:w].to_s end end end |
#advance_operation_time(new_operation_time) ⇒ BSON::Timestamp
Advance the cached operation time for this session.
1070 1071 1072 1073 1074 1075 1076 |
# File 'lib/mongo/session.rb', line 1070 def advance_operation_time(new_operation_time) if @operation_time @operation_time = [ @operation_time, new_operation_time ].max else @operation_time = new_operation_time end end |
#cluster ⇒ Object
111 112 113 |
# File 'lib/mongo/session.rb', line 111 def cluster @client.cluster end |
#commit_transaction(options = nil) ⇒ Object
Commit the currently active transaction on the session.
618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 |
# File 'lib/mongo/session.rb', line 618 def commit_transaction(=nil) QueryCache.clear check_if_ended! check_if_no_transaction! if within_states?(TRANSACTION_ABORTED_STATE) raise Mongo::Error::InvalidTransactionOperation.new( Mongo::Error::InvalidTransactionOperation.cannot_call_after_msg( :abortTransaction, :commitTransaction)) end ||= {} begin # If commitTransaction is called twice, we need to run the same commit # operation again, so we revert the session to the previous state. if within_states?(TRANSACTION_COMMITTED_STATE) @state = @last_commit_skipped ? STARTING_TRANSACTION_STATE : TRANSACTION_IN_PROGRESS_STATE @already_committed = true end if starting_transaction? @last_commit_skipped = true else @last_commit_skipped = false @committing_transaction = true write_concern = [:write_concern] || [:write_concern] if write_concern && !write_concern.is_a?(WriteConcern::Base) write_concern = WriteConcern.get(write_concern) end context = Operation::Context.new(client: @client, session: self) write_with_retry(write_concern, ending_transaction: true, context: context, ) do |connection, txn_num, context| if context.retry? if write_concern wco = write_concern..merge(w: :majority) wco[:wtimeout] ||= 10000 write_concern = WriteConcern.get(wco) else write_concern = WriteConcern.get(w: :majority, wtimeout: 10000) end end spec = { selector: { commitTransaction: 1 }, db_name: 'admin', session: self, txn_num: txn_num, write_concern: write_concern, } Operation::Command.new(spec).execute_with_connection(connection, context: context) end end ensure @state = TRANSACTION_COMMITTED_STATE @committing_transaction = false end # No official return value, but return true so that in interactive # use the method hints that it succeeded. true end |
#committing_transaction? ⇒ true | false
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Returns Whether the session is currently committing a transaction.
766 767 768 |
# File 'lib/mongo/session.rb', line 766 def committing_transaction? !!@committing_transaction end |
#dirty!(mark = true) ⇒ Object
Sets the dirty state to the given value for the underlying server session. If there is no server session, this does nothing.
131 132 133 |
# File 'lib/mongo/session.rb', line 131 def dirty!(mark = true) @server_session&.dirty!(mark) end |
#dirty? ⇒ true | false | nil
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Returns whether the underlying server session is dirty. If no server session exists for this session, returns nil.
139 140 141 |
# File 'lib/mongo/session.rb', line 139 def dirty? @server_session&.dirty? end |
#end_session ⇒ nil
End this session.
If there is an in-progress transaction on this session, the transaction is aborted. The server session associated with this session is returned to the server session pool. Finally, this session is marked ended and is no longer usable.
If this session is already ended, this method does nothing.
Note that this method does not directly issue an endSessions command to this server, contrary to what its name might suggest.
370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 |
# File 'lib/mongo/session.rb', line 370 def end_session if !ended? && @client if within_states?(TRANSACTION_IN_PROGRESS_STATE) begin abort_transaction rescue Mongo::Error, Error::AuthError end end if @server_session @client.cluster.session_pool.checkin(@server_session) end end ensure @server_session = nil @ended = true end |
#ended? ⇒ true, false
Whether this session has ended.
236 237 238 |
# File 'lib/mongo/session.rb', line 236 def ended? !!@ended end |
#explicit? ⇒ true, false
Is this session an explicit one (i.e. user-created).
171 172 173 |
# File 'lib/mongo/session.rb', line 171 def explicit? !implicit? end |
#implicit? ⇒ true, false
Is this session an implicit one (not user-created).
159 160 161 |
# File 'lib/mongo/session.rb', line 159 def implicit? @implicit ||= !!(@options.key?(:implicit) && @options[:implicit] == true) end |
#in_transaction? ⇒ true | false
Whether or not the session is currently in a transaction.
758 759 760 |
# File 'lib/mongo/session.rb', line 758 def in_transaction? within_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE) end |
#inspect ⇒ String
Get a formatted string for use in inspection.
348 349 350 |
# File 'lib/mongo/session.rb', line 348 def inspect "#<Mongo::Session:0x#{object_id} session_id=#{session_id} options=#{@options}>" end |
#materialize_if_needed ⇒ Session
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
If not already set, populate a session objects’s server_session by checking out a session from the session pool.
1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 |
# File 'lib/mongo/session.rb', line 1084 def materialize_if_needed if ended? raise Error::SessionEnded end return unless implicit? && !@server_session @server_session = cluster.session_pool.checkout self end |
#materialized? ⇒ Boolean
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
1097 1098 1099 1100 1101 1102 1103 |
# File 'lib/mongo/session.rb', line 1097 def materialized? if ended? raise Error::SessionEnded end !@server_session.nil? end |
#next_txn_num ⇒ Integer
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Increment and return the next transaction number.
1114 1115 1116 1117 1118 1119 1120 |
# File 'lib/mongo/session.rb', line 1114 def next_txn_num if ended? raise Error::SessionEnded end @server_session.next_txn_num end |
#pin_to_connection(connection_global_id) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Pins this session to the specified connection.
this session to.
801 802 803 804 805 806 |
# File 'lib/mongo/session.rb', line 801 def pin_to_connection(connection_global_id) if connection_global_id.nil? raise ArgumentError, 'Cannot pin to a nil connection id' end @pinned_connection_global_id = connection_global_id end |
#pin_to_server(server) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Pins this session to the specified server, which should be a mongos.
783 784 785 786 787 788 789 790 791 792 793 |
# File 'lib/mongo/session.rb', line 783 def pin_to_server(server) if server.nil? raise ArgumentError, 'Cannot pin to a nil server' end if Lint.enabled? unless server.mongos? raise Error::LintError, "Attempted to pin the session to server #{server.summary} which is not a mongos" end end @pinned_server = server end |
#process(result) ⇒ Operation::Result
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Process a response from the server that used this session.
1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 |
# File 'lib/mongo/session.rb', line 1042 def process(result) unless implicit? set_operation_time(result) if cluster_time_doc = result.cluster_time advance_cluster_time(cluster_time_doc) end end @server_session.set_last_use! if doc = result.reply && result.reply.documents.first if doc[:recoveryToken] self.recovery_token = doc[:recoveryToken] end end result end |
#retry_reads? ⇒ Boolean
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Whether reads executed with this session can be retried according to the modern retryable reads specification.
If this method returns true, the modern retryable reads have been requested by the application. If the server selected for a read operation supports modern retryable reads, they will be used for that particular operation. If the server selected for a read operation does not support modern retryable reads, the read will not be retried.
If this method returns false, legacy retryable reads have been requested by the application. Legacy retryable read logic will be used regardless of server version of the server(s) that the client is connected to. The number of read retries is given by :max_read_retries client option, which is 1 by default and can be set to 0 to disable legacy read retries.
191 192 193 |
# File 'lib/mongo/session.rb', line 191 def retry_reads? client.[:retry_reads] != false end |
#retry_writes? ⇒ true, false
Retryable writes are only available on server versions at least 3.6 and with sharded clusters, replica sets, or load-balanced topologies.
Will writes executed with this session be retried.
206 207 208 |
# File 'lib/mongo/session.rb', line 206 def retry_writes? !!client.[:retry_writes] && (cluster.replica_set? || cluster.sharded? || cluster.load_balanced?) end |
#session_id ⇒ BSON::Document
Get the server session id of this session, if the session has not been ended. If the session had been ended, raises Error::SessionEnded.
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 |
# File 'lib/mongo/session.rb', line 248 def session_id if ended? raise Error::SessionEnded end # An explicit session will always have a session_id, because during # construction a server session must be provided. An implicit session # will not have a session_id until materialized, thus calls to # session_id might fail. An application should not have an opportunity # to experience this failure because an implicit session shouldn't be # accessible to applications due to its lifetime being constrained to # operation execution, which is done entirely by the driver. unless materialized? raise Error::SessionNotMaterialized end @server_session.session_id end |
#snapshot? ⇒ true | false
Returns Whether the session is configured for snapshot reads.
117 118 119 |
# File 'lib/mongo/session.rb', line 117 def snapshot? !![:snapshot] end |
#start_transaction(options = nil) ⇒ Object
Places subsequent operations in this session into a new transaction.
Note that the transaction will not be started on the server until an operation is performed after start_transaction is called.
557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 |
# File 'lib/mongo/session.rb', line 557 def start_transaction( = nil) check_transactions_supported! if Lint.validate_read_concern_option([:read_concern]) =begin # It would be handy to detect invalid read preferences here, but # some of the spec tests require later detection of invalid read prefs. # Maybe we can do this when lint mode is on. mode = options[:read] && options[:read][:mode].to_s if mode && mode != 'primary' raise Mongo::Error::InvalidTransactionOperation.new( "read preference in a transaction must be primary (requested: #{mode})" ) end =end end if snapshot? raise Mongo::Error::SnapshotSessionTransactionProhibited end check_if_ended! if within_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE) raise Mongo::Error::InvalidTransactionOperation.new( Mongo::Error::InvalidTransactionOperation::TRANSACTION_ALREADY_IN_PROGRESS) end unpin next_txn_num @txn_options = (@options[:default_transaction_options] || {}).merge( || {}) if txn_write_concern && !WriteConcern.get(txn_write_concern).acknowledged? raise Mongo::Error::InvalidTransactionOperation.new( Mongo::Error::InvalidTransactionOperation::UNACKNOWLEDGED_WRITE_CONCERN) end @state = STARTING_TRANSACTION_STATE @already_committed = false # This method has no explicit return value. # We could return nil here but true indicates to the user that the # operation succeeded. This is intended for interactive use. # Note that the return value is not documented. true end |
#starting_transaction? ⇒ Boolean
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
746 747 748 |
# File 'lib/mongo/session.rb', line 746 def starting_transaction? within_states?(STARTING_TRANSACTION_STATE) end |
#suppress_read_write_concern!(command) ⇒ Hash, BSON::Document
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Remove the read concern and/or write concern from the command if not applicable.
967 968 969 970 971 972 973 974 |
# File 'lib/mongo/session.rb', line 967 def suppress_read_write_concern!(command) command.tap do |c| next unless in_transaction? c.delete(:readConcern) unless starting_transaction? c.delete(:writeConcern) unless c[:commitTransaction] || c[:abortTransaction] end end |
#txn_num ⇒ Integer
Get the current transaction number.
1130 1131 1132 1133 1134 1135 1136 |
# File 'lib/mongo/session.rb', line 1130 def txn_num if ended? raise Error::SessionEnded end @server_session.txn_num end |
#txn_options ⇒ Hash
on this session.
147 148 149 |
# File 'lib/mongo/session.rb', line 147 def @txn_options or raise ArgumentError, "There is no active transaction" end |
#txn_read_preference ⇒ Hash
Get the read preference the session will use in the currently active transaction.
This is a driver style hash with underscore keys.
221 222 223 224 225 226 |
# File 'lib/mongo/session.rb', line 221 def txn_read_preference rp = [:read] || @client.read_preference Mongo::Lint.validate_underscore_read_preference(rp) rp end |
#unpin(connection = nil) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Unpins this session from the pinned server or connection, if the session was pinned.
814 815 816 817 818 |
# File 'lib/mongo/session.rb', line 814 def unpin(connection = nil) @pinned_server = nil @pinned_connection_global_id = nil connection.unpin unless connection.nil? end |
#unpin_maybe(error, connection = nil) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Unpins this session from the pinned server or connection, if the session was pinned and the specified exception instance and the session’s transaction state require it to be unpinned.
The exception instance should already have all of the labels set on it (both client- and server-side generated ones).
831 832 833 834 835 836 837 838 839 840 841 842 843 |
# File 'lib/mongo/session.rb', line 831 def unpin_maybe(error, connection = nil) if !within_states?(Session::NO_TRANSACTION_STATE) && error.label?('TransientTransactionError') then unpin(connection) end if committing_transaction? && error.label?('UnknownTransactionCommitResult') then unpin(connection) end end |
#update_state! ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Update the state of the session due to a (non-commit and non-abort) operation being run.
1003 1004 1005 1006 1007 1008 1009 1010 |
# File 'lib/mongo/session.rb', line 1003 def update_state! case @state when STARTING_TRANSACTION_STATE @state = TRANSACTION_IN_PROGRESS_STATE when TRANSACTION_COMMITTED_STATE, TRANSACTION_ABORTED_STATE @state = NO_TRANSACTION_STATE end end |
#validate!(client) ⇒ Session
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Validate the session for use by the specified client.
The session must not be ended and must have been created by a client with the same cluster as the client that the session is to be used with.
1025 1026 1027 1028 1029 |
# File 'lib/mongo/session.rb', line 1025 def validate!(client) check_matching_cluster!(client) check_if_ended! self end |
#validate_read_preference!(command) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Ensure that the read preference of a command primary.
986 987 988 989 990 991 992 993 994 995 996 997 |
# File 'lib/mongo/session.rb', line 986 def validate_read_preference!(command) return unless in_transaction? return unless command['$readPreference'] mode = command['$readPreference']['mode'] || command['$readPreference'][:mode] if mode && mode != 'primary' raise Mongo::Error::InvalidTransactionOperation.new( "read preference in a transaction must be primary (requested: #{mode})" ) end end |
#with_transaction(options = nil) ⇒ Object
with_transaction contains a loop, therefore the if with_transaction itself is placed in a loop, its block should not call next or break to control the outer loop because this will instead affect the loop in with_transaction. The driver will warn and abort the transaction if it detects this situation.
Executes the provided block in a transaction, retrying as necessary.
Returns the return value of the block.
Exact number of retries and when they are performed are implementation details of the driver; the provided block should be idempotent, and should be prepared to be called more than once. The driver may retry the commit command within an active transaction or it may repeat the transaction and invoke the block again, depending on the error encountered if any. Note also that the retries may be executed against different servers.
Transactions cannot be nested - InvalidTransactionOperation will be raised if this method is called when the session already has an active transaction.
Exceptions raised by the block which are not derived from Mongo::Error stop processing, abort the transaction and are propagated out of with_transaction. Exceptions derived from Mongo::Error may be handled by with_transaction, resulting in retries of the process.
Currently, with_transaction will retry commits and block invocations until at least 120 seconds have passed since with_transaction started executing. This timeout is not configurable and may change in a future driver version.
441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 |
# File 'lib/mongo/session.rb', line 441 def with_transaction(=nil) # Non-configurable 120 second timeout for the entire operation deadline = Utils.monotonic_time + 120 transaction_in_progress = false loop do = {} if [:write_concern] = [:write_concern] end start_transaction() transaction_in_progress = true begin rv = yield self rescue Exception => e if within_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE) log_warn("Aborting transaction due to #{e.class}: #{e}") abort_transaction transaction_in_progress = false end if Utils.monotonic_time >= deadline transaction_in_progress = false raise end if e.is_a?(Mongo::Error) && e.label?('TransientTransactionError') next end raise else if within_states?(TRANSACTION_ABORTED_STATE, NO_TRANSACTION_STATE, TRANSACTION_COMMITTED_STATE) transaction_in_progress = false return rv end begin commit_transaction() transaction_in_progress = false return rv rescue Mongo::Error => e if e.label?('UnknownTransactionCommitResult') if Utils.monotonic_time >= deadline || e.is_a?(Error::OperationFailure) && e.max_time_ms_expired? then transaction_in_progress = false raise end = case v = [:write_concern] when WriteConcern::Base v. when nil {} else v end [:write_concern] = .merge(w: :majority) retry elsif e.label?('TransientTransactionError') if Utils.monotonic_time >= deadline transaction_in_progress = false raise end @state = NO_TRANSACTION_STATE next else transaction_in_progress = false raise end rescue Error::AuthError transaction_in_progress = false raise end end end # No official return value, but return true so that in interactive # use the method hints that it succeeded. true ensure if transaction_in_progress log_warn('with_transaction callback broke out of with_transaction loop, aborting transaction') begin abort_transaction rescue Error::OperationFailure, Error::InvalidTransactionOperation end end end |