reentrant_flock.rb in reentrant_flock-0.1.1

- old
+ new

@@ -9,13 +9,11 @@
     # Note that File#flock is automatically unlocked when a file is closed,
     # but ReentrantFlock.flock cannot automatically reset internal counts
     # when a file is closed. Use ReentrantFlock.synchronize to assure
     # decrementing internal counts.
     #
-    # @param fp [File]
-    # @param operation [PARAM]
-    # @see File#flock for more details
+    # @param [File] fp
     # @param [PARAM] operation See File#flock
     # @return see File#flock
     def flock(fp, operation)
       if (operation & File::LOCK_UN) > 0
         unlock(fp)
@@ -48,11 +46,11 @@
     end
 
     private
 
     # @return [0] if current thread holds the lock
-    # @return [false] if current thread holds the lock
+    # @return [false] if another already locked (LOCK_NB)
     def lock(fp, operation)
       c = incr(key(fp))
       if c <= 1
         # flock returns 0 if successfully locked.
         # LOCK_NB returns false if somebody else already locked
@@ -89,23 +87,24 @@
       Thread.current[key] = nil
     end
   end
 end
 
-# There is a fact that
+# Please note that:
 #
 # ```
 # fp = File.open('a', 'w')
 # fp.flock(File::LOCK_EX)
 # fp.flock(File::LOCK_EX) # does not block
 # fp = File.open('a', 'w')
 # fp.flock(File::LOCK_EX) # block
 # ```
 #
-# That is, File#flock is orginally reentrant for the same
-# file object because its file descriptor has lock information
-# on kernel layer. So, this instance version, which holds an
-# instance of File, may not worth to be prepared.
+# That is, File#flock is orginally reentrant for the same file
+# object. On linux, file lock is associated with file descriptor,
+# so another file descriptor is required to get blocked.
+# This version holds the same file object, so might be useless.
+# I may delete this. Using flock directly should be enough.
 class ReentrantFlock
   attr_reader :fp
 
   def initialize(fp)
     @fp = fp