Class: Mongo::Session

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/mongo/session.rb,
lib/mongo/session/session_pool.rb,
lib/mongo/session/server_session.rb

Overview

A logical session representing a set of sequential operations executed

by an application that are related in some way.

Since:

  • 2.5.0

Defined Under Namespace

Classes: ServerSession, SessionPool

Constant Summary

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

'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.

Since:

  • 2.5.0

'This session has ended and cannot be used. Please create a new one.'.freeze
SESSIONS_NOT_SUPPORTED =

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

Since:

  • 2.5.0

'Sessions are not supported by the connected servers.'.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(server_session, cluster, options = {}) ⇒ Session

Initialize a Session.

Examples:

Session.new(server_session, cluster, options)

Parameters:

  • server_session (ServerSession)

    The server session this session is associated with.

  • cluster (Cluster)

    The cluster through which this session is created.

  • options (Hash) (defaults to: {})

    The options for this session.

Since:

  • 2.5.0



75
76
77
78
79
80
# 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

Instance Attribute Details

#clusterObject (readonly)

Get the cluster through which this session was created.

Since:

  • 2.5.1



35
36
37
# File 'lib/mongo/session.rb', line 35

def cluster
  @cluster
end

#cluster_timeObject (readonly)

The cluster time for this session.

Since:

  • 2.5.0



40
41
42
# File 'lib/mongo/session.rb', line 40

def cluster_time
  @cluster_time
end

#operation_timeObject (readonly)

The latest seen operation time for this session.

Since:

  • 2.5.0



45
46
47
# File 'lib/mongo/session.rb', line 45

def operation_time
  @operation_time
end

#optionsObject (readonly)

Get the options for this session.

Since:

  • 2.5.0



30
31
32
# File 'lib/mongo/session.rb', line 30

def options
  @options
end

Instance Method Details

#add_id!(command) ⇒ Hash, BSON::Document

Add this session's id to a command document.

Examples:

session.add_id!(cmd)

Returns:

  • (Hash, BSON::Document)

    The command document.

Since:

  • 2.5.0



130
131
132
# File 'lib/mongo/session.rb', line 130

def add_id!(command)
  command.merge!(lsid: session_id)
end

#advance_cluster_time(new_cluster_time) ⇒ BSON::Document, Hash

Advance the cached cluster time document for this session.

Examples:

Advance the cluster time.

session.advance_cluster_time(doc)

Parameters:

  • new_cluster_time (BSON::Document, Hash)

    The new cluster time.

Returns:

  • (BSON::Document, Hash)

    The new cluster time.

Since:

  • 2.5.0



181
182
183
184
185
186
187
# 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) ⇒ BSON::Timestamp

Advance the cached operation time for this session.

Examples:

Advance the operation time.

session.advance_operation_time(timestamp)

Parameters:

  • new_operation_time (BSON::Timestamp)

    The new operation time.

Returns:

  • (BSON::Timestamp)

    The max operation time, considering the current and new times.

Since:

  • 2.5.0



199
200
201
202
203
204
205
# 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_sessionnil

End this session.

Examples:

session.end_session

Returns:

  • (nil)

    Always nil.

Since:

  • 2.5.0



102
103
104
105
106
107
108
# 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?true, false

Whether this session has ended.

Examples:

session.ended?

Returns:

  • (true, false)

    Whether the session has ended.

Since:

  • 2.5.0



118
119
120
# File 'lib/mongo/session.rb', line 118

def ended?
  @server_session.nil?
end

#implicit?true, false

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

Examples:

Is the session implicit?

session.implicit?

Returns:

  • (true, false)

    Whether this session is implicit.

Since:

  • 2.5.1



254
255
256
# File 'lib/mongo/session.rb', line 254

def implicit?
  @implicit_session ||= !!(@options.key?(:implicit) && @options[:implicit] == true)
end

#inspectString

Get a formatted string for use in inspection.

Examples:

Inspect the session object.

session.inspect

Returns:

  • (String)

    The session inspection.

Since:

  • 2.5.0



90
91
92
# File 'lib/mongo/session.rb', line 90

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

#next_txn_numInteger

Increment and return the next transaction number.

Examples:

Get the next transaction number.

session.next_txn_num

Returns:

  • (Integer)

    The next transaction number.

Since:

  • 2.5.0



242
243
244
# File 'lib/mongo/session.rb', line 242

def next_txn_num
  @server_session.next_txn_num if @server_session
end

#process(result) ⇒ Operation::Result

Process a response from the server that used this session.

Examples:

Process a response from the server.

session.process(result)

Parameters:

Returns:

Since:

  • 2.5.0



162
163
164
165
166
167
168
169
# 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?true, false

Note:

Retryable writes are only available on server versions at least 3.6 and with sharded clusters or replica sets.

Will writes executed with this session be retried.

Examples:

Will writes be retried.

session.retry_writes?

Returns:

  • (true, false)

    If writes will be retried.

Since:

  • 2.5.0



218
219
220
# File 'lib/mongo/session.rb', line 218

def retry_writes?
  !!cluster.options[:retry_writes] && (cluster.replica_set? || cluster.sharded?)
end

#session_idBSON::Document

Get the session id.

Examples:

Get the session id.

session.session_id

Returns:

  • (BSON::Document)

    The session id.

Since:

  • 2.5.0



230
231
232
# File 'lib/mongo/session.rb', line 230

def session_id
  @server_session.session_id if @server_session
end

#validate!(cluster) ⇒ nil

Validate the session.

Examples:

session.validate!(cluster)

Parameters:

  • cluster (Cluster)

    The cluster the session is attempted to be used with.

Returns:

  • (nil)

    nil if the session is valid.

Raises:

Since:

  • 2.5.0



146
147
148
149
150
# File 'lib/mongo/session.rb', line 146

def validate!(cluster)
  check_matching_cluster!(cluster)
  check_if_ended!
  self
end