Class: Mongo::Retryable::ReadWorker Private

Do not use. This class is for internal use only.

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `BaseWorker`, Forwardable
Instance Chain: self, `BaseWorker`
Inherits:	Mongo::Retryable::BaseWorker Object Mongo::Retryable::BaseWorker Mongo::Retryable::ReadWorker
Defined in:	lib/mongo/retryable/read_worker.rb

Overview

Implements the logic around retrying read operations.

Since:

2.19.0

Class Method Summary

`BaseWorker` - Inherited

.new	Constructs a new worker.

Instance Attribute Summary

Instance Method Summary

#read_with_one_retry(options = nil) { ... } ⇒ Result Internal use only

Execute a read operation with a single retry on network errors.
#read_with_retry(session = nil, server_selector = nil, &block) ⇒ Result Internal use only

Execute a read operation with retrying.
#read_with_retry_cursor(session, server_selector, view, &block) ⇒ Cursor Internal use only

Execute a read operation returning a cursor with retrying.
#deprecated_legacy_read_with_retry(&block) ⇒ Result private Internal use only

Attempts to do a legacy read_with_retry, without either a session or server_selector.
#legacy_read_with_retry(session, server_selector, &block) ⇒ Result private Internal use only

Attempts to do a “legacy” read with retry.
#modern_read_with_retry(session, server_selector, &block) ⇒ Result private Internal use only

Attempts to do a “modern” read with retry.
#read_without_retry(session, server_selector, &block) ⇒ Result private Internal use only

Attempts to do a read without a retry; for example, when retries have been explicitly disabled.
#retry_read(original_error, session, server_selector, failed_server: nil, &block) ⇒ Result private Internal use only

The retry logic of the “modern” read_with_retry implementation.

`BaseWorker` - Inherited

#deprecation_warning	Logs the given deprecation warning the first time it is called for a given key; after that, it does nothing when given the same key.
#is_retryable_exception?	Tests to see if the given exception instance is of a type that can be retried.
#log_retry	Log a warning so that any application slow down is immediately obvious.
#retryable_exceptions	Indicate which exception classes that are generally retryable.

Instance Method Details

#deprecated_legacy_read_with_retry(&block) ⇒ `Result` (private)

Attempts to do a legacy read_with_retry, without either a session or server_selector. This is a deprecated use-case, and a warning will be issued the first time this is invoked.

Parameters:

block (Proc) —

The block to execute.

Returns:

(Result) —

The result of the operation.

Since:

2.19.0

[ GitHub ]

# File 'lib/mongo/retryable/read_worker.rb', line 168


def deprecated_legacy_read_with_retry(&block)
  deprecation_warning :read_with_retry,
    'Legacy read_with_retry invocation - ' \
    'please update the application and/or its dependencies'

  # Since we don't have a session, we cannot use the modern read retries.
  # And we need to select a server but we don't have a server selector.
  # Use PrimaryPreferred which will work as long as there is a data
  # bearing node in the cluster; the block may select a different server
  # which is fine.
  server_selector = ServerSelector.get(mode: :primary_preferred)
  legacy_read_with_retry(nil, server_selector, &block)
end

#legacy_read_with_retry(session, server_selector, &block) ⇒ `Result` (private)

