em-pg-client 0.2.1 → 0.3.0

data/Rakefile

@@ -4,40 +4,56 @@ task :default => [:test]
 
 $gem_name = "em-pg-client"
 
-desc "Run spec tests"
-task :test, [:which] do |t, args|
-  args.with_defaults(:which => 'safe')
+def windows_os?
+  RbConfig::CONFIG['host_os'] =~ /cygwin|mswin|mingw|bccwin|wince|emx/
+end
+
+desc "Run tests"
+task :test => :'test:safe'
 
+namespace :test do
   env_common = {'PGDATABASE' => 'test'}
-  env_pg_013 = {'EM_PG_CLIENT_TEST_PG_VERSION' => '= 0.13.2'}
   env_unix_socket = env_common.merge('PGHOST' => '/tmp')
   env_tcpip = env_common.merge('PGHOST' => 'localhost')
 
-  puts "WARNING: The test needs to be run with an available local PostgreSQL server"
+  task :warn do
+    puts "WARNING: The test needs to be run with an available local PostgreSQL server"
+  end
+
+  desc "Run specs only"
+  task :spec do
+    sh "rspec spec/pg_em_featured_deferrable.rb"
+    sh "rspec spec/pg_em_client_options.rb"
+    sh "rspec spec/pg_em_client_connect_finish.rb"
+    sh "rspec spec/pg_em_client_connect_timeout.rb"
+    sh "rspec spec/pg_em_connection_pool.rb"
+  end
 
-  if %w[all safe].include? args[:which]
+  desc "Run safe tests only"
+  task :safe => [:warn, :spec] do
     %w[
-      spec/em_release_client.rb
-      spec/em_devel_client.rb
+      spec/em_client.rb
       spec/em_synchrony_client.rb
     ].each do |spec|
-      sh env_unix_socket, "rspec #{spec}"
+      sh env_unix_socket, "rspec #{spec}" unless windows_os?
       sh env_tcpip, "rspec #{spec}"
-      sh env_pg_013.merge(env_unix_socket), "rspec #{spec}"
-      sh env_pg_013.merge(env_tcpip), "rspec #{spec}"
     end
   end
 
-  if %w[all unsafe dangerous autoreconnect].include? args[:which]
+  desc "Run unsafe tests only"
+  task :unsafe => :warn do
     raise "Set PGDATA environment variable before running the autoreconnect tests." unless ENV['PGDATA']
     %w[
       spec/em_client_autoreconnect.rb
       spec/em_synchrony_client_autoreconnect.rb
     ].each do |spec|
-      sh env_unix_socket, "rspec #{spec}"
+      sh env_unix_socket, "rspec #{spec}" unless windows_os?
       sh env_tcpip, "rspec #{spec}"
     end
   end
+
+  desc "Run safe and unsafe tests"
+  task :all => [:spec, :safe, :unsafe]
 end
 
 desc "Build the gem"
@@ -62,7 +78,7 @@ end
 
 desc "Documentation"
 task :doc do
-  sh "rdoc --encoding=UTF-8 --title=em-pg-client --main=README.rdoc README.rdoc BENCHMARKS.rdoc lib/*/*.rb"
+  sh "yardoc"
 end
 
 desc "Benchmark"

data/em-pg-client.gemspec

@@ -1,26 +1,27 @@
 $:.unshift "lib"
+require 'pg/em-version'
 
 Gem::Specification.new do |s|
   s.name = "em-pg-client"
-  s.version = "0.2.1"
-  s.required_ruby_version = ">= 1.9.1"
+  s.version = PG::EM::VERSION
+  s.required_ruby_version = ">= 1.9.2"
   s.date = "#{Time.now.strftime("%Y-%m-%d")}"
   s.summary = "EventMachine PostgreSQL client"
   s.email = "rafal@yeondir.com"
   s.homepage = "http://github.com/royaltm/ruby-em-pg-client"
+  s.license = "MIT"
   s.require_path = "lib"
   s.description = "PostgreSQL asynchronous EventMachine client, based on pg interface (PG::Connection)"
   s.authors = ["Rafal Michalski"]
   s.files = `git ls-files`.split("\n") - ['.gitignore']
   s.test_files = Dir.glob("spec/**/*")
   s.rdoc_options << "--title" << "em-pg-client" <<
-    "--main" << "README.rdoc"
+    "--main" << "README.md"
   s.has_rdoc = true
-  s.extra_rdoc_files = ["README.rdoc", "BENCHMARKS.rdoc"]
+  s.extra_rdoc_files = ["README.md", "BENCHMARKS.md", "LICENSE", "HISTORY.md"]
   s.requirements << "PostgreSQL server"
-  s.add_runtime_dependency "pg", ">= 0.13.2"
-  s.add_runtime_dependency "eventmachine", ">= 0.12.10"
+  s.add_runtime_dependency "pg", ">= 0.17.0"
+  s.add_runtime_dependency "eventmachine", "~> 1.0.0"
   s.add_development_dependency "rspec", "~> 2.8.0"
-  s.add_development_dependency "eventmachine", ">= 1.0.0.beta.1"
   s.add_development_dependency "em-synchrony", "~> 1.0.0"
 end

data/lib/em-pg-client.rb

@@ -0,0 +1 @@
+require 'pg/em'

data/lib/em-synchrony/pg.rb

@@ -1,108 +1,3 @@
+# for backward compatibility with
+# require 'em-synchrony/pg'
 require 'pg/em'
