类：Mongo::Session

继承：
对象
  • 对象
显示全部
扩展方式：
可转发
包括：
ClusterTime::Consumer 、 Loggable 、 Retryable
定义于：
lib/ Mongo/session.rb 、
lib/ Mongo/session/session_pool.rb、
lib/ Mongo/session/server_session.rb、
lib/ Mongo/session/server_session/dirtyable.rb

Overview

注意：

会话对象不是线程安全的。 应用程序一次只能使用来自一个线程或进程的会话。

一种逻辑会话，表示应用程序执行的以某种方式相关的一设立顺序操作。

由于：

  • 2.5.0

在命名空间下定义

类： ServerSession, SessionPool

常量摘要折叠

MISMATCHED_CLUSTER_ERROR_MSG =

错误消息，指示会话是从与当前使用会话的客户端具有不同集群的客户端端检索的。

由于：

  • 2.5.0

'用于创建此会话的客户端配置与此不匹配' +
” （拥有此操作的客户端）。请仅使用此会话通过其父会话进行操作 +
'客户端。 '.冻结
SESSION_ENDED_ERROR_MSG =

错误消息，描述会话无法使用，因为它已结束。

由于：

  • 2.5.0

'此会话已结束，无法使用。请创建一个新的。 '.冻结
SESSIONS_NOT_SUPPORTED =
已弃用。

描述服务器版本不支持会话的错误消息。

由于：

  • 2.5.0

'连接的服务器不支持会话。 '.冻结
NO_TRANSACTION_STATE =

上次操作与任何事务无关或尚未发生任何操作的会话状态。

由于：

  • 2.6.0

:no_transaction
STARTING_TRANSACTION_STATE =

用户已启动ACID 事务但事务中尚未发生任何操作的会话状态。

由于：

  • 2.6.0

:starting_transaction
TRANSACTION_IN_PROGRESS_STATE =

一种会话状态，在该状态下，ACID 事务已启动，并且至少发生了一个操作，但ACID 事务尚未提交或中止。

由于：

  • 2.6.0

:transaction_in_progress
TRANSACTION_COMMITTED_STATE =

最后执行的操作是事务提交的会话状态。

由于：

  • 2.6.0

:transaction_committed
TRANSACTION_ABORTED_STATE =

最后执行的操作为事务中止的会话状态。

由于：

  • 2.6.0

:transaction_aborted
UNLABELED_WRITE_CONCERN_CodeS =

此常量是私有 API 的一部分。 应尽可能避免使用此常量，因为它将来可能会被删除或更改。

由于：

  • 2.5.0

[
  79,  # UnknownReplWriteConcern
  100, # CannotSatisfyWriteConcern,
].冻结

Loggable中包含的常量

Loggable::PREFIX

实例属性摘要折叠

ClusterTime::Consumer中包含的属性

#cluster_time

实例方法摘要折叠

ClusterTime::Consumer中包含的方法

#advance_cluster_time

Loggable中包含的方法

#log_debug 、 #log_error 、 #log_ Fatal 、 #log_info 、 #log_warn 、 #logger

Retryable 中包含的方法

#read_worker 、 #select_server 、 #write_worker

构造函数详情

#initialize (server_session, client, options = {}) ⇒会话

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

注意：

应用程序应使用 Client#start_session 开始会话。 此构造函数仅供内部驾驶员使用。

初始化会话。

会话可以是显式会话，也可以是隐式会话。 显式会话的生命周期由应用程序管理 - 应用程序显式创建此类会话并显式结束此类会话。 隐式会话由驱动程序在向支持会话 ( 3.6 +) 的服务器发送操作时自动创建，其生命周期由驱动程序管理。

创建隐式会话后，不能有与之关联的服务器会话。 当实际执行使用此会话的操作时，将从会话池中检出服务器会话。 创建显式会话时，它必须引用已分配的服务器会话。

参数：

  • server_session ( ServerSession | nil ) —

    与此会话关联的服务器会话。 如果 :implicit 选项为 true，则必须为 nil。

  • 客户端 (客户端) —

    创建此会话的客户端。

  • 选项 （哈希） （默认为： {} ） —

    此会话的选项。

选项哈希 ( options )：

  • :因果一致性 ( true|false ) —

    是否为此会话启用因果一致性。

  • :default_timeout_ms （整数） —

    在会话上执行以下操作的 timeoutMS 值：

    • commitTransaction

    • abortTransaction

    • withTransaction

    • endSession

  • :default_transaction_options （哈希） —

    默认传递给 start_transaction 的选项可以包含 start_transaction 接受的任何选项。

  • :implicit ( true|false ) —

    仅供内部驾驶员使用 — 指定会话是否为隐式会话。 如果为 true，则 server_session 将为 nil。 这样做是为了仅在签出连接后才签出服务器会话。

  • :read_preference （哈希） —

    读取偏好选项哈希，具有以下可选键：

    • ：模式— 作为string或符号的读取偏好（read preference）；有效值为： 主节点 (primary node in the replica set) 、 :primary_preferred 、 : secondary_preferred和:nearest 。

  • ：快照 ( true | false ) —

    为快照读取设置会话。

由于：

  • 2.5.0



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/ Mongo/session.rb', 第 83 行

