transaction-simple 1.4.0 → 1.4.0.2

data/lib/transaction/simple/group.rb

@@ -1,61 +1,49 @@
-#--
-# Transaction::Simple
-# Simple object transaction support for Ruby
-# http://rubyforge.org/projects/trans-simple/
-#   Version 1.4.0
+# -*- ruby encoding: utf-8 -*-
+
+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.
 #
-# Licensed under a MIT-style licence. See Licence.txt in the main
-# distribution for full licensing information.
+# == Transaction Group Usage
+#   require 'transaction/simple/group'
 #
-# Copyright (c) 2003 - 2007 Austin Ziegler
+#   x = "Hello, you."
+#   y = "And you, too."
 #
-# $Id: group.rb 47 2007-02-03 15:02:51Z austin $
-#++
-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."
+#   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.
+  # 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
@@ -70,77 +58,79 @@ class Transaction::Simple::Group
     end
   end
 
-    # Returns the objects that are covered by this transaction group.
+  # 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.
+  # 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.
+  # 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+.
+  # 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.
+  # 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.
+  # 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+.
+  # 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.
+  # 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?
+  # 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
+
+# vim: syntax=ruby

data/lib/transaction/simple/threadsafe.rb

@@ -1,16 +1,5 @@
-#--
-# Transaction::Simple
-# Simple object transaction support for Ruby
-# http://rubyforge.org/projects/trans-simple/
-#   Version 1.4.0
-#
-# Licensed under a MIT-style licence. See Licence.txt in the main
-# distribution for full licensing information.
-#
-# Copyright (c) 2003 - 2007 Austin Ziegler
-#
-# $Id: threadsafe.rb 50 2007-02-03 20:26:19Z austin $
-#++
+# -*- ruby encoding: utf-8 -*-
+
 require 'transaction/simple'
 require 'thread'
 
@@ -20,28 +9,27 @@ module Transaction
   class TransactionThreadError < TransactionError; end
 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 Fernandez 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
+# 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 Fernandez 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
 
@@ -66,3 +54,5 @@ module Transaction::Simple::ThreadSafe
     EOS
   end
 end
+
+# vim: syntax=ruby

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

@@ -1,24 +1,12 @@
-#--
-# Transaction::Simple
-# Simple object transaction support for Ruby
-# http://rubyforge.org/projects/trans-simple/
-#   Version 1.4.0
-#
-# Licensed under a MIT-style licence. See Licence.txt in the main
-# distribution for full licensing information.
-#
-# Copyright (c) 2003 - 2007 Austin Ziegler
-#
-# $Id: group.rb 47 2007-02-03 15:02:51Z austin $
-#++
+# -*- ruby encoding: utf-8 -*-
+
 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.
+# 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 || []
@@ -34,3 +22,5 @@ class Transaction::Simple::ThreadSafe::Group < Transaction::Simple::Group
     end
   end
 end
+
+# vim: syntax=ruby

data/research/instance_variable_defined.rb

@@ -0,0 +1,22 @@
+# -*- ruby encoding: utf-8 -*-
+
+# Provided by Nobu Nakada.
+# You can use this code for previous versions.
+
+unless defined?(instance_variable_defined?)
+  module Kernel
+    (t = Object.new).instance_eval { @instance_variable = 1 }
+    case t.instance_variables[0]
+    when Symbol
+      def instance_variable_defined?(var)
+        instance_variables.include?(var.to_sym)
+      end
+    when String
+      def instance_variable_defined?(var)
+        instance_variables.include?(var.to_s)
+      end
+    end
+  end
+end
+
+# vim: syntax=ruby

data/research/special-dumpable-string.rb

@@ -0,0 +1,42 @@
+# -*- ruby encoding: utf-8 -*-
+
+load 'special-dumpable.rb'
+
+class Child
+  attr_accessor :parent
+end
+
+class Parent < String
+  include SpecialDumpable
+
+  attr_reader :children
+  def initialize(value)
+    super
+    @children = []
+  end
+
+  def << child
+    child.parent = self
+    @children << child
+  end
+end
+
+parent = Parent.new("gold")
+puts "parent(#{parent}).object_id: #{parent.object_id}"
+parent << Child.new
+puts "parent(#{parent}).children[0].parent.object_id: #{parent.children[0].parent.object_id}"
+puts "starting transaction with childcount #{parent.children.size}"
+s = parent.special_dump
+parent << Child.new
+parent.gsub!(/gold/, 'pyrite')
+puts "parent(#{parent}).children[1].parent.object_id: #{parent.children[1].parent.object_id}"
+puts "aborting transaction with childcount #{parent.children.size}"
+parent.special_restore s
+puts "parent(#{parent})"
+puts "aborted transaction with childcount #{parent.children.size}"
+puts "parent.object_id: #{parent.object_id}"
+puts "parent.children[0].parent.object_id: #{parent.children[0].parent.object_id}"
+parent << Child.new
+puts "parent.children[1].parent.object_id: #{parent.children[1].parent.object_id}"
+
+# vim: syntax=ruby

