threasy 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 864b05c24ba407f0763f65f7a07e1af3d9678efd
-  data.tar.gz: c83f33b9c2ea06fa1783ba51b51b07948920e359
+  metadata.gz: 24769445131b62b227817a4cd7eacf4682e3855e
+  data.tar.gz: f5d317aee9b0de3f7b4989526b8716738f9f45fb
 SHA512:
-  metadata.gz: cb206f8de354b6192c0bb5153cedda328b9d928abedf86423bcdc1e601c720bdb312c87b9bde65353d73a03f8f1a0ccc7384ffe80c60e837c7be53c443751a48
-  data.tar.gz: ca0f60b71576b34b325cf7bc2a3c94a793f1c52ede65fe9ef79914414417303c59a54d5a7c04828c333fdda89c5be4d17e37a4b85f0cdaa17b4c3d576fd5ad72
+  metadata.gz: a2b47d68b23493aa3a66e6ef6a5369c06d5301a07cb952a9a1b77f322991176f7d4052ec9dd97f533be0fb31391460fce429d6cdda3abf95be8e7b84db728c6e
+  data.tar.gz: db3c0cebce5e18bc13854112782d91c273c34f3a14c0e6b1a9a2c94360f6b0d6ecd4e5e2173bf8fa30ca8bc2e514a3292ce6fbfcfd0d80b2700d6f12d4440cc9

data/lib/threasy/schedule/entry.rb

@@ -1,5 +1,16 @@
 module Threasy
   class Schedule::Entry
+    # = Schedule Entry
+    #
+    # Represents a single entry in a schedule.
+    #
+    # Class is responsible for keeping track of the timing and recurrance of
+    # a the supplied `job` object.
+    #
+    # Entry instances are usually created by a `Threasy::Schedule` instance
+    # and should not be created by hand.
+    #
+    # See `Threasy::Schedule#add`
     attr_accessor :schedule, :work, :job, :at, :repeat
 
     def initialize(job, options = {})

data/lib/threasy/schedule.rb

@@ -1,9 +1,35 @@
 module Threasy
   class Schedule
+    # = Threasy::Schedule
+    #
+    # Class that manages a "schedule".
+    #
+    # A "schedule" is a collection of jobs, some one-time, some repeating,
+    # that execute at specific times.
+    #
+    # `Threasy::Schedule` maintains an ordered list of jobs, sorted by which
+    # jobs are up "next".
+    #
+    # The `watcher` thread periodically wakes up, finds jobs that need to be
+    # worked, and enqueues them into the `work` queue.
+    #
+    # The `work` queue defaults to the default `Threasy::Work` instance, but
+    # can be any object that responds to `enqueue` and accepts your job objects.
+    #
+    # == Example
+    #
+    #     schedule = Threasy::Schedule.new
+    #     schedule.add(MyJob.new(1,2,3), in: 1.hour, every: 0.5.days)
     include Enumerable
 
     attr_reader :schedules, :watcher
 
+    # Creates new `Threasy::Schedule` instance
+    #
+    # === Parameters
+    #
+    # * `work` - Optional. Usually a `Threasy::Work` instance.
+    #            Defaults to `Threasy.work`
     def initialize(work = nil)
       @work = work
       @semaphore = Mutex.new
@@ -11,12 +37,44 @@ module Threasy
       @watcher = Thread.new{ watch }
     end
 