def 初始化(server_session, 客户端, 选项 = {})
  if 选项[:因果一致性] && 选项[：快照]
    提高 ArgumentError, '不能在会话上同时设置 :causal_consistency 和 :snapshot 选项'
  end

  if 选项[:implicit]
    除非 server_session.nil?
      提高 ArgumentError, “隐式会话在构造期间无法引用服务器会话”
    end
  else
    if server_session.nil?
      提高 ArgumentError, '显式会话必须在构造期间引用服务器会话'
    end
  end

  @server_session = server_session
  选项 = 选项.dup

  @client = 客户端.请使用(: admin)
  @options = 选项.dup.冻结
  @cluster_time = nil
  @state = NO_TRANSACTION_STATE
  @with_transaction_deadline = nil
end

实例属性详细信息

# 客户端 ⇒客户端（只读）

返回 创建此会话的客户端。

返回：

  • (客户端) —

    创建此会话的客户端。

由于：

  • 2.5.1



116
117
118
 
# File 'lib/ Mongo/session.rb', 第 116 行

def 客户端
  @client
end

# operation_time =" BSON::Timestamp （只读）

返回此会话的最新看到的optime 。

返回：

  • ( BSON::Timestamp ) —

    此会话的最新optime 。

由于：

  • 2.5.0



131
132
133
 
# File 'lib/ Mongo/session.rb', 第 131 行

def operation_time
  @operation_time
end

# options ⇒哈希（只读）

返回 此会话的选项。

返回：

  • (哈希) —

    此会话的选项。

由于：

  • 2.5.0



111
112
113
 
# File 'lib/ Mongo/session.rb', 第 111 行

def 选项
  @options
end

#pinned_connection_global_id ⇒整数 | nil （只读）

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回此会话固定的连接全局 ID（如果有）。

返回：

  • ( Integer | nil ) —

    此会话固定的连接全局 ID（如果有）。

由于：

  • 2.5.0



284
285
286
 
# File 'lib/ Mongo/session.rb', 第 284 行

def pinned_connection_global_id
  @pinned_connection_global_id
end

#pinned_server ⇒ MongoDB Server | nil （只读）

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回此会话固定到的服务器（应该是mongos），如果有的话。

返回：

  • ( MongoDB Server | nil ) —

    此会话固定到的服务器（应该是mongos）（如果有）。

由于：

  • 2.5.0



278
279
280
 
# File 'lib/ Mongo/session.rb', 第 278 行

def pinned_server
  @pinned_server
end

# Recovery_token ⇒ BSON::Document | nil

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回在此会话上执行的分片ACID 事务的恢复分片的（如果有）。

返回：

  • ( BSON::Document | nil ) —

    在此会话上执行的分片事务的恢复令牌（如果有）。

由于：

  • 2.5.0



290
291
292
 
# File 'lib/ Mongo/session.rb', 第 290 行

def Recovery_token
  @recovery_token
end

# snapshot_timestamp ⇒对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

由于：

  • 2.5.0



1192
1193
1194
 
# File 'lib/ Mongo/session.rb', 第 1192 行

def snapshot_timestamp
  @snapshot_timestamp
end

# with_transaction_deadline ⇒ 对象（只读）

由于：

  • 2.5.0



1194
1195
1196
 
# File 'lib/ Mongo/session.rb', 第 1194 行

def with_transaction_deadline
  @with_transaction_deadline
end

实例方法详细信息

# abort_transaction (options = nil) ⇒ 对象

中止当前活动的ACID 事务，而不对数据库进行任何更改。

例子：

中止ACID 事务。

session.abort_transaction

参数：

  • 选项 （哈希） （默认为： nil ） —

    一组可自定义的选项

选项哈希 ( options )：

  • :timeout_ms （整数） —

    操作超时（以毫秒为单位）。 必须是非负整数。 0 的显式值表示无限。 未设置默认值，这意味着该值是从客户端继承的。

引发：

由于：

  • 2.6.0



730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
 
# File 'lib/ Mongo/session.rb', 第 730 行

def abort_transaction(选项 = nil)
  查询缓存.清除

  check_if_ended!
  check_if_no_transaction!

  if inside_states?(TRANSACTION_COMMITTED_STATE)
    提高 mongo::错误::InvalidTransactionOperation.new(
      mongo::错误::InvalidTransactionOperation.cannot_call_after_msg(
        :commitTransaction, :abortTransaction))
  end

  if inside_states?(TRANSACTION_ABORTED_STATE)
    提高 mongo::错误::InvalidTransactionOperation.new(
      mongo::错误::InvalidTransactionOperation.不能_call_tice_msg(:abortTransaction))
  end

  选项 ||= {}

  开始
    除非 startup_transaction?
      @aborting_transaction = true
      上下文 = 操作::上下文.new(
        客户端: @client,
        会话： self,
        operation_timeups: operation_timeups(选项)
      )
      write_with_retry(txn_options[:write_concern],
        ending_transaction: true, 上下文： 上下文,
      ) do |连接, txn_num, 上下文|
        开始
          操作::命令.new(
            选择器： { abortTransaction: 1 },
            db_name: ' admin ',
            会话： self,
            txn_num: txn_num
          ).execute_with_connection(连接, 上下文： 上下文)
        确保
          取消固定
        end
      end
    end

    @state = TRANSACTION_ABORTED_STATE
  救援 mongo::错误::InvalidTransactionOperation
    提高
  救援 mongo::错误
    @state = TRANSACTION_ABORTED_STATE
  救援 例外
    @state = TRANSACTION_ABORTED_STATE
    提高
  确保
    @aborting_transaction = false
  end

  # 无官方返回值，但返回 true，以便在交互式
  # 使用方法提示已成功。
  true
