transaction-simple 1.2.0 → 1.3.0

data/lib/transaction/simple/group.rb

@@ -0,0 +1,133 @@
+require 'transaction/simple'
+
+  # A transaction group is an object wrapper that manages a group of objects
+  # as if they were a single object for the purpose of transaction
+  # management. All transactions for this group of objects should be
+  # performed against the transaction group object, not against individual
+  # objects in the group.
+  #
+  # == Transaction Group Usage
+  #   require 'transaction/simple/group'
+  #   
+  #   x = "Hello, you."
+  #   y = "And you, too."
+  #   
+  #   g = Transaction::Simple::Group.new(x, y)
+  #   g.start_transaction(:first)     # -> [ x, y ]
+  #   g.transaction_open?(:first)     # -> true
+  #   x.transaction_open?(:first)     # -> true
+  #   y.transaction_open?(:first)     # -> true
+  #   
+  #   x.gsub!(/you/, "world")         # -> "Hello, world."
+  #   y.gsub!(/you/, "me")            # -> "And me, too."
+  #   
+  #   g.start_transaction(:second)    # -> [ x, y ]
+  #   x.gsub!(/world/, "HAL")         # -> "Hello, HAL."
+  #   y.gsub!(/me/, "Dave")           # -> "And Dave, too."
+  #   g.rewind_transaction(:second)   # -> [ x, y ]
+  #   x                               # -> "Hello, world."
+  #   y                               # -> "And me, too."
+  #   
+  #   x.gsub!(/world/, "HAL")         # -> "Hello, HAL."
+  #   y.gsub!(/me/, "Dave")           # -> "And Dave, too."
+  #   
+  #   g.commit_transaction(:second)   # -> [ x, y ]
+  #   x                               # -> "Hello, HAL."
+  #   y                               # -> "And Dave, too."
+  #   
+  #   g.abort_transaction(:first)     # -> [ x, y ]
+  #   x                               = -> "Hello, you."
+  #   y                               = -> "And you, too."
+class Transaction::Simple::Group
+    # Creates a transaction group for the provided objects. If a block is
+    # provided, the transaction group object is yielded to the block; when
+    # the block is finished, the transaction group object will be cleared
+    # with #clear.
+  def initialize(*objects)
+    @objects = objects || []
+    @objects.freeze
+    @objects.each { |obj| obj.extend(Transaction::Simple) }
+
+    if block_given?
+      begin
+        yield self
+      ensure
+        self.clear
+      end
+    end
+  end
+
+    # Returns the objects that are covered by this transaction group.
+  attr_reader :objects
+
+    # Clears the object group. Removes references to the objects so that
+    # they can be garbage collected.
+  def clear
+    @objects = @objects.dup.clear
+  end
+
+    # Tests to see if all of the objects in the group have an open
+    # transaction. See Transaction::Simple#transaction_open? for more
+    # information.
+  def transaction_open?(name = nil)
+    @objects.inject(true) do |val, obj|
+      val = val and obj.transaction_open?(name)
+    end
+  end
+
+    # Returns the current name of the transaction for the group.
+    # Transactions not explicitly named are named +nil+.
+  def transaction_name
+    @objects[0].transaction_name
+  end
+
+    # Starts a transaction for the group. Stores the current object state.
+    # If a transaction name is specified, the transaction will be named.
+    # Transaction names must be unique. Transaction names of +nil+ will be
+    # treated as unnamed transactions.
+  def start_transaction(name = nil)
+    @objects.each { |obj| obj.start_transaction(name) }
+  end
+
+    # Rewinds the transaction. If +name+ is specified, then the intervening
+    # transactions will be aborted and the named transaction will be
+    # rewound. Otherwise, only the current transaction is rewound.
+  def rewind_transaction(name = nil)
+    @objects.each { |obj| obj.rewind_transaction(name) }
+  end
+
+    # Aborts the transaction. Resets the object state to what it was before
+    # the transaction was started and closes the transaction. If +name+ is
+    # specified, then the intervening transactions and the named transaction
+    # will be aborted. Otherwise, only the current transaction is aborted.
+    #
+    # If the current or named transaction has been started by a block
+    # (Transaction::Simple.start), then the execution of the block will be
+    # halted with +break+ +self+.
+  def abort_transaction(name = nil)
+    @objects.each { |obj| obj.abort_transaction(name) }
+  end
+
+    # If +name+ is +nil+ (default), the current transaction level is closed
+    # out and the changes are committed.
+    #
+    # If +name+ is specified and +name+ is in the list of named
+    # transactions, then all transactions are closed and committed until the
+    # named transaction is reached.
+  def commit_transaction(name = nil)
+    @objects.each { |obj| obj.commit_transaction(name) }
+  end
+
+    # Alternative method for calling the transaction methods. An optional
+    # name can be specified for named transaction support.
+    #
+    # #transaction(:start)::  #start_transaction
+    # #transaction(:rewind):: #rewind_transaction
+    # #transaction(:abort)::  #abort_transaction
+    # #transaction(:commit):: #commit_transaction
+    # #transaction(:name)::   #transaction_name
+    # #transaction::          #transaction_open?
+  def transaction(action = nil, name = nil)
+    @objects.each { |obj| obj.transaction(action, name) }
+  end
+end

