em-pg-client-helper 0.3.1 → 0.3.2

data/.gitignore

@@ -1,3 +1,5 @@
 Gemfile.lock
 /pkg
 /html
+/doc
+/.yardoc

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/Rakefile

@@ -1,5 +1,4 @@
-require 'rubygems'
-require 'bundler'
+exec(*(["bundle", "exec", $PROGRAM_NAME] + ARGV)) if ENV['BUNDLE_GEMFILE'].nil?
 
 task :default => :test
 
@@ -17,13 +16,10 @@ task :release do
 	sh "git release"
 end
 
-require 'rdoc/task'
+require 'yard'
 
-RDoc::Task.new do |rd|
-	rd.main = "README.md"
-	rd.title = 'em-pg-client-helper'
-	rd.markup = "markdown"
-	rd.rdoc_files.include("README.md", "lib/**/*.rb")
+YARD::Rake::YardocTask.new :doc do |yardoc|
+	yardoc.files = %w{lib/**/*.rb - README.md}
 end
 
 desc "Run guard"

data/em-pg-client-helper.gemspec

@@ -26,7 +26,8 @@ Gem::Specification.new do |s|
 	# Needed for guard
 	s.add_development_dependency 'rb-inotify', '~> 0.9'
 	s.add_development_dependency 'pry-debugger'
-	s.add_development_dependency 'rake'
-	s.add_development_dependency 'rdoc'
+	s.add_development_dependency 'rake', '~> 10.4', '>= 1.0.4.2'
+	s.add_development_dependency 'redcarpet'
 	s.add_development_dependency 'rspec'
+	s.add_development_dependency 'yard'
 end

data/lib/em-pg-client-helper.rb

@@ -11,34 +11,37 @@ module PG::EM::Client::Helper
 	# a two-element array consisting of the parameterised SQL as the first
 	# element, and the array of parameters as the second element.
 	#
+	# @param tbl [#to_s]
+	#
+	# @param params [Hash<#to_s, Object>]
+	#
 	def insert_sql(tbl, params)
 		keys = params.keys.map { |k| quote_identifier(k.to_s) }.join(',')
 		vals = params.values
 		val_places = (1..vals.length).to_a.map { |i| "$#{i}" }.join(',')
 
-		["INSERT INTO #{quote_identifier(tbl)} (#{keys}) VALUES (#{val_places})", vals]
+		["INSERT INTO #{quote_identifier(tbl.to_s)} (#{keys}) VALUES (#{val_places})", vals]
 	end
 
 	# Run an insert query, without having to write a great pile of SQL all by
 	# yourself.
 	#
-	# Arguments:
-	#
-	#  * `db` -- A PG::EM::Client or PG::EM::ConnectionPool instance, against
-	#    which all database operations will be executed.
+	# @param db [PG::EM::Client, PG::EM::ConnectionPool] the connection
+	#   against which all database operations will be run.
 	#
-	#  * `tbl` -- The name of the table into which you wish to insert your data.
-	#    This parameter will be automatically quoted, if necessary.
+	# @param tbl [#to_s] the name of the table into which you wish to insert
+	#   your data.  This parameter will be automatically quoted, if
+	#   necessary.
 	#
-	#  * `params` -- A hash containing the fields you wish to insert into
-	#    (the keys of the hash) and the values to insert into each field (the
-	#    values of the hash).  All field names and data will be automatically
-	#    quoted and made safe, so you're automatically SQL injection-proof!
+	# @param params [Hash<#to_s, Object>] the fields you wish to insert into
+	#   (the keys of the hash) and the values to insert into each field (the
+	#   values of the hash).  All field names and data will be automatically
+	#   quoted and made safe, so you're automatically SQL injection-proof!
 	#
-	# This method returns the deferrable in which the query is being called;
-	# this means you should attach the code to run after the query completes
-	# with `#callback`, and you can attach an error handler with `#errback`
-	# if you like.
+	# @return [EM::Deferrable] the deferrable in which the query is being
+	#   called; this means you should attach the code to run after the query
+	#   completes with `#callback`, and you can attach an error handler with
+	#   `#errback` if you like.
 	#
 	def db_insert(db, tbl, params)
 		db.exec_defer(*insert_sql(tbl, params))