end

# aborting_transaction? ⇒ true | false

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回 会话当前是否正在中止事务。

返回：

  • ( true | false ) —

    会话当前是否正在中止ACID 事务。

由于：

  • 2.5.0



819
820
821
 
# File 'lib/ Mongo/session.rb', 第 819 行

def aborting_transaction?
  !!@aborting_transaction
end

# add_autocommit! （命令）→ 哈希 ( Hash )， BSON::Document

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

将自动提交字段添加到命令文档（如果适用）。

例子：

session.add_autocommit!(cmd)

返回：

  • ( Hash , BSON::Document ) —

    命令文档。

由于：

  • 2.6.0



899
900
901
902
903
 
# File 'lib/ Mongo/session.rb', 第 899 行

def add_autocommit!(命令)
  命令.点击 do |C|
    C[:autocommit] = false if in_transaction?
  end
end

# add_start_transaction! （命令）⇒哈希, BSON::Document

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

将 startTransaction 字段添加到命令文档（如果适用）。

例子：

session.add_start_transaction!(cmd)

返回：

  • ( Hash , BSON::Document ) —

    命令文档。

由于：

  • 2.6.0



914
915
916
917
918
919
920
 
# File 'lib/ Mongo/session.rb', 第 914 行

def add_start_transaction!(命令)
  命令.点击 do |C|
    if startup_transaction?
      C[:startTransaction] = true
    end
  end
end

# add_txn_num! （命令）⇒哈希, BSON::Document

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

将事务编号添加到命令文档（如果适用）。

例子：

session.add_txn_num!(cmd)

返回：

  • ( Hash , BSON::Document ) —

    命令文档。

由于：

  • 2.6.0



931
932
933
934
935
 
# File 'lib/ Mongo/session.rb', 第 931 行

def add_txn_num!(命令)
  命令.点击 do |C|
    C[:txnNumber] = BSON::Int64.new(@server_session.txn_num) if in_transaction?
  end
end

# add_txn_opts! (command, read, context) ⇒ Hash , BSON::Document

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

添加事务选项（如果适用）。

例子：

session.add_txn_opts!(cmd)

返回：

  • ( Hash , BSON::Document ) —

    命令文档。

由于：

  • 2.6.0



946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
 
# File 'lib/ Mongo/session.rb', 第 946 行

