fiber_connection_pool 0.3.0 → 0.3.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 11dbf1d76b0a43dd34325a66e350d16d0bd27ded
+  data.tar.gz: b1af865a443903cca63885dc8f3a262e13dc96b6
+SHA512:
+  metadata.gz: 3c6e61ff7b08b2163cf10057c9d2e84be87577e6d5fcdee5e90472f560f77fef2174da09cbe40a0e886bc8b9c580460f7e92a1f2e0d32b965acb2f220004ee4e
+  data.tar.gz: 01659369b1a7079d945c048df1330e6ba02245af2f86e2626014a514dc7e3609f053b6453e9e4f7d68f7aabd8312cbf2d3d29361d8e39609b9fcad6710bcd604

data/README.md

@@ -157,10 +157,14 @@ it from the fiber itself, worry should not.
 Save data
 -------------------
 
-Sometimes we need to get something more than de return value from the `query_me` call, but that _something_ is related to _that_ call on _that_ connection.
-For example, maybe you need to call `affected_rows` right after the query was made on that particular connection.
-If you make that extra calls on the `pool` object, it will acquire a new connection from the pool an run on it. So it's useless.
-There is a way to gather all that data from the connection so we can work on it, but also release the connection for other fiber to use it.
+Sometimes we need to get something more than de return value from the `query_me` call, 
+but that _something_ is related to _that_ call on _that_ connection.
+For example, maybe you need to call `affected_rows` right after the query was 
+made on that particular connection.
+If you make that extra calls on the `pool` object, it will acquire a new connection 
+from the pool an run on it. So it's useless.
+There is a way to gather all that data from the connection so we can work on it, 
+but also release the connection for other fiber to use it.
 
 ``` ruby
 # define the pool
@@ -186,7 +190,8 @@ puts pool.gathered_data
 
 You must access the gathered data from the same fiber that triggered its gathering.
 Also any new call to `query_me` or any other method from the connection would execute the block again,
-overwriting that position on the hash (unless you code to prevent it, of course). Usually you would use the gathered data
+overwriting that position on the hash (unless you code to prevent it, of course). 
+Usually you would use the gathered data
 right after you made the query that generated it. But you could:
 
 ``` ruby