Attempts to do a “legacy” read with retry. The operation will be attempted multiple times, up to the client’s ‘max_read_retries` setting.

Parameters:

session (Mongo::Session) —

The session that the operation is being run on.
server_selector (Mongo::ServerSelector::Selectable) —

::Mongo::Server selector for the operation.
block (Proc) —

The block to execute.

Returns:

(Result) —

The result of the operation.

Since:

2.19.0

[ GitHub ]

# File 'lib/mongo/retryable/read_worker.rb', line 213


def legacy_read_with_retry(session, server_selector, &block)
  attempt = attempt ? attempt + 1 : 1
  yield select_server(cluster, server_selector, session)
rescue *retryable_exceptions, Error::OperationFailure, Error::PoolError => e
  e.add_notes('legacy retry', "attempt #{attempt}")
  
  if is_retryable_exception?(e)
    raise e if attempt > client.max_read_retries || session&.in_transaction?
  elsif e.retryable? && !session&.in_transaction?
    raise e if attempt > client.max_read_retries
  else
    raise e
  end
  
  log_retry(e, message: 'Legacy read retry')
  sleep(client.read_retry_interval) unless is_retryable_exception?(e)
  retry
end

#modern_read_with_retry(session, server_selector, &block) ⇒ `Result` (private)

Attempts to do a “modern” read with retry. Only a single retry will be attempted.

Parameters:

session (Mongo::Session) —

The session that the operation is being run on.
server_selector (Mongo::ServerSelector::Selectable) —

::Mongo::Server selector for the operation.
block (Proc) —

The block to execute.

Returns:

(Result) —

The result of the operation.

Since:

2.19.0

[ GitHub ]

# File 'lib/mongo/retryable/read_worker.rb', line 192


def modern_read_with_retry(session, server_selector, &block)
  server = select_server(cluster, server_selector, session)
  yield server
rescue *retryable_exceptions, Error::OperationFailure, Auth::Unauthorized, Error::PoolError => e
  e.add_notes('modern retry', 'attempt 1')
  raise e if session.in_transaction?
  raise e if !is_retryable_exception?(e) && !e.write_retryable?
  retry_read(e, session, server_selector, failed_server: server, &block)
end

#read_with_one_retry(options = nil) { ... } ⇒ `Result`

Note:

This only retries read operations on socket errors.

Execute a read operation with a single retry on network errors.

This method is used by the driver for some of the internal housekeeping operations. Application-requested reads should use read_with_retry rather than this method.

Examples:

Execute the read.

read_with_one_retry do
  ...
end

Parameters:

options (Hash | nil) (defaults to: nil) —

::Mongo::Options.

Options Hash (options):

:retry_message (String) —

Message to log when retrying.

Yields:

Calls the provided block with no arguments

Returns:

(Result) —

The result of the operation.

Since:

2.2.6

[ GitHub ]

# File 'lib/mongo/retryable/read_worker.rb', line 149


def read_with_one_retry(options = nil)
  yield
rescue *retryable_exceptions, Error::PoolError => e
  raise e unless e.write_retryable?

  retry_message = options && options[:retry_message]
  log_retry(e, message: retry_message)
  yield
end

#read_with_retry(session = nil, server_selector = nil, &block) ⇒ `Result`

Execute a read operation with retrying.

This method performs server selection for the specified server selector and yields to the provided block, which should execute the initial query operation and return its result. The block will be passed the server selected for the operation. If the block raises an exception, and this exception corresponds to a read retryable error, and read retries are enabled for the client, this method will perform server selection again and yield to the block again (with potentially a different server). If the block returns successfully, the result of the block is returned.

If modern retry reads are on (which is the default), the initial read operation will be retried once. If legacy retry reads are on, the initial read operation will be retried zero or more times depending on the :max_read_retries client setting, the default for which is 1. To disable read retries, turn off modern read retries by setting retry_reads: false and set :max_read_retries to 0 on the client.

Examples:

Execute the read.

read_with_retry(session, server_selector) do |server|
  ...
end

Parameters:

session (Mongo::Session | nil) (defaults to: nil) —

The session that the operation is being run on.
server_selector (Mongo::ServerSelector::Selectable | nil) (defaults to: nil) —

::Mongo::Server selector for the operation.
block (Proc) —

The block to execute.

Returns:

(Result) —

The result of the operation.

Since:

2.19.0

[ GitHub ]

# File 'lib/mongo/retryable/read_worker.rb', line 113


def read_with_retry(session = nil, server_selector = nil, &block)
  if session.nil? && server_selector.nil?
    deprecated_legacy_read_with_retry(&block)
  elsif session&.retry_reads?
    modern_read_with_retry(session, server_selector, &block)
  elsif client.max_read_retries > 0
    legacy_read_with_retry(session, server_selector, &block)
  else
    read_without_retry(session, server_selector, &block)
  end
end

#read_with_retry_cursor(session, server_selector, view, &block) ⇒ Cursor

Execute a read operation returning a cursor with retrying.

Examples:

Execute a read returning a cursor.

cursor = read_with_retry_cursor(session, server_selector, view) do |server|
  # return a Mongo::Operation::Result
  ...
end

Parameters:

session (Mongo::Session) —

The session that the operation is being run on.
server_selector (Mongo::ServerSelector::Selectable) —

::Mongo::Server selector for the operation.
view (CollectionView) —

The CollectionView defining the query.
block (Proc) —

The block to execute.

Returns:

(Cursor) —

The cursor for the result set.

Since:

2.19.0

[ GitHub ]

# File 'lib/mongo/retryable/read_worker.rb', line 66


def read_with_retry_cursor(session, server_selector, view, &block)
  read_with_retry(session, server_selector) do |server|
    result = yield server

    # RUBY-2367: This will be updated to allow the query cache to
    # cache cursors with multi-batch results.
    if QueryCache.enabled? && !view.collection.system_collection?
      CachingCursor.new(view, result, server, session: session)
    else
      Cursor.new(view, result, server, session: session)
    end
  end
end

#read_without_retry(session, server_selector, &block) ⇒ `Result` (private)

Attempts to do a read without a retry; for example, when retries have been explicitly disabled.

Parameters:

session (Mongo::Session) —

The session that the operation is being run on.
server_selector (Mongo::ServerSelector::Selectable) —

::Mongo::Server selector for the operation.
block (Proc) —

The block to execute.

Returns:

(Result) —

The result of the operation.

Since:

2.19.0

[ GitHub ]

# File 'lib/mongo/retryable/read_worker.rb', line 242


def read_without_retry(session, server_selector, &block)
  server = select_server(cluster, server_selector, session)

  begin
    yield server
  rescue *retryable_exceptions, Error::PoolError, Error::OperationFailure => e
    e.add_note('retries disabled')
    raise e
  end
end

#retry_read(original_error, session, server_selector, failed_server: nil, &block) ⇒ `Result` (private)

The retry logic of the “modern” read_with_retry implementation.

Parameters:

original_error (Exception) —

The original error that triggered the retry.
session (Mongo::Session) —

The session that the operation is being run on.
server_selector (Mongo::ServerSelector::Selectable) —

::Mongo::Server selector for the operation.
failed_server (Mongo::Server) —

The server on which the original operation failed.
block (Proc) —

The block to execute.

Returns:

(Result) —

The result of the operation.

Since:

2.19.0

[ GitHub ]

# File 'lib/mongo/retryable/read_worker.rb', line 266


def retry_read(original_error, session, server_selector, failed_server: nil, &block)
  begin
    server = select_server(cluster, server_selector, session, failed_server)
  rescue Error, Error::AuthError => e
    original_error.add_note("later retry failed: #{e.class}: #{e}")
    raise original_error
  end
  
  log_retry(original_error, message: 'Read retry')
  
  begin
    yield server, true
  rescue *retryable_exceptions => e
    e.add_notes('modern retry', 'attempt 2')
    raise e
  rescue Error::OperationFailure, Error::PoolError => e
    e.add_note('modern retry')
    unless e.write_retryable?
      original_error.add_note("later retry failed: #{e.class}: #{e}")
      raise original_error
    end
    e.add_note("attempt 2")
    raise e
  rescue Error, Error::AuthError => e
    e.add_note('modern retry')
    original_error.add_note("later retry failed: #{e.class}: #{e}")
    raise original_error
  end
end

Class: Mongo::Retryable::ReadWorker Private

Overview

Class Method Summary

BaseWorker - Inherited

Instance Attribute Summary

BaseWorker - Inherited

Instance Method Summary

BaseWorker - Inherited

Instance Method Details

#deprecated_legacy_read_with_retry(&block) ⇒ Result (private)

#legacy_read_with_retry(session, server_selector, &block) ⇒ Result (private)

#modern_read_with_retry(session, server_selector, &block) ⇒ Result (private)

#read_with_one_retry(options = nil) { ... } ⇒ Result

#read_with_retry(session = nil, server_selector = nil, &block) ⇒ Result

#read_with_retry_cursor(session, server_selector, view, &block) ⇒ Cursor

#read_without_retry(session, server_selector, &block) ⇒ Result (private)

#retry_read(original_error, session, server_selector, failed_server: nil, &block) ⇒ Result (private)

`BaseWorker` - Inherited

`BaseWorker` - Inherited

`BaseWorker` - Inherited

#deprecated_legacy_read_with_retry(&block) ⇒ `Result` (private)

#legacy_read_with_retry(session, server_selector, &block) ⇒ `Result` (private)

#modern_read_with_retry(session, server_selector, &block) ⇒ `Result` (private)

#read_with_one_retry(options = nil) { ... } ⇒ `Result`

#read_with_retry(session = nil, server_selector = nil, &block) ⇒ `Result`

#read_without_retry(session, server_selector, &block) ⇒ `Result` (private)

#retry_read(original_error, session, server_selector, failed_server: nil, &block) ⇒ `Result` (private)