def add_txn_opts!(命令, 读, 上下文)
  命令.点击 do |C|
    # 应将读关注添加到启动事务的任何命令中。
    if startup_transaction?
      # http://jira.mongodb.org/browse/SPEC- 1161 : 事务的
      # 读关注会覆盖集合/数据库/客户端读关注，
      # 即使未设置事务的读关注。
      # 这里的读关注是发送到服务器的关注，可能
      # include afterClusterTime。
      if rc = C[:readConcern]
        rc = rc.dup
        rc.删除(: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.空？
        C.删除(:readConcern)
      else
        C[:readConcern ] = 选项::映射器.transform_values_to_strings(rc)
      end
    end

    # 我们需要将读关注级别作为string而不是符号发送。
    if C[:readConcern]
      C[:readConcern] = 选项::映射器.transform_values_to_strings(C[:readConcern])
    end

    if C[:commitTransaction]
      if max_time_ms = txn_options[:max_commit_time_ms]
        C[:maxTimeMS] = max_time_ms
      end
    end

    # 应将写关注（write concern）添加到任何 abortTransaction 或 commitTransaction 命令中。
    if (C[:abortTransaction] || C[:commitTransaction])
      if @already_committed
        wc = BSON::文档.new(C[:writeConcern] || txn_write_concern || {})
        wc.合并！(w: : majority)
        wc[:wtimeout] ||= 10000
        C[:writeConcern] = wc
      elsif txn_write_concern
        C[:writeConcern] ||= txn_write_concern
      end
    end

    # 非数字写关注 w 值需要作为string而不是符号发送。
    if C[:writeConcern] && C[:writeConcern][:w] && C[:writeConcern][:w].is_a?(符号)
      C[:writeConcern][:w] = C[:writeConcern][:w].to_s
    end

    # Ignore wtimeout if csot
    if 上下文&。csot?
      C[:writeConcern]&。删除(:wtimeout)
    end

    # 我们不得发送空（服务器默认）写关注（write concern）。
    C.删除(:writeConcern) if C[:writeConcern]&。空？
  end
end

# advance_operation_time (new_operation_time) =" BSON::Timestamp "

提前此会话的缓存 optime。

例子：

将 optime 提前。

session.advance_operation_time(timestamp)

参数：

  • new_operation_time ( BSON::Timestamp ) —

    新的optime 。

返回：

  • ( BSON::Timestamp ) —

    考虑当前时间和新时间的 max optime 。

由于：

  • 2.5.0



1123
1124
1125
1126
1127
1128
1129
 
# File 'lib/ Mongo/session.rb', 第 1123 行

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

由于：

  • 2.5.0



118
119
120
 
# File 'lib/ Mongo/session.rb', 第 118 行

def 集群
  @client.集群
end

# commit_transaction (options = nil) ⇒对象

提交会话上当前活动的ACID 事务。

例子：

提交事务。

session.commit_transaction

参数：

  • 选项 （哈希） （默认为： nil ） —

    一组可自定义的选项

选项哈希 ( options )：

  • :write_concern ( nil | WriteConcern::Base ) —

    用于此操作的写关注。

  • :timeout_ms （整数） —

    操作超时（以毫秒为单位）。 必须是非负整数。 0 的显式值表示无限。 未设置默认值，这意味着该值是从客户端继承的。

引发：

由于：

  • 2.6.0



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
682
683
684
685
686
687
688
689
690
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
 
# File 'lib/ Mongo/session.rb', 第 648 行

def commit_transaction(选项=nil)
  查询缓存.清除
  check_if_ended!
  check_if_no_transaction!

  if inside_states?(TRANSACTION_ABORTED_STATE)
    提高 mongo::错误::InvalidTransactionOperation.new(
      mongo::错误::InvalidTransactionOperation.cannot_call_after_msg(
        :abortTransaction, :commitTransaction))
  end

  选项 ||= {}

  开始
    # 如果 commitTransaction 被调用两次，则需要运行相同的提交
    # 再次操作，因此我们将会话恢复到之前的状态。
    if inside_states?(TRANSACTION_COMMITTED_STATE)
      @state = @last_commit_skipped ? STARTING_TRANSACTION_STATE : TRANSACTION_IN_PROGRESS_STATE
      @already_committed = true
    end

    if startup_transaction?
      @last_commit_skipped = true
    else
      @last_commit_skipped = false
      @committing_transaction = true

      write_concern = 选项[:write_concern] || txn_options[:write_concern]
      if write_concern && !write_concern.is_a?(writeConcern::Base)
        write_concern = writeConcern.获取(write_concern)
      end

      上下文 = 操作::上下文.new(
        客户端: @client,
        会话： self,
        operation_timeups: operation_timeups(选项)
      )
      write_with_retry(write_concern, ending_transaction: true,
        上下文： 上下文,
      ) do |连接, txn_num, 上下文|
        if 上下文.重试？
          if write_concern
            wco = write_concern.选项.合并(merge)(w: : majority)
            wco[:wtimeout] ||= 10000
            write_concern = writeConcern.获取(wco)
          else
            write_concern = writeConcern.获取(w: : majority, wtimeout: 10000)
          end
        end
        spec = {
          选择器： { commitTransaction: 1 },
          db_name: ' admin ',
          会话： self,
          txn_num: txn_num,
          write_concern: write_concern,
        }
        操作::命令.new(spec).execute_with_connection(连接, 上下文： 上下文)
      end
    end
  确保
    @state = TRANSACTION_COMMITTED_STATE
    @committing_transaction = false
  end

  # 无官方返回值，但返回 true，以便在交互式
  # 使用方法提示已成功。
  true
end

# committing_transaction? ⇒ true | false

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回此会话当前是否正在提交事务。

返回：

  • ( true | false ) —

    会话当前是否正在提交ACID 事务。

由于：

  • 2.5.0



811
812
813
 
# File 'lib/ Mongo/session.rb', 第 811 行

def committing_transaction?
  !!@committing_transaction
end

# 脏！ (mark = true) ⇒ 对象

将根本的服务器会话的脏状态设置为给定值。 如果没有服务器会话，则不会执行任何操作。

参数：

  • 标记 ( true | false ) （默认为： true ） —

    是否将服务器会话标记为脏会话。

由于：

  • 2.5.0



138
139
140
 
# File 'lib/ Mongo/session.rb', 第 138 行

def dirty!(标记 = true)
  @server_session&。dirty!(标记)
end

# 脏？ ⇒ true | false | false nil

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回根本的服务器会话是否为脏会话。 如果此会话不存在服务器会话，则返回 nil。

返回：

  • ( true | false | nil ) —

    根本的服务器会话是否为脏会话。 如果此会话不存在服务器会话，则返回 nil。

由于：

  • 2.5.0



146
147
148
 
# File 'lib/ Mongo/session.rb', 第 146 行

def dirty?
  @server_session&。dirty?
end

# end_session ⇒ nil

结束此会话。

如果此会话中有正在进行的事务，则该事务将中止。 与此会话关联的服务器会话将返回到服务器会话池。 最后，此会话被标记为已结束并且不再可用。

如果此会话已结束，则此方法不执行任何操作。

请注意，此方法不会直接向此服务器发出 endSessions 命令，这与其名称所暗示的相反。

例子：

session.end_session

返回：

  • ( nil ) —

    始终为零。

由于：

  • 2.5.0



377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
 
# File 'lib/ Mongo/session.rb', 第 377 行

def end_session
  if !结束？ && @client
    if inside_states?(TRANSACTION_IN_PROGRESS_STATE)
      开始
        abort_transaction
      救援 mongo::错误, 错误::AuthError
      end
    end
    if @server_session
      @client.集群.session_pool.checkin(@server_session)
    end
  end
确保
  @server_session = nil
  @ended = true
end

#结束？ ⇒ true , false

此会话是否已结束。

例子：

session.ended?

返回：

  • ( true , false ) —

    会话是否已结束。

由于：

  • 2.5.0



243
244
245
 
# File 'lib/ Mongo/session.rb', 第 243 行

def 结束？
  !!@ended
end

#显式？ ⇒ true , false

此会话是否为显式会话（即 用户创建）。

例子：

会话是否显式？

session.explicit?

返回：

  • ( true , false ) —

    此会话是否为显式会话。

由于：

  • 2.5.2



178
179
180
 
# File 'lib/ Mongo/session.rb', 第 178 行

def explicit?
  !隐式？
end

#隐式？ ⇒ true , false

此会话是否为隐式会话（不是用户创建的）。

例子：

会话是隐式的吗？

session.implicit?

返回：

  • ( true , false ) —

    此会话是否为隐式会话。

由于：

  • 2.5.1



166
167
168
 
# File 'lib/ Mongo/session.rb', 第 166 行

def 隐式？
  @implicit ||= !!(@options.键？(:implicit) && @options[:implicit] == true)
end

# in_transaction? ⇒ true | false

会话当前是否处于ACID 事务中。

例子：

会话是否在ACID 事务中？

session.in_transaction?

返回：

  • ( true | false ) —

    会话是否位于事务中。

由于：

  • 2.6.0



803
804
805
 
# File 'lib/ Mongo/session.rb', 第 803 行

def in_transaction?
  inside_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE)