+    # Schedule a job
+    #
+    # === Examples
+    #
+    #     schedule = Threasy::Schedule.new(work: Threasy::Work.new)
+    #
+    #     # Schedule blocks
+    #     schedule.add(in: 5.min) { do_some_background_work }
+    #
+    #     # Schedule job objects compatible with the `work` queue
+    #     schedule.add(BackgroundJob.new(some: data), every: 1.hour)
+    #
+    #     # Enqueue strings that can be evals to a job object
+    #     schedule.add("BackgroundJob.new", every: 1.day)
+    #
+    # === Parameters
+    #
+    # * `job` - Job object which responds to `perform` or `call`
+    # * `options`
+    #   * `every: n` - If present, job is repeated every `n` seconds
+    #   * `in: n` - `n` seconds until job is executed
+    #   * `at: Time` - Time to execute job at
+    # * `&block` - Job block
+    #
+    # Must have either a `job` object or job `&block` present.
+    #
+    # === Returns
+    #
+    # * `Threasy::Schedule::Entry` if job was successfully added to schedule
+    # * `nil` if job was for the past
     def add(*args, &block)
       options = args.last.is_a?(Hash) ? args.pop : {}
       job = block_given? ? block : args.first
-      add_entry Entry.new(job, {schedule: self}.merge(options))
+      entry = Entry.new job, {schedule: self}.merge(options)
+      add_entry entry if entry.future?
     end
 
+    # Add a `Threasy::Schedule::Entry` object to `schedules`
     def add_entry(entry)
       sync do
         schedules << entry
@@ -26,6 +84,7 @@ module Threasy
       entry
     end
 
+    # Returns the current work queue
     def work
       @work ||= Threasy.work
     end
@@ -34,6 +93,7 @@ module Threasy
       sync { schedules.delete entry }
     end
 
+    # Wakes up the watcher thread if its sleeping
     def tickle_watcher
       watcher.wakeup if watcher.stop?
     end
@@ -51,6 +111,9 @@ module Threasy
       sync { schedules.clear }
     end
 
+    # Used by the watcher thread to find jobs that are due, add them to the
+    # `work` queue, re-sort the schedule, and attempt to sleep until the next
+    # job is due.
     def watch
       loop do
         Thread.stop if schedules.empty?
@@ -68,6 +131,7 @@ module Threasy
       end
     end
 
+    # Pop entries off the schedule that are due
     def entries_due
       [].tap do |entries|
         sync do

data/lib/threasy/version.rb

@@ -1,3 +1,3 @@
 module Threasy
-  VERSION = "0.3.0"
+  VERSION = "0.3.2"
 end

data/lib/threasy/work.rb

@@ -1,5 +1,18 @@
 module Threasy
   class Work
+    # = Threasy::Work
+    #
+    # Class to manage the work queue.
+    #
+    # An instance of `Threasy::Work` will manage a pool of worker threads and
+    # a queue of jobs. As the job queue grows, new worker threads are created
+    # process the jobs. When the Queue remains empty, worker threads are culled.
+    #
+    # == Example
+    #
+    #     work = Threasy::Work.new
+    #     work.enqueue { puts "Hello from the background!" }
+    #     # Outputs: Hello from the background!
     attr_reader :queue, :pool
 
     def initialize
@@ -8,8 +21,23 @@ module Threasy
       @semaphore = Mutex.new
     end
 
+    # Enqueue a job into the work queue
+    #
+    # === Examples
+    #
+    #     work = Threasy::Work.new
+    #
+    #     # Enqueue blocks
+    #     work.enqueue { do_some_background_work }
+    #
+    #     # Enqueue job objects that respond to `perform` or `call`
+    #     work.enqueue BackgroundJob.new(some: data)
+    #
+    #     # Enqueue string that evals to a job object
+    #     Threasy.enqueue("BackgroundJob.new")
+    #
     def enqueue(job = nil, &block)
-      queue.push(block_given? ? block : job).tap{ check_workers }
+      queue.push(block_given? ? block : job).tap { check_workers }
     end
 
     alias_method :enqueue_block, :enqueue
@@ -38,11 +66,9 @@ module Threasy
     end
 
     def add_worker(size)
-      # sync do
-        log "Adding new worker to pool"
-        worker = Worker.new(self, size)
-        pool.add worker
-      # end
+      log "Adding new worker to pool"
+      worker = Worker.new(self, size)
+      pool.add worker
       worker.work
     end
 

data/lib/threasy.rb

@@ -1,4 +1,7 @@
 require "logger"
