Module: Transaction::Simple

Module | Transaction::Simple
In: | lib/transaction/simple.rb

# Transaction::Simple for Ruby

Simple object transaction support for Ruby

### Methods

abort_transaction commit_transaction debug_io debug_io= debugging? rewind_transaction start start_named start_transaction transaction transaction_exclusions transaction_name transaction_open?

### Classes and Modules

Module Transaction::Simple::ThreadSafe
Class Transaction::Simple::Group

### Constants

TRANSACTION_SIMPLE_VERSION | = | '1.4.0'
SKIP_TRANSACTION_VARS | = | %w(@__transaction_checkpoint__ @__transaction_level__)

### Public Class methods

debug_io()

Returns the Transaction::Simple debug object. It must respond to #<<.

debug_io=(io)

Sets the Transaction::Simple debug object. It must respond to #<<. Debugging will be performed automatically if there‘s a debug object.

debugging?()

Returns `true` if we are debugging.

start(*vars, &block)

Start a named transaction in a block. The transaction will auto-commit when the block finishes.

start_named(name, *vars, &block)

Start a named transaction in a block. The transaction will auto-commit when the block finishes.

### Public Instance methods

abort_transaction(name = nil)

Aborts the transaction. Rewinds 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.

See rewind_transaction for information about dealing with complex self-referential object graphs.

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`.

commit_transaction(name = nil)

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.

rewind_transaction(name = nil)

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.

After each level of transaction is rewound, if the callback method _post_transaction_rewind is defined, it will be called. It is intended to allow a complex self-referential graph to fix itself. The simplest way to explain this is with an example.

      class Child
        attr_accessor :parent
      end

      class Parent
        include Transaction::Simple

        attr_reader :children
        def initialize
          @children = []
        end

        def << child
          child.parent = self
          @children << child
        end

        def valid?
          @children.all? { |child| child.parent == self }
        end
      end

      parent = Parent.new
      parent << Child.new
      parent.start_transaction
      parent << Child.new
      parent.abort_transaction
      puts parent.valid? # => false

This problem can be fixed by modifying the Parent class to include the _post_transaction_rewind callback.

      class Parent
        # Reconnect the restored children to me, instead of to the bogus me
        # that was restored to them by Marshal::load.
        def _post_transaction_rewind
          @children.each { |child| child.parent = self }
        end
      end

      parent = Parent.new
      parent << Child.new
      parent.start_transaction
      parent << Child.new
      parent.abort_transaction
      puts parent.valid? # => true

start_transaction(name = nil)

Starts a transaction. 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.

transaction(action = nil, name = nil)

Alternative method for calling the transaction methods. An optional name can be specified for named transaction support. This method is deprecated and will be removed in Transaction::Simple 2.0.

transaction(:start): | start_transaction
transaction(:rewind): | rewind_transaction
transaction(:abort): | abort_transaction
transaction(:commit): | commit_transaction
transaction(:name): | transaction_name
transaction: | transaction_open?

transaction_exclusions()

Allows specific variables to be excluded from transaction support. Must be done after extending the object but before starting the first transaction on the object.

      vv.transaction_exclusions << "@io"

transaction_name()

Returns the current name of the transaction. Transactions not explicitly named are named `nil`.

transaction_open?(name = nil)

If `name` is `nil` (default), then returns `true` if there is currently a transaction open. If `name` is specified, then returns `true` if there is currently a transaction known as `name` open.

[Validate]