README.md in rufus-scheduler-3.8.2 vs README.md in rufus-scheduler-3.9.0
- old
+ new
@@ -1,11 +1,10 @@
# rufus-scheduler
[](https://github.com/jmettraux/rufus-scheduler/actions)
[](https://badge.fury.io/rb/rufus-scheduler)
-[](https://gitter.im/floraison/fugit?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
Job scheduler for Ruby (at, cron, in and every jobs).
It uses threads.
@@ -104,11 +103,11 @@
* The scheduler isn't catching the whole of Exception anymore, only StandardError
* The error_handler is [#on_error](#rufusscheduleron_errorjob-error) (instead of #on_exception), by default it now prints the details of the error to $stderr (used to be $stdout)
* Rufus::Scheduler::TimeOutError renamed to Rufus::Scheduler::TimeoutError
* Introduction of "interval" jobs. Whereas "every" jobs are like "every 10 minutes, do this", interval jobs are like "do that, then wait for 10 minutes, then do that again, and so on"
* Introduction of a lockfile: true/filename mechanism to prevent multiple schedulers from executing
-* "discard_past" is on by default. If the scheduler (its host) sleeps for 1 hour and a `every '10m'` job is on, it will trigger once at wakeup, not 6 times (discard_past was false by default in rufus-scheduler 2.x). No intention to re-introduce `discard_past: false` in 3.0 for now.
+* "discard_past" is on by default. If the scheduler (its host) sleeps for 1 hour and a `every '10m'` job is on, it will trigger once at wakeup, not 6 times (discard_past was false by default in rufus-scheduler 2.x).
* Introduction of Scheduler #on_pre_trigger and #on_post_trigger callback points
## getting help
@@ -118,16 +117,10 @@
Go read [how to report bugs effectively](https://www.chiark.greenend.org.uk/~sgtatham/bugs.html), twice.
Update: [help_help.md](https://gist.github.com/jmettraux/310fed75f568fd731814) might help help you.
-### on Gitter
-
-You can find help via chat over at [https://gitter.im/floraison/fugit](https://gitter.im/floraison/fugit). It's [fugit](https://github.com/floraison/fugit), [et-orbi](https://github.com/floraison/et-orbi), and rufus-scheduler combined chat room.
-
-Please be courteous.
-
### issues
Yes, issues can be reported in [rufus-scheduler issues](https://github.com/jmettraux/rufus-scheduler/issues), I'd actually prefer bugs in there. If there is nothing wrong with rufus-scheduler, a [Stack Overflow question](https://stackoverflow.com/questions/ask?tags=rufus-scheduler+ruby) is better.
### faq
@@ -196,12 +189,39 @@
Interval jobs trigger, execute and then trigger again after the interval elapsed. (every jobs time between trigger times, interval jobs time between trigger termination and the next trigger start).
Cron jobs are based on the venerable cron utility (```man 5 crontab```). They trigger following a pattern given in (almost) the same language cron uses.
-####
+### Chronic and "Wed at 2pm"
+By default, rufus-scheduler relies on Ruby to parse strings like "Wed at 2pm". But most of the time, when calling this on Thursday, the day before is "invoked". Relying on [Chronic](https://github.com/mojombo/chronic) might solve the issue.
+
+Compare
+
+```ruby
+require 'rufus-scheduler'
+
+scheduler = Rufus::Scheduler.new
+
+scheduler.at('Wed at 2pm') do
+ # ... might point in the past and thus get triggered immediately
+end
+```
+
+with
+
+```ruby
+require 'chronic'
+require 'rufus-scheduler'
+
+scheduler = Rufus::Scheduler.new
+
+scheduler.at('Wed at 2pm') do
+ # ... will point to a time in the future and trigger appropriately
+end
+```
+
### #schedule_x vs #x
schedule_in, schedule_at, schedule_cron, etc will return the new Job instance.
in, at, cron will return the new Job instance's id (a String).
@@ -557,9 +577,46 @@
# later on...
job.times = 10
# 10 days and it will be over
+```
+
+### discard_past: false/true/:fail
+
+`in` and `at` accept a `discard_past:` option since rufus-scheduler 3.9.0:
+
+```ruby
+require 'rufus-scheduler'
+
+scheduler = Rufus::Scheduler.new
+
+scheduler.in(-3600, discard_past: true) {}
+ # the job will never get scheduled
+
+scheduler.in(-3600, discard_past: false) {}
+ # the job will trigger immediately
+
+scheduler.in(-3600, discard_past: :fail) {}
+ # will raise an error...
+```
+
+Please note that `discard_past` can be set at the scheduler level:
+
+```ruby
+require 'rufus-scheduler'
+
+s0 = Rufus::Scheduler.new(discard_past: true) # default
+
+s1 = Rufus::Scheduler.new(discard_past: false)
+ # or
+s1 = Rufus::Scheduler.new
+s1.discard_past = false
+
+s2 = Rufus::Scheduler.new(discard_past: :fail)
+ # or
+s2 = Rufus::Scheduler.new
+s2.discard_past = :fail
```
## Job methods