mongoid 7.5.3 → 8.1.2

data/lib/mongoid/contextual/memory.rb

@@ -25,7 +25,7 @@ module Mongoid
       #
       # @param [ Array ] other The other array.
       #
-      # @return [ true, false ] If the objects are equal.
+      # @return [ true | false ] If the objects are equal.
       def ==(other)
         return false unless other.respond_to?(:entries)
         entries == other.entries
@@ -74,7 +74,7 @@ module Mongoid
       # @example Get the distinct values.
       #   context.distinct(:name)
       #
-      # @param [ String, Symbol ] field The name of the field.
+      # @param [ String | Symbol ] field The name of the field.
       #
       # @return [ Array<Object> ] The distinct values for the field.
       def distinct(field)
@@ -110,9 +110,24 @@ module Mongoid
       # @example Do any documents exist for the context.
       #   context.exists?
       #
-      # @return [ true, false ] If the count is more than zero.
-      def exists?
-        count > 0
+      # @example Do any documents exist for given _id.
+      #   context.exists?(BSON::ObjectId(...))
+      #
+      # @example Do any documents exist for given conditions.
+      #   context.exists?(name: "...")
+      #
+      # @param [ Hash | Object | false ] id_or_conditions an _id to
+      #   search for, a hash of conditions, nil or false.
+      #
+      # @return [ true | false ] If the count is more than zero.
+      #   Always false if passed nil or false.
+      def exists?(id_or_conditions = :none)
+        case id_or_conditions
+        when :none then any?
+        when nil, false then false
+        when Hash then Memory.new(criteria.where(id_or_conditions)).exists?
+        else Memory.new(criteria.where(_id: id_or_conditions)).exists?
+        end
       end
 
       # Get the first document in the database for the criteria's selector.
@@ -120,20 +135,33 @@ module Mongoid
       # @example Get the first document.
       #   context.first
       #
-      # @param [ Integer | Hash ] limit_or_opts The number of documents to
-      #   return, or a hash of options.
+      # @param [ Integer ] limit The number of documents to return.
       #
       # @return [ Document ] The first document.
-      def first(limit_or_opts = nil)
-        if limit_or_opts.nil? || limit_or_opts.is_a?(Hash)
-          eager_load([documents.first]).first
+      def first(limit = nil)
+        if limit
+          eager_load(documents.first(limit))
         else
-          eager_load(documents.first(limit_or_opts))
+          eager_load([documents.first]).first
         end
       end
       alias :one :first
       alias :find_first :first
 
+      # Get the first document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the first document.
+      #   context.first!
+      #
+      # @return [ Document ] The first document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def first!
+        first || raise_document_not_found_error
+      end
+
       # Create the new in memory context.
       #
       # @example Create the new context.
@@ -170,52 +198,29 @@ module Mongoid
       # @example Get the last document.
       #   context.last
       #
-      # @param [ Integer | Hash ] limit_or_opts The number of documents to
-      #   return, or a hash of options.
-      #
-      # @option limit_or_opts [ :none ] :id_sort This option is deprecated.
-      #   Don't apply a sort on _id if no other sort is defined on the criteria.
+      # @param [ Integer ] limit The number of documents to return.
       #
       # @return [ Document ] The last document.
-      def last(limit_or_opts = nil)
-        if limit_or_opts.nil? || limit_or_opts.is_a?(Hash)
-          eager_load([documents.last]).first
-        else
-          eager_load(documents.last(limit_or_opts))
-        end
-      end
-
-      # Take the given number of documents from the database.
-      #
-      # @example Take a document.
-      #   context.take
-      #
-      # @param [ Integer | nil ] limit The number of documents to take or nil.
-      #
-      # @return [ Document ] The document.
-      def take(limit = nil)
+      def last(limit = nil)
         if limit
-          eager_load(documents.take(limit))
+          eager_load(documents.last(limit))
         else
-          eager_load([documents.first]).first
+          eager_load([documents.last]).first
         end
       end
 
-      # Take the given number of documents from the database.
+      # Get the last document in the database for the criteria's selector or
+      # raise an error if none is found.
       #
-      # @example Take a document.
-      #   context.take
+      # @example Get the last document.
+      #   context.last!
       #
-      # @return [ Document ] The document.
+      # @return [ Document ] The last document.
       #
       # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
