petra_core 0.0.1

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'petra'
+
+require 'pry'
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/continuation_error.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/GlobalVars
+
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'spec', 'support')
+require 'petra'
+require 'faker'
+
+#
+# This example shows why continuations and production code / code
+# that uses external libraries are not a good combination.
+#
+
+#----------------------------------------------------------------
+#                    Sample Class Definitions
+#----------------------------------------------------------------
+
+class SimpleUser
+  attr_accessor :first_name
+  attr_accessor :last_name
+
+  def initialize
+    @first_name, @last_name = Faker::Name.name.split(' ')
+  end
+
+  def save
+    # Do nothing, we just want an explicit save method.
+    # We could also set every attribute write to also be a persistence method
+  end
+end
+
+Petra.configure do
+  configure_class 'SimpleUser' do
+    proxy_instances true
+
+    attribute_reader? do |method_name|
+      %w[first_name last_name].include?(method_name.to_s)
+    end
+
+    attribute_writer? do |method_name|
+      %w[first_name= last_name=].include?(method_name.to_s)
+    end
+
+    persistence_method? do |method_name|
+      %w[save].include?(method_name.to_s)
+    end
+  end
+end
+
+class ConfidentialData < String
+  def read?
+    !!@read
+  end
+
+  def read!
+    @read = true
+  end
+end
+
+class SimpleHandler
+  def with_confidential_data(string)
+    @confidential_data = ConfidentialData.new(string)
+    yield
+  rescue Exception
+    # The data might have been compromised! Delete it!
+    @confidential_data = nil
+    raise
+  end
+
+  def do_confidential_stuff(user)
+    puts "User #{user.first_name} #{user.last_name} is very confidential."
+    user.last_name = user.last_name + ' ' + ('I' * @confidential_data.length) + '.'
+  ensure
+    @confidential_data.read!
+  end
+end
+
+#----------------------------------------------------------------
+#                        Helper Methods
+#----------------------------------------------------------------
+
+# rubocop:disable Security/Eval
+def transaction(id_no)
+  Petra.transaction(identifier: eval("$t_id_#{id_no}", nil, __FILE__, __LINE__)) do
+    yield
+  rescue Petra::ValueComparisonError => e
+    e.ignore!
+    e.continue!
+  end
+end
+
+# rubocop:enable Security/Eval
+
+#----------------------------------------------------------------
+#                        Actual Example
+#----------------------------------------------------------------
+
+# Create 2 transaction identifiers
+$t_id_1 = Petra.transaction {}
+$t_id_2 = Petra.transaction {}
+
+# Instantiate a handler and a SimpleUser object proxy
+handler = SimpleHandler.new
+user    = SimpleUser.petra.new
+
+transaction(1) do
+  user.first_name
+  user.last_name = Faker::Name.last_name
+  user.save
+end
+
+transaction(2) do
+  user.first_name, user.last_name = Faker::Name.name.split(' ')
+  user.save
+  Petra.commit!
+end
+
+transaction(1) do
+  handler.with_confidential_data('Ulf.') do
+    handler.do_confidential_stuff(user) #=> Undefined method #read! for nil:NilClass...
+  end
+end
+
+# rubocop:enable Style/GlobalVars

data/examples/dining_philosophers.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+require 'petra'
+
+# This file contains a transaction based solution to the dining philosophers problem
+# with five philosophers. It uses the transactions' retry mechanic to ensure
+# that both sticks have to be taken at the same time.
+
+class Philosopher
+  attr_reader :number
+
+  def initialize(number, *sticks)
+    @number                   = number
+    @left_stick, @right_stick = sticks.map(&:petra)
+  end
+
+  def eating?
+    !!@eating
+  end
+
+  def think
+    sleep(rand(5))
+  end
+
+  def take_stick(stick)
+    fail Petra::Retry if stick.taken
+    stick.taken = true
+    stick.save
+  end
+
+  def put_stick(stick)
+    stick.taken = false
+    stick.save
+  end
+
+  def take_sticks
+    Petra.transaction(identifier: "philosopher_#{@number}") do
+      take_stick(@left_stick)
+      take_stick(@right_stick)
+      Petra.commit!
+    rescue Petra::LockError => e
+      e.retry!
+    rescue Petra::ReadIntegrityError, Petra::WriteClashError => e
+      e.retry!
+    end
+  end
+
+  def put_sticks
+    Petra.transaction(identifier: "philosopher_#{@number}") do
+      put_stick(@left_stick)
+      put_stick(@right_stick)
+      Petra.commit!
+    end
+  end
+
+  def eat
+    take_sticks
+
+    @eating = true
+    sleep(2)
+    @eating = false
+
+    put_sticks
+  end
+
+  def live
+    loop do
+      think
+      eat
+    end
+  end
+end
+
+class Stick < Mutex
+  attr_reader :number
+
+  def initialize(number)
+    @number = number
+  end
+
+  alias taken locked?
+
+  def taken=(new_value)
+    if new_value
+      try_lock || fail(Exception, 'Already locked!')
+    else
+      unlock
+    end
+  end
+
+  def save; end
+end
+
+Petra.configure do
+  log_level :warn
+
+  configure_class 'Stick' do
+    proxy_instances true
+
+    attribute_reader? do |method_name|
+      %w[taken].include?(method_name.to_s)
+    end
+
+    attribute_writer? do |method_name|
+      %w[taken=].include?(method_name.to_s)
+    end
+
+    persistence_method? do |method_name|
+      %w[save].include?(method_name)
+    end
+  end
+end
+
+# If not set, a thread would silently fail without
+# interrupting the main thread.
+Thread.abort_on_exception = true
+
+sticks       = Array.new(5) { |i| Stick.new(i) }
+philosophers = Array.new(5) { |i| Philosopher.new(i, sticks[i], sticks[(i + 1) % 5]) }
+
+philosophers.map do |phil|
+  t      = Thread.new { phil.live }
+  t.name = "Philosopher #{phil.number}"
+end
+
+# The output may contain some invalid states as it might happen
+# during a commit phase with only one stick taken.
+loop do
+  philosophers.each_with_index do |phil, idx|
+    stick = sticks[idx]
+    STDOUT.write stick.taken ? ' _ ' : ' | '
+    STDOUT.write phil.eating? ? ' 😁 ' : ' 😑 '
+  end
+
+  STDOUT.write("\r")
+  sleep(0.2)
+end

