类：Mongo::Session

继承：
对象
  • 对象
显示全部
扩展方式：
可转发
包括：
ClusterTime::Consumer 、 Loggable 、 Retryable
定义于：
构建/ruby-driver-v2.19/lib/ mongo /session.rb 、
构建/ruby-driver-v2.19/lib/ mongo /session/session_pool.rb,
构建/ruby-driver-v2.19/lib/ mongo /session/server_session.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_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



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 77

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
end

实例属性详细信息

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

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

返回：

  • (客户端) —

    创建此会话的客户端。

由于：

  • 2.5.1



109
110
111
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 109

def 客户端
  @client
end

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

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

返回：

  • ( BSON::Timestamp ) —

    此会话的最新optime 。

由于：

  • 2.5.0



124
125
126
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 124

def operation_time
  @operation_time
end

# options ⇒哈希（只读）

返回 此会话的选项。

返回：

  • (哈希) —

    此会话的选项。

由于：

  • 2.5.0



104
105
106
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 104

def 选项
  @options
end

#pinned_connection_global_id ⇒整数 | nil （只读）

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

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

返回：

  • ( Integer | nil ) —

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

由于：

  • 2.5.0



260
261
262
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 260

def pinned_connection_global_id
  @pinned_connection_global_id
end

#pinned_server ⇒ MongoDB Server | nil （只读）

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

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

返回：

  • ( MongoDB Server | nil ) —

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

由于：

  • 2.5.0



254
255
256
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 254

def pinned_server
  @pinned_server
end

# Recovery_token ⇒ BSON::Document | nil

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

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

返回：

  • ( BSON::Document | nil ) —

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

由于：

  • 2.5.0



266
267
268
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 266

def Recovery_token
  @recovery_token
end

# snapshot_timestamp ⇒对象

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

由于：

  • 2.5.0



1120
1121
1122
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 1120

def snapshot_timestamp
  @snapshot_timestamp
end

实例方法详细信息

# abort_transaction ⇒对象

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

例子：

中止ACID 事务。

session.abort_transaction

引发：

由于：

  • 2.6.0



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
716
717
718
719
720
721
722
723
724
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 672

def abort_transaction
  查询缓存.清除

  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)
      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



755
756
757
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 755

def aborting_transaction?
  !!@aborting_transaction
end

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

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

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

例子：

session.add_autocommit!(cmd)

返回：

  • ( Hash , BSON::Document ) —

    命令文档。

由于：

  • 2.6.0



835
836
837
838
839
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 835

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



850
851
852
853
854
855
856
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 850

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



867
868
869
870
871
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 867

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) ⇒ Hash , BSON::Document

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

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

例子：

session.add_txn_opts!(cmd)

返回：

  • ( Hash , BSON::Document ) —

    命令文档。

由于：

  • 2.6.0



882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
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
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 882

def add_txn_opts!(命令, 读)
  命令.点击 do |C|
    # 应将读关注添加到启动事务的任何命令中。
    if startup_transaction?
      # https://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
  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



1051
1052
1053
1054
1055
1056
1057
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 1051

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



111
112
113
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 111

def 集群
  @client.集群
end

# commit_transaction (options = nil) ⇒对象

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

例子：

提交事务。

session.commit_transaction

参数：

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

    一组可自定义的选项

选项哈希 ( options )：

引发：

由于：

  • 2.6.0



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
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
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 599

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)
      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



747
748
749
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 747

def committing_transaction?
  !!@committing_transaction
end

# end_session ⇒ nil

结束此会话。

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

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

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

例子：

session.end_session

返回：

  • ( nil ) —

    始终为零。

由于：

  • 2.5.0



353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 353

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



219
220
221
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 219

def 结束？
  !!@ended
end

#显式？ ⇒ true , false

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

例子：

会话是否显式？

session.explicit?

返回：

  • ( true , false ) —

    此会话是否为显式会话。

由于：

  • 2.5.2



154
155
156
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 154

def explicit?
  !隐式？