-module PG
-  module EM
-    class Client
-      # Author:: Rafal Michalski (mailto:royaltm75@gmail.com)
-      # Licence:: MIT License
-      #
-      # =PostgreSQL Client for EM-Synchrony/Fibered EventMachine
-      #
-
-      # conform to *standard*
-      alias_method :aquery, :async_query
-
-      # fiber aware methods:
-      # - exec (aliased as query)
-      # - exec_prepared
-      # - prepare
-      # - describe_prepared
-      # - describe_portal
-      # - reset
-      # - Client.connect
-      %w(exec
-         exec_prepared
-         prepare
-         describe_prepared
-         describe_portal
-         reset
-         self.connect).each do |name|
-        async_name = "async_#{name.split('.').last}"
-        blocking_call = case name
-        when 'reset'
-          '@async_command_aborted = false
-            super(*args, &blk)'
-        else
-          'super(*args, &blk)'
-        end
-        clear_method = case name
-        when 'reset', 'self.connect'
-          'finish'
-        else
-          'clear'
-        end
-        class_eval <<-EOD
-          def #{name}(*args, &blk)
-            if ::EM.reactor_running?
-              f = Fiber.current
-              #{async_name}(*args) do |res|
-                f.resume(res)
-              end
-
-              result = Fiber.yield
-              raise result if result.is_a?(::Exception)
-              if block_given?
-                begin
-                  yield result
-                ensure
-                  result.#{clear_method}
-                end
-              else
-                result
-              end
-            else
-              #{blocking_call}
-            end
-          end
-        EOD
-      end
-
-      class << self
-        alias_method :new, :connect
-        alias_method :open, :connect
-        alias_method :setdb, :connect
-        alias_method :setdblogin, :connect
-      end
-
-      alias_method :query, :exec
-
-      def async_autoreconnect!(deferrable, error, &send_proc)
-         if async_autoreconnect && self.status != PG::CONNECTION_OK
-          reset_df = async_reset
-          reset_df.errback { |ex| deferrable.fail(ex) }
-          reset_df.callback do
-            Fiber.new do
-              if on_autoreconnect
-                returned_df = on_autoreconnect.call(self, error)
-                if returned_df == false
-                  ::EM.next_tick { deferrable.fail(error) }
-                elsif returned_df.respond_to?(:callback) && returned_df.respond_to?(:errback)
-                  returned_df.callback { deferrable.protect(&send_proc) }
-                  returned_df.errback { |ex| deferrable.fail(ex) }
-                elsif returned_df.is_a?(Exception)
-                  ::EM.next_tick { deferrable.fail(returned_df) }
-                else
-                  deferrable.protect(&send_proc)
-                end
-              else
-                deferrable.protect(&send_proc)
-              end
-            end.resume
-          end
-        else
-          ::EM.next_tick { deferrable.fail(error) }
-        end
-      end
-
-    end
-  end
-end

data/lib/pg/em-version.rb

@@ -0,0 +1,5 @@
+module PG
+  module EM
+    VERSION = '0.3.0'
+  end
+end

data/lib/pg/em.rb

@@ -1,3 +1,4 @@
+require 'fiber'
 begin
   require 'pg'
 rescue LoadError => error
@@ -10,366 +11,387 @@ unless defined? EventMachine
     raise 'Missing EventMachine: gem install eventmachine'
   end
 end
+require 'pg/em-version'
+require 'pg/em/featured_deferrable'
+require 'pg/em/client/watcher'
+require 'pg/em/client/connect_watcher'
 
 module PG
-
   module EM
-    class FeaturedDeferrable < ::EM::DefaultDeferrable
-      def initialize(&blk)
-        if block_given?
-          callback(&blk)
-          errback(&blk)
-        end
-      end
-      
-      def protect(fail_value = nil)
-        yield
-      rescue Exception => e
-        ::EM.next_tick { fail(e) }
-        fail_value
-      end
-      
-      def protect_and_succeed(fail_value = nil)
-        ret = yield
-      rescue Exception => e
-        ::EM.next_tick { fail(e) }
-        fail_value
-      else
-        ::EM.next_tick { succeed(ret) }
-        ret
-      end
-    end
+
     # == PostgreSQL EventMachine client
     #
-    # Author:: Rafal Michalski (mailto:royaltm75@gmail.com)
-    # Licence:: MIT License
+    # Author:: Rafal Michalski
     #
+    # {PG::EM::Client} is a PG::Connection[http://deveiate.org/code/pg/PG/Connection.html]
+    # wrapper designed for EventMachine[http://rubyeventmachine.com/].
     #
-    # PG::EM::Client is a wrapper for PG::Connection[http://deveiate.org/code/pg/PG/Connection.html]
-    # which (re)defines methods:
+    # The following new methods:
     #
-    # - +async_exec+ (alias: +async_query+)
-    # - +async_prepare+
-    # - +async_exec_prepared+
-    # - +async_describe_prepared+
-    # - +async_describe_portal+
+    # - {#exec_defer} (alias: +query_defer+)
+    # - {#exec_params_defer}
+    # - {#prepare_defer}
+    # - {#exec_prepared_defer}
+    # - {#describe_prepared_defer}
+    # - {#describe_portal_defer}
     #
-    # which are suitable to run in EM event loop (they return +Deferrable+)
+    # are added to execute queries asynchronously,
+    # returning +Deferrable+ object.
     #
-    # and following:
+    # The following methods of PG::Connection[http://deveiate.org/code/pg/PG/Connection.html]
+    # are overloaded:
     #
-    # - +exec+ (alias: +query+)
-    # - +prepare+
-    # - +exec_prepared+
-    # - +describe_prepared+
-    # - +describe_portal+
+    # - {#exec} (alias: +query+, +async_exec+, +async_query+)
+    # - {#exec_params}
+    # - {#prepare}
+    # - {#exec_prepared}
+    # - {#describe_prepared}
+    # - {#describe_portal}
     #
-    # autodetecting if EventMachine is running and using the appropriate
-    # (async or sync) method version.
+    # and are now auto-detecting if EventMachine is running and
+    # performing commands asynchronously (blocking only current fiber) or
+    # calling parent thread-blocking methods.
     #
-    # Additionally to the above, there are asynchronous methods defined for
-    # establishing connection and re-connecting:
+    # If {#async_autoreconnect} option is set to +true+, all of the above
+    # methods (in asynchronous mode) try to re-connect after a connection
+    # error occurs. It's performed behind the scenes, so no error is raised,
+    # except if there was a transaction in progress. In such instance the error
+    # is raised after establishing connection to signal that
+    # the transaction was aborted.
     #
-    # - +Client.async_connect+
-    # - +async_reset+
-    #
-    # They are async equivalents of PG::Connection.connect (which is also
-    # aliased by PG::Connection as +new+, +open+, +setdb+, +setdblogin+) and
-    # +reset+.
-    #
-    # When #async_autoreconnect is +true+, async methods might try to
-    # re-connect after a connection error. You won't even notice that
-    # (except for warning message from PG).
-    # If you want to detect such event use #on_autoreconnect property.
+    # If you want to detect auto re-connect event use {#on_autoreconnect}
+    # property/option.
     #
     # To enable auto-reconnecting set:
     #   client.async_autoreconnect = true
     #