@@ -59,23 +62,27 @@ module PG::EM::Client::Helper
 	# `db_transaction` returns to specify what to run after the transaction
 	# completes successfully or fails, respectively.
 	#
-	# Arguments:
+	# @param db [PG::EM::Client, PG::EM::ConnectionPool] the connection
+	#   against which the transaction will be executed.  If you pass a
+	#   `ConnectionPool`, we will automatically hold a single connection for
+	#   the transaction to complete against, so you don't have to worry about
+	#   that, either.
 	#
-	#  * `db` -- A PG::EM::Client or PG::EM::ConnectionPool instance, against
-	#    which all database operations will be executed.  If you pass a
-	#    ConnectionPool, we will automatically hold a single connection for
-	#    the transaction to complete against, so you don't have to worry
-	#    about that, either.
+	# @param blk [Proc] code which will be executed within the context of the
+	#   transaction.  This block will be passed a
+	#   {PG::EM::Client::Helper::Transaction} instance, which has methods to
+	#   allow you to commit or rollback the transaction, and execute SQL
+	#   statements within the context of the transaction.
 	#
-	#  * `blk` -- A block of code which will be executed within the context
-	#    of the transaction.  This block will be passed a
-	#    `PG::EM::Client::Helper::Transaction` instance, which has methods to
-	#    allow you to commit or rollback the transaction, and execute SQL
-	#    statements within the context of the transaction.
+	# @return [EM::Deferrable] on which you can call `#callback` and
+	#   `#errback` to define what to do when the transaction succeeds or
+	#   fails, respectively.
 	#
-	# Returns a deferrable object, on which you can call `#callback` and
-	# `#errback` to define what to do when the transaction succeeds or fails,
-	# respectively.
+	# @note Due to the way that transactions detect when they are completed,
+	#   every deferrable in the scope of the transaction must be generated
+	#   by the transaction.  That is, you cannot use objects other than the
+	#   transaction asynchronously.  This is a known limitation, and will be
+	#   addressed in a future version of this library.
 	#
 	def db_transaction(db, opts = {}, &blk)
 		if db.is_a? PG::EM::ConnectionPool
@@ -91,11 +98,14 @@ module PG::EM::Client::Helper
 	# it so that it will always be valid, no matter what insanity someone's
 	# decided to put in their names.
 	#
+	# @param id [String]
+	#
+	# @return [String] just like `id`, but with added quoting.
+	#
 	def quote_identifier(id)
 		"\"#{id.gsub(/"/, '""')}\""
 	end
 end
 
-require_relative 'em-pg-client-helper/transaction'
-require_relative 'em-pg-client-helper/deferrable_group'
-
+require 'em-pg-client-helper/transaction'
+require 'em-pg-client-helper/deferrable_group'

data/lib/em-pg-client-helper/deferrable_group.rb

@@ -7,23 +7,56 @@
 class PG::EM::Client::Helper::DeferrableGroup
 	include ::EventMachine::Deferrable
 
+	# Create a new deferrable group.
+	#
 	def initialize
 		@failed = false
+		@finished = false
 		@first_failure = nil
 		@outstanding = []
 		yield(self) if block_given?
 	end
 
+	# Add a new deferrable to this group.
+	#
+	# @param df [EM::Deferrable] the deferrable to wait on.
+	#
+	# @return [EM::Deferrable] the same deferrable.
+	#
+	# @raise [RuntimeError] if you attempt to add a deferrable after the
+	#   group has already "completed" (that is, all deferrables that were
+	#   previously added to the group have finished).
+	#
 	def add(df)
+		if @finished
+			raise RuntimeError,
+			      "This deferrable group has already completed."
+		end
+
 		@outstanding << df
 		df.callback { completed(df) }.errback { |ex| failed(df, ex) }
 	end
 
+	# Mark a deferrable as having been completed.
+	#
+	# If this is the last deferrable in the group, then the callback/errback
+	# will be triggered.
+	#
+	# @param df [EM::Deferrable]
+	#
 	def completed(df)
 		@outstanding.delete(df)
 		maybe_done
 	end
 