@@ -196,12 +201,58 @@ pool.save_data(:affected_rows) do |connection, method, args|
 end
 ```
 
-You can define as much `save_data` blocks as you want, and run any wonder ruby lets you. But great power comes with great responsability.
+You can define as much `save_data` blocks as you want, and run any wonder ruby lets you. 
+But great power comes with great responsability.
 You must consider that any requests for saving data are executed for _every call_ on the pool from that fiber.
 So keep it stupid simple, and blindly fast. At least as much as you can. That would affect performance otherwise.
 
 Any gathered_data is released when the fiber is dead, but as you must access it from the fiber itself, worry should not.
 
+
+Manual acquire
+-------------------
+
+Sometimes you may need to execute a sequence of methods on the same instance. 
+Then you should use manually acquire the connection from the pool. But then you are entirely
+responsible of releasing it back again into the pool. See this example:
+
+``` ruby
+def transaction
+  @pool.acquire          # reserve one instance for this fiber
+  @pool.query 'BEGIN'    # start SQL transaction
+  
+  yield                  # perform queries inside the transaction
+  
+  @pool.query 'COMMIT'   # confirm it
+rescue => ex
+  @pool.query 'ROLLBACK' # discard it
+  raise ex
+ensure
+  @pool.release          # always release it back
+end
+
+transaction do
+  @pool.query 'UPDATE ...'
+  @pool.query 'SELECT ...'
+end
+```
+
+When you call `acquire`, one connection will be taken out of the pool and reserved for exclusive use
+of the current fiber. Every call you make to the pool from this fiber will be using the same connection instance, 
+until `release` is called. Then it's put back into the pool and made available for the other fibers.
+
+If for some reason `release` is not called, then the connection will remain unavailable for the other
+fibers until the death of the fiber that acquired it. Then it's returned to the pool. That's a garbage 
+collecting mechanism, not to rely on for performance. _You should definitely ensure_ you call `release`.
+
+Notice that when you use `with_failed_connection` you may lose the actual instance. 
+Remember that `with_failed_connection` replaces the failing connection with the return value of the given block.
+Only if you return the same instance you will not lose it. 
+Sometimes even that will not be enough, just look at the `transaction` example. 
+If anything raises before the `COMMIT`, it's not so easy to avoid being forced 
+to start the whole transaction all over again, whether you lost the actual instance or not.
+
+
 Supported Platforms
 -------------------
 

data/lib/fiber_connection_pool.rb

@@ -2,13 +2,13 @@ require 'fiber'
 require_relative 'fiber_connection_pool/exceptions'
 
 class FiberConnectionPool
-  VERSION = '0.3.0'
+  VERSION = '0.3.1'
 
   RESERVED_TTL_SECS = 30 # reserved cleanup trigger
   SAVED_DATA_TTL_SECS = 30 # saved_data cleanup trigger
 
   attr_accessor :saved_data, :treated_exceptions
-  
+
   attr_reader :size
 
   # Initializes the pool with 'size' instances
@@ -18,7 +18,7 @@ class FiberConnectionPool
   #
   def initialize(opts)
     raise ArgumentError.new('size > 0 is mandatory') if opts[:size].to_i <= 0
-    
+
     @size = opts[:size].to_i
 
     @saved_data = {} # placeholder for requested save data
@@ -34,16 +34,6 @@ class FiberConnectionPool
     @available = Array.new(@size) { yield }
   end
 
-  # DEPRECATED: use save_data
-  def save_data_for_fiber
-    nil
-  end
-
-  # DEPRECATED: use release_data
-  def stop_saving_data_for_fiber
-    @saved_data.delete Fiber.current
-  end
-
   # Add a save_data request to the pool.
   # The given block will be executed after each successful
   # call to -any- method on the connection.
@@ -122,16 +112,19 @@ class FiberConnectionPool
   # Raises NoReservedConnection if cannot find the failed connection instance.
   #
   def with_failed_connection
-    bad_conn = @reserved[Fiber.current]
+    fiber = Fiber.current
+    bad_conn = @reserved[fiber]
     raise NoReservedConnection.new if bad_conn.nil?
     new_conn = yield bad_conn
     @available.reject!{ |v| v == bad_conn }
     @reserved.reject!{ |k,v| v == bad_conn }
-    @available.unshift new_conn
-    # try to cleanup
-    begin
-      bad_conn.close
-    rescue
+
+    # we should keep it if manually acquired,
+    # just in case it is still useful
+    if @keep_connection[fiber] then
+      @reserved[fiber] = new_conn
+    else
+      @available.unshift new_conn # or else release into the pool
     end
   end
 
@@ -154,8 +147,19 @@ class FiberConnectionPool
   #
   # Ex:
   #
-  #   ...
+  #    def transaction
+  #      @pool.acquire          # reserve one instance for this fiber
+  #      @pool.query 'BEGIN'    # start SQL transaction
   #
+  #      yield                  # perform queries inside the transaction
+  #
+  #      @pool.query 'COMMIT'   # confirm it
+  #    rescue => ex
+  #      @pool.query 'ROLLBACK' # discard it
+  #      raise ex
+  #    ensure
+  #      @pool.release          # always release it back
+  #    end
   #
   #
   def acquire(fiber = nil, opts = { :keep => true })
@@ -179,7 +183,7 @@ class FiberConnectionPool
   def release(fiber = nil)
     fiber = Fiber.current if fiber.nil?
     @keep_connection.delete fiber
-    
+
     @available.unshift @reserved.delete(fiber)
 
     # try cleanup

metadata

@@ -1,8 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fiber_connection_pool
 version: !ruby/object:Gem::Version
-  version: 0.3.0
-  prerelease: 
+  version: 0.3.1
 platform: ruby
 authors:
 - Ruben Caro
@@ -15,38 +14,35 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: ! "Fiber-based generic connection pool for Ruby, allowing\n                  non-blocking
-  IO behaviour on the same thread\n                  as provided by EventMachine or
-  Celluloid."
+description: |-
+  Fiber-based generic connection pool for Ruby, allowing
+                    non-blocking IO behaviour on the same thread
+                    as provided by EventMachine or Celluloid.
 email:
 - ruben.caro@lanuez.org
 executables: []
@@ -85,27 +81,26 @@ files:
 homepage: https://github.com/rubencaro/fiber_connection_pool
 licenses:
 - GPLv3
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 2.0.6
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Fiber-based generic connection pool for Ruby
 test_files:
 - test/fiber_connection_pool_test.rb