-    # or pass as new() hash argument:
-    #   ::new database: 'bar', async_autoreconnect: true
+    # or pass as {new} hash argument:
+    #   PG::EM::Client.new dbname: 'bar', async_autoreconnect: true
+    #
+    # There are also new methods:
+    #
+    # - {Client.connect_defer}
+    # - {#reset_defer}
+    #
+    # which are asynchronous versions of PG::Connection.new and
+    # PG:Connection#reset.
+    #
+    # Additionally the following methods are overloaded:
+    #
+    # - {new} (alias: +connect+, +open+, +setdb+, +setdblogin+ )
+    # - {#reset}
+    #
+    # providing auto-detecting asynchronous (fiber-synchronized) or
+    # thread-blocking methods for (re)connecting.
     #
     # Otherwise nothing changes in PG::Connection API.
     # See PG::Connection[http://deveiate.org/code/pg/PG/Connection.html] docs
-    # for arguments to above methods.
+    # for explanation of arguments to the above methods.
     #
     # *Warning:*
     #
-    # +describe_prepared+ and +exec_prepared+ after
-    # +prepare+ should only be invoked on the *same* connection.
-    # If you are using a connection pool, make sure to acquire single connection first.
+    # {#describe_prepared} and {#exec_prepared} after
+    # {#prepare} should only be invoked on the *same* connection.
+    # If you are using a connection pool, make sure to acquire a single
+    # connection first.
     #
     class Client < PG::Connection
 
+      ROOT_FIBER = Fiber.current
 
-      # Connection timeout. Changing this property only affects
-      # ::async_connect and #async_reset.
-      # However if passed as initialization option, it also affects blocking
-      # ::new and #reset.
+      # @!attribute connect_timeout
+      #   @return [Float] connection timeout in seconds
+      #   Connection timeout. Affects {#reset} and {#reset_defer}.
+      #
+      #   Changing this property does not affect thread-blocking {#reset}.
+      #
+      #   However if passed as initialization option, it also affects blocking
+      #   {#reset}.
+      #
+      #   To enable it set to some positive value. To disable it: set to 0.
+      #   You can also specify this as an option to {new} or {connect_defer}.
       attr_accessor :connect_timeout
 
-      # Aborts async command processing if waiting for response from server
-      # exceedes +query_timeout+ seconds. This does not apply to
-      # ::async_connect and #async_reset. For them
-      # use +connect_timeout+ instead.
+      # @!attribute query_timeout
+      #   @return [Float] query timeout in seconds
+      #   Aborts async command processing if server response time
+      #   exceedes +query_timeout+ seconds. This does not apply to
+      #   {#reset} and {#reset_defer}.
       #
-      # To enable it set to seconds (> 0). To disable: set to 0.
-      # You can also specify this as initialization option.
+      #   To enable it set to some positive value. To disable it: set to 0.
+      #   You can also specify this as an option to {new} or {connect_defer}.
       attr_accessor :query_timeout
 
-      # Enable/disable auto-reconnect feature (+true+/+false+).
-      # Defaults to +false+. However it is implicitly set to +true+
-      # if #on_autoreconnect is specified as initialization option.
-      # Changing #on_autoreconnect with accessor method doesn't change
-      # #async_autoreconnect.
+      # @!attribute async_autoreconnect
+      #   @return [Boolean] asynchronous auto re-connect status
+      #   Enable/disable auto re-connect feature (+true+/+false+).
+      #   Defaults to +false+ unless {#on_autoreconnect} is specified
+      #   as an initialization option.
+      #
+      #   Changing {#on_autoreconnect} with accessor method doesn't change
+      #   the state of {#async_autoreconnect}.
+      #
+      #   You can also specify this as an option to {new} or {connect_defer}.
       attr_accessor :async_autoreconnect
 
-      # +on_autoreconnect+ is a user defined Proc that is called after a connection
-      # with the server has been re-established.
-      # It's invoked with two arguments. First one is the +connection+.
-      # The second is the original +exception+ that caused the reconnecting process.
+      # @!attribute on_autoreconnect
+      #   @return [Proc<Client, Error>] auto re-connect hook
+      #   Proc that is called after a connection with the server has been
+      #   automatically re-established. It's being invoked just before the
+      #   pending command is sent to the server.
+      #
+      #   The first argument it receives is the +connection+ instance.
+      #   The second is the original +exception+ that caused the reconnecting
+      #   process.
+      #
+      #   The proc can control the later action with its return value:
       #
-      # Certain rules should apply to #on_autoreconnect proc:
+      #   - +false+ (explicitly, +nil+ is ignored) - the original +exception+
+      #     is raised/passed back and the pending query command is not sent
+      #     again to the server.
+      #   - +true+ (explicitly, truish values are ignored), the pending command
+      #     is called regardless of the connection's last transaction status.
+      #   - Exception object - is raised/passed back and the pending command
+      #     is not sent.
+      #   - Deferrable object - the chosen action will depend on the deferred
+      #     status.
+      #   - Other values are ignored and the pending query command is
+      #     immediately sent to the server unless there was a pending
+      #     transaction before the connection was reset.
       #
-      # - If proc returns +false+ (explicitly, +nil+ is ignored),
-      #   the original +exception+ is passed to Defferable's +errback+ and
-      #   the send query command is not invoked at all.
-      # - If return value is an instance of exception, it is passed to
-      #   Defferable's +errback+ and the send query command is not invoked at all.
-      # - If return value responds to +callback+ and +errback+ methods,
-      #   the send query command will be bound to value's success +callback+
-      #   and the original Defferable's +errback+ or value's +errback+.
-      # - Other return values are ignored and the send query command is called
-      #   immediately after #on_autoreconnect proc is executed.
+      #   It's possible to execute queries from inside of the proc.
       #
-      # You may pass this proc as +:on_autoreconnect+ option to ::new.
+      #   You may pass this proc as an option to {new} or {connect_defer}.
       #