end

#检查⇒ string

获取用于检查的格式化string 。

例子：

检查会话对象。

session.inspect

返回：

  • ( string ) —

    会话检查。

由于：

  • 2.5.0



355
356
357
 
# File 'lib/ Mongo/session.rb', 第 355 行

def 检查
  " #<Mongo::Session: 0 x #{ object_id } session_id= #{ session_id } options= #{ @options } > "
end

# Materialize_if_needed ⇒会话

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

如果尚未设立，则通过从会话池中检出会话来填充会话对象的 server_session。

返回：

由于：

  • 2.5.0



1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
 
# File 'lib/ Mongo/session.rb', 第 1137 行

def Materialize_if_needed
  if 结束？
    提高 错误::SessionEnded
  end

  return 除非 隐式？ && !@server_session

  @server_session = 集群.session_pool.checkout

  self
end

#物化？ ⇒布尔

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回：

  • （布尔值）

由于：

  • 2.5.0



1150
1151
1152
1153
1154
1155
1156
 
# File 'lib/ Mongo/session.rb', 第 1150 行

def 物化？
  if 结束？
    提高 错误::SessionEnded
  end

  !@server_session.nil?
end

# next_txn_num ⇒整数

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

递增并返回下一个ACID 事务编号。

例子：

获取下ACID 事务编号。

session.next_txn_num

返回：

  • ( Integer ) —

    下一个事务编号。

由于：

  • 2.5.0



1167
1168
1169
1170
1171
1172
1173
 
# File 'lib/ Mongo/session.rb', 第 1167 行

def next_txn_num
  if 结束？
    提高 错误::SessionEnded
  end

  @server_session.next_txn_num
end

#pin_to_connection (connection_global_id) ⇒对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

将此会话固定到指定连接。

此会话到。

参数：

  • connection_global_id ( Integer ) —

    连接到管脚的全局 ID

由于：

  • 2.5.0



846
847
848
849
850
851
 
# File 'lib/ Mongo/session.rb', 第 846 行

def pin_to_connection(connection_global_id)
  if connection_global_id.nil?
    提高 ArgumentError, '无法固定到零连接 ID '
  end
  @pinned_connection_global_id = connection_global_id
end

#pin_to_server (server) ⇒对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

将此会话固定到指定服务器，该服务器应该是mongos。

参数：

由于：

  • 2.5.0



828
829
830
831
832
833
834
835
836
837
838
 
# File 'lib/ Mongo/session.rb', 第 828 行

def pin_to_server(server)
  if server.nil?
    提高 ArgumentError, “无法固定到零服务器”
  end
  if Lint.已启用？
    除非 server.mongos?
      提高 错误::LintError, “ 尝试将会话固定到 不是 mongos 的服务器 #{ server .summary } } ”
    end
  end
  @pinned_server = server
end

# process (result) = "Operation::Result"

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

处理来自使用此会话的服务器的响应。

例子：

处理来自服务器的响应。

session.process(result)

参数：

返回：

由于：

  • 2.5.0



1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
 
# File 'lib/ Mongo/session.rb', 第 1095 行

def 处理(结果)
  除非 隐式？
    set_operation_time(结果)
    if cluster_time_doc = 结果.cluster_time
      advance_cluster_time(cluster_time_doc)
    end
  end
  @server_session.set_last_use!

  if doc = 结果.回复 && 结果.回复.文档.first
    if doc[:recoveryToken]
      self.Recovery_token = doc[:recoveryToken]
    end
  end

  结果
end

# retry_reads? ⇒布尔

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

是否可以根据现代可重试读取规范重试使用此会话执行的读取。

如果此方法返回 true，则应用程序已请求现代可重试读取。 如果为读取操作选择的服务器支持现代可重试读取，则将用于该特定操作。 如果为读取操作选择的服务器不支持现代可重试读取，则不会重试读取。