data/examples/showcase.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'spec', 'support', 'classes')
+require 'petra'
+require 'simple_user'
+require 'simple_user_with_auto_save'
+
+Petra.configure do
+  log_level :warn
+end
+
+def log(message, identifier = 'External')
+  puts [identifier, message].join(': ')
+end
+
+user = Classes::SimpleUserWithAutoSave.petra.new('John', 'Doe')
+
+# Start a new transaction and start changing attributes
+Petra.transaction(identifier: 'tr1') do
+  user.first_name = 'Foo'
+end
+
+# No changes outside the transaction yet...
+log user.name #=> 'John Doe'
+
+# Continue the same transaction
+Petra.transaction(identifier: 'tr1') do
+  log(user.name, 'tr1') #=> 'Foo Doe'
+  user.last_name = 'Bar'
+end
+
+# Another transaction changes a value already changed in 'tr1'
+Petra.transaction(identifier: 'tr2') do
+  log(user.name, 'tr2') #=> John Doe
+  user.first_name = 'Moo'
+  Petra.commit!
+end
+
+log user.name #=> 'Moo Doe'
+
+# Try to commit our first transaction
+Petra.transaction(identifier: 'tr1') do
+  log(user.name, 'tr1')
+  Petra.commit!
+rescue Petra::WriteClashError => e
+  # => "The attribute `first_name` has been changed externally and in the transaction. (Petra::WriteClashError)"
+  # Let's use our value and go on with committing the transaction
+  e.use_ours!
+  e.continue!
+end
+
+# The actual object is updated with the values from tr1
+log user.name #=> 'Foo Bar'

data/lib/petra/components/entries/attribute_change.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Petra
+  module Components
+    module Entries
+      class AttributeChange < Petra::Components::LogEntry
+        field_accessor :old_value
+        field_accessor :new_value
+        field_accessor :method
+
+        def self.kind
+          :attribute_change
+        end
+
+        def apply!
+          # Check if there is an an attribute change veto which is newer than this
+          # attribute change. If there is, we may not apply this entry.
+          # TODO: Check if this behaviour is sufficient.
+          return if transaction.attribute_change_veto?(load_proxy, attribute: attribute)
+
+          # Otherwise, use the logged method to set the new attribute value
+          proxied_object.send(method, new_value)
+        end
+
+        Petra::Components::LogEntry.register_entry_type(kind, self)
+      end
+    end
+  end
+end

data/lib/petra/components/entries/attribute_change_veto.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Petra
+  module Components
+    module Entries
+      #
+      # Tells the system to ignore all attribute changes we made to the current
+      # attribute during the transaction.
+      #
+      class AttributeChangeVeto < Petra::Components::LogEntry
+        # Mostly for debugging purposes: The external value that caused
+        # the creation of this log entry
+        field_accessor :external_value
+
+        def self.kind
+          :attribute_change_veto
+        end
+
+        #
+        # As for ReadIntegrityOverrides, we have to make sure that
+        # AttributeChangeVetoes are always persisted.
+        #
+        def persist?
+          true
+        end
+
+        def persist_on_retry?
+          true
+        end
+
+        def apply!; end
+
+        Petra::Components::LogEntry.register_entry_type(kind, self)
+      end
+    end
+  end
+end

