class Mongo::Session

A logical session representing a set of sequential operations executed

by an application that are related in some way.

@since 2.5.0

Constants

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.

@since 2.5.0

SESSIONS_NOT_SUPPORTED

Error message describing that sessions are not supported by the server version.

@since 2.5.0

SESSION_ENDED_ERROR_MSG

Error message describing that the session cannot be used because it has already been ended.

@since 2.5.0

Attributes

cluster[R]

Get the cluster through which this session was created.

@since 2.5.1

cluster_time[R]

The cluster time for this session.

@since 2.5.0

operation_time[R]

The latest seen operation time for this session.

@since 2.5.0

options[R]

Get the options for this session.

@since 2.5.0

Public Class Methods

new(server_session, cluster, options = {}) click to toggle source

Initialize a Session.

@example

Session.new(server_session, cluster, options)

@param [ ServerSession ] server_session The server session this session is associated with. @param [ Cluster ] cluster The cluster through which this session is created. @param [ Hash ] options The options for this session.

@since 2.5.0

# File lib/mongo/session.rb, line 75
def initialize(server_session, cluster, options = {})
  @server_session = server_session
  @cluster = cluster
  @options = options.dup.freeze
  @cluster_time = nil
end

Public Instance Methods

add_id!(command) click to toggle source

Add this session's id to a command document.

@example

session.add_id!(cmd)

@return [ Hash, BSON::Document ] The command document.

@since 2.5.0

# File lib/mongo/session.rb, line 130
def add_id!(command)
  command.merge!(lsid: session_id)
end
advance_cluster_time(new_cluster_time) click to toggle source

Advance the cached cluster time document for this session.

@example Advance the cluster time.

session.advance_cluster_time(doc)

@param [ BSON::Document, Hash ] new_cluster_time The new cluster time.

@return [ BSON::Document, Hash ] The new cluster time.

@since 2.5.0

# File lib/mongo/session.rb, line 181
def advance_cluster_time(new_cluster_time)
  if @cluster_time
    @cluster_time = [ @cluster_time, new_cluster_time ].max_by { |doc| doc[Cluster::CLUSTER_TIME] }
  else
    @cluster_time = new_cluster_time
  end
end
advance_operation_time(new_operation_time) click to toggle source

Advance the cached operation time for this session.

@example Advance the operation time.

session.advance_operation_time(timestamp)

@param [ BSON::Timestamp ] new_operation_time The new operation time.

@return [ BSON::Timestamp ] The max operation time, considering the current and new times.

@since 2.5.0

# File lib/mongo/session.rb, line 199
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
end_session() click to toggle source

End this session.

@example

session.end_session

@return [ nil ] Always nil.

@since 2.5.0

# File lib/mongo/session.rb, line 102
def end_session
  if !ended? && @cluster
    @cluster.session_pool.checkin(@server_session)
  end
ensure
  @server_session = nil
end
ended?() click to toggle source

Whether this session has ended.

@example

session.ended?

@return [ true, false ] Whether the session has ended.

@since 2.5.0

# File lib/mongo/session.rb, line 118
def ended?
  @server_session.nil?
end
implicit?() click to toggle source

Is this session an implicit one (not user-created).

@example Is the session implicit?

session.implicit?

@return [ true, false ] Whether this session is implicit.

@since 2.5.1

# File lib/mongo/session.rb, line 254
def implicit?
  @implicit_session ||= !!(@options.key?(:implicit) && @options[:implicit] == true)
end
inspect() click to toggle source

Get a formatted string for use in inspection.

@example Inspect the session object.

session.inspect

@return [ String ] The session inspection.

@since 2.5.0

# File lib/mongo/session.rb, line 90
def inspect
  "#<Mongo::Session:0x#{object_id} session_id=#{session_id} options=#{@options}>"
end
next_txn_num() click to toggle source

Increment and return the next transaction number.

@example Get the next transaction number.

session.next_txn_num

@return [ Integer ] The next transaction number.

@since 2.5.0

# File lib/mongo/session.rb, line 242
def next_txn_num
  @server_session.next_txn_num if @server_session
end
process(result) click to toggle source

Process a response from the server that used this session.

@example Process a response from the server.

session.process(result)

@param [ Operation::Result ] result The result from the operation.

@return [ Operation::Result ] The result.

@since 2.5.0

# File lib/mongo/session.rb, line 162
def process(result)
  unless implicit?
    set_operation_time(result)
    set_cluster_time(result)
  end
  @server_session.set_last_use!
  result
end
retry_writes?() click to toggle source

Will writes executed with this session be retried.

@example Will writes be retried.

session.retry_writes?

@return [ true, false ] If writes will be retried.

@note Retryable writes are only available on server versions at least 3.6 and with

sharded clusters or replica sets.

@since 2.5.0

# File lib/mongo/session.rb, line 218
def retry_writes?
  !!cluster.options[:retry_writes] && (cluster.replica_set? || cluster.sharded?)
end
session_id() click to toggle source

Get the session id.

@example Get the session id.

session.session_id

@return [ BSON::Document ] The session id.

@since 2.5.0

# File lib/mongo/session.rb, line 230
def session_id
  @server_session.session_id if @server_session
end
validate!(cluster) click to toggle source

Validate the session.

@example

session.validate!(cluster)

@param [ Cluster ] cluster The cluster the session is attempted to be used with.

@return [ nil ] nil if the session is valid.

@raise [ Mongo::Error::InvalidSession ] Raise error if the session is not valid.

@since 2.5.0

# File lib/mongo/session.rb, line 146
def validate!(cluster)
  check_matching_cluster!(cluster)
  check_if_ended!
  self
end

Private Instance Methods

causal_consistency?() click to toggle source
# File lib/mongo/session.rb, line 268
def causal_consistency?
  @causal_consistency ||= (if @options.key?(:causal_consistency)
                             @options[:causal_consistency] == true
                           else
                             true
                           end)
end
causal_consistency_doc(read_concern) click to toggle source
# File lib/mongo/session.rb, line 260
def causal_consistency_doc(read_concern)
  if operation_time && causal_consistency?
    (read_concern || {}).merge(:afterClusterTime => operation_time)
  else
    read_concern
  end
end
check_if_ended!() click to toggle source
# File lib/mongo/session.rb, line 292
def check_if_ended!
  raise Mongo::Error::InvalidSession.new(SESSION_ENDED_ERROR_MSG) if ended?
end
check_matching_cluster!(cluster) click to toggle source
# File lib/mongo/session.rb, line 296
def check_matching_cluster!(cluster)
  if @cluster != cluster
    raise Mongo::Error::InvalidSession.new(MISMATCHED_CLUSTER_ERROR_MSG)
  end
end
set_cluster_time(result) click to toggle source
# File lib/mongo/session.rb, line 282
def set_cluster_time(result)
  if cluster_time_doc = result.cluster_time
    if @cluster_time.nil?
      @cluster_time = cluster_time_doc
    elsif cluster_time_doc[Cluster::CLUSTER_TIME] > @cluster_time[Cluster::CLUSTER_TIME]
      @cluster_time = cluster_time_doc
    end
  end
end
set_operation_time(result) click to toggle source
# File lib/mongo/session.rb, line 276
def set_operation_time(result)
  if result && result.operation_time
    @operation_time = result.operation_time
  end
end