-      # Example:
-      #   pg.on_autoreconnect = proc do |conn, ex|
-      #     conn.prepare("species_by_name", 
-      #      "select id, name from animals where species=$1 order by name")
-      #   end
+      #   @example How to use prepare in on_autoreconnect hook
+      #     pg.on_autoreconnect = proc do |conn, ex|
+      #       conn.prepare("species_by_name", 
+      #        "select id, name from animals where species=$1 order by name")
+      #     end
       #
       attr_accessor :on_autoreconnect
 
+      # @!visibility private
       # Used internally for marking connection as aborted on query timeout.
       attr_accessor :async_command_aborted
 
-      module Watcher
-        def initialize(client, deferrable, send_proc)
-          @last_result = nil
-          @client = client
-          @deferrable = deferrable
-          @send_proc = send_proc
-          if (timeout = client.query_timeout) > 0
-            @notify_timestamp = Time.now
-            setup_timer timeout
-          else
-            @timer = nil
-          end
-        end
+      # environment variable name for connect_timeout fallback value
+      @@connect_timeout_envvar = conndefaults.find{|d| d[:keyword] == "connect_timeout" }[:envvar]
 
-        def setup_timer(timeout, adjustment = 0)
-          @timer = ::EM::Timer.new(timeout - adjustment) do
-            if (last_interval = Time.now - @notify_timestamp) >= timeout
-              detach
-              @client.async_command_aborted = true
-              @deferrable.protect do
-                raise PG::Error, "query timeout expired (async)"
-              end
-            else
-              setup_timer timeout, last_interval
-            end
-          end
-        end
-
-        def notify_readable
-          result = false
-          @client.consume_input
-          until @client.is_busy
-            if (single_result = @client.get_result).nil?
-              if (result = @last_result).nil?
-                error = PG::Error.new(@client.error_message)
-                error.instance_variable_set(:@connection, @client)
-                raise error
-              end
-              result.check
-              detach
-              @timer.cancel if @timer
-              break
-            end
-            @last_result.clear if @last_result
-            @last_result = single_result
-          end
-        rescue Exception => e
-          detach
-          @timer.cancel if @timer
-          if e.is_a?(PG::Error)
-            @client.async_autoreconnect!(@deferrable, e, &@send_proc)
-          else
-            @deferrable.fail(e)
-          end
-        else
-          if result == false
-            @notify_timestamp = Time.now if @timer
-          else
-            @deferrable.succeed(result) 
-          end
-        end
-      end
-
-      module ConnectWatcher
-        def initialize(client, deferrable, poll_method)
-          @client = client
-          @deferrable = deferrable
-          @poll_method = :"#{poll_method}_poll"
-          if (timeout = client.connect_timeout) > 0
-            @timer = ::EM::Timer.new(timeout) do
-              begin
-                detach
-                @deferrable.protect do
-                  raise PG::Error, "timeout expired (async)"
-                end
-              ensure
-                @client.finish unless reconnecting?
-              end
-            end
-          end
-        end
-
-        def reconnecting?
-          @poll_method == :reset_poll
-        end
+      DEFAULT_ASYNC_VARS = {
+        :@async_autoreconnect => nil,
+        :@connect_timeout => nil,
+        :@query_timeout => 0,
+        :@on_autoreconnect => nil,
+        :@async_command_aborted => false,
+      }.freeze
 
-        def notify_writable
-          poll_connection_and_check
-        end
-
-        def notify_readable
-          poll_connection_and_check
-        end
-
-        def poll_connection_and_check
-          case @client.__send__(@poll_method)
-          when PG::PGRES_POLLING_READING
-            self.notify_readable = true
-            self.notify_writable = false
-          when PG::PGRES_POLLING_WRITING
-            self.notify_writable = true
-            self.notify_readable = false
-          when PG::PGRES_POLLING_OK, PG::PGRES_POLLING_FAILED
-            @timer.cancel if @timer
-            detach
-            @deferrable.protect_and_succeed do
-              unless @client.status == PG::CONNECTION_OK
-                begin
-                  raise PG::Error, @client.error_message
-                ensure
-                  @client.finish unless reconnecting?
-                end
-              end
-              # mimic blocking connect behavior
-              @client.set_default_encoding unless reconnecting?
-              @client
-            end
-          end
-        end
-      end
-
-      def self.parse_async_args(args)
-        async_args = {
-          :@async_autoreconnect => nil,
-          :@connect_timeout => 0,
-          :@query_timeout => 0,
-          :@on_autoreconnect => nil,
-          :@async_command_aborted => false,
-        }
+      # @!visibility private
+      def self.parse_async_options(args)
+        options = DEFAULT_ASYNC_VARS.dup
         if args.last.is_a? Hash
           args[-1] = args.last.reject do |key, value|
-            case key.to_s
-            when 'async_autoreconnect'
-              async_args[:@async_autoreconnect] = !!value
+            case key.to_sym
+            when :async_autoreconnect
+              options[:@async_autoreconnect] = value
               true
-            when 'on_reconnect'
-              raise ArgumentError.new("on_reconnect is no longer supported, use on_autoreconnect")
-            when 'on_autoreconnect'
+            when :on_reconnect
+              raise ArgumentError, "on_reconnect is no longer supported, use on_autoreconnect"
+            when :on_autoreconnect
               if value.respond_to? :call
-                async_args[:@on_autoreconnect] = value
-                async_args[:@async_autoreconnect] = true if async_args[:@async_autoreconnect].nil?
+                options[:@on_autoreconnect] = value
+                options[:@async_autoreconnect] = true if options[:@async_autoreconnect].nil?
+              else
+                raise ArgumentError, "on_autoreconnect must respond to `call'"
               end
               true
-            when 'connect_timeout'
-              async_args[:@connect_timeout] = value.to_f
+            when :connect_timeout
+              options[:@connect_timeout] = value.to_f
               false
-            when 'query_timeout'
-              async_args[:@query_timeout] = value.to_f
+            when :query_timeout
+              options[:@query_timeout] = value.to_f
               true
             end
           end
         end
-        async_args[:@async_autoreconnect] = false if async_args[:@async_autoreconnect].nil?
-        async_args
+        options[:@async_autoreconnect] = !!options[:@async_autoreconnect]
+        options[:@connect_timeout] ||= ENV[@@connect_timeout_envvar].to_f
+        options
       end
 
+      # @!group Deferrable connection methods
+
       # Attempts to establish the connection asynchronously.
