@@ -20,14 +20,39 @@ # THE SOFTWARE. class DaemonController + +# A lock file is a synchronization mechanism, like a Mutex, but it also allows +# inter-process synchronization (as opposed to only inter-thread synchronization +# within a single process). +# +# Processes can obtain either a shared lock or an exclusive lock. It's possible +# for multiple processes to obtain a shared lock on a file as long as no +# exclusive lock has been obtained by a process. If a process has obtained an +# exclusive lock, then no other processes can lock the file, whether they're +# trying to obtain a shared lock or an exclusive lock. class LockFile class AlreadyLocked < StandardError end + # Create a LockFile object. The lock file is initially not locked. + # + # +filename+ may point to a nonexistant file. In that case, the lock + # file will not be created until one's trying to obtain a lock. + # + # Note that LockFile will use this exact filename. So if +filename+ + # is a relative filename, then the actual lock file that will be used + # depends on the current working directory. def initialize(filename) @filename = filename end + # Obtain an exclusive lock on the lock file, yield the given block, + # then unlock the lockfile. If the lock file was already locked (whether + # shared or exclusively) by another process/thread then this method will + # block until the lock file has been unlocked. + # + # The lock file *must* be writable, otherwise an Errno::EACCESS + # exception will be raised. def exclusive_lock File.open(@filename, 'w') do |f| if Fcntl.const_defined? :F_SETFD @@ -38,6 +63,14 @@ class LockFile end end + # Obtain an exclusive lock on the lock file, yield the given block, + # then unlock the lockfile. If the lock file was already exclusively + # locked by another process/thread then this method will + # block until the exclusive lock has been released. This method will not + # block if only shared locks have been obtained. + # + # The lock file *must* be writable, otherwise an Errno::EACCESS + # exception will be raised. def shared_lock File.open(@filename, 'w') do |f| if Fcntl.const_defined? :F_SETFD @@ -48,6 +81,11 @@ class LockFile end end + # Try to obtain a shared lock on the lock file, similar to #shared_lock. + # But unlike #shared_lock, this method will raise AlreadyLocked if + # no lock can be obtained, instead of blocking. + # + # If a lock can be obtained, then the given block will be yielded. def try_shared_lock File.open(@filename, 'w') do |f| if Fcntl.const_defined? :F_SETFD @@ -61,6 +99,11 @@ class LockFile end end + # Try to obtain an exclusive lock on the lock file, similar to #exclusive_lock. + # But unlike #exclusive_lock, this method will raise AlreadyLocked if + # no lock can be obtained, instead of blocking. + # + # If a lock can be obtained, then the given block will be yielded. def try_exclusive_lock File.open(@filename, 'w') do |f| if Fcntl.const_defined? :F_SETFD lib/daemon_controller/lock_file.rb 9ef0263d74e2cf552956d6363b5051193072236a Hongli Lai (Phusion) hongli@phusion.nl http://github.com/FooBarWidget/daemon_controller/commit/9a1fbe6cac534c974a2e139ec7a5cfd8c4c06425 9a1fbe6cac534c974a2e139ec7a5cfd8c4c06425 2009-02-25T05:47:22-08:00 2009-02-25T05:47:22-08:00 Document LockFile. 7f3fdf347567c724b0159fb8148abd3262d1e6a9 Hongli Lai (Phusion) hongli@phusion.nl