Module: Mongo::CursorHost

Included in:
Mongo::Collection::View::Iterable, Database::View, Index::View
Defined in:
lib/mongo/cursor_host.rb

Overview

A shared concern implementing settings and configuration for entities that “host” (or spawn) cursors.

The class or module that includes this concern must implement:

* timeout_ms -- this must return either the operation level timeout_ms
    (if set) or an inherited timeout_ms from a hierarchically higher
    level (if any).

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#cursor ⇒ nil | Cursor (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the cursor associated with this view, if any.

Returns:

  • (nil | Cursor) —

    The cursor, if any.



17
18
19
 
# File 'lib/mongo/cursor_host.rb', line 17

def cursor
  @cursor
end

#timeout_mode ⇒ :cursor_lifetime | :iteration (readonly)

Returns The timeout mode to be used by this object.

Returns:

  • (:cursor_lifetime | :iteration) —

    The timeout mode to be used by this object.



21
22
23
 
# File 'lib/mongo/cursor_host.rb', line 21

def timeout_mode
  @timeout_mode
end

Instance Method Details

#validate_timeout_mode!(options, forbid: []) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Ensure the timeout mode is appropriate for other options that have been given.

Parameters:

  • options (Hash) —

    The options to inspect.

  • forbid (Array<Symbol>) (defaults to: []) —

    The list of options to forbid for this class.

Raises:

  • (ArgumentError) —

    if inconsistent or incompatible options are detected.



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/mongo/cursor_host.rb', line 34

def validate_timeout_mode!(options, forbid: [])
  forbid.each do |key|
    raise ArgumentError, "#{key} is not allowed here" if options.key?(key)
  end

  cursor_type = options[:cursor_type]
  timeout_mode = options[:timeout_mode]

  if timeout_ms
    # "Tailable cursors only support the ITERATION value for the
    # timeoutMode option. This is the default value and drivers MUST
    # error if the option is set to CURSOR_LIFETIME."
    if cursor_type
      timeout_mode ||= :iteration
      if timeout_mode == :cursor_lifetime
        raise ArgumentError, 'tailable cursors only support `timeout_mode: :iteration`'
      end
    else
      # "For non-tailable cursors, the default value of timeoutMode
      # is CURSOR_LIFETIME."
      timeout_mode ||= :cursor_lifetime
    end

    # "Drivers MUST error if [the maxAwaitTimeMS] option is set,
    # timeoutMS is set to a non-zero value, and maxAwaitTimeMS is
    # greater than or equal to timeoutMS."
    max_await_time_ms = options[:max_await_time_ms] || 0
    if max_await_time_ms.positive? && max_await_time_ms >= timeout_ms
      raise ArgumentError, ':max_await_time_ms must not be >= :timeout_ms'
    end
  elsif timeout_mode
    # "Drivers MUST error if timeoutMode is set and timeoutMS is not."
    raise ArgumentError, ':timeout_ms must be set if :timeout_mode is set'
  end

  if timeout_mode == :iteration && respond_to?(:write?) && write?
    raise ArgumentError, 'timeout_mode=:iteration is not supported for aggregation pipelines with $out or $merge'
  end

  # set it as an instance variable, rather than updating the options,
  # because if the cursor type changes (e.g. via #configure()), the new
  # View instance must be able to select a different default timeout_mode
  # if no timeout_mode was set initially.
  @timeout_mode = timeout_mode
end