-      # For args see PG::Connection.new[http://deveiate.org/code/pg/PG/Connection.html#method-c-new].
-      # Returns +Deferrable+. Use its +callback+ to obtain newly created and
-      # already connected PG::EM::Client object.
-      # If block is provided, it's bound to +callback+ and +errback+ of returned
-      # +Deferrable+.
-      #
-      # Special PG::EM::Client options (e.g.: +async_autoreconnect+) must be provided
-      # as +connection_hash+ argument variant. They will be ignored in +connection_string+.
-      # 
-      # +client_encoding+ *will* be set for you according to Encoding.default_internal.
-      def self.async_connect(*args, &blk)
+      #
+      # @return [FeaturedDeferrable]
+      # @yieldparam pg [Client|PG::Error] new and connected client instance on
+      #                             success or an instance of raised PG::Error
+      #
+      # Pass the block to the returned deferrable's +callback+ to obtain newly
+      # created and already connected {Client} object. In case of connection
+      # error +errback+ hook receives an error object as an argument.
+      # If the block is provided it's bound to both +callback+ and +errback+
+      # hooks of the returned deferrable.
+      #
+      # Special {Client} options (e.g.: {#async_autoreconnect}) must be
+      # provided as +connection_hash+ argument variant. They will be ignored
+      # if passed as a +connection_string+.
+      #
+      # +client_encoding+ *will* be set according to +Encoding.default_internal+.
+      #
+      # @see http://deveiate.org/code/pg/PG/Connection.html#method-c-new PG::Connection.new
+      def self.connect_defer(*args, &blk)
         df = PG::EM::FeaturedDeferrable.new(&blk)
-        async_args = parse_async_args(args)
+        async_args = parse_async_options(args)
         conn = df.protect { connect_start(*args) }
         if conn
           async_args.each {|k, v| conn.instance_variable_set(k, v) }
-          ::EM.watch(conn.socket, ConnectWatcher, conn, df, :connect).poll_connection_and_check
+          ::EM.watch(conn.socket_io, ConnectWatcher, conn, df, false).
+            poll_connection_and_check
         end
         df
       end
 
+      class << self
+        # @deprecated Use {connect_defer} instead.
+        alias_method :async_connect, :connect_defer
+      end
+
       # Attempts to reset the connection asynchronously.
-      # There are no arguments, except block argument.
       #
-      # Returns +Deferrable+. Use it's +callback+ to handle success.
-      # If block is provided, it's bound to +callback+ and +errback+ of returned
-      # +Deferrable+.
-      def async_reset(&blk)
+      # @return [FeaturedDeferrable]
+      # @yieldparam pg [Client|PG::Error] reconnected client instance on
+      #                             success or an instance of raised PG::Error
+      #
+      # Pass the block to the returned deferrable's +callback+ to execute
+      # after successfull reset.
+      # If the block is provided it's bound to +callback+ and +errback+ hooks
+      # of the returned deferrable.
+      def reset_defer(&blk)
         @async_command_aborted = false
         df = PG::EM::FeaturedDeferrable.new(&blk)
+        # there can be only one watch handler over the socket
+        # apparently eventmachine has hard time dealing with more than one
+        # for blocking reset this is not needed
+        if @watcher
+          @watcher.detach if @watcher.watching?
+          @watcher = nil
+        end
         ret = df.protect(:fail) { reset_start }
         unless ret == :fail
-          ::EM.watch(self.socket, ConnectWatcher, self, df, :reset).poll_connection_and_check
+          ::EM.watch(self.socket_io, ConnectWatcher, self, df, true).
+            poll_connection_and_check
         end
         df
       end
 
-      # Uncheck #async_command_aborted on blocking reset.
+      # @deprecated Use {reset_defer} instead.
+      alias_method :async_reset, :reset_defer
+
+      # @!endgroup
+
+      # @!group Auto-sensing fiber-synchronized connection methods
+
+      # Attempts to reset the connection.
+      #
+      # Performs command asynchronously yielding from current fiber
+      # if EventMachine reactor is running and current fiber isn't the root
+      # fiber. Other fibers can process while waiting for the server to
+      # complete the request.
+      #
+      # Otherwise performs a thread-blocking call to the parent method.
+      #
+      # @raise [PG::Error]
+      #
+      # @see http://deveiate.org/code/pg/PG/Connection.html#method-i-reset PG::Connection#reset
       def reset
         @async_command_aborted = false
-        super
+        if ::EM.reactor_running? && !(f = Fiber.current).equal?(ROOT_FIBER)
+          reset_defer {|r| f.resume(r) }
+
+          conn = Fiber.yield
+          raise conn if conn.is_a?(::Exception)
+          conn
+        else
+          super
+        end
       end
 
-      # Creates new instance of PG::EM::Client and attempts to establish connection.
-      # See PG::Connection.new[http://deveiate.org/code/pg/PG/Connection.html#method-c-new].
+      # Creates new instance of PG::EM::Client and attempts to establish
+      # connection.
       #
-      # Special PG::EM::Client options (e.g.: +async_autoreconnect+) must be provided
-      # as +connection_hash+ argument variant. They will be ignored in +connection_string+.
-      # 
-      # +em-synchrony+ version *will* do set +client_encoding+ for you according to
-      # Encoding.default_internal.
+      # Performs command asynchronously yielding from current fiber
+      # if EventMachine reactor is running and current fiber isn't the root
+      # fiber. Other fibers can process while waiting for the server to
+      # complete the request.
+      #
+      # Otherwise performs a thread-blocking call to the parent method.
+      #
+      # @raise [PG::Error]
+      #
+      # Special {Client} options (e.g.: {#async_autoreconnect}) must be
+      # provided as +connection_hash+ argument variant. They will be ignored
+      # if passed as a +connection_string+.
+      #
+      # +client_encoding+ *will* be set according to +Encoding.default_internal+.
+      #
+      # @see http://deveiate.org/code/pg/PG/Connection.html#method-c-new PG::Connection.new
+      def self.new(*args, &blk)
+        if ::EM.reactor_running? && !(f = Fiber.current).equal?(ROOT_FIBER)
+          connect_defer(*args) {|r| f.resume(r) }
+
+          conn = Fiber.yield
+          raise conn if conn.is_a?(::Exception)
+          if block_given?
+            begin
+              yield conn
+            ensure
+              conn.finish
+            end
+          else
+            conn
+          end
+        else
+          super(*args)
+        end
+      end
+
+      # @!visibility private
       def initialize(*args)
