pg_advisory_locker 1.0.2 → 1.1.0

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+rvm:
+  - 1.9.3
+bundler_args: --without staging development deploy
+before_install:
+before_script: cp spec/dummy/config/database-sample.yml spec/dummy/config/database.yml; cd spec/dummy; bundle exec rake db:create;
+script: rspec spec
+branches:
+  only:
+    - master
+    - production
+notifications:
+  email:
+    - dev-fma@fiksu.com
+

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2012, Fiksu, Inc.
+Copyright (c) 2010-2013, Fiksu, Inc.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/README.md

@@ -0,0 +1,61 @@
+pg_advisory_locker
+==================
+
+Helper for calling PostgreSQL functions: pg_advisory_lock,
+pg_advisory_try_lock, and pg_advisory_unlock.
+
+Examples
+========
+
+Basic example of passing a block to the locker
+
+```
+class Foo < ActiveRecord::Base
+  include PgAdvisoryLocker
+
+  def self.lock_for_whatever(&block)
+	return lock_record(0, &block)
+  end
+
+  def self.do_something
+    lock_for_whatever do
+      # do something here
+    end
+  end
+end
+```
+
+Advisory lock on id:
+
+```
+class Foo < ActiveRecord::Base
+  include PgAdvisoryLocker
+
+  def lock_for_whatever
+	return advisory_lock
+  end
+
+  def unlock_for_whatever
+	return advisory_unlock
+  end
+
+  def do_something
+    lock_for_whatever
+	begin
+      # do something
+    ensure
+	 unlock_for_whatever
+    end
+  end
+end
+```
+Generic locking:
+```
+class Foo < ActiveRecord::Base
+  include PgAdvisoryLocker
+end
+
+Foo.pg_advisory_lock(0, 0) do
+  # do something
+end
+```

data/lib/pg_advisory_locker/pg_advisory_locker.rb

@@ -3,19 +3,40 @@ module PgAdvisoryLocker
     base.extend(ClassMethods)
   end
 
+  # advisory lock this row associated identified by model#id
+  #
+  # blocks until advisory lock is release
+  # acquires lock on return
+  #
+  # if block is passed in, lock/unlock around the block
   def advisory_lock(&block)
     return self.class.lock_record(id, &block)
   end
 
+  # advisory try lock this row associated identified by model#id
+  #
+  # if lock is acquired, acquires lock and returns true
+  # if lock is currently acquired, returns false
+  # never blocks
+  #
+  # if block is passed in, lock/unlock around the block
+  # executing block only if lock is acquired
   def advisory_try_lock(&block)
     return self.class.try_lock_record(id, &block)
   end
 
+  # advisory unlock this row associated identified by model#id
+  #
+  # on return releases lock
   def advisory_unlock
     self.class.unlock_record(id)
   end
 
   module ClassMethods
+    # table_oid is good unique identifier value for the table
+    # We could use a has of the name if the thought there would
+    # be no collisions
+    # The OID is always unique, so we use it
     def table_oid
       if @table_oid.nil?
         sql_table_components = table_name.split('.')
@@ -37,39 +58,85 @@ module PgAdvisoryLocker
       return @table_oid
     end
 
-    def lock_record(id, &block)
+    # advisory lock for this model, with key2 as argument
+    # blocks until advisory lock is release
+    # acquires lock on return
+    #
+    # if block is passed in, lock/unlock around the block
+    def lock_record(key2, &block)
+      return pg_advisory_lock(table_oid, key2, &block)
+    end
+
+    # advisory try lock for this model, with key2 as argument
+    #
+    # if lock is acquired, acquires lock and returns true
+    # if lock is currently acquired, returns false
+    # never blocks
+    #
+    # if block is passed in, lock/unlock around the block
+    # executing block only if lock is acquired
+    def try_lock_record(key2, &block)
+      return pg_try_advisory_lock(table_oid, key2, &block)
+    end
+
+    # advisory unlock for this model, with key2 as argument
+    # on return releases lock
+    def unlock_record(key2)
+      return pg_advisory_unlock(table_oid, key2)
+    end
+
+    # pg_advisory_lock - direct access to postgres pg_advisory_lock function
+    # key1: int
+    # key2: int
+    # if block is passed in, lock/unlock around the block
+    def pg_advisory_lock(key1, key2, &block)
       locked = uncached do
