bento_search 1.7.0.beta.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ac054c4415c845492a1e7e9c472264d242bfb0cf
-  data.tar.gz: 0f32e4789d3ad0ae264f5cbb28f448cee18c11c9
+  metadata.gz: 65bfa7da3d1e0896569d44cb7875931b92876186
+  data.tar.gz: 222147474c34a761bfc483abd5185a3b4712b6fa
 SHA512:
-  metadata.gz: 14ad5a420be09d2a01e68834e2508a93ae62eebceea84b2077e49494a6ff942b0aca46050f395bb9e3fee9f27ea400c37446c2cb89919ff44222d1dab3c955cb
-  data.tar.gz: fbeb0bc33bcac41521f642aced391f21d1e04251d0ab05417fe3ae2adb0ada71384d57956a02800a0157c47c8c597dc20028997e8f6fb84abfc6d7ca6bc3870a
+  metadata.gz: ee8d316144f84e0469c37d0784d894cda427dc8606ad736af9a0172223c5ace2a61db026fb3d44d2b586791894160dbf5fdce368ae1c5e510314b067ca66bbd0
+  data.tar.gz: 3b31f327569b5e9de6fce19da85b7d6f653dae97c9b3ace77139be4c0048a3dff992a3579b4da9b54a553870c23c4fcc681ce193f2dfe3465b7f5487be2ba3e2

data/README.md

@@ -250,12 +250,12 @@ to execute concurrently in seperate threads, so the total wait time is the slowe
 engine, not the sum of the engines.
 
 You can write your own logic using ruby threads to do this, but
-BentoSearch provides a multi-searching helper using [Celluloid](https://github.com/celluloid/celluloid)
+BentoSearch provides a multi-searching helper using [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby)
 to help you do this easily. Say, in a controller:
 
 ~~~~ruby
     # constructor takes id's registered with BentoSearch.register_engine
-    searcher = BentoSearch::MultiSearcher.new(:gbs, :scopus, :summon)
+    searcher = BentoSearch::ConcurentSearcher.new(:gbs, :scopus, :summon)
 
     # Call 'search' with any parameters you would give to an_engine.search
     searcher.search("my query", :semantic_search_field => :author, :sort => "title")
@@ -273,13 +273,22 @@ search execute in a seperate thread, so you can continue doing other work
 in the main thread (like search a local store of some kind outside of
 bento_search)
 
-You will need to add the 'celluloid' gem to your app to use this feature,
-BentoSearch doesn't automatically include the celluloid dependency. Note
-that Celluloid uses multi-threading in such a way that you might need
-to turn Rails config.cache_classes=true even in development.
+If you are using a Rails previous to 5.x, you will have to add the
+`concurrent-ruby` gem to your `Gemfile` (It's already a dependency of
+Rails5).
+
+If you are using Rails5, ConcurrentSearcher uses new Rails API that
+should make development-mode class reloading work fine even with
+the ConcurrentSearcher's concurrency.
+
+For more info, see [BentoSearch::ConcurrentSearcher](./app/models/bento_search/concurrent_searcher.rb).
+
+The previous **MultiSearcher** class is now deprecated, ConcurrentSearcher
+is the replacement, and will likely work as a drop-in replacement.
+See [CHANGES](./CHANGES.md#17) for more info.
+
 
 
-For more info, see [BentoSearch::MultiSearcher](./app/models/bento_search/multi_searcher.rb).
 
 ### Delayed results loading via AJAX (actually more like AJAHtml)
 

data/app/assets/javascripts/bento_search/ajax_load.js

@@ -1,56 +1,72 @@
 var BentoSearch = BentoSearch || {}
 
-// Pass in a DOM node that has a data-ajax-url attribute. 
+// Pass in a DOM node that has a data-ajax-url attribute.
 // Will AJAX load bento search results inside that node.
-// optional second arg success callback function. 
+//
+// optional success_callback function.
+//
+// success_callback: will have the container div as 'this', and new content
+// as first argument (in JQuery wrapper). Called before DOM update happens, so
+// first arg div is not yet placed in the DOM. Callback can
+// return `false` to prevent automatic placement in the DOM, if you want
+// to handle it yourself.
+//
+// You can set default success_callback function for all calls with:
+//
+//     BentoSearch.ajax_load.default_success_callback = function(div) { ...
 BentoSearch.ajax_load = function(node, success_callback) {
+  // default success_callback
+  if (success_callback === undefined) {
+    success_callback = BentoSearch.ajax_load.default_success_callback;
+  }
+
   var div = $(node);
-  
+
   if (div.length == 0) {
     //we've got nothing
     return
   }
-  
+
 
   // We find the "waiting"/spinner section already rendered,
   // and show it. We experimented with generating the spinner/waiting
   // purely in JS, instead of rendering a hidden one server-side. But
-  // it was too weird and unreliable to do that, sorry.   
+  // it was too weird and unreliable to do that, sorry.
   div.find(".bento_search_ajax_loading").show();
-  
-  
+
+
   // Now load the actual external content from html5 data-bento-ajax-url
   $.ajax({
-      url: div.data("bentoAjaxUrl"), 
+      url: div.data("bentoAjaxUrl"),
       success: function(response, status, xhr) {
-        var do_replace = true;         
+        var do_replace = true;
         if (success_callback) {
           // We need to make the response into a DOM so the callback
           // can deal with it better. Wrapped in a div, so it makes
-          // jquery happy even if there isn't a single parent element. 
+          // jquery happy even if there isn't a single parent element.
           response = $("<div>" + response + "</div>");
-          
-          do_replace = success_callback.apply(div, [response]);                    
+
+          do_replace = success_callback.apply(div, [response]);
         }
-        if (do_replace != false) { 
+        if (do_replace != false) {
           div.replaceWith(response);
-        }          
+        }
       },
       error: function(xhr, status, errorThrown) {
         var msg = "Sorry but there was an error: ";
         div.html(msg + xhr.status + " " + xhr.statusText + ", " + status);
       }
   });
- 
-  
+
+
 }
 
 jQuery(document).ready(function($) {
     //Intentionally wait for window.load, not just onready, to
-    //prevent interfering with rest of page load. 
-    $(window).bind("load", function() {   
+    //prevent interfering with rest of page load.
+    $(window).bind("load", function() {
         $("*[data-bento-search-load=ajax_auto]").each(function(i, div) {
-            BentoSearch.ajax_load(div);                              
+            BentoSearch.ajax_load(div);
       });
-    });    
-});
+    });
+});