+require "thread"
+require "timeout"
+require "set"
 
 require "threasy/version"
 require "threasy/config"
@@ -7,28 +10,96 @@ require "threasy/schedule"
 require "threasy/schedule/entry"
 
 module Threasy
+  # Returns default instance of `Threasy::Config`.
+  #
+  # Can be used with a block for changing multiple configs.
+  #
+  #     Threasy.config do |c|
+  #       c.max_sleep   = 10.minutes
+  #       c.max_overdue = 1.hour
+  #     end
+  #
+  # ==== Parameters
+  #
+  # * `&block` - Optional block that will be yielded the config object
+  #
+  # ==== Returns
+  #
+  # * `Threasy::Config` instance
   def self.config
     @@config ||= Config.new
     yield @@config if block_given?
     @@config
   end
 
+  # Shortcut for `Threasy::Config#logger`
   def self.logger
     config.logger
   end
 
+  # Shortcut for default `Threasy::Work` instance.
+  #
+  # === Returns
+  #
+  # * `Threasy::Work` instance
   def self.work
     config.work ||= Work.new
   end
 
+  # Shortcut to enqueue work into default `Threasy::Work` instance.
+  #
+  # === Examples
+  #
+  #     # Enqueue blocks
+  #     Threasy.enqueue { do_some_background_work }
+  #
+  #     # Enqueue objects that respond to `perform` or `call`
+  #     Threasy.enqueue BackgroundJob.new(some: data)
+  #
+  #     # Enqueue strings that can be evals to an object
+  #     Threasy.enqueue("BackgroundJob.new")
+  #
   def self.enqueue(*args, &block)
     work.enqueue *args, &block
   end
 
+  # Shortcut for default `Threasy::Schedule` instance.
+  #
+  # === Returns
+  #
+  # * `Threasy::Schedule` instance
   def self.schedules
     config.schedule ||= Schedule.new(work)
   end
 
+  # Shortcut to schedule work with the default `Threasy::Schedule` instance.
+  #
+  # === Examples
+  #
+  #     # Schedule blocks
+  #     Threasy.schedule(in: 5.min) { do_some_background_work }
+  #
+  #     # Schedule job objects that respond to `perform` or `call`
+  #     Threasy.schedule(BackgroundJob.new(some: data), every: 1.hour)
+  #
+  #     # Schedule strings that can be evals to a job object
+  #     Threasy.schedule("BackgroundJob.new", every: 1.day)
+  #
+  # === Parameters
+  #
+  # * `job` - Job object which responds to `perform` or `call`
+  # * `options`
+  #   * `every: n` - If present, job is repeated every `n` seconds
+  #   * `in: n` - `n` seconds until job is executed
+  #   * `at: Time` - Time to execute job at
+  # * `&block` - Job block
+  #
+  # Must have either a `job` object or job `&block` present.
+  #
+  # === Returns
+  #
+  # * `Threasy::Schedule::Entry` if job was successfully added to schedule
+  # * `nil` if job was for the past
   def self.schedule(*args, &block)
     schedules.add *args, &block
   end

data/spec/spec_helper.rb

@@ -1,7 +1,6 @@
-# require 'pry'
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), "..", "lib")
 require 'timecop'
-
-require File.join(File.dirname(__FILE__), "..", "lib", "threasy")
+require 'threasy'
 
 def async(timeout = 10)
   t = Thread.new do

data/spec/threasy/schedule_spec.rb

@@ -26,6 +26,16 @@ describe "Threasy::Schedule" do
         end
       end
     end
+
+    it "should add jobs scheduled for the future" do
+      expect(subject).to receive(:add_entry)
+      subject.add(job, at: Time.now + 100)
+    end
+
+    it "should ignore jobs scheduled for the past" do
+      expect(subject).not_to receive(:add_entry)
+      subject.add(job, at: Time.now - 100)
+    end
   end
 
   describe "#remove" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: threasy
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Carl Zulauf
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-17 00:00:00.000000000 Z
+date: 2015-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler