Document TimedStack

lib/connection_pool/timed_stack.rb

@@ -1,10 +1,37 @@
 require 'thread'
 require 'timeout'
 
+##
+# Raised when you attempt to retrieve a connection from a pool that has been
+# shut down.
+#
+# Examples:
+#
+#    ts = TimedStack.new(1) { MyConnection.new }
+#
+#    # fetch a connection
+#    conn = ts.pop
+#
+#    # return a connection
+#    ts.push conn
+#
+#    conn = ts.pop
+#    ts.pop timeout: 5
+#    #=> raises Timeout::Error after 5 seconds
+
 class ConnectionPool::PoolShuttingDownError < RuntimeError; end
 
+##
+# The TimedStack manages a pool of homogeneous connections (or any resource
+# you wish to manage).  Connections are created lazily up to a given maximum
+# number.
+
 class ConnectionPool::TimedStack
 
+  ##
+  # Creates a new pool with +size+ connections that are created from the given
+  # +block+.
+
   def initialize(size = 0, &block)
     @create_block = block
     @created = 0
@@ -15,6 +42,10 @@ class ConnectionPool::TimedStack
     @shutdown_block = nil
   end
 
+  ##
+  # Returns +obj+ to the stack.  +options+ is ignored in TimedStack but may be
+  # used by subclasses that extend TimedStack.
+
   def push(obj, options = {})
     @mutex.synchronize do
       if @shutdown_block
@@ -28,6 +59,15 @@ class ConnectionPool::TimedStack
   end
   alias_method :<<, :push
 
+  ##
+  # Retrieves a connection from the stack.  If a connection is available it is
+  # immediately returned.  If no connection is available within the given
+  # timeout a Timeout::Error is raised.
+  #
+  # +:timeout+ is the only checked entry in +options+ and is preferred over
+  # the +timeout+ argument (which will be removed in a future release).  Other
+  # options may be used by subclasses that extend TimedStack.
+
   def pop(timeout = 0.5, options = {})
     options, timeout = timeout, 0.5 if Hash === timeout
     timeout = options.fetch :timeout, timeout
@@ -48,6 +88,10 @@ class ConnectionPool::TimedStack
     end
   end
 
+  ##
+  # Shuts down the TimedStack which prevents connections from being checked
+  # out.  The +block+ is called once for each connection on the stack.
+
   def shutdown(&block)
     raise ArgumentError, "shutdown must receive a block" unless block_given?
 
@@ -59,36 +103,68 @@ class ConnectionPool::TimedStack
     end
   end
 
+  ##
+  # Returns +true+ if there are no available connections.
+
   def empty?
     (@created - @que.length) >= @max
   end
 
+  ##
+  # The number of connections available on the stack.
+
   def length
     @max - @created + @que.length
   end
 
   private
 
-  def connection_stored?(options = nil) # :nodoc:
+  ##
+  # This is an extension point for TimedStack and is called with a mutex.
+  #
+  # This method must returns true if a connection is available on the stack.
+
+  def connection_stored?(options = nil)
     !@que.empty?
   end
 
-  def fetch_connection(options = nil) # :nodoc:
+  ##
+  # This is an extension point for TimedStack and is called with a mutex.
+  #
+  # This method must return a connection from the stack.
+
+  def fetch_connection(options = nil)
     @que.pop
   end
 
-  def shutdown_connections(options = nil) # :nodoc:
+  ##
+  # This is an extension point for TimedStack and is called with a mutex.
+  #
+  # This method must shut down all connections on the stack.
+
+  def shutdown_connections(options = nil)
     while connection_stored?(options)
       conn = fetch_connection(options)
       @shutdown_block.call(conn)
     end
   end
 
-  def store_connection(obj, options = nil) # :nodoc:
+  ##
+  # This is an extension point for TimedStack and is called with a mutex.
+  #
+  # This method must return +obj+ to the stack.
+
+  def store_connection(obj, options = nil)
     @que.push obj
   end
 
-  def try_create(options = nil) # :nodoc:
+  ##
+  # This is an extension point for TimedStack and is called with a mutex.
+  #
+  # This method must create a connection if and only if the total number of
+  # connections allowed has not been met.
+
+  def try_create(options = nil)
     unless @created == @max
       @created += 1
       @create_block.call