qfill 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in qfill.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Peter Boling
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# Qfill - Advanced Queue Tranformations
+
+This gem takes a dynamic number of queues (arrays) of things, and manages the transformation into a new set of queues,
+according to a dynamic set of guidelines.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'qfill'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install qfill
+
+## Usage & List Fill Methodology
+
+There will be a dynamic number of origination queues each containing a set of snapshots which are grouped together by
+some matching criteria.
+There is a Popper which is called to pop the next object from the next origination queue.
+There is a Filter which is optionally called to validate any object that is popped from the origin.
+Origin keeps popping until an object is validated for as a result-worthy object.
+
+Example:
+
+    filter1 = Qfill::Filter.new( -> (object, stuff, stank) { object.is_awesome_enough_to_be_in_results?(stuff, stank) }, stuff, stank)
+    filter2 = Qfill::Filter.new( -> (object, rank, bank) { object.is_awesome_enough_to_be_in_results?(rank, bank) }, rank, bank)
+
+    popper = Qfill::Popper.new(
+      Qfill::Origin.new( :name => "High List",
+                            :elements => [Thing1, Thing3],
+                            :backfill => "Medium List",
+                            :filter => filter1),
+      Qfill::Origin.new( :name => "Medium List",
+                            :elements => [Thing2, Thing6],
+                            :backfill => "Low List",
+                            :filter => filter2),
+      Qfill::Origin.new( :name => "Low List",
+                            :elements => [Thing4, Thing5],
+                            :backfill => nil,
+                            :filter => filter1),
+    )
+
+Or:
+
+    popper = Qfill::Popper.from_array_of_hashes([
+      { :name => "High List",
+        :elements => [Thing1, Thing3, Thing7, Thing8, Thing12, Thing15, Thing17],
+        :backfill => "Medium List",
+        :filter => filter1},
+      { :name => "Medium List",
+        :elements => [Thing2, Thing6, Thing11, Thing 16],
+        :backfill => "Low List",
+        :filter => filter2},
+      { :name => "Low List",
+        :elements => [Thing4, Thing5, Thing9, Thing10, Thing13, Thing14, Thing18, Thing19, Thing20],
+        :backfill => false,
+        :filter => filter1}
+    ])
+
+There are a dynamic number of result queues that need to be filled with objects from the origination queues.
+There is a Pusher which is called to add the object from the Popper to the next result queue.
+A filter can be given to perform additional check to verify that the object should be added to a particular result queue.
+At least one result queue should be left with no filter, or you risk a result set that is completely empty.
+A filter_alternate can be given to indicate which alternate result queue objects failing the filter should be placed in.
+A ratio can be given to indicate the portion of the total results which should go into the result queue.
+A set of queue ratios can be defined to indicate the rate at which the result queue will be filled from each origin queue.
+When queue ratios are not given an even split is assumed.
+
+Example:
+
+    filter3 = Qfill::Filter.new( -> (object, stuff, stank) { object.can_be_best_results?(stuff, stank) }, stuff, stank)
+
+    pusher = Qfill::Pusher.new(
+      Qfill::Result.new( :name => "Best Results",
+                            :filter => filter3,
+                            :ratio => 0.5,
+                            :list_ratios => {
+                              "High List" => 0.4,
+                              "Medium List" => 0.2,
+                              "Low List" => 0.4
+                            }
+                          ),
+      Qfill::Result.new( :name => "More Results",
+                            :ratio => 0.5,
+                            :list_ratios => {
+                              "High List" => 0.2,
+                              "Medium List" => 0.4,
+                              "Low List" => 0.4
+                            }
+      )
+    )
+
+Or:
+
+    pusher = Qfill::Pusher.from_array_of_hashes([
+      { :name => "First Result",
+        :ratio => 0.125,
+        :filter => filter3,
+        :ratios => {
+          "High List" => 0.4,
+          "Medium List" => 0.2,
+          "Low List" => 0.4
+        }
+      },
+      { :name => "Second Result",
+        :ratio => 0.25 },
+      { :name => "Third Result",
+        :ratio => 0.125 },
+      { :name => "Fourth Result",
+        :ratio => 0.50 },
+    ])
+
+There is a Manager which maintains state: always knows which queue to pop from next, and which queue to push onto next.
+
+    manager = Qfill::Manager.new(
+      :all_list_max => 40,
+      :popper => popper,
+      :pusher => pusher,
+    )
+    manager.fill!
+
+For the best usage please look in `spec/qfill/manager_spec.rb` and the other spec files.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am ‘Added some feature’`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
+6. Create new Pull Request
+
+## Versioning
+
+This library aims to adhere to [Semantic Versioning 2.0.0][semver].
+Violations of this scheme should be reported as bugs. Specifically,
+if a minor or patch version is released that breaks backward
+compatibility, a new version should be immediately released that
+restores compatibility. Breaking changes to the public API will
+only be introduced with new major versions.
+As a result of this policy, you can (and should) specify a
+dependency on this gem using the [Pessimistic Version Constraint][pvc] with two digits of precision.
+For example:
+    spec.add_dependency 'qfill', '~> 0.0'
+
+[semver]: http://semver.org/
+[pvc]: http://docs.rubygems.org/read/chapter/16#page74

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/qfill.rb

@@ -0,0 +1,13 @@
+require "qfill/version"
+require "qfill/filter"
+require "qfill/list"
+require "qfill/list_set"
+require "qfill/origin"
+require "qfill/result"
+require "qfill/popper"
+require "qfill/pusher"
+require "qfill/manager"
+
+module Qfill
+  # Your code goes here...
+end

data/lib/qfill/filter.rb

@@ -0,0 +1,18 @@
+#filter1 = Qfill::Filter.new( -> (object, stuff, stank) { object.is_awesome_enough_to_be_in_results?(stuff, stank) }, stuff, stank)
+#filter2 = Qfill::Filter.new( -> (object, rank, bank) { object.is_awesome_enough_to_be_in_results?(rank, bank) }, rank, bank)
+#
+# Filters are destructive. If an item is filtered from a Result list it is lost, since it has already been popped off the origin list, and won't be coming back
+module Qfill
+  class Filter
+    attr_accessor :processor, :processor_arguments
+
+    def initialize(proc, *params)
+      @processor = proc
+      @processor_arguments = params
+    end
+
+    def run(*args)
+      self.processor.call(*args, *self.processor_arguments)
+    end
+  end
+end

data/lib/qfill/list.rb

@@ -0,0 +1,18 @@
+# This is the base queue class for Origin queues and Result queues.
+#
+#Qfill::List.new(:name => "High List",
+#                    :elements => [Thing1, Thing3],
+#                    :filter => filter1),
+module Qfill
+  class List
+    attr_accessor :name, :elements, :filter
+
+    def initialize(options = {})
+      raise ArgumentError, "Missing required option :name for #{self.class}.new()" unless options && options[:name]
+      @name = options[:name]
+      @elements = options[:elements] || []
+      @filter = options[:filter]
+    end
+
+  end
+end

data/lib/qfill/list_set.rb

@@ -0,0 +1,29 @@
+#popper = Qfill::ListSet.new(
+#  Qfill::List.new( :name => "High List",
+#                       :elements => [Thing1, Thing3],
+#                       :filter => filter1 ) )
+module Qfill
+  class ListSet
+
+    attr_accessor :queues, :current_index
+
+    def initialize(*args)
+      raise ArgumentError, "Missing required arguments for #{self.class}.new(queues)" unless args.length > 0
+      @queues = args
+      @current_index = 0
+    end
+
+    def [](key)
+      return self.queues.find { |queue| queue.name == key }
+    end
+
+    def reset!
+      self.current_index = 0
+    end
+
+    def get_total_elements
+      self.queues.inject(0) {|counter, queue| counter += queue.elements.length}
+    end
+
+  end
+end

data/lib/qfill/manager.rb

@@ -0,0 +1,91 @@
+#Qfill::Manager.new(
+#  :all_list_max => 40,
+#  :popper => popper,
+#  :pusher => pusher,
+#)
+module Qfill
+  class Manager
+    attr_accessor :all_list_max, :popper, :pusher, :fill_count, :strategy
+
+    STRATEGY_OPTIONS = [:drain, :sample]
+
+    def initialize(options = {})
+      unless options[:popper] && options[:pusher]
+        raise ArgumentError, "#{self.class}: popper and pusher are required options for #{self.class}.new(options)"
+      end
+      unless options[:strategy].nil? || STRATEGY_OPTIONS.include?(options[:strategy])
+        raise ArgumentError, "#{self.class}: strategy is optional, but must be one of #{STRATEGY_OPTIONS.inspect} if provided"
+      end
+      @popper = options[:popper]
+      @pusher = options[:pusher]
+      # Provided by user, or defaults to the total number of primary elements in popper list set
+      @all_list_max = options[:all_list_max] ? [options[:all_list_max], self.popper.get_primary_elements].min : self.popper.get_primary_elements
+      @fill_count = 0
+      @strategy = options[:strategy] || :drain # or :sample
+    end
+
+    def fill!
+      while !is_full? && !self.popper.primary_empty? && (result = self.pusher.current_list)
+        self.fill_to_ratio!(result, self.all_list_max)
+        self.pusher.set_next_as_current!
+      end
+    end
+
+    def fill_to_ratio!(result, all_list_max)
+      result.max = Qfill::Result.get_limit_from_max_and_ratio(all_list_max, result.ratio)
+      if !result.list_ratios.empty?
+        self.fill_according_to_list_ratios!(result)
+      else
+        self.fill_up_to_ratio!(result)
+      end
+    end
+
+    def fill_according_to_list_ratios!(result)
+      added = 0
+      if self.strategy == :drain
+        result.list_ratios.each do |list_name, list_ratio|
+          #puts "fill_according_to_list_ratios!, :drain, #{list_name}: Primary remaining => #{self.popper.get_primary_elements}"
+          max_from_list = Qfill::Result.get_limit_from_max_and_ratio(result.max, list_ratio)
+          array_to_push = self.popper.next_objects!(list_name, max_from_list)
+          added = result.push(array_to_push, list_name)
+        end
+        self.fill_count += added
+      elsif self.strategy == :sample
+        while !is_full? && !result.is_full? && !self.popper.totally_empty? && (list_ratio_tuple = result.current_list_ratio)
+          #puts "fill_according_to_list_ratios!, :sample, #{list_ratio_tuple[0]}: Primary remaining => #{self.popper.get_primary_elements}"
+          max_from_list = Qfill::Result.get_limit_from_max_and_ratio(result.max, list_ratio_tuple[1])
+          array_to_push = self.popper.next_objects!(list_ratio_tuple[0], max_from_list)
+          added = result.push(array_to_push, list_ratio_tuple[0])
+          self.fill_count += added
+          result.set_next_as_current!
+        end
+      end
+    end
+
+    def fill_up_to_ratio!(result)
+      ratio = 1.0 / self.popper.primary.length
+      max_from_list = Qfill::Result.get_limit_from_max_and_ratio(result.max, ratio)
+      added = 0
+      if self.strategy == :drain
+        self.popper.primary.each do |queue|
+          #puts "fill_up_to_ratio!, :drain max #{max_from_list}, #{queue.name}: Primary remaining => #{self.popper.get_primary_elements}"
+          array_to_push = self.popper.next_objects!(queue.name, max_from_list)
+          added = result.push(array_to_push, queue.name)
+        end
+        self.fill_count += added
+      elsif self.strategy == :sample
+        while !is_full? && !result.is_full? && !self.popper.totally_empty? && (origin_list = self.popper.current_list)
+          #puts "fill_up_to_ratio!, :sample max #{max_from_list}, #{origin_list.name}: Primary remaining => #{self.popper.get_primary_elements}"
+          array_to_push = self.popper.next_objects!(origin_list.name, max_from_list)
+          added = result.push(array_to_push, origin_list.name)
+          self.fill_count += added
+          self.popper.set_next_as_current!
+        end
+      end
+    end
+
+    def is_full?
+      self.fill_count >= self.all_list_max
+    end
+  end
+end

data/lib/qfill/origin.rb

@@ -0,0 +1,19 @@
+#Qfill::Origin.new(:name => "High List",
+#                     :elements => [Thing1, Thing3],
+#                     :backfill => "Medium List",
+#                     :filter => filter1),
+module Qfill
+  class Origin < Qfill::List
+    attr_accessor :backfill
+
+    def initialize(options = {})
+      super(options)
+      @backfill = options[:backfill]
+    end
+
+    def has_backfill?
+      !!self.backfill
+    end
+
+  end
+end

data/lib/qfill/popper.rb

@@ -0,0 +1,96 @@
+#popper = Qfill::Popper.new(
+#  Qfill::Origin.new( :name => "High List",
+#                        :elements => [Thing1, Thing3],
+#                        :backfill => "Medium List",
+#                        :filter => filter1),
+#  Qfill::Origin.new( :name => "Medium List",
+#                        :elements => [Thing2, Thing6],
+#                        :backfill => "Low List",
+#                        :filter => filter2),
+#  Qfill::Origin.new( :name => "Low List",
+#                        :elements => [Thing4, Thing5],
+#                        :backfill => nil,
+#                        :filter => filter1),
+#)
+#
+#popper = Qfill::Popper.from_array_of_hashes([
+#  { :name => "High List",
+#    :elements => [Thing1, Thing3, Thing7, Thing8, Thing12, Thing15, Thing17],
+#    :backfill => "Medium List",
+#    :filter => filter1},
+#  { :name => "Medium List",
+#    :elements => [Thing2, Thing6, Thing11, Thing 16],
+#    :backfill => "Low List",
+#    :filter => filter2},
+#  { :name => "Low List",
+#    :elements => [Thing4, Thing5, Thing9, Thing10, Thing13, Thing14, Thing18, Thing19, Thing20],
+#    :backfill => nil,
+#    :filter => filter1},
+#])
+#
+# Popper is made up of an array (called queues) of Origin objects.
+module Qfill
+  class Popper < Qfill::ListSet
+
+    attr_accessor :total_elements
+
+    def initialize(*args)
+      super(*args)
+      @total_elements = get_total_elements
+    end
+
+    def primary
+      @primary ||= self.queues.select {|x| x.backfill != true}
+    end
+
+    def current_list
+      self.primary[self.current_index]
+    end
+
+    def set_next_as_current!
+      next_index = self.current_index + 1
+      if (next_index) == self.primary.length
+        # If we have iterated through all the queues, then we reset
+        self.reset!
+      else
+        self.current_index = next_index
+      end
+    end
+
+    def next_objects!(list_name, n = 1)
+      origin_list = self[list_name]
+      if origin_list.elements.length >= n
+        return origin_list.elements.pop(n)
+      else
+        result = origin_list.elements.pop(n)
+        while result.length < n && origin_list.has_backfill?
+          secondary_list = self[origin_list.backfill]
+          remaining = n - result.length
+          result += secondary_list.elements.pop(remaining)
+          origin_list = secondary_list
+        end
+        return result
+      end
+    end
+
+    def self.from_array_of_hashes(array_of_hashes = [])
+      args = array_of_hashes.map do |hash|
+        Qfill::Origin.new(hash)
+      end
+      Qfill::Popper.new(*args)
+    end
+
+    def primary_empty?
+      self.get_primary_elements == 0
+    end
+
+    def totally_empty?
+      self.get_total_elements == 0
+    end
+
+    def get_primary_elements
+      self.primary.inject(0) {|counter, queue| counter += queue.elements.length}
+    end
+
+  end
+end