-        find_by_sql(["select pg_advisory_lock(?, ?)", table_oid, id])[0].pg_advisory_lock == "t"
+        find_by_sql(["select pg_advisory_lock(?, ?)", key1, key2]).first.pg_advisory_lock == "t"
       end
       if block.present?
         begin
           return block.call
         ensure
-          unlock_record(id)
+          pg_advisory_unlock(key1, key2)
         end
       end
       return locked
     end
 
-    def try_lock_record(id, &block)
+    # pg_try_advisory_lock - direct access to postgres pg_try_advisory_lock function
+    # key1: int
+    # key2: int
+    #
+    # if lock is acquired, acquires lock and returns true
+    # if lock is currently acquired, returns false
+    # never blocks
+    #
+    # if block is passed in, lock/unlock around the block
+    # executing block only if lock is acquired
+    def pg_try_advisory_lock(key1, key2, &block)
       locked = uncached do
-        find_by_sql(["select pg_try_advisory_lock(?, ?)", table_oid, id])[0].pg_try_advisory_lock == "t"
+        find_by_sql(["select pg_try_advisory_lock(?, ?)", key1, key2]).first.pg_try_advisory_lock == "t"
       end
       if locked
         if block.present?
           begin
             block.call
           ensure
-            unlock_record(id)
+            pg_advisory_unlock(key1, key2)
           end
         end
       end
       return locked
     end
 
-    def unlock_record(id)
+    # pg_advisory_unlock - direct access to postgres pg_advisory_unlock function
+    # key1: int
+    # key2: int
+    #
+    # on return releases lock
+    def pg_advisory_unlock(key1, key2)
       unlocked = uncached do
-        find_by_sql(["select pg_advisory_unlock(?, ?)", table_oid, id])[0].pg_advisory_unlock == "t"
+        find_by_sql(["select pg_advisory_unlock(?, ?)", key1, key2]).first.pg_advisory_unlock == "t"
       end
       return unlocked
     end

data/lib/pg_advisory_locker/version.rb

@@ -1,4 +1,4 @@
 module PgAdvisoryLocker
   # the current version of this gem
-  VERSION = "1.0.2"
+  VERSION = "1.1.0"
 end

data/pg_advisory_locker.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
  s.name        = 'pg_advisory_locker'
  s.version     = PgAdvisoryLocker::VERSION
  s.license     = 'New BSD License'
- s.date        = '2012-10-02'
+ s.date        = '2013-04-26'
  s.summary     = "Helper for calling PostgreSQL pg_advisory_lock, pg_advisory_try_lock, and pg_advisory_unlock."
  s.description = "This gem provides a module that, when included in your ActiveRecord model, provides methods to acquire and release advisory locks for PostgreSQL connections."
  s.authors     = ["Keith Gabryelski"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_advisory_locker
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-02 00:00:00.000000000 Z
+date: 2013-04-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -68,10 +68,11 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .rspec
+- .travis.yml
 - Gemfile
 - Gemfile.lock
 - LICENSE
-- README
+- README.md
 - Rakefile
 - lib/pg_advisory_locker.rb
 - lib/pg_advisory_locker/pg_advisory_locker.rb

data/README

@@ -1,47 +0,0 @@
-pg_advisory_locker
-==================
-
-Helper for calling PostgreSQL functions: pg_advisory_lock,
-pg_advisory_try_lock, and pg_advisory_unlock.
-
-Examples
-========
-
-Basic example of passing a block to the locker
-
-    class Foo < ActiveRecord::Base
-      include PgAdvisoryLocker
-
-      def self.lock_for_whatever(&block)
-	return lock_record(0, &block)
-      end
-
-      def self.do_something
-        lock_for_whatever do
-          # do something here
-        end
-      end
-    end
-
-Advisory lock on id:
-
-    class Foo < ActiveRecord::Base
-      include PgAdvisoryLocker
-
-      def lock_for_whatever
-	return advisory_lock
-      end
-
-      def unlock_for_whatever
-	return advisory_unlock
-      end
-
-      def do_something
-        lock_for_whatever
-	begin
-          # do something
-        ensure
-	 unlock_for_whatever
-        end
-      end
-    end