class Mongo::Session

A logical client 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 describing that the session was attempted to be used by a client different from the one it was originally associated with.

@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

client[R]

Get the client through which this session was created.

@since 2.5.0

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, client, options = {}) click to toggle source

Initialize a Session.

@example

Session.new(server_session, client, options)

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

@since 2.5.0

# File lib/mongo/session.rb, line 76
def initialize(server_session, client, options = {})
  @server_session = server_session
  @client = client
  @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 144
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 194
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 212
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_implicit_session() click to toggle source

End this session if it's an implicit session.

@example

session.end_implicit_session

@return [ nil ] Always nil.

@since 2.5.0

# File lib/mongo/session.rb, line 120
def end_implicit_session
  end_session if implicit_session?
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 103
def end_session
  if !ended? && @client
    @client.instance_variable_get(:@session_pool).checkin(@server_session)
    nil
  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 132
def ended?
  @server_session.nil?
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 91
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.

server_session.next_txn_num

@return [ Integer ] The next transaction number.

@since 2.5.0

# File lib/mongo/session.rb, line 255
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 175
def process(result)
  unless implicit_session?
    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 231
def retry_writes?
  !!client.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 243
def session_id
  @server_session.session_id if @server_session
end

validate!(client) click to toggle source

Validate the session.

@example

session.validate!(client)

@param [ Client ] client The client 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 160
def validate!(client)
  check_matching_client!(client)
  check_if_ended!
end

Private Instance Methods

causal_consistency?() click to toggle source

# File lib/mongo/session.rb, line 269
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 261
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 297
def check_if_ended!
  raise Mongo::Error::InvalidSession.new(SESSION_ENDED_ERROR_MSG) if ended?
end

check_matching_client!(client) click to toggle source

# File lib/mongo/session.rb, line 301
def check_matching_client!(client)
  if @client != client
    raise Mongo::Error::InvalidSession.new(MISMATCHED_CLUSTER_ERROR_MSG)
  end
end

implicit_session?() click to toggle source

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

set_cluster_time(result) click to toggle source

# File lib/mongo/session.rb, line 287
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 281
def set_operation_time(result)
  if result && result.operation_time
    @operation_time = result.operation_time
  end
end