-        Client.parse_async_args(args).each {|k, v| self.instance_variable_set(k, v) }
+        Client.parse_async_options(args).each {|k, v| instance_variable_set(k, v) }
         super(*args)
       end
 
-      # Return +CONNECTION_BAD+ for connections with +async_command_aborted+
-      # flag set by expired query timeout. Otherwise return whatever
-      # PG::Connection#status[http://deveiate.org/code/pg/PG/Connection.html#method-i-status] provides.
+      class << self
+        alias_method :connect,    :new
+        alias_method :open,       :new
+        alias_method :setdb,      :new
+        alias_method :setdblogin, :new
+      end
+
+      # @!endgroup
+
+      # Closes the backend connection.
+      #
+      # Detaches watch handler to prevent memory leak then
+      # calls parent PG::Connection#finish[http://deveiate.org/code/pg/PG/Connection.html#method-i-finish].
+      # @see http://deveiate.org/code/pg/PG/Connection.html#method-i-finish PG::Connection#finish
+      def finish
+        super
+        if @watcher
+          @watcher.detach if @watcher.watching?
+          @watcher = nil
+        end
+      end
+
+      alias_method :close, :finish
+
+      # Returns status of connection: PG::CONNECTION_OK or PG::CONNECTION_BAD.
+      #
+      # @return [Number]
+      # Returns +PG::CONNECTION_BAD+ for connections with +async_command_aborted+
+      # flag set by expired query timeout. Otherwise return whatever PG::Connection#status returns.
+      # @see http://deveiate.org/code/pg/PG/Connection.html#method-i-status PG::Connection#status
       def status
         if @async_command_aborted
           PG::CONNECTION_BAD
@@ -378,53 +400,155 @@ module PG
         end
       end
 
-      # Perform autoreconnect. Used internally.
+      # @!visibility private
+      # Perform auto re-connect. Used internally.
       def async_autoreconnect!(deferrable, error, &send_proc)
-        if async_autoreconnect && self.status != PG::CONNECTION_OK
-          reset_df = async_reset
-          reset_df.errback { |ex| deferrable.fail(ex) }
+        # reconnect only if connection is bad and flag is set
+        if self.status != PG::CONNECTION_OK && async_autoreconnect
+          # check if transaction was active
+          was_in_transaction = case @last_transaction_status
+          when PG::PQTRANS_IDLE, PG::PQTRANS_UNKNOWN
+            false
+          else
+            true
+          end
+          # reset asynchronously
+          reset_df = reset_defer
+          # just fail on reset failure
+          reset_df.errback { |ex| deferrable.fail ex }
+          # reset succeeds
           reset_df.callback do
+            # handle on_autoreconnect
             if on_autoreconnect
-              returned_df = on_autoreconnect.call(self, error)
-              if returned_df == false
-                ::EM.next_tick { deferrable.fail(error) }
-              elsif returned_df.respond_to?(:callback) && returned_df.respond_to?(:errback)
-                returned_df.callback { deferrable.protect(&send_proc) }
-                returned_df.errback { |ex| deferrable.fail(ex) }
-              elsif returned_df.is_a?(Exception)
-                ::EM.next_tick { deferrable.fail(returned_df) }
-              else
-                deferrable.protect(&send_proc)
-              end
+              # wrap in a fiber, so on_autoreconnect code may yield from it
+              Fiber.new do
+                # call on_autoreconnect handler and fail if it raises an error
+                returned_df = begin
+                  on_autoreconnect.call(self, error)
+                rescue => ex
+                  ex
+                end
+                if returned_df.respond_to?(:callback) && returned_df.respond_to?(:errback)
+                  # the handler returned a deferrable
+                  returned_df.callback do
+                    if was_in_transaction
+                      # there was a transaction in progress, fail anyway
+                      deferrable.fail error
+                    else
+                      # try to call failed query command again
+                      deferrable.protect(&send_proc)
+                    end
+                  end
+                  # fail when handler's deferrable fails
+                  returned_df.errback { |ex| deferrable.fail ex }
+                elsif returned_df.is_a?(Exception)
+                  # tha handler returned an exception object, so fail with it
+                  deferrable.fail returned_df
+                elsif returned_df == false || (was_in_transaction && returned_df != true)
+                  # tha handler returned false or raised an exception
+                  # or there was an active transaction and handler didn't return true
+                  deferrable.fail error
+                else
+                  # try to call failed query command again
+                  deferrable.protect(&send_proc)
+                end
+              end.resume
+            elsif was_in_transaction
+              # there was a transaction in progress, fail anyway
+              deferrable.fail error
             else
+              # no on_autoreconnect handler, no transaction, then
+              # try to call failed query command again
               deferrable.protect(&send_proc)
             end
           end
         else
-          ::EM.next_tick { deferrable.fail(error) }
+          # connection is good, or the async_autoreconnect is not set
+          deferrable.fail error
         end
       end
 