end

#隐式？ ⇒ true , false

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

例子：

会话是隐式的吗？

session.implicit?

返回：

  • ( true , false ) —

    此会话是否为隐式会话。

由于：

  • 2.5.1



142
143
144
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 142

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

# in_transaction? ⇒ true | false

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

例子：

会话是否在ACID 事务中？

session.in_transaction?

返回：

  • ( true | false ) —

    会话是否位于事务中。

由于：

  • 2.6.0



739
740
741
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 739

def in_transaction?
  inside_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE)
end

#检查⇒ string

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

例子：

检查会话对象。

session.inspect

返回：

  • ( string ) —

    会话检查。

由于：

  • 2.5.0



331
332
333
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 331

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

# Materialize_if_needed ⇒会话

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

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

返回：

由于：

  • 2.5.0



1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 1065

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

  return 除非 隐式？ && !@server_session

  @server_session = 集群.session_pool.checkout

  self
end

#物化？ ⇒布尔

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

返回：

  • （布尔值）

由于：

  • 2.5.0



1078
1079
1080
1081
1082
1083
1084
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 1078

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

  !@server_session.nil?
end

# next_txn_num ⇒整数

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

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

例子：

获取下ACID 事务编号。

session.next_txn_num

返回：

  • ( Integer ) —

    下一个事务编号。

由于：

  • 2.5.0



1095
1096
1097
1098
1099
1100
1101
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 1095

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



782
783
784
785
786
787
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 782

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



764
765
766
767
768
769
770
771
772
773
774
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 764

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



1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 1023

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



174
175
176
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 174

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

# retry_writes? ⇒ true , false

注意：

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

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

例子：

将重试写入。

session.retry_writes?

返回：

  • ( true , false ) —

    如果写入，则会重试。

由于：

  • 2.5.0



189
190
191
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 189

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

#session_id ⇒ BSON::Document

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

返回：

  • ( BSON::Document ) —

    服务器会话 ID。

引发：

由于：

  • 2.5.0



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 231

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



117
118
119
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 117

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

# start_transaction (options = nil) ⇒对象

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

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

例子：

启动新事务

session.start_transaction(options)

参数：

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

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

选项哈希 ( options )：

  • :max_commit_time_ms （整数） —

    允许单个 commitTransaction 命令运行的最长时间（以毫秒为单位）。

  • :read_concern （哈希） —

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

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

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

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

  • :read （哈希） —

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

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

引发：

由于：

  • 2.6.0



540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
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
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 540

def start_transaction(选项 = nil)
  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



727
728
729
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 727

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



948
949
950
951
952
953
954
955
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 948

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



1111
1112
1113
1114
1115
1116
1117
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 1111

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

  @server_session.txn_num
end

# txn_options ⇒哈希

在此会话上。

返回：

  • (哈希) —

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

由于：

  • 2.6.0



130
131
132
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 130

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

# txn_read_preference ⇒哈希

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

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

例子：

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

session.txn_read_preference

返回：

  • (哈希) —

    事务的读取偏好。

由于：

  • 2.6.0



204
205
206
207
208
209
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 204

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



795
796
797
798
799
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 795

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

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

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

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

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

参数：

  • 错误 （错误） —

    要进程的异常实例。

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

    要从中取消固定的连接。

由于：

  • 2.5.0



812
813
814
815
816
817
818
819
820
821
822
823
824
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 812

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



984
985
986
987
988
989
990
991
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 984

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



1006
1007
1008
1009
1010
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 1006

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

# validate_read_preference! （命令）→对象

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

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

例子：

session.validate_read_preference!(command)

引发：

由于：

  • 2.6.0



967
968
969
970
971
972
973
974
975
976
977
978
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 967

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



424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
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
 
# File 'build/Ruby-driver-v 2 . 19 /lib/mongo/session.rb', line 424

def with_transaction(选项=nil)
  # 整个操作的不可配置120秒超时
  截止日期 = Utils.monotic_time + 120
  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 } ")
        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
end