unixisms.rb in zk-0.9.0

- old
+ new

@@ -3,26 +3,25 @@
     module Unixisms
       include ZookeeperConstants
 
       # Creates all parent paths and 'path' in zookeeper as persistent nodes with
       # zero data.
+      # 
+      # @param [String] path An absolute znode path to create
+      # 
+      # @example
       #
-      # ==== Arguments
-      # * <tt>path</tt>: An absolute znode path to create
-      #
-      # ==== Examples
-      #
       #   zk.exists?('/path')
       #   # => false
       # 
       #   zk.mkdir_p('/path/to/blah')
       #   # => "/path/to/blah"  
       #
-      #--
-      # TODO: write a non-recursive version of this. ruby doesn't have TCO, so
-      # this could get expensive w/ psychotically long paths
       def mkdir_p(path)
+        # TODO: write a non-recursive version of this. ruby doesn't have TCO, so
+        # this could get expensive w/ psychotically long paths
+
         create(path, '', :mode => :persistent)
       rescue Exceptions::NodeExists
         return
       rescue Exceptions::NoNode
         if File.dirname(path) == '/'
@@ -47,25 +46,86 @@
           rescue Exceptions::NoNode
           end
         end
       end
 
-      # see ZK::Find for explanation
+      # Acts in a similar way to ruby's Find class. Performs a depth-first
+      # traversal of every node under the given paths, and calls the given
+      # block with each path found. Like the ruby Find class, you can call
+      # {ZK::Find.prune} to avoid descending further into a given sub-tree
+      #
+      # @example list the paths under a given node
+      #
+      #   zk = ZK.new
+      #   
+      #   paths = %w[
+      #     /root
+      #     /root/alpha
+      #     /root/bravo
+      #     /root/charlie
+      #     /root/charlie/rose
+      #     /root/charlie/manson
+      #     /root/charlie/manson/family
+      #     /root/charlie/manson/murders
+      #     /root/charlie/brown
+      #     /root/delta
+      #     /root/delta/blues
+      #     /root/delta/force
+      #     /root/delta/burke
+      #   ]
+      #   
+      #   paths.each { |p| zk.create(p) }
+      #   
+      #   zk.find('/root') do |path|
+      #     puts path
+      #   
+      #     ZK::Find.prune if path == '/root/charlie/manson'
+      #   end
+      #
+      #   # this produces the output:
+      #
+      #   # /root
+      #   # /root/alpha
+      #   # /root/bravo
+      #   # /root/charlie
+      #   # /root/charlie/brown
+      #   # /root/charlie/manson
+      #   # /root/charlie/rose
+      #   # /root/delta
+      #   # /root/delta/blues
+      #   # /root/delta/burke
+      #   # /root/delta/force
+      #
+      # @param [Array[String]] paths a list of paths to recursively 
+      #   yield the sub-paths of
+      #
+      # @see ZK::Find#find 
       def find(*paths, &block)
         ZK::Find.find(self, *paths, &block)
       end
 
-      # will block the caller until +abs_node_path+ has been removed
+      # Will _safely_ block the caller until `abs_node_path` has been removed.
+      # This is trickier than it first appears. This method will wake the caller
+      # if a session event occurs that would ensure the event would never be
+      # delivered, and also checks to make sure that the caller is not calling
+      # from the event distribution thread (which would cause a deadlock).
       #
-      # @private this method is of dubious value and may be removed in a later
-      #   version
-      #
       # @note this is dangerous to use in callbacks! there is only one
       #   event-delivery thread, so if you use this method in a callback or
       #   watcher, you *will* deadlock!
+      #
+      # @raise [Exceptions::InterruptedSession] If a session event occurs while we're
+      #   blocked waiting for the node to be deleted, an exception that
+      #   mixes in the InterruptedSession module will be raised. 
+      #
       def block_until_node_deleted(abs_node_path)
-        queue = Queue.new
         subs = []
+
+        assert_we_are_not_on_the_event_dispatch_thread!
+
+        raise ArgumentError, "argument must be String-ish, not: #{abs_node_path.inspect}" unless abs_node_path
+
+        queue = Queue.new
 
         node_deletion_cb = lambda do |event|
           if event.node_deleted?
             queue.enq(:deleted) 
           else