data/lib/transaction/simple/threadsafe.rb

@@ -0,0 +1,52 @@
+require 'transaction/simple'
+require 'thread'
+
+class Transaction::TransactionThreadError < StandardError
+end
+
+  # = Transaction::Simple::ThreadSafe
+  # Thread-safe simple object transaction support for Ruby.
+  # Transaction::Simple::ThreadSafe is used in the same way as
+  # Transaction::Simple. Transaction::Simple::ThreadSafe uses a Mutex object
+  # to ensure atomicity at the cost of performance in threaded applications.
+  #
+  # Transaction::Simple::ThreadSafe will not wait to obtain a lock; if the
+  # lock cannot be obtained immediately, a
+  # Transaction::TransactionThreadError will be raised.
+  #
+  # Thanks to Mauricio Fern�ndez for help with getting this part working.
+  #
+  # Threadsafe transactions can be used in any place that normal
+  # transactions would. The main difference would be in setup:
+  #
+  #   require 'transaction/simple/threadsafe'
+  #
+  #   x = "Hello, you."
+  #   x.extend(Transaction::Simple::ThreadSafe) # Threadsafe
+  #
+  #   y = "Hello, you."
+  #   y.extend(Transaction::Simple)             # Not threadsafe
+module Transaction::Simple::ThreadSafe
+  include Transaction::Simple
+
+  SKIP_TRANSACTION_VARS = Transaction::Simple::SKIP_TRANSACTION_VARS.dup #:nodoc:
+  SKIP_TRANSACTION_VARS << "@__transaction_mutex__"
+
+  Transaction::Simple.instance_methods(false) do |meth|
+    next if meth == "transaction"
+    arg = "(name = nil)" unless meth == "transaction_name"
+    module_eval <<-EOS
+    def #{meth}#{arg}
+      if (@__transaction_mutex__ ||= Mutex.new).try_lock
+        result = super
+        @__transaction_mutex__.unlock
+        return result
+      else
+        raise TransactionThreadError, Messages[:cannot_obtain_transaction_lock] % meth
+      end
+    ensure
+      @__transaction_mutex__.unlock
+    end
+    EOS
+  end
+end

data/lib/transaction/simple/threadsafe/group.rb

@@ -0,0 +1,23 @@
+require 'transaction/simple/threadsafe'
+
+  # A transaction group is an object wrapper that manages a group of objects
+  # as if they were a single object for the purpose of transaction
+  # management. All transactions for this group of objects should be
+  # performed against the transaction group object, not against individual
+  # objects in the group. This is the threadsafe version of a transaction
+  # group.
+class Transaction::Simple::ThreadSafe::Group < Transaction::Simple::Group
+  def initialize(*objects)
+    @objects = objects || []
+    @objects.freeze
+    @objects.each { |obj| obj.extend(Transaction::Simple::ThreadSafe) }
+
+    if block_given?
+      begin
+        yield self
+      ensure
+        self.clear
+      end
+    end
+  end
+end