如果此方法返回 false，则应用程序已请求传统可重试读取。 无论客户端连接到的服务器的版本如何，都将使用传统的可重试读取逻辑。 读取重试次数由 :max_read_retries 客户端选项指定，默认为1 ，可以设置为0以禁用传统读取重试。

返回：

  • （布尔值）

由于：

  • 2.5.0



198
199
200
 
# File 'lib/ Mongo/session.rb', 第 198 行

def retry_reads?
  客户端.选项[:retry_reads] != false
end

# retry_writes? ⇒ true , false

注意：

可重试写入仅适用于至少为3.6且具有分片集群、副本集或负载均衡拓扑的服务器版本。

是否会重试使用此会话执行的写入。

例子：

将重试写入。

session.retry_writes?

返回：

  • ( true , false ) —

    如果写入，则会重试。

由于：

  • 2.5.0



213
214
215
 
# File 'lib/ Mongo/session.rb', 第 213 行

def retry_writes?
  !!客户端.选项[:retry_writes] && (集群.replica_set? || 集群.分片的? || 集群.load_balanced?)
end

#session_id ⇒ BSON::Document

如果会话尚未结束，则获取此会话的服务器会话 ID。 如果会话已结束，则引发 Error::SessionEnded。

返回：

  • ( BSON::Document ) —

    服务器会话 ID。

引发：

由于：

  • 2.5.0



255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/ Mongo/session.rb', 第 255 行

def session_id
  if 结束？
    提高 错误::SessionEnded
  end

  # 显式会话始终有一个 session_id，因为在
  # 必须提供服务器会话构建。 隐式会话
  # 在物化之前不会有 session_id，因此调用
  # session_id 可能会失败。 应用程序不应有机会
  # 会出现此故障，因为隐式会话不应
  # 可供应用程序访问，因为其生命周期被限制为
  # 操作执行，完全由驾驶员完成。
  除非 物化？
    提高 错误::SessionNotMaterialized
  end

  @server_session.session_id
end

# snapshot? ⇒ true | false

返回该会话是否配置为支持快照读取。

返回：

  • ( true | false ) —

    是否为会话配置了快照读取。

由于：

  • 2.5.0



124
125
126
 
# File 'lib/ Mongo/session.rb', 第 124 行

def 快照？
  !!选项[：快照]
end

# start_transaction (options = nil) ⇒对象

将此会话中的后续操作放入新ACID 事务中。

请注意，在调用 start_transaction 后执行操作之前，不会在服务器上启动事务。

例子：

启动新事务

session.start_transaction(options)

参数：

  • 选项 （哈希） （默认为： nil ） —

    正在启动的ACID 事务的选项。

选项哈希 ( options )：

  • :max_commit_time_ms （整数） —

    允许单个 commitTransaction 命令运行的最长时间（以毫秒为单位）。 此选项已弃用，请改用 :timeout_ms。

  • :read_concern （哈希） —

    读关注（read concern）选项哈希，具有以下可选键：

    • :level — 以符号表示的读取偏好（read preference）级别；有效值

      are *:local*, *:majority*, and *:snapshot*
  • :write_concern （哈希） —

    写关注（write concern）选项。 可以是 :w => 整数|字符串、: fsync => 布尔值、:j => 布尔值。

  • :read （哈希） —

    读取偏好选项。 哈希可能包含以下项目：

    • :mode — 以符号指定的读取偏好；唯一有效值为:primary 。

  • :timeout_ms （整数） —

    操作超时（以毫秒为单位）。 必须是非负整数。 0 的显式值表示无限。 未设置默认值，这意味着该值是从客户端继承的。

引发：

由于：

  • 2.6.0



583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
 
# File 'lib/ Mongo/session.rb', 第 583 行

def start_transaction(选项 = nil)
  check_transactions_supported!

  if 选项
    Lint.validate_read_concern_option(选项[:read_concern])

=begin
    # 在这里检测无效的读取偏好会很方便，但是
    # 某些规范测试需要稍后检测无效的读取偏好。
    # 也许我们可以在 lint模式开启时执行此操作。
    mode = options[:read] && options[:read][:mode].to_s
    if mode && mode != 'primary'
      引发 Mongo::Error::InvalidTransactionOperation.new(
        “事务中的读取偏好必须是主节点（已请求：#{mode}）”
      )
    end
=end
  end

  if 快照？
    提高 mongo::错误::SnapshotSessionTransactionProhibited
  end

  check_if_ended!

  if inside_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE)
    提高 mongo::错误::InvalidTransactionOperation.new(
      mongo::错误::InvalidTransactionOperation::TRANSACTION_ALREADY_IN_PROGRESS)
  end

  取消固定

  next_txn_num
  @txn_options = (@options[:default_transaction_options] || {}).合并(merge)(选项 || {})

  if txn_write_concern && !writeConcern.获取(txn_write_concern).已确认？
    提高 mongo::错误::InvalidTransactionOperation.new(
      mongo::错误::InvalidTransactionOperation::UNACKNOWLEDGED_WRITE_CONCERN)
  end

  @state = STARTING_TRANSACTION_STATE
  @already_committed = false

  # 该方法没有显式返回值。
  # 我们可以在此处返回 nil，但 true 向用户表明
  # 操作成功。 这是供交互式使用的。
  # 请注意，返回值没有记录。
  true