data/app/helpers/bento_search_helper.rb

@@ -3,112 +3,110 @@
 require 'nokogiri'
 
 # Rails helper module provided by BentoSearch meant to be included
-# in host app's helpers. 
+# in host app's helpers.
 module BentoSearchHelper
-  
+
   # Renders bento search results on page, or an AJAX loader, etc, as appropriate.
   # Pass in:
   #   * BentoSearch::SearchResults => will render
   #   * an instantiated BentoSearch::SearchEngine => Will do search and render
-  #   * an id that a search engine was registered under with 
-  #     BentoSearch.register_engine => will do search and render. 
+  #   * an id that a search engine was registered under with
+  #     BentoSearch.register_engine => will do search and render.
   #
   #  Second arg options hash includes options for bento_search helper,
   #  as well as other options pased on to BentoSearch::Engine.search(options)
   #
+  # Partial used for display can be configured on engine with
+  #   * for_display.error_partial => gets `results` local
+  #   * for_display.no_results_partial => gets `results` local
+  #   * for_display.item_partial => `:collection => results, :as => :item, :locals => {:results => results}`
+  #   * for_display.ajax_loading_partial => local `engine`
+  #
+  # If not specified for a particular engine, the partials listed in BentoSearch.defaults will be used.
+  #
   # == Options
   #
   #  load: :ajax_auto, :immediate.  :ajax_auto will put a spinner up there,
   #        and load actual results via AJAX request. :immediate preloads
-  #        results. 
+  #        results.
   #
   # == Examples
   #
   #     bento_results( results_obj )
   #     bento_results( engine_obj, :query => "cancer")
   #     bento_results("google_books", :query => "cancer", :load => :ajax_auto)
-  #  
+  #
   def bento_search(search_arg, options = {})
-    
+
     results = search_arg if search_arg.kind_of? BentoSearch::Results
-    
-    load_mode = options.delete(:load) 
-    
+
+    load_mode = options.delete(:load)
+
     engine = nil
     unless results
-      # need to load an engine and do a search, or ajax, etc. 
+      # need to load an engine and do a search, or ajax, etc.
       engine = (if search_arg.kind_of? BentoSearch::SearchEngine
         search_arg
       else
         raise ArgumentError.new("Need Results, engine, or registered engine_id as first argument to #bento_search") unless search_arg
         BentoSearch.get_engine(search_arg.to_s)
       end)