data/research/special-dumpable.rb

@@ -0,0 +1,130 @@
+#!/usr/bin/env ruby
+# -*- ruby encoding: utf-8 -*-
+#
+#  SpecialDumpable - workaround for a problem in Transaction::Simple
+#
+#  (C) 2006 Pit Capitain
+#
+#  For a description of the problem see http://www.halostatue.ca/2006/10/22/
+#    ruby-conference-2006-day-1-evening-friday-20-october-2006/
+#  and http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/155092
+#
+#  The workaround:
+#
+#  The objects that are restored from Marshal shouldn't reference the newly
+#  created root object, but the original root object. After studying the
+#  source code of Marshal, I found that this could be achieved with a
+#  special _load method of the root object's class which returns the
+#  original root object. Then the original root object would be stored in
+#  the internal list of restored objects and references to the root object
+#  would use the original one.
+#
+#  See SpecialDumpable::ClassMethods#_load
+#
+#  In order to get at the original root object from a class method, we store
+#  its object_id in the Marshal string.
+#
+#  See SpecialDumpable#_dump
+#
+#  Note: this means that classes with their own _load and _dump methods
+#  cannot be used with this implementation. I think it should be possible to
+#  enhance the implementation to support these classes, too.
+#
+#  Using those two methods, the objects restored from Marshal really
+#  reference the original root object. But this is not enough. We have to
+#  restore the instance variables of the root object, too. The _dump method
+#  from above only dumps the object_id of the root object, not its instance
+#  variables.
+#
+#  For the instance variables, we create a new object and store the instance
+#  variables of the root object there. Then we not only serialize the root
+#  object, but an array with both the root object and the object with the
+#  instance variables.
+#
+#  See SpecialDumpable#special_dump
+#
+#  The root object dumps its object_id, and the object with the instance
+#  variables dumps the instance variables of the root object.
+#
+#  When restoring the objects, Marshal creates an array with the root object
+#  plus an object with the restored instance variables of the root object.
+#  We only need to replace the current instance variables of the root object
+#  with the restored instance variables to get the desired behaviour.
+#
+#  See SpecialDumpable#special_restore
+#
+#  That's it.
+
+module SpecialDumpable
+  def self.included base
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def _load source
+      ObjectSpace._id2ref source.to_i
+    end
+  end
+
+  def _dump limit
+    object_id.to_s
+  end
+
+  def special_dump
+    value_holder = Object.new
+    SpecialDumpable.copy_instance_variables self, value_holder
+    Marshal.dump [ self, value_holder ]
+  end
+
+  def special_restore source
+    self_that_can_be_ignored, value_holder = Marshal.restore source
+    SpecialDumpable.copy_instance_variables value_holder, self
+    self
+  end
+
+  def self.copy_instance_variables from, to
+    from.instance_variables.each do |var|
+      val = from.instance_variable_get var
+      to.instance_variable_set var, val
+    end
+  end
+
+end
+
+if __FILE__ == $0
+  class Child
+    attr_accessor :parent
+  end
+
+  class Parent
+    include SpecialDumpable
+
+    attr_reader :children
+    def initialize
+      @children = []
+    end
+
+    def << child
+      child.parent = self
+      @children << child
+    end
+  end
+
+  parent = Parent.new
+  puts "parent.object_id: #{parent.object_id}"
+  parent << Child.new
+  puts "parent.children[0].parent.object_id: #{parent.children[0].parent.object_id}"
+  puts "starting transaction with childcount #{parent.children.size}"
+  s = parent.special_dump
+  parent << Child.new
+  puts "parent.children[1].parent.object_id: #{parent.children[1].parent.object_id}"
+  puts "aborting transaction with childcount #{parent.children.size}"
+  parent.special_restore s
+  puts "aborted transaction with childcount #{parent.children.size}"
+  puts "parent.object_id: #{parent.object_id}"
+  puts "parent.children[0].parent.object_id: #{parent.children[0].parent.object_id}"
+  parent << Child.new
+  puts "parent.children[1].parent.object_id: #{parent.children[1].parent.object_id}"
+end
+
+# vim: syntax=ruby