+      # @!macro deferrable_api
+      #   @yieldparam result [PG::Result|Error] command result on success or a PG::Error instance on error.
+      #   @return [FeaturedDeferrable]
+      #   Use the returned deferrable's +callback+ and +errback+ method to get the result.
+      #   If the block is provided it's bound to both the +callback+ and +errback+ hooks
+      #   of the returned deferrable.
+
+      # @!group Deferrable command methods
+
+      # @!method exec_defer(sql, params=nil, result_format=nil, &blk)
+      #   Sends SQL query request specified by +sql+ to PostgreSQL for asynchronous processing,
+      #   and immediately returns with +deferrable+.
+      #
+      #   @macro deferrable_api
+      #
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-exec PG::Connection#exec
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-exec_params PG::Connection#exec_params
+      #
+      # @!method prepare_defer(stmt_name, sql, param_types=nil, &blk)
+      #   Prepares statement +sql+ with name +stmt_name+ to be executed later asynchronously,
+      #   and immediately returns with deferrable.
+      #
+      #   @macro deferrable_api
+      #
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-prepare PG::Connection#prepare
+      #
+      # @!method exec_prepared_defer(statement_name, params=nil, result_format=nil, &blk)
+      #   Execute prepared named statement specified by +statement_name+ asynchronously,
+      #   and immediately returns with deferrable.
+      #
+      #   @macro deferrable_api
+      #
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-send_query_prepared PG::Connection#send_query_prepared
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-exec_prepared PG::Connection#send_exec_prepared
+      #
+      # @!method describe_prepared_defer(statement_name, &blk)
+      #   Asynchronously sends command to retrieve information about the prepared statement +statement_name+,
+      #   and immediately returns with deferrable.
+      #
+      #   @macro deferrable_api
+      #
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-describe_prepared PG::Connection#describe_prepared
+      #
+      # @!method describe_portal_defer(portal_name, &blk)
+      #   Asynchronously sends command to retrieve information about the portal +portal_name+,
+      #   and immediately returns with deferrable.
+      #
+      #   @macro deferrable_api
+      #
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-describe_portal PG::Connection#describe_portal
+      #
       %w(
-        exec              send_query
-        prepare           send_prepare
-        exec_prepared     send_query_prepared
-        describe_prepared send_describe_prepared
-        describe_portal   send_describe_portal
-          ).each_slice(2) do |name, send_name|
-
-        class_eval <<-EOD
-        def async_#{name}(*args, &blk)
+        exec_defer              send_query
+        prepare_defer           send_prepare
+        exec_prepared_defer     send_query_prepared
+        describe_prepared_defer send_describe_prepared
+        describe_portal_defer   send_describe_portal
+      ).each_slice(2) do |defer_name, send_name|
+
+        class_eval <<-EOD, __FILE__, __LINE__
+        def #{defer_name}(*args, &blk)
           df = PG::EM::FeaturedDeferrable.new(&blk)
           send_proc = proc do
             #{send_name}(*args)
-            ::EM.watch(self.socket, Watcher, self, df, send_proc).notify_readable = true
+            if @watcher && @watcher.watching?
+              @watcher.watch_query(df, send_proc)
+            else
+              @watcher = ::EM.watch(self.socket_io, Watcher, self).
+                            watch_query(df, send_proc)
+            end
           end
           begin
-            raise PG::Error, "previous query expired, need connection reset" if @async_command_aborted
+            if @async_command_aborted
+              error = ConnectionBad.new("previous query expired, need connection reset")
+              error.instance_variable_set(:@connection, self)
+              raise error
+            end
+            @last_transaction_status = transaction_status
             send_proc.call
           rescue PG::Error => e
-            async_autoreconnect!(df, e, &send_proc)
+            ::EM.next_tick { async_autoreconnect!(df, e, &send_proc) }
           rescue Exception => e
             ::EM.next_tick { df.fail(e) }
           end
@@ -432,61 +556,231 @@ module PG
         end
         EOD
 
-        class_eval <<-EOD
-        def #{name}(*args, &blk)
-          if ::EM.reactor_running?
-            async_#{name}(*args, &blk)
-          else
-            super(*args, &blk)
-          end
-        end
-        EOD
-
       end
 
-      alias_method :query, :exec
-      alias_method :async_query, :async_exec
+      alias_method :query_defer,       :exec_defer
+      alias_method :async_query_defer, :exec_defer
+      alias_method :async_exec_defer,  :exec_defer
+      alias_method :exec_params_defer, :exec_defer
+
+      # @!endgroup
+
+      # @!macro auto_synchrony_api
+      #   Performs command asynchronously yielding current fiber
+      #   if EventMachine reactor is running and the current fiber isn't the
+      #   root fiber. Other fibers can process while waiting for the server
+      #   to complete the request.
+      #
+      #   Otherwise performs a blocking call to parent method.
+      #
+      #   @yieldparam result [PG::Result] command result on success
+      #   @return [PG::Result] if block wasn't given
+      #   @return [Object] result of the given block
+      #   @raise [PG::Error]
+
+      # @!group Auto-sensing thread or fiber blocking command methods
+
+      # @!method exec(sql, &blk)
+      #   Sends SQL query request specified by +sql+ to PostgreSQL.
+      #
+      #   @macro auto_synchrony_api
+      #
+      #   @see PG::EM::Client#exec_defer
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-exec PG::Connection#exec
+      #
+      # @!method exec_params(sql, params=nil, result_format=nil, &blk)
+      #   Sends SQL query request specified by +sql+ with optional +params+ and +result_format+ to PostgreSQL.
+      #
+      #   @macro auto_synchrony_api
+      #
+      #   @see PG::EM::Client#exec_params_defer
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-exec_params PG::Connection#exec_params
+      #
+      # @!method prepare(stmt_name, sql, param_types=nil, &blk)
+      #   Prepares statement +sql+ with name +stmt_name+ to be executed later.
+      #
+      #   @macro auto_synchrony_api
+      #
+      #   @see PG::EM::Client#prepare_defer
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-prepare PG::Connection#prepare
+      #
+      # @!method exec_prepared(statement_name, params=nil, result_format=nil, &blk)
+      #   Execute prepared named statement specified by +statement_name+.
+      #
+      #   @macro auto_synchrony_api
+      #
+      #   @see PG::EM::Client#exec_prepared_defer
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-exec_prepared PG::Connection#exec_prepared
+      #
+      # @!method describe_prepared(statement_name, &blk)
+      #   Retrieve information about the prepared statement +statement_name+,
+      #
+      #   @macro auto_synchrony_api
+      #
+      #   @see PG::EM::Client#describe_prepared_defer
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-describe_prepared PG::Connection#describe_prepared
+      #
+      # @!method describe_portal(portal_name, &blk)
+      #   Retrieve information about the portal +portal_name+,
+      #
+      #   @macro auto_synchrony_api
+      #
+      #   @see PG::EM::Client#describe_portal_defer
+      #   @see http://deveiate.org/code/pg/PG/Connection.html#method-i-describe_portal PG::Connection#describe_portal
+      #
+      %w(
+        exec              exec_defer
+        exec_params       exec_defer
+        exec_prepared     exec_prepared_defer
+        prepare           prepare_defer
+        describe_prepared describe_prepared_defer
+        describe_portal   describe_portal_defer
+        ).each_slice(2) do |name, defer_name|
+
+        class_eval <<-EOD, __FILE__, __LINE__
+          def #{name}(*args, &blk)
+            if ::EM.reactor_running? && !(f = Fiber.current).equal?(ROOT_FIBER)
+              #{defer_name}(*args) do |res|
+                f.resume(res)
+              end
 