data/tests/{tests.rb → tc_transaction_simple.rb}

@@ -120,7 +120,6 @@ class Test__Transaction_Simple < Test::Unit::TestCase #:nodoc:
   end
 
   def test_block
-    @value = VALUE.dup
     Transaction::Simple.start(@value) do |tv|
       assert_equal(true, tv.transaction_open?)
       assert_nothing_raised { tv.gsub!(/men/, 'women') }
@@ -144,7 +143,6 @@ class Test__Transaction_Simple < Test::Unit::TestCase #:nodoc:
   end
 
   def test_named_block
-    @value = VALUE.dup
     Transaction::Simple.start_named(:first, @value) do |tv|
       assert_equal(true, tv.transaction_open?)
       assert_equal(true, tv.transaction_open?(:first))
@@ -233,7 +231,6 @@ class Test__Transaction_Simple < Test::Unit::TestCase #:nodoc:
   end
 
   def test_multilevel_block
-    @value = VALUE.dup
     Transaction::Simple.start_named(:outer, @value) do |tv0|
       assert_equal(1, tv0.instance_variable_get(:@__transaction_level__))
       assert_equal(true, tv0.transaction_open?(:outer))
@@ -267,136 +264,14 @@ class Test__Transaction_Simple < Test::Unit::TestCase #:nodoc:
     assert_nothing_raised { @value.abort_transaction }
     assert_equal(@orig, @value)
   end
-end
 
-class Test__Transaction_Simple_ThreadSafe < Test::Unit::TestCase #:nodoc:
-  VALUE = "Now is the time for all good men to come to the aid of their country."
-
-  def setup
+  def test_instance_var
     @value = VALUE.dup
-    @value.extend(Transaction::Simple::ThreadSafe)
-  end
-
-  def test_extended
-    assert_respond_to(@value, :start_transaction)
-  end
-
-  def test_started
-    assert_equal(false, @value.transaction_open?)
-    assert_nothing_raised { @value.start_transaction }
-    assert_equal(true, @value.transaction_open?)
-  end
-
-  def test_rewind
-    assert_equal(false, @value.transaction_open?)
-    assert_raises(Transaction::TransactionError) { @value.rewind_transaction }
-    assert_nothing_raised { @value.start_transaction }
-    assert_equal(true, @value.transaction_open?)
-    assert_nothing_raised { @value.gsub!(/men/, 'women') }
-    assert_not_equal(VALUE, @value)
-    assert_nothing_raised { @value.rewind_transaction }
-    assert_equal(true, @value.transaction_open?)
-    assert_equal(VALUE, @value)
-  end
-
-  def test_abort
-    assert_equal(false, @value.transaction_open?)
-    assert_raises(Transaction::TransactionError) { @value.abort_transaction }
-    assert_nothing_raised { @value.start_transaction }
-    assert_equal(true, @value.transaction_open?)
-    assert_nothing_raised { @value.gsub!(/men/, 'women') }
-    assert_not_equal(VALUE, @value)
-    assert_nothing_raised { @value.abort_transaction }
-    assert_equal(false, @value.transaction_open?)
-    assert_equal(VALUE, @value)
-  end
-
-  def test_commit
-    assert_equal(false, @value.transaction_open?)
-    assert_raises(Transaction::TransactionError) { @value.commit_transaction }
-    assert_nothing_raised { @value.start_transaction }
-    assert_equal(true, @value.transaction_open?)
-    assert_nothing_raised { @value.gsub!(/men/, 'women') }
-    assert_not_equal(VALUE, @value)
-    assert_equal(true, @value.transaction_open?)
-    assert_nothing_raised { @value.commit_transaction }
-    assert_equal(false, @value.transaction_open?)
-    assert_not_equal(VALUE, @value)
-  end
-
-  def test_multilevel
-    assert_equal(false, @value.transaction_open?)
-    assert_nothing_raised { @value.start_transaction }
-    assert_equal(true, @value.transaction_open?)
-    assert_nothing_raised { @value.gsub!(/men/, 'women') }
-    assert_equal(VALUE.gsub(/men/, 'women'), @value)
-    assert_equal(true, @value.transaction_open?)
-    assert_nothing_raised { @value.start_transaction }
-    assert_nothing_raised { @value.gsub!(/country/, 'nation-state') }
-    assert_nothing_raised { @value.commit_transaction }
-    assert_equal(VALUE.gsub(/men/, 'women').gsub(/country/, 'nation-state'), @value)
-    assert_equal(true, @value.transaction_open?)
-    assert_nothing_raised { @value.abort_transaction }
-    assert_equal(VALUE, @value)
-  end
-
-  def test_multilevel_named
-    assert_equal(false, @value.transaction_open?)
-    assert_raises(Transaction::TransactionError) { @value.transaction_name }
-    assert_nothing_raised { @value.start_transaction(:first) } # 1
-    assert_raises(Transaction::TransactionError) { @value.start_transaction(:first) }
-    assert_equal(true, @value.transaction_open?)
-    assert_equal(true, @value.transaction_open?(:first))
-    assert_equal(:first, @value.transaction_name)
-    assert_nothing_raised { @value.start_transaction } # 2
-    assert_not_equal(:first, @value.transaction_name)
-    assert_equal(nil, @value.transaction_name)
-    assert_raises(Transaction::TransactionError) { @value.abort_transaction(:second) }
-    assert_nothing_raised { @value.abort_transaction(:first) }
-    assert_equal(false, @value.transaction_open?)
-    assert_nothing_raised do
-      @value.start_transaction(:first)
-      @value.gsub!(/men/, 'women')
-      @value.start_transaction(:second)
-      @value.gsub!(/women/, 'people')
-      @value.start_transaction
-      @value.gsub!(/people/, 'sentients')
-    end
-    assert_nothing_raised { @value.abort_transaction(:second) }
-    assert_equal(true, @value.transaction_open?(:first))
-    assert_equal(VALUE.gsub(/men/, 'women'), @value)
-    assert_nothing_raised do
-      @value.start_transaction(:second)
-      @value.gsub!(/women/, 'people')
-      @value.start_transaction
-      @value.gsub!(/people/, 'sentients')
-    end
-    assert_raises(Transaction::TransactionError) { @value.rewind_transaction(:foo) }
-    assert_nothing_raised { @value.rewind_transaction(:second) }
-    assert_equal(VALUE.gsub(/men/, 'women'), @value)
-    assert_nothing_raised do
-      @value.gsub!(/women/, 'people')
-      @value.start_transaction
-      @value.gsub!(/people/, 'sentients')
-    end
-    assert_raises(Transaction::TransactionError) { @value.commit_transaction(:foo) }
-    assert_nothing_raised { @value.commit_transaction(:first) }
-    assert_equal(VALUE.gsub(/men/, 'sentients'), @value)
-    assert_equal(false, @value.transaction_open?)
-  end
-
-  def test_array
-    assert_nothing_raised do
-      @orig = ["first", "second", "third"]
-      @value = ["first", "second", "third"]
-      @value.extend(Transaction::Simple::ThreadSafe)
-    end
-    assert_equal(@orig, @value)
-    assert_nothing_raised { @value.start_transaction }
+    @value.extend(Transaction::Simple)
+    @value.start_transaction
     assert_equal(true, @value.transaction_open?)
-    assert_nothing_raised { @value[1].gsub!(/second/, "fourth") }
-    assert_not_equal(@orig, @value)
-    assert_nothing_raised { @value.abort_transaction }
-    assert_equal(@orig, @value)
+    @value.instance_variable_set("@foo", "bar")
+    @value.rewind_transaction
+    assert_nil(@value.instance_variable_get("@foo"))
   end
 end

data/tests/tc_transaction_simple_group.rb

@@ -0,0 +1,44 @@
+$LOAD_PATH.unshift("#{File.dirname(__FILE__)}/../lib") if __FILE__ == $0
+
+require 'transaction/simple/group'
+require 'test/unit'
+class Test__Transaction_Simple_Group < Test::Unit::TestCase #:nodoc:
+  VALUE1  = "Hello, you."
+  VALUE2  = "And you, too."
+
+  def setup
+    @x = VALUE1.dup
+    @y = VALUE2.dup
+  end
+
+  def test_group
+    group = Transaction::Simple::Group.new(@x, @y)
+
+    assert_nothing_raised { group.start_transaction(:first) }
+    assert_equal(true, group.transaction_open?(:first))
+    assert_equal(true, @x.transaction_open?(:first))
+    assert_equal(true, @y.transaction_open?(:first))
+
+    assert_equal("Hello, world.", @x.gsub!(/you/, "world"))
+    assert_equal("And me, too.", @y.gsub!(/you/, "me"))
+
+    assert_nothing_raised { group.start_transaction(:second) }
+    assert_equal("Hello, HAL.", @x.gsub!(/world/, "HAL"))
+    assert_equal("And Dave, too.", @y.gsub!(/me/, "Dave"))
+
+    assert_nothing_raised { group.rewind_transaction(:second) }
+    assert_equal("Hello, world.", @x)
+    assert_equal("And me, too.", @y)
+
+    assert_equal("Hello, HAL.", @x.gsub!(/world/, "HAL"))
+    assert_equal("And Dave, too.", @y.gsub!(/me/, "Dave"))
+
+    assert_nothing_raised { group.commit_transaction(:second) }
+    assert_equal("Hello, HAL.", @x)
+    assert_equal("And Dave, too.", @y)
+
+    assert_nothing_raised { group.abort_transaction(:first) }
+    assert_equal("Hello, you.", @x)
+    assert_equal("And you, too.", @y)
+  end
+end

data/tests/tc_transaction_simple_threadsafe.rb

@@ -0,0 +1,135 @@
+$LOAD_PATH.unshift("#{File.dirname(__FILE__)}/../lib") if __FILE__ == $0
+
+require 'transaction/simple/threadsafe'
+require 'test/unit'
+class Test__Transaction_Simple_ThreadSafe < Test::Unit::TestCase #:nodoc:
+  VALUE = "Now is the time for all good men to come to the aid of their country."
+
+  def setup
+    @value = VALUE.dup
+    @value.extend(Transaction::Simple::ThreadSafe)
+  end
+
+  def test_extended
+    assert_respond_to(@value, :start_transaction)
+  end
+
+  def test_started
+    assert_equal(false, @value.transaction_open?)
+    assert_nothing_raised { @value.start_transaction }
+    assert_equal(true, @value.transaction_open?)
+  end
+
+  def test_rewind
+    assert_equal(false, @value.transaction_open?)
+    assert_raises(Transaction::TransactionError) { @value.rewind_transaction }
+    assert_nothing_raised { @value.start_transaction }
+    assert_equal(true, @value.transaction_open?)
+    assert_nothing_raised { @value.gsub!(/men/, 'women') }
+    assert_not_equal(VALUE, @value)
+    assert_nothing_raised { @value.rewind_transaction }
+    assert_equal(true, @value.transaction_open?)
+    assert_equal(VALUE, @value)
+  end
+
+  def test_abort
+    assert_equal(false, @value.transaction_open?)
+    assert_raises(Transaction::TransactionError) { @value.abort_transaction }
+    assert_nothing_raised { @value.start_transaction }
+    assert_equal(true, @value.transaction_open?)
+    assert_nothing_raised { @value.gsub!(/men/, 'women') }
+    assert_not_equal(VALUE, @value)
+    assert_nothing_raised { @value.abort_transaction }
+    assert_equal(false, @value.transaction_open?)
+    assert_equal(VALUE, @value)
+  end
+
+  def test_commit
+    assert_equal(false, @value.transaction_open?)
+    assert_raises(Transaction::TransactionError) { @value.commit_transaction }
+    assert_nothing_raised { @value.start_transaction }
+    assert_equal(true, @value.transaction_open?)
+    assert_nothing_raised { @value.gsub!(/men/, 'women') }
+    assert_not_equal(VALUE, @value)
+    assert_equal(true, @value.transaction_open?)
+    assert_nothing_raised { @value.commit_transaction }
+    assert_equal(false, @value.transaction_open?)
+    assert_not_equal(VALUE, @value)
+  end
+
+  def test_multilevel
+    assert_equal(false, @value.transaction_open?)
+    assert_nothing_raised { @value.start_transaction }
+    assert_equal(true, @value.transaction_open?)
+    assert_nothing_raised { @value.gsub!(/men/, 'women') }
+    assert_equal(VALUE.gsub(/men/, 'women'), @value)
+    assert_equal(true, @value.transaction_open?)
+    assert_nothing_raised { @value.start_transaction }
+    assert_nothing_raised { @value.gsub!(/country/, 'nation-state') }
+    assert_nothing_raised { @value.commit_transaction }
+    assert_equal(VALUE.gsub(/men/, 'women').gsub(/country/, 'nation-state'), @value)
+    assert_equal(true, @value.transaction_open?)
+    assert_nothing_raised { @value.abort_transaction }
+    assert_equal(VALUE, @value)
+  end
+
+  def test_multilevel_named
+    assert_equal(false, @value.transaction_open?)
+    assert_raises(Transaction::TransactionError) { @value.transaction_name }
+    assert_nothing_raised { @value.start_transaction(:first) } # 1
+    assert_raises(Transaction::TransactionError) { @value.start_transaction(:first) }
+    assert_equal(true, @value.transaction_open?)
+    assert_equal(true, @value.transaction_open?(:first))
+    assert_equal(:first, @value.transaction_name)
+    assert_nothing_raised { @value.start_transaction } # 2
+    assert_not_equal(:first, @value.transaction_name)
+    assert_equal(nil, @value.transaction_name)
+    assert_raises(Transaction::TransactionError) { @value.abort_transaction(:second) }
+    assert_nothing_raised { @value.abort_transaction(:first) }
+    assert_equal(false, @value.transaction_open?)
+    assert_nothing_raised do
+      @value.start_transaction(:first)
+      @value.gsub!(/men/, 'women')
+      @value.start_transaction(:second)
+      @value.gsub!(/women/, 'people')
+      @value.start_transaction
+      @value.gsub!(/people/, 'sentients')
+    end
+    assert_nothing_raised { @value.abort_transaction(:second) }
+    assert_equal(true, @value.transaction_open?(:first))
+    assert_equal(VALUE.gsub(/men/, 'women'), @value)
+    assert_nothing_raised do
+      @value.start_transaction(:second)
+      @value.gsub!(/women/, 'people')
+      @value.start_transaction
+      @value.gsub!(/people/, 'sentients')
+    end
+    assert_raises(Transaction::TransactionError) { @value.rewind_transaction(:foo) }
+    assert_nothing_raised { @value.rewind_transaction(:second) }
+    assert_equal(VALUE.gsub(/men/, 'women'), @value)
+    assert_nothing_raised do
+      @value.gsub!(/women/, 'people')
+      @value.start_transaction
+      @value.gsub!(/people/, 'sentients')
+    end
+    assert_raises(Transaction::TransactionError) { @value.commit_transaction(:foo) }
+    assert_nothing_raised { @value.commit_transaction(:first) }
+    assert_equal(VALUE.gsub(/men/, 'sentients'), @value)
+    assert_equal(false, @value.transaction_open?)
+  end
+
+  def test_array
+    assert_nothing_raised do
+      @orig = ["first", "second", "third"]
+      @value = ["first", "second", "third"]
+      @value.extend(Transaction::Simple::ThreadSafe)
+    end
+    assert_equal(@orig, @value)
+    assert_nothing_raised { @value.start_transaction }
+    assert_equal(true, @value.transaction_open?)
+    assert_nothing_raised { @value[1].gsub!(/second/, "fourth") }
+    assert_not_equal(@orig, @value)
+    assert_nothing_raised { @value.abort_transaction }
+    assert_equal(@orig, @value)
+  end
+end