+	# Register that a given deferrable completed, but has failed.
+	#
+	# As soon as `failed` has been called, the deferrable group is guaranteed
+	# to fail, no matter how many of the deferrables in the group succeed.
+	# If this is the first deferrable in the group to have failed, then `ex`
+	# will be the exception passed to the `errback`, otherwise the exception
+	# will unfortunately be eaten by a grue.
+	#
 	def failed(df, ex)
 		@first_failure ||= ex
 		@failed = true
@@ -31,8 +64,11 @@ class PG::EM::Client::Helper::DeferrableGroup
 	end
 
 	private
+	# Called every time a deferrable finishes, just in case we're ready to
+	# trigger our callbacks.
 	def maybe_done
 		if @outstanding.empty?
+			@finished = true
 			if @failed
 				fail(@first_failure)
 			else

data/lib/em-pg-client-helper/transaction.rb

@@ -11,16 +11,21 @@ class PG::EM::Client::Helper::Transaction
 
 		DeferrableGroup.new do |dg|
 			@dg = dg
-			dg.add(
-				conn.exec_defer("BEGIN").callback do
-					begin
-						blk.call(self)
-					rescue StandardError => ex
-						rollback(ex)
-					end
-				end.errback { |ex| rollback(ex) }
-			)
-		end.callback { commit }.errback { |ex| rollback(ex) }
+
+			df = conn.exec_defer("BEGIN").callback do
+				begin
+					blk.call(self)
+				rescue StandardError => ex
+					rollback(ex)
+				end
+			end.errback { |ex| rollback(ex) }
+
+			@dg.add(df)
+		end.callback do
+			rollback(RuntimeError.new("txn.commit was not called"))
+		end.errback do |ex|
+			rollback(ex)
+		end
 	end
 
 	# Signal the database to commit this transaction.  You must do this
@@ -31,10 +36,12 @@ class PG::EM::Client::Helper::Transaction
 	#
 	def commit
 		if @active
-			@conn.exec_defer("COMMIT").callback do
+			df = @conn.exec_defer("COMMIT").callback do
 				@active = false
 				self.succeed
 			end.errback { |ex| rollback(ex) }
+
+			@dg.add(df)
 		end
 	end
 
@@ -45,10 +52,12 @@ class PG::EM::Client::Helper::Transaction
 	#
 	def rollback(ex)
 		if @active
-			@conn.exec_defer("ROLLBACK") do
+			df = @conn.exec_defer("ROLLBACK") do
 				@active = false
 				self.fail(ex)
 			end
+
+			@dg.add(df)
 		end
 	end
 
@@ -70,12 +79,12 @@ class PG::EM::Client::Helper::Transaction
 	def exec(sql, values=[], &blk)
 		unless @active
 			raise RuntimeError,
-					"Cannot execute a query in a transaction that has been closed"
+			      "Cannot execute a query in a transaction that has been closed"
 		end
 
 		@dg.add(
 			@conn.exec_defer(sql, values).
-					  tap { |df| df.callback(&blk) if blk }
+			        tap { |df| df.callback(&blk) if blk }
 		)
 	end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: em-pg-client-helper
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-26 00:00:00.000000000 Z
+date: 2015-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: git-version-bump
@@ -157,6 +157,28 @@ dependencies:
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.4'
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.4'
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.4.2
+- !ruby/object:Gem::Dependency
+  name: redcarpet
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -172,7 +194,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rdoc
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -188,7 +210,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -211,6 +233,7 @@ extra_rdoc_files:
 - README.md
 files:
 - .gitignore
+- .yardopts
 - Gemfile
 - Guardfile
 - LICENCE
@@ -238,7 +261,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -448126625621409328
+      hash: 1485031503438797399
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -247,7 +270,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -448126625621409328
+      hash: 1485031503438797399
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -255,3 +278,4 @@ signing_key:
 specification_version: 3
 summary: Simplify common operations using em-pg-client
 test_files: []
+has_rdoc: