util: shorten outdated grace period (#56)

* util: shorten outdated grace period

* scheduler: make grace period configurable

* outdated: scheduler testing and documentation

quartz/scheduler.go

@@ -80,14 +80,29 @@ type StdSchedulerOptions struct {
 	// dispatched. If BlockingExecution is set, then WorkerLimit
 	// is ignored.
 	WorkerLimit int
+
+	// When the scheduler attempts to schedule a job, if the job
+	// is due to run in less than or equal to this value, then the
+	// scheduler will run the job, even if the "next scheduled
+	// job" is in the future. Historically, Go-Quartz had a
+	// scheduled time of 30 seconds, by default (NewStdScheduler)
+	// has a threshold of 100ms (if a job will be "triggered" in
+	// 100ms, then it is run now.)
+	//
+	// As a rule of thumb, your OutdatedThreshold should always be
+	// greater than 0, but less than the shortest interval used by
+	// your job or jobs.
+	OutdatedThreshold time.Duration
 }
 
 // Verify StdScheduler satisfies the Scheduler interface.
 var _ Scheduler = (*StdScheduler)(nil)
 
 // NewStdScheduler returns a new StdScheduler with the default configuration.
 func NewStdScheduler() Scheduler {
-	return NewStdSchedulerWithOptions(StdSchedulerOptions{})
+	return NewStdSchedulerWithOptions(StdSchedulerOptions{
+		OutdatedThreshold: 100 * time.Millisecond,
+	})
 }
 
 // NewStdSchedulerWithOptions returns a new StdScheduler configured as specified.
@@ -305,14 +320,16 @@ func (sched *StdScheduler) executeAndReschedule(ctx context.Context) {
 
 	// fetch an item
 	var it *item
+	var outdatedThreshold int64
 	func() {
 		sched.mtx.Lock()
 		defer sched.mtx.Unlock()
 		it = heap.Pop(sched.queue).(*item)
+		outdatedThreshold = sched.opts.OutdatedThreshold.Nanoseconds()
 	}()
 
 	// execute the Job
-	if !isOutdated(it.priority) {
+	if !isOutdated(it.priority, outdatedThreshold) {
 		switch {
 		case sched.opts.BlockingExecution:
 			it.Job.Execute(ctx)

quartz/scheduler_test.go

@@ -83,6 +83,8 @@ func TestSchedulerBlockingSemantics(t *testing.T) {
 				t.Fatal("unknown semantic:", tt)
 			}
 
+			opts.OutdatedThreshold = 10 * time.Millisecond
+
 			sched := quartz.NewStdSchedulerWithOptions(opts)
 			ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
 			defer cancel()
@@ -101,9 +103,9 @@ func TestSchedulerBlockingSemantics(t *testing.T) {
 						return true, nil
 					}
 				}),
-				quartz.NewSimpleTrigger(time.Millisecond))
+				quartz.NewSimpleTrigger(20*time.Millisecond))
 
-			ticker := time.NewTicker(4 * time.Millisecond)
+			ticker := time.NewTicker(100 * time.Millisecond)
 			<-ticker.C
 			if atomic.LoadInt64(&n) == 0 {
 				t.Error("job should have run at least once")

quartz/util.go

@@ -108,8 +108,8 @@ func NowNano() int64 {
 	return time.Now().UTC().UnixNano()
 }
 
-func isOutdated(_time int64) bool {
-	return _time < NowNano()-(time.Second*30).Nanoseconds()
+func isOutdated(_time, threshold int64) bool {
+	return _time < NowNano()-threshold
 }
 
 // HashCode calculates and returns a hash code for the given string.