-      def take!
-        if documents.empty?
-          raise Errors::DocumentNotFound.new(klass, nil, nil)
-        else
-          eager_load([documents.first]).first
-        end
+      def last!
+        last || raise_document_not_found_error
       end
 
       # Get the length of matching documents in the context.
@@ -236,28 +241,44 @@ module Mongoid
       #
       # @param [ Integer ] value The number of documents to return.
       #
-      # @return [ Mongo ] The context.
+      # @return [ Memory ] The context.
       def limit(value)
         self.limiting = value
         self
       end
 
+      # Pluck the field values in memory.
+      #
+      # @example Get the values in memory.
+      #   context.pluck(:name)
+      #
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pluck.
+      #
+      # @return [ Array<Object> | Array<Array<Object>> ] The plucked values.
       def pluck(*fields)
         if Mongoid.legacy_pluck_distinct
           documents.pluck(*fields)
         else
-          documents.map do |d|
-            if fields.length == 1
-              retrieve_value_at_path(d, fields.first)
-            else
-              fields.map do |field|
-                retrieve_value_at_path(d, field)
-              end
-            end
+          documents.map do |doc|
+            pluck_from_doc(doc, *fields)
           end
         end
       end
 
+      # Pick the field values in memory.
+      #
+      # @example Get the values in memory.
+      #   context.pick(:name)
+      #
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pick.
+      #
+      # @return [ Object | Array<Object> ] The picked values.
+      def pick(*fields)
+        if doc = documents.first
+          pluck_from_doc(doc, *fields)
+        end
+      end
+
       # Tally the field values in memory.
       #
       # @example Get the counts of values in memory.
@@ -274,6 +295,36 @@ module Mongoid
         end
       end
 
+      # Take the given number of documents from the database.
+      #
+      # @example Take a document.
+      #   context.take
+      #
+      # @param [ Integer | nil ] limit The number of documents to take or nil.
+      #
+      # @return [ Document ] The document.
+      def take(limit = nil)
+        if limit
+          eager_load(documents.take(limit))
+        else
+          eager_load([documents.first]).first
+        end
+      end
+
+      # Take the given number of documents from the database or raise an error
+      # if none are found.
+      #
+      # @example Take a document.
+      #   context.take
+      #
+      # @return [ Document ] The document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def take!
+        take || raise_document_not_found_error
+      end
+
       # Skips the provided number of documents.
       #
       # @example Skip the documents.
@@ -281,7 +332,7 @@ module Mongoid
       #
       # @param [ Integer ] value The number of documents to skip.
       #
-      # @return [ Mongo ] The context.
+      # @return [ Memory ] The context.
       def skip(value)
         self.skipping = value
         self
@@ -295,7 +346,7 @@ module Mongoid
       # @param [ Hash ] values The sorting values as field/direction(1/-1)
       #   pairs.
       #
-      # @return [ Mongo ] The context.
+      # @return [ Memory ] The context.
       def sort(values)
         in_place_sort(values) and self
       end
@@ -307,7 +358,7 @@ module Mongoid
       #
       # @param [ Hash ] attributes The new attributes for the document.
       #
-      # @return [ nil, false ] False if no attributes were provided.
+      # @return [ nil | false ] False if no attributes were provided.
       def update(attributes = nil)
         update_documents(attributes, [ first ])
       end
@@ -319,11 +370,167 @@ module Mongoid
       #
       # @param [ Hash ] attributes The new attributes for each document.
       #
-      # @return [ nil, false ] False if no attributes were provided.
+      # @return [ nil | false ] False if no attributes were provided.
       def update_all(attributes = nil)
         update_documents(attributes, entries)
       end
 
+      # Get the second document in the database for the criteria's selector.
+      #
+      # @example Get the second document.
+      #   context.second
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The second document.
+      def second
+        eager_load([documents.second]).first
+      end
+
+      # Get the second document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the second document.
+      #   context.second!
+      #
+      # @return [ Document ] The second document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def second!
+        second || raise_document_not_found_error
+      end
+
+      # Get the third document in the database for the criteria's selector.
+      #
+      # @example Get the third document.
+      #   context.third
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The third document.
+      def third
+        eager_load([documents.third]).first
+      end
+
+      # Get the third document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the third document.
+      #   context.third!
+      #
+      # @return [ Document ] The third document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def third!
+        third || raise_document_not_found_error
+      end
+
+      # Get the fourth document in the database for the criteria's selector.
+      #
+      # @example Get the fourth document.
+      #   context.fourth
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The fourth document.
+      def fourth
+        eager_load([documents.fourth]).first
+      end
+
+      # Get the fourth document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the fourth document.
+      #   context.fourth!
+      #
+      # @return [ Document ] The fourth document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def fourth!
+        fourth || raise_document_not_found_error
+      end
+
+      # Get the fifth document in the database for the criteria's selector.
+      #
+      # @example Get the fifth document.
+      #   context.fifth
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The fifth document.
+      def fifth
+        eager_load([documents.fifth]).first
+      end
+
+      # Get the fifth document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the fifth document.
+      #   context.fifth!
+      #
+      # @return [ Document ] The fifth document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def fifth!
+        fifth || raise_document_not_found_error
+      end
+
+      # Get the second to last document in the database for the criteria's selector.
+      #
+      # @example Get the second to last document.
+      #   context.second_to_last
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The second to last document.
+      def second_to_last
+        eager_load([documents.second_to_last]).first
+      end
+
+      # Get the second to last document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the second to last document.
+      #   context.second_to_last!
+      #
+      # @return [ Document ] The second to last document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def second_to_last!
+        second_to_last || raise_document_not_found_error
+      end
+
+      # Get the third to last document in the database for the criteria's selector.
+      #
+      # @example Get the third to last document.
+      #   context.third_to_last
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The third to last document.
+      def third_to_last
+        eager_load([documents.third_to_last]).first
+      end
+
+      # Get the third to last document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the third to last document.
+      #   context.third_to_last!
+      #
+      # @return [ Document ] The third to last document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def third_to_last!
+        third_to_last || raise_document_not_found_error
+      end
+
       private
 
       # Get the documents the context should iterate. This follows 3 rules:
@@ -546,6 +753,26 @@ module Mongoid
           retrieve_value_at_path(curr, remaining)
         end
       end
+
+      # Pluck the field values from the given document.
+      #
+      # @param [ Document ] doc The document to pluck from.
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pluck.
+      #
+      # @return [ Object | Array<Object> ] The plucked values.
+      def pluck_from_doc(doc, *fields)
+        if fields.length == 1
+          retrieve_value_at_path(doc, fields.first)
+        else
+          fields.map do |field|
+            retrieve_value_at_path(doc, field)
+          end
+        end
+      end
+
+      def raise_document_not_found_error
+        raise Errors::DocumentNotFound.new(klass, nil, nil)
+      end
     end
   end
 end

data/lib/mongoid/contextual/mongo/documents_loader.rb