end

# startup_transaction? ⇒布尔

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回：

  • （布尔值）

由于：

  • 2.5.0



791
792
793
 
# File 'lib/ Mongo/session.rb', 第 791 行

def startup_transaction?
  inside_states?(STARTING_TRANSACTION_STATE)
end

# Suppress_read_write_concern! （命令）⇒哈希, BSON::Document

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

如果不适用，请从命令中删除读关注和/或写关注。

例子：

session.suppress_read_write_concern!(cmd)

返回：

  • ( Hash , BSON::Document ) —

    命令文档。

由于：

  • 2.6.0



1020
1021
1022
1023
1024
1025
1026
1027
 
# File 'lib/ Mongo/session.rb', 第 1020 行

def subsup_read_write_concern!(命令)
  命令.点击 do |C|
    来年 除非 in_transaction?

    C.删除(:readConcern) 除非 startup_transaction?
    C.删除(:writeConcern) 除非 C[:commitTransaction] || C[:abortTransaction]
  end
end

# txn_num ⇒整数

获取当前ACID 事务编号。

例子：

获取当前ACID 事务编号。

session.txn_num

返回：

  • ( Integer ) —

    当前事务编号。

由于：

  • 2.6.0



1183
1184
1185
1186
1187
1188
1189
 
# File 'lib/ Mongo/session.rb', 第 1183 行

def txn_num
  if 结束？
    提高 错误::SessionEnded
  end

  @server_session.txn_num
end

# txn_options ⇒哈希

在此会话上。

返回：

  • (哈希) —

    当前正在执行的事务的选项

由于：

  • 2.6.0



154
155
156
 
# File 'lib/ Mongo/session.rb', 第 154 行

def txn_options
  @txn_options or 提高 ArgumentError, "没有活跃的ACID 事务"
end

# txn_read_preference ⇒哈希

获取会话将在当前活动ACID 事务中使用的读取偏好（read preference）。

这是带有下划线键的驾驶员风格的哈希。

例子：

获取事务的读取偏好（read preference）

session.txn_read_preference

返回：

  • (哈希) —

    事务的读取偏好。

由于：

  • 2.6.0



228
229
230
231
232
233
 
# File 'lib/ Mongo/session.rb', 第 228 行

def txn_read_preference
  rp = txn_options[:read] ||
    @client.read_preference
  mongo::Lint.validate_underscore_read_preference(rp)
  rp
end

# unpin (connection = nil) ⇒对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

如果此会话已固定，则从固定的服务器或连接中取消固定此会话。

参数：

  • 连接 ( Connection | nil ) （默认为： nil ） —

    要从中取消固定的连接。

由于：

  • 2.5.0



859
860
861
862
863
 
# File 'lib/ Mongo/session.rb', 第 859 行

def 取消固定(连接 = nil)
  @pinned_server = nil
  @pinned_connection_global_id = nil
  连接.取消固定 除非 连接.nil?
end

# unpin_maybe (error, connection = nil) ⇒对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

如果会话已固定，并且指定的异常实例和会话的事务状态要求将其取消固定，请从固定的服务器或连接上取消固定此会话。

异常实例应该已经设立了所有标签（客户端和服务器端生成的标签）。

参数：

  • 错误 （错误） —

    要进程的异常实例。

  • 连接 ( Connection | nil ) （默认为： nil ） —

    要从中取消固定的连接。

由于：

  • 2.5.0



876
877
878
879
880
881
882
883
884
885
886
887
888
 
# File 'lib/ Mongo/session.rb', 第 876 行

def unpin_maybe(错误, 连接 = nil)
  if !inside_states?(会话::NO_TRANSACTION_STATE) &&
    错误.标签？('TransientTransactionError')
  then
    取消固定(连接)
  end

  if committing_transaction? &&
    错误.标签？(' UnknownTransactionCommitResult ')
  then
    取消固定(连接)
  end
end

#update_state! ⇒ Object

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

由于正在运行的（非提交和非中止）操作而更新会话状态。

由于：

  • 2.6.0



1056
1057
1058
1059
1060
1061
1062
1063
 
# File 'lib/ Mongo/session.rb', 第 1056 行

def update_state!
  案例 @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

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

验证会话以供指定客户端使用。

不得结束会话，并且必须由与要使用该会话的客户端具有相同集群的客户端创建该会话。

参数：

  • 客户端 (客户端) —

    要使用会话的客户端。

返回：

  • (会话) —

    self（如果会话有效）。

引发：

由于：

  • 2.5.0



1078
1079
1080
1081
1082
 
# File 'lib/ Mongo/session.rb', 第 1078 行

def validate!(客户端)
  check_matching_cluster!(客户端)
  check_if_ended!
  self
end

# validate_read_preference! （命令）→对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

确保命令的读取偏好是主节点。

例子：

session.validate_read_preference!(command)

引发：

由于：

  • 2.6.0



1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
 
# File 'lib/ Mongo/session.rb', 第 1039 行

