implement :first => :now for repeat jobs

closes gh-96

CHANGELOG.txt

@@ -4,6 +4,8 @@
 
 == rufus-scheduler - 3.0.5    not yet released
 
+- implement :first => :now for repeat jobs, gh-96
+
 
 == rufus-scheduler - 3.0.4    released 2014/10/19
 

README.md

@@ -366,7 +366,7 @@ end
 
 The :timeout option accepts either a duration (like "1d" or "2w3d") or a point in time (like "2013/12/12 12:00").
 
-### :first_at, :first_in, :first
+### :first_at, :first_in, :first, :first_time
 
 This option is for repeat jobs (cron / every) only.
 
@@ -393,6 +393,34 @@ job.first_at = Time.now + 10
 job.first_at = Rufus::Scheduler.parse('2029-12-12')
 ```
 
+The first argument (in all its flavours) accepts a :now or :immediately value. That schedules the first occurence for immediate triggering. Consider:
+
+```ruby
+require 'rufus-scheduler'
+
+s = Rufus::Scheduler.new
+
+n = Time.now; p [ :scheduled_at, n, n.to_f ]
+
+s.every '3s', :first => :now do
+  n = Time.now; p [ :in, n, n.to_f ]
+end
+
+s.join
+
+```
+
+that'll output something like:
+
+```
+[:scheduled_at, 2014-01-22 22:21:21 +0900, 1390396881.344438]
+[:in, 2014-01-22 22:21:21 +0900, 1390396881.6453865]
+[:in, 2014-01-22 22:21:24 +0900, 1390396884.648807]
+[:in, 2014-01-22 22:21:27 +0900, 1390396887.651686]
+[:in, 2014-01-22 22:21:30 +0900, 1390396890.6571937]
+...
+```
+
 ### :last_at, :last_in, :last
 
 This option is for repeat jobs (cron / every) only.

lib/rufus/scheduler/jobs.rb

@@ -368,19 +368,24 @@ def initialize(scheduler, duration, opts, block)
         ) unless @times == nil || @times.is_a?(Fixnum)
 
         self.first_at =
-          opts[:first] || opts[:first_at] || opts[:first_in] || 0
+          opts[:first] || opts[:first_time] ||
+          opts[:first_at] || opts[:first_in] ||
+          0
         self.last_at =
           opts[:last] || opts[:last_at] || opts[:last_in]
       end
 
       def first_at=(first)
 
+        n = Time.now
+        first = n + 0.001 if first == :now || first == :immediately
+
         @first_at = Rufus::Scheduler.parse_to_time(first)
 
         raise ArgumentError.new(
           "cannot set first[_at|_in] in the past: " +
           "#{first.inspect} -> #{@first_at.inspect}"
-        ) if first != 0 && @first_at < Time.now
+        ) if first != 0 && @first_at < n
       end
 
       def last_at=(last)

spec/job_repeat_spec.rb

@@ -174,6 +174,29 @@
 
       }.should raise_error(ArgumentError)
     end
+
+    context ':first_time => :now/:immediately' do
+
+      it 'schedules the first execution immediately' do
+
+        n = Time.now
+        ft = nil
+
+        job =
+          @scheduler.schedule_every '7s', :first => :now do
+            ft ||= Time.now
+          end
+
+        sleep 0.5
+
+        #p n.to_f
+        #p job.first_at.to_f
+        #p ft.to_f
+
+        job.first_at.should < n + 0.5
+        ft.should < job.first_at + @scheduler.frequency + 0.1
+      end
+    end
   end
 
   describe ':first/:first_in/:first_at => duration' do