-      
+
     end
 
     if (!results && [:ajax_auto, :ajax_triggered].include?(load_mode))
       raise ArgumentError.new("`:load => :ajax` requires a registered engine with an id") unless engine.configuration.id
       content_tag(:div,
         :class => "bento_search_ajax_wait",
-        :"data-bento-search-load" => load_mode.to_s, 
+        :"data-bento-search-load" => load_mode.to_s,
         :"data-bento-ajax-url"    => to_bento_search_url( {:engine_id => engine.configuration.id}.merge(options) )) do
-      
-      # An initially hidden div with loading msg/spinner that will be shown
-      # by js on ajax load
-      content_tag("noscript") do
-        I18n.t("bento_search.ajax_noscript")
-      end +
-      content_tag(:div, 
-        :class => "bento_search_ajax_loading", 
-        :style => "display:none") do      
-          image_tag("bento_search/large_loader.gif", 
-            :alt => I18n.translate("bento_search.ajax_loading")            
-          ) 
+
+          partial = (engine.configuration.for_display.ajax_loading_partial if engine.configuration.for_display) || BentoSearch.defaults.ajax_loading_partial
+          render :partial => partial, locals: { engine: engine }
         end
-      end
     else
       results = engine.search(options) unless results
 
       if results.failed?
-        partial = (results.display_configuration.error_partial if results.display_configuration) || "bento_search/search_error"         
+        partial = (results.display_configuration.error_partial if results.display_configuration) || BentoSearch.defaults.error_partial
         render :partial => partial, :locals => {:results => results}
-      elsif results.length > 0   
-        partial = (results.display_configuration.item_partial if results.display_configuration) || "bento_search/std_item"        
+      elsif results.length > 0
+        partial = (results.display_configuration.item_partial if results.display_configuration) || BentoSearch.defaults.item_partial
         render :partial => partial, :collection => results, :as => :item, :locals => {:results => results}
       else
         content_tag(:div, :class=> "bento_search_no_results") do
-          partial = (results.display_configuration.no_results_partial if results.display_configuration) || "bento_search/no_results"                   
+          partial = (results.display_configuration.no_results_partial if results.display_configuration) || BentoSearch.defaults.no_results_partial
           render :partial => partial, :locals => {:results => results}
         end
       end
-    end                          
+    end
   end
-  
+
   # Wrap a ResultItem in a decorator! For now hard-coded to
   # BentoSearch::StandardDecorator
-  def bento_decorate(result_item)    
+  def bento_decorate(result_item)
     # in a helper method, 'self' is a view_context already I think?
-    decorated = BentoSearch::DecoratorBase.decorate(result_item, self)    
-    yield(decorated) if block_given?    
-    return decorated    
+    decorated = BentoSearch::DecoratorBase.decorate(result_item, self)
+    yield(decorated) if block_given?
+    return decorated
   end
-    
-  
+
+
   ##
   # More methods used by bento standard views, namespaced with bento_, sorry
   # no great way to take logic out of views into helper methods without
-  # namespacey hack. 
+  # namespacey hack.
   #
   # You can use these methods in your own custom views, you also should be
   # able to over-ride them (including calling super) in local helpers to
-  # change behavior in standard views. 
+  # change behavior in standard views.
   #
   ##
-  
+
   # Like rails truncate helper, and taking the same options, but html_safe.
-  # 
-  # If input string is NOT marked html_safe?, simply passes to rails truncate helper. 
-  # If a string IS marked html_safe?, uses nokogiri to parse it, and truncate 
+  #
+  # If input string is NOT marked html_safe?, simply passes to rails truncate helper.
+  # If a string IS marked html_safe?, uses nokogiri to parse it, and truncate
   # actual displayed text to max_length, while keeping html structure valid.
   #
   # Default omission marker is unicode elipsis
@@ -118,23 +116,23 @@ module BentoSearchHelper
   def bento_truncate(str, options = {})
     return str if str.nil? || str.empty?
 
-    options.reverse_merge!(:omission => "…", :length => 280, :separator => ' ')       
-    
+    options.reverse_merge!(:omission => "…", :length => 280, :separator => ' ')
+
     # works for non-html of course, but for html a quick check
     # to avoid expensive nokogiri parse if the whole string, even
-    # with tags, is still less than max length. 
+    # with tags, is still less than max length.
     return str if str.length < options[:length]
-    
-    if str.html_safe? 
+
+    if str.html_safe?
       noko = Nokogiri::HTML::DocumentFragment.parse(str)
       BentoSearch::Util.nokogiri_truncate(noko, options[:length], options[:omission], options[:separator]).inner_html.html_safe
     else
       return truncate(str, options)
     end
   end
-    
 
-  
+
+
   # Deprecated, made more sense to put this in a partial. Just
   # call partial directly:
   #  <%= render :partial => "bento_search/item_title", :object => item, :as => 'item'  %>
@@ -142,41 +140,41 @@ module BentoSearchHelper
     render :partial => "bento_search/item_title", :object => item, :as => 'item'
   end
   deprecate :bento_item_title
-  
+
   # pass in 0-based rails current collection counter and a BentoSearch::Results,
-  # calculates a user-displayable result set index label. 
+  # calculates a user-displayable result set index label.
   #
   # Only non-trivial thing is both inputs are allowed to be nil; if either
-  # is nil, nil is returned.  
+  # is nil, nil is returned.
   def bento_item_counter(counter, results)
     return nil if counter.nil? || results.nil? || results.start.nil?
-    
+
     return counter + results.start + 1
   end
-    
-     
+
+
   # returns a hash of label => key suitable for passing to rails
-  # options_for_select. (Yes, it works backwards from how you'd expect). 
+  # options_for_select. (Yes, it works backwards from how you'd expect).
   # Label is looked up using I18n, at bento_search.sort_keys.*
   #
   # If no i18n is found, titleized version of key itself is used as somewhat
-  # reasonable default. 
+  # reasonable default.
   def bento_sort_hash_for(engine)
-    Hash[ 
+    Hash[
       engine.sort_definitions.keys.collect do |key|
         [I18n.translate(key.to_s, :scope => "bento_search.sort_keys", :default => key.to_s.titleize), key.to_s]
-      end        
-    ]    
+      end
+    ]
   end
-  
+
   # Returns a hash of label => key suitable for passing to rails
   # options_for_select. ONLY includes fields with :semantics set at
-  # present. Key will be _semantic_ key name. 
+  # present. Key will be _semantic_ key name.
   # For engine-specific fields, you're on you're own, sorry!
   #
   # If first arg is an engine instance, will
   # be search fields supported by that engine. If first arg is nil,
-  # will be any field in our i18n lists for search fields. 
+  # will be any field in our i18n lists for search fields.
   #
   # Can pass in options :only or :except to customize list. Values
   # in :only and :except will match on internal field names OR
@@ -190,25 +188,25 @@ module BentoSearchHelper
       hash = I18n.t("bento_search.search_fields").invert
     else
       hash = Hash[ engine.search_field_definitions.collect do |k, defn|
-        if defn[:semantic] && (label = I18n.t(defn[:semantic], :scope => "bento_search.search_fields", :default => defn[:semantic].to_s.titlecase )) 
+        if defn[:semantic] && (label = I18n.t(defn[:semantic], :scope => "bento_search.search_fields", :default => defn[:semantic].to_s.titlecase ))
           [label,  defn[:semantic].to_s]
         end
       end.compact]
     end
-  
-    # :only/:except    
-    if options[:only]      
+
+    # :only/:except
+    if options[:only]
       keys = [options[:only]].flatten.collect(&:to_s)
-      hash.delete_if {|key, value|  ! keys.include?(value) }  
+      hash.delete_if {|key, value|  ! keys.include?(value) }
     end
-    
+
     if options[:except]
       keys = [options[:except]].flatten.collect(&:to_s)
       hash.delete_if {|key, value|  keys.include?(value) }
     end
-    
+
     return hash
   end
-  
-  
+
+
 end

data/app/models/bento_search/concurrent_searcher.rb

@@ -0,0 +1,136 @@
+begin
+  require 'concurrent'
+
+  # Concurrently runs multiple searches in separate threads. Since a search
+  # generally spends most of it's time waiting on foreign API, this is
+  # useful to significantly reduce total latency of running multiple searches,
+  # even in MRI.
+  #
+  # Uses [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby),
+  # already a dependency of Rails 5.x. To use with Rails previous to 5.x,
+  # just add concurrent-ruby to your `Gemfile`:
+  #
+  #     gem 'concurrent-ruby', '~> 1.0'
+  #
+  # # Usage
+  #
+  # initialize with id's of registered engines:
+  #
+  #     searcher = BentoBox::MultiSearcher.new(:gbs, :scopus)
+  #
+  # start the concurrent searches, params same as engine.search
+  #
+  #     searcher.search( query_params )
+  #
+  # retrieve results, blocking until all are completed:
+  #
+  #     results = searcher.results
+  #
+  # returns a Hash keyed by engine id, values BentoSearch::Results objects.
+  #
+  #     results # => { "gbs" => <BentoSearch::Results ...>, "scopus" =>  <BentoSearch::Results ...>}
+  #
+  # Calling results more than once will just return the initial results again
+  # (cached), it won't run a search again.
+  #
+  # ## Dev-mode autoloading and concurrency
+  #
+  # In Rails previous to Rails5, you may have to set config.cache_classes=true
+  # even in development to avoid problems. In Rails 5.x, we take advantage of
+  # new api that should allow concurrency-save autoloading. But if you run into
+  # any weird problems (such as a deadlock), `cache_classes = true` and
+  # `eager_load = true` should eliminate them, at the cost of dev-mode
+  # auto-reloading.
+  #
+  #
+  # TODO: have a method that returns Futures instead of only supplying the blocking
+  # results method? Several tricks, including making sure to properly terminate actors.
+  class BentoSearch::ConcurrentSearcher
+    def initialize(*engine_ids)
+      auto_rescued_exceptions = [StandardError]
+
+      @engines = []
+      engine_ids.each do |id|
+        add_engine( BentoSearch.get_engine(id).tap { |e| e.auto_rescued_exceptions = auto_rescued_exceptions + e.auto_rescued_exceptions })
+      end
+      @extra_auto_rescue_exceptions = [StandardError]
+    end
+
+    # Adds an instantiated engine directly, rather than by id from global
+    # registry.
+    def add_engine(engine)
+      unless engine.configuration.id.present?
+        raise ArgumentError.new("ConcurrentSearcher engines need `configuration.id`, this one didn't have one: #{engine}")
+      end
+      @engines << engine
+    end
+
+    # Starts all searches, returns self so you can chain method calls if you like.
+    def search(*search_args)
+      search_args.freeze
+      @futures = @engines.collect do |engine|
+        Concurrent::Future.execute { rails_future_wrap { engine.search(*search_args) } }
+      end
+      return self
+    end
+
+    # Have you called #search yet? You can only call #results if you have.
+    # Will stay true forever, it doesn't tell you if the search is done or not.
+    def search_started?
+      !! @futures
+    end
+
+    # Call after #search. Blocks until each included engine is finished
+    # then returns a Hash keyed by engine registered id, value is a
+    # BentoSearch::Results object.
+    #
+    # If called multiple times, returns the same results each time, does
+    # not re-run searches.
+    #
+    # It is an error to invoke without having previously called #search
+    def results
+      unless search_started?
+        raise ArgumentError, "Can't call ConcurrentSearcher#results before you have executed a #search"
+      end
+
+      @results ||= begin
+        pairs = rails_wait_wrap do
+          @futures.collect { |future| [future.value!.engine_id, future.value!] }
+        end
+        Hash[ pairs ].freeze
+      end
+    end
+
+    protected
+
+    # In Rails5, future body's need to be wrapped in an executor,
+    # to handle auto-loading right in dev-mode, among other things.
+    # Rails docs coming, see https://github.com/rails/rails/issues/26847
+    @@rails_has_executor = Rails.application.respond_to?(:executor)
+    def rails_future_wrap
+      if @@rails_has_executor
+        Rails.application.executor.wrap { yield }
+      else
+        yield
+      end
+    end
+
+    # In Rails5, if we are collecting from within an action method
+    # (ie the 'request loop'), as we usually will be, we need to
+    # give up the autoload lock. Rails docs coming, see https://github.com/rails/rails/issues/26847
+    @@rails_needs_interlock_permit = ActiveSupport::Dependencies.respond_to?(:interlock) &&
+      !(Rails.application.config.eager_load && Rails.application.config.cache_classes)
+    def rails_wait_wrap
+      if @@rails_needs_interlock_permit
+        ActiveSupport::Dependencies.interlock.permit_concurrent_loads { yield }
+      else
+        yield
+      end
+    end
+
+  end
+rescue LoadError
+  # you can use bento_search without celluloid, just not
+  # this class.
+  $stderr.puts "Tried but could not load BentoSearch::ConcurrentSearcher, concurrent-ruby not available!"
+end