@@ -0,0 +1,177 @@
+require "mongoid/association/eager_loadable"
+
+module Mongoid
+  module Contextual
+    class Mongo
+      # Loads documents for the provided criteria.
+      #
+      # @api private
+      class DocumentsLoader
+        extend Forwardable
+        include Association::EagerLoadable
+
+        def_delegators :@future, :value!, :value, :wait!, :wait
+
+        # Returns synchronous executor to be used when async_query_executor config option
+        # is set to :immediate. This executor runs all operations on the current
+        # thread, blocking as necessary.
+        #
+        # @return [ Concurrent::ImmediateExecutor ] The executor
+        #   to be used to execute document loading tasks.
+        def self.immediate_executor
+          @@immediate_executor ||= Concurrent::ImmediateExecutor.new
+        end
+
+        # Returns asynchronous executor to be used when async_query_executor config option
+        # is set to :global_thread_pool. This executor runs operations on background threads
+        # using a thread pool.
+        #
+        # @return [ Concurrent::ThreadPoolExecutor ] The executor
+        #   to be used to execute document loading tasks.
+        def self.global_thread_pool_async_query_executor
+          create_pool = Proc.new do |concurrency|
+            Concurrent::ThreadPoolExecutor.new(
+              min_threads: 0,
+              max_threads: concurrency,
+              max_queue: concurrency * 4,
+              fallback_policy: :caller_runs
+            )
+          end
+          concurrency = Mongoid.global_executor_concurrency || 4
+          @@global_thread_pool_async_query_executor ||= create_pool.call(concurrency)
+          if @@global_thread_pool_async_query_executor.max_length != concurrency
+            old_pool = @@global_thread_pool_async_query_executor
+            @@global_thread_pool_async_query_executor = create_pool.call(concurrency)
+            old_pool.shutdown
+          end
+          @@global_thread_pool_async_query_executor
+        end
+
+        # Returns suitable executor according to Mongoid config options.
+        #
+        # @param [ String | Symbol] name The query executor name, can be either
+        #   :immediate or :global_thread_pool. Defaulted to `async_query_executor`
+        #   config option.
+        #
+        # @return [ Concurrent::ImmediateExecutor | Concurrent::ThreadPoolExecutor ] The executor
+        #   to be used to execute document loading tasks.
+        #
+        # @raise [ Errors::InvalidQueryExecutor ] If an unknown name is provided.
+        def self.executor(name = Mongoid.async_query_executor)
+          case name.to_sym
+          when :immediate
+            immediate_executor
+          when :global_thread_pool
+            global_thread_pool_async_query_executor
+          else
+            raise Errors::InvalidQueryExecutor.new(name)
+          end
+        end
+
+        # @return [ Mongoid::Criteria ] Criteria that specifies which documents should
+        #   be loaded. Exposed here because `eager_loadable?` method from
+        #   `Association::EagerLoadable` expects this to be available.
+        attr_accessor :criteria
+
+        # Instantiates the document loader instance and immediately schedules
+        # its execution using the provided executor.
+        #
+        # @param [ Mongo::Collection::View ] view The collection view to get
+        #   records from the database.
+        # @param [ Class ] klass Mongoid model class to instantiate documents.
+        #   All records obtained from the database will be converted to an
+        #   instance of this class, if possible.
+        # @param [ Mongoid::Criteria ] criteria. Criteria that specifies which
+        #   documents should be loaded.
+        # @param [ Concurrent::AbstractExecutorService ] executor. Executor that
+        #   is capable of running `Concurrent::Promises::Future` instances.
+        def initialize(view, klass, criteria, executor: self.class.executor)
+          @view = view
+          @klass = klass
+          @criteria = criteria
+          @mutex = Mutex.new
+          @state = :pending
+          @future = Concurrent::Promises.future_on(executor) do
+            start && execute
+          end
+        end
+
+        # Returns false or true whether the loader is in pending state.
+        #
+        # Pending state means that the loader execution has been scheduled,
+        # but has not been started yet.
+        #
+        # @return [ true | false ] true if the loader is in pending state,
+        #   otherwise false.
+        def pending?
+          @mutex.synchronize do
+            @state == :pending
+          end
+        end
+
+        # Returns false or true whether the loader is in started state.
+        #
+        # Started state means that the loader execution has been started.
+        # Note that the loader stays in this state even after the execution
+        # completed (successfully or failed).
+        #
+        # @return [ true | false ] true if the loader is in started state,
+        #   otherwise false.
+        def started?
+          @mutex.synchronize do
+            @state == :started
+          end
+        end
+
+        # Mark the loader as unscheduled.
+        #
+        # If the loader is marked unscheduled, it will not be executed. The only
+        # option to load the documents is to call `execute` method directly.
+        #
+        # Please note that if execution of a task has been already started,
+        # unscheduling does not have any effect.
+        def unschedule
+          @mutex.synchronize do
+            @state = :cancelled unless @state == :started
+          end
+        end
+
+        # Loads records specified by `@criteria` from the database, and convert
+        # them to Mongoid documents of `@klass` type.
+        #
+        # This method is called by the task (possibly asynchronous) scheduled
+        # when creating an instance of the loader. However, this method can be
+        # called directly, if it is desired to execute loading on the caller
+        # thread immediately.
+        #
+        # Calling this method does not change the state of the loader.
+        #
+        # @return [ Array<Mongoid::Document> ] Array of document loaded from
+        #   the database.
+        def execute
+          documents = @view.map do |doc|
+            Factory.from_db(@klass, doc, @criteria)
+          end
+          eager_load(documents) if eager_loadable?
+          documents
+        end
+
+        private
+
+        # Mark the loader as started if possible.
+        #
+        # @return [ true | false ] Whether the state was changed to :started.
+        def start
+          @mutex.synchronize do
+            if @state == :pending
+              @state = :started
+              true
+            else
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end