data/lib/petra/components/entries/attribute_read.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Petra
+  module Components
+    module Entries
+      class AttributeRead < Petra::Components::LogEntry
+        field_accessor :method
+        field_accessor :value
+
+        def self.kind
+          :attribute_read
+        end
+
+        def apply!; end
+
+        Petra::Components::LogEntry.register_entry_type(:attribute_read, self)
+      end
+    end
+  end
+end

data/lib/petra/components/entries/object_destruction.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Petra
+  module Components
+    module Entries
+      class ObjectDestruction < Petra::Components::LogEntry
+        field_accessor :method
+
+        def self.kind
+          :object_destruction
+        end
+
+        def apply!
+          # TODO: React to `false` responses from destruction methods?
+          proxied_object.send(method)
+        end
+
+        Petra::Components::LogEntry.register_entry_type(:object_destruction, self)
+      end
+    end
+  end
+end

data/lib/petra/components/entries/object_initialization.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Petra
+  module Components
+    module Entries
+      class ObjectInitialization < Petra::Components::LogEntry
+        field_accessor :method
+
+        def self.kind
+          :object_initialization
+        end
+
+        def apply!; end
+
+        Petra::Components::LogEntry.register_entry_type(kind, self)
+      end
+    end
+  end
+end

data/lib/petra/components/entries/object_persistence.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Petra
+  module Components
+    module Entries
+      class ObjectPersistence < Petra::Components::LogEntry
+        field_accessor :method
+
+        # Arguments given to the persistence method.
+        # This is especially necessary for persistence methods which are
+        # also attribute writers or similar.
+        field_accessor :args
+
+        def self.kind
+          :object_persistence
+        end
+
+        def apply!
+          proxied_object.send(method, *(args || []))
+        end
+
+        Petra::Components::LogEntry.register_entry_type(kind, self)
+      end
+    end
+  end
+end

data/lib/petra/components/entries/read_integrity_override.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Petra
+  module Components
+    module Entries
+      #
+      # Tells the system not to raise further ReadIntegrityErrors for the given attribute
+      # as long as the external value stays the same.
+      #
+      class ReadIntegrityOverride < Petra::Components::LogEntry
+        # The external attribute value at the time this log entry
+        # was created. It is used to determine whether a new ReadIntegrityError has
+        # to be raised or not.
+        field_accessor :external_value
+
+        def self.kind
+          :read_integrity_override
+        end
+
+        #
+        # ReadIntegrityOverrides always have to be persisted:
+        # They are only generated if an exception (ReadIntegrityError, etc) happened
+        # which in most cases (except for a rescue within the transaction proc itself)
+        # means that its execution stopped and the only thing left is persisting the transaction.
+        # Therefore, this log entry will most likely be the last one in the current section
+        # and would be lost if we wouldn't persist it.
+        #
+        def persist?
+          true
+        end
+
+        def persist_on_retry?
+          true
+        end
+
+        def apply!; end
+
+        Petra::Components::LogEntry.register_entry_type(kind, self)
+      end
+    end
+  end
+end

data/lib/petra/components/entry_set.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'petra/components/log_entry'
+
+module Petra
+  module Components
+    #
+    # An EntrySet is a collection of log entries for a certain section.
+    # It may be used to chain-filter entries, e.g. only object_persisted entries for a certain proxy.
+    #
+    # TODO: Probably be Enumerator::Lazy...
+    #
+    class EntrySet < Array
+
+      #----------------------------------------------------------------
+      #                          Filters
+      #----------------------------------------------------------------
+
+      def for_proxy(proxy)
+        wrap { select { |e| e.for_object?(proxy.__object_key) } }
+      end
+
+      def of_kind(kind)
+        wrap { select { |e| e.kind?(kind) } }
+      end
+
+      def for_attribute_key(key)
+        wrap { select { |e| e.attribute_key.to_s == key.to_s } }
+      end
+
+      def object_persisted
+        wrap { select(&:object_persisted?) }
+      end
+
+      def not_object_persisted
+        wrap { reject(&:object_persisted?) }
+      end
+
+      def latest
+        last
+      end
+
+      #----------------------------------------------------------------
+      #                      Persistence / Commit
+      #----------------------------------------------------------------
+
+      #
+      # Applies all log entries which were marked as object persisted
+      # The log entry itself decides whether it is actually executed or not.
+      #
+      def apply!
+        object_persisted.each(&:apply!)
+      end
+
+      #
+      # Tells each log entry to enqueue for persisting.
+      # The individual log entries may decided whether they actually want
+      # to be persisted or not.
+      #
+      def enqueue_for_persisting!
+        each(&:enqueue_for_persisting!)
+      end
+
+      def prepare_for_retry!
+        select(&:persist_on_retry?).each(&:enqueue_for_persisting!)
+      end
+
+      #----------------------------------------------------------------
+      #                      Wrapped Array Methods
+      #----------------------------------------------------------------
+
+      def reverse(*)
+        wrap { super }
+      end
+
+      def sort(*)
+        wrap { super }
+      end
+
+      private
+
+      def wrap
+        self.class.new(yield)
+      end
+    end
+  end
+end