lib/rufus/scheduler.rb in rufus-scheduler-3.0.2 vs lib/rufus/scheduler.rb in rufus-scheduler-3.0.3

@@ -36,11 +36,11 @@
     require 'rufus/scheduler/util'
     require 'rufus/scheduler/jobs'
     require 'rufus/scheduler/cronline'
     require 'rufus/scheduler/job_array'
 
-    VERSION = '3.0.2'
+    VERSION = '3.0.3'
 
     #
     # A common error class for rufus-scheduler
     #
     class Error < StandardError; end
@@ -91,11 +91,11 @@
 
       @stderr = $stderr
 
       @thread_key = "rufus_scheduler_#{self.object_id}"
 
-      consider_lockfile || return
+      lock || return
 
       start
     end
 
     # Returns a singleton Rufus::Scheduler instance
@@ -132,11 +132,11 @@
         join_all_work_threads
       elsif opt == :kill
         kill_all_work_threads
       end
 
-      @lockfile.flock(File::LOCK_UN) if @lockfile
+      unlock
     end
 
     alias stop shutdown
 
     def uptime
@@ -156,10 +156,15 @@
       ) unless @thread
 
       @thread.join
     end
 
+    def down?
+
+      ! @started_at
+    end
+
     def paused?
 
       @paused
     end
 
@@ -401,11 +406,29 @@
       else
         [ job(job_or_job_id), job_or_job_id ]
       end
     end
 
-    def consider_lockfile
+    # Returns true if the scheduler has acquired the [exclusive] lock and
+    # thus may run.
+    #
+    # Most of the time, a scheduler is run alone and this method should
+    # return true. It is useful in cases where among a group of applications
+    # only one of them should run the scheduler. For schedulers that should
+    # not run, the method should return false.
+    #
+    # Out of the box, rufus-scheduler proposes the
+    # :lockfile => 'path/to/lock/file' scheduler start option. It makes
+    # it easy for schedulers on the same machine to determine which should
+    # run (to first to write the lockfile and lock it). It uses "man 2 flock"
+    # so it probably won't work reliably on distributed file systems.
+    #
+    # If one needs to use a special/different locking mechanism, providing
+    # overriding implementation for this #lock and the #unlock complement is
+    # easy.
+    #
+    def lock
 
       @lockfile = nil
 
       return true unless f = @opts[:lockfile]
 
@@ -429,9 +452,16 @@
       f.flush
 
       @lockfile = f
 
       true
+    end
+
+    # Sister method to #lock, is called when the scheduler shuts down.
+    #
+    def unlock
+
+      @lockfile.flock(File::LOCK_UN) if @lockfile
     end
 
     def terminate_all_jobs
 
       jobs.each { |j| j.unschedule }