-      # support for pg < 0.14.0
-      unless method_defined? :set_default_encoding
-        def set_default_encoding
-          unless Encoding.default_internal.nil?
-            self.internal_encoding = Encoding.default_internal
+              result = Fiber.yield
+              raise result if result.is_a?(::Exception)
+              if block_given?
+                begin
+                  yield result
+                ensure
+                  result.clear
+                end
+              else
+                result
+              end
+            else
+              super
+            end
           end
-        rescue EncodingError
-          warn "warning: Failed to set the default_internal encoding to #{Encoding.default_internal}: '#{self.error_message}'"
-          Encoding.default_internal
-        end
+        EOD
       end
 
-    end
-  end
+      alias_method :query,       :exec
+      alias_method :async_query, :exec
+      alias_method :async_exec,  :exec
 
-  # support for pg < 0.14.0
-  unless Result.method_defined? :check
-    class Result
-      def check
-        case result_status
-          when PG::PGRES_BAD_RESPONSE,
-               PG::PGRES_FATAL_ERROR,
-               PG::PGRES_NONFATAL_ERROR
-            error = PG::Error.new(error_message)
-            error.instance_variable_set(:@result, self)
-            error.instance_variable_set(:@connection, @connection)
-            raise error
-        end
-      end
-      alias_method :check_result, :check
-    end
+      # @!endgroup
 
-    module EM
-      class Client < PG::Connection
-        def get_result(&blk)
-          result = super(&blk)
-          result.instance_variable_set(:@connection, self) unless block_given?
+      TRAN_BEGIN_QUERY = 'BEGIN'
+      TRAN_ROLLBACK_QUERY = 'ROLLBACK'
+      TRAN_COMMIT_QUERY = 'COMMIT'
+      # Executes a BEGIN at the start of the block and a COMMIT at the end
+      # of the block or ROLLBACK if any exception occurs.
+      #
+      # @note Avoid using PG::EM::Client#*_defer calls inside the block or make sure
+      #       all queries are completed before the provided block terminates.
+      # @return [Object] result of the block
+      # @yieldparam client [self]
+      # @see http://deveiate.org/code/pg/PG/Connection.html#method-i-transaction PG::Connection#transaction
+      #
+      # Calls to {#transaction} may be nested, however without sub-transactions
+      # (save points). If the innermost transaction block raises an error
+      # the transaction is rolled back to the state before the outermost
+      # transaction began.
+      #
+      # This is an extension to the +PG::Connection#transaction+ method
+      # as it does not support nesting in this way.
+      #
+      # The method is sensitive to the transaction status and will safely
+      # rollback on any sql error even when it was catched by some rescue block.
+      # But consider that rescuing any sql error within an utility method
+      # is a bad idea.
+      #
+      # This method works in both blocking/async modes (regardles of the reactor state)
+      # and is considered as a generic extension to the +PG::Connection#transaction+
+      # method.
+      #
+      # @example Nested transaction example
+      #  def add_comment(user_id, text)
+      #    db.transaction do
+      #      cmt_id = db.query(
+      #        'insert into comments (text) where user_id=$1 values ($2) returning id',
+      #        [user_id, text]).getvalue(0,0)
+      #      db.query(
+      #        'update users set last_comment_id=$2 where id=$1', [user_id, cmt_id])
+      #      cmt_id
+      #    end
+      #  end
+      #  
+      #  def update_comment_count(page_id)
+      #    db.transaction do
+      #      count = db.query('select count(*) from comments where page_id=$1', [page_id]).getvalue(0,0)
+      #      db.query('update pages set comment_count=$2 where id=$1', [page_id, count])
+      #    end
+      #  end
+      #
+      #  # to run add_comment and update_comment_count within the same transaction
+      #  db.transaction do
+      #    add_comment(user_id, some_text)
+      #    update_comment_count(page_id)
+      #  end
+      #
+      def transaction
+        raise ArgumentError, 'Must supply block for PG::EM::Client#transaction' unless block_given?
+        tcount = @client_tran_count.to_i
+
+        case transaction_status
+        when PG::PQTRANS_IDLE
+          # there is no transaction yet, so let's begin
+          exec(TRAN_BEGIN_QUERY)
+          # reset transaction count in case user code rolled it back before
+          tcount = 0 if tcount != 0
+        when PG::PQTRANS_INTRANS
+          # transaction in progress, leave it be
+        else
+          # transaction failed, is in unknown state or command is active
+          # in any case calling begin will raise server transaction error
+          exec(TRAN_BEGIN_QUERY) # raises PG::InFailedSqlTransaction
+        end
+        # memoize nested count
+        @client_tran_count = tcount + 1
+        begin
+
+          result = yield self
+
+        rescue
+          # error was raised
+          case transaction_status
+          when PG::PQTRANS_INTRANS, PG::PQTRANS_INERROR
+            # do not rollback if transaction was rolled back before
+            # or is in unknown state, which means connection reset is needed
+            # and rollback only from the outermost transaction block
+            exec(TRAN_ROLLBACK_QUERY) if tcount.zero?
+          end
+          # raise again
+          raise
+        else
+          # we are good (but not out of woods yet)
+          case transaction_status
+          when PG::PQTRANS_INTRANS
+            # commit only from the outermost transaction block
+            exec(TRAN_COMMIT_QUERY) if tcount.zero?
+          when PG::PQTRANS_INERROR
+            # no ruby error was raised (or an error was rescued in code block)
+            # but there was an sql error anyway
+            # so rollback after the outermost block
+            exec(TRAN_ROLLBACK_QUERY) if tcount.zero?
+          when PG::PQTRANS_IDLE
+            # the code block has terminated the transaction on its own
+            # so just reset the counter
+            tcount = 0
+          else
+            # something isn't right, so provoke an error just in case
+            exec(TRAN_ROLLBACK_QUERY) if tcount.zero?
+          end
           result
+        ensure
+          @client_tran_count = tcount
         end
       end
+
     end
   end