def validate_read_preference!(命令)
  return 除非 in_transaction?
  return 除非 命令[' $readPreference ']

  模式 = 命令[' $readPreference ']['mode'] || 命令[' $readPreference '][:mode]

  if 模式 && 模式 != ' primary '
    提高 mongo::错误::InvalidTransactionOperation.new(
      "事务中的读取偏好必须是主节点（已请求： #{ mode } ) "
    )
  end
end

# with_transaction (options = nil) ⇒对象

注意：

with_transaction 包含一个循环，因此如果 with_transaction 本身被置于一个循环中，其区块不应调用 next 或break 来控制外循环，因为这会影响 with_transaction 中的循环。 如果检测到这种情况，驱动程序将发出警告并中止事务。

执行ACID 事务中提供的区块，并根据需要重试。

返回区块的返回值。

确切的重试次数和执行时间是驱动程序的实现细节；提供的区块应该是幂等的，并且应该准备好被多次调用。 驱动程序可以在活动事务中重试提交命令，也可以重复事务并再次调用区块，具体取决于遇到的错误（如果有）。 另请注意，可能会对不同的服务器执行重试。

事务无法嵌套 - 如果在会话已有活动事务时调用此方法，则会引发 InvalidTransactionOperation。

区块引发的非派生自 Mongo::Error 的异常会停止处理、中止ACID 事务并从 with_transaction 中传播出去。 从 Mongo::Error 派生的异常可能会由 with_transaction 进行处理，从而导致进程重试。

目前，with_transaction 将重试提交并阻止调用，直到 with_transaction 自开始执行以来至少过去了120秒。 此超时不可配置，可能会在未来的驱动程序版本中更改。

例子：

在ACID 事务中执行声明

session.with_transaction(write_concern: {w: :majority}) do
  collection.update_one({ id: 3 }, { '$set' => { status: 'Inactive'} },
                        session: session)

end

在ACID 事务中执行声明，限制消耗的总时间

Timeout.timeout(5) do
  session.with_transaction(write_concern: {w: :majority}) do
    collection.update_one({ id: 3 }, { '$set' => { status: 'Inactive'} },
                          session: session)

  end
end

参数：

  • 选项 （哈希） （默认为： nil ） —

    正在启动的ACID 事务的选项。 这些选项与 start_transaction 接受的选项相同。

引发：

由于：

  • 2.7.0



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
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
 
# File 'lib/ Mongo/session.rb', 第 448 行

def with_transaction(选项 = nil)
  if timeout_ms = (选项 || {})[:timeout_ms]
    timeout_sec = timeout_ms / 1_000.0
    截止日期 = Utils.monotic_time + timeout_sec
    @with_transaction_deadline = 截止日期
  elsif default_timeout_ms = @options[:default_timeout_ms]
    timeout_sec = default_timeout_ms / 1_000.0
    截止日期 = Utils.monotic_time + timeout_sec
    @with_transaction_deadline = 截止日期
  elsif @client.timeout_sec
    截止日期 = Utils.monotic_time + @client.timeout_sec
    @with_transaction_deadline = 截止日期
  else
    截止日期 = Utils.monotic_time + 120
  end
  transaction_in_progress = false
  循环 do
    commit_options = {}
    if 选项
      commit_options[:write_concern] = 选项[:write_concern]
    end
    start_transaction(选项)
    transaction_in_progress = true
    开始
      rv = 产量 self
    救援 例外 => e
      if inside_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE)
        log_warn(" Aboring transaction due to #{ e . class } : #{ e } ")
        @with_transaction_deadline = nil
        abort_transaction
        transaction_in_progress = false
      end

      if Utils.monotic_time >= 截止日期
        transaction_in_progress = false
        提高
      end

      if e.is_a?(mongo::错误) && e.标签？('TransientTransactionError')
        来年
      end

      提高
    else
      if inside_states?(TRANSACTION_ABORTED_STATE, NO_TRANSACTION_STATE, TRANSACTION_COMMITTED_STATE)
        transaction_in_progress = false
        return rv
      end

      开始
        commit_transaction(commit_options)
        transaction_in_progress = false
        return rv
      救援 mongo::错误 => e
        if e.标签？(' UnknownTransactionCommitResult ')
          if Utils.monotic_time >= 截止日期 ||
            e.is_a?(错误::OperationFailure::家庭情况) && e.max_time_ms_expired?
          then
            transaction_in_progress = false
            提高
          end
          wc_options = 案例 v = commit_options[:write_concern]
            when writeConcern::Base
              v.选项
            when nil
              {}
            else
              v
            end
          commit_options[:write_concern] = wc_options.合并(merge)(w: : majority)
          重试
        elsif e.标签？('TransientTransactionError')
          if Utils.monotic_time >= 截止日期
            transaction_in_progress = false
            提高
          end
          @state = NO_TRANSACTION_STATE
          来年
        else
          transaction_in_progress = false
          提高
        end
      救援 错误::AuthError
        transaction_in_progress = false
        提高
      end
    end
  end

  # 无官方返回值，但返回 true，以便在交互式
  # 使用方法提示已成功。
  true
确保
  if transaction_in_progress
    log_warn(' with_transaction 回调打破了 with_transaction 循环，中止了事务')
    开始
      abort_transaction
    救援 错误::OperationFailure::家庭情况, 错误::InvalidTransactionOperation
    end
  end
  @with_transaction_deadline = nil
end