perobs 3.0.1 → 4.3.0

data/lib/perobs/Object.rb

@@ -2,7 +2,7 @@
 #
 # = Object.rb -- Persistent Ruby Object Store
 #
-# Copyright (c) 2015, 2016 by Chris Schlaeger <chris@taskjuggler.org>
+# Copyright (c) 2015, 2016, 2017 by Chris Schlaeger <chris@taskjuggler.org>
 #
 # MIT License
 #
@@ -49,9 +49,11 @@ module PEROBS
       attr_reader :attributes
 
       # This method can be used to define instance variable for
-      # PEROBS::Object derived classes.
+      # PEROBS::Object derived classes. Persistent attributes always have
+      # getter and setter methods defined. So it's essentially equivalent to
+      # attr_accessor but additionally declares an attribute as persistent.
       # @param attributes [Symbol] Name of the instance variable
-      def po_attr(*attributes)
+      def attr_persist(*attributes)
         attributes.each do |attr_name|
           unless attr_name.is_a?(Symbol)
             PEROBS.log.fatal "name must be a symbol but is a " +
@@ -73,6 +75,9 @@ module PEROBS
         end
       end
 
+      # This is the deprecated name for the attr_persist method
+      alias po_attr attr_persist
+
     end
 
     attr_reader :attributes
@@ -108,7 +113,7 @@ module PEROBS
     # object was saved with an earlier version of the program that did not yet
     # have the instance variable. If you want to assign another PEROBS object
     # to the variable you should use the block variant to avoid unnecessary
-    # creation of PEROBS object that later need to be collected again.
+    # creation of PEROBS objects that later need to be collected again.
     def attr_init(attr, val = nil, &block)
       if _all_attributes.include?(attr)
         unless instance_variable_defined?('@' + attr.to_s)
@@ -140,7 +145,7 @@ module PEROBS
 
     # Return a list of all object IDs that the attributes of this instance are
     # referencing.
-    # @return [Array of Fixnum or Bignum] IDs of referenced objects
+    # @return [Array of Integer] IDs of referenced objects
     def _referenced_object_ids
       ids = []
       _all_attributes.each do |attr|
@@ -152,7 +157,7 @@ module PEROBS
 
     # This method should only be used during store repair operations. It will
     # delete all references to the given object ID.
-    # @param id [Fixnum/Bignum] targeted object ID
+    # @param id [Integer] targeted object ID
     def _delete_reference_to_id(id)
       _all_attributes.each do |attr|
         ivar = ('@' + attr.to_s).to_sym
@@ -207,17 +212,7 @@ module PEROBS
     end
 
     def _set(attr, val)
-      if val.respond_to?(:is_poxreference?)
-        # References to other PEROBS::Objects must be handled somewhat
-        # special.
-        if @store != val.store
-          PEROBS.log.fatal 'The referenced object is not part of this store'
-        end
-      elsif val.is_a?(ObjectBase)
-        PEROBS.log.fatal 'A PEROBS::ObjectBase object escaped! ' +
-          'Have you used self() instead of myself() to get the reference ' +
-          'of the PEROBS object that you are trying to assign here?'
-      end
+      _check_assignment_value(val)
       instance_variable_set(('@' + attr.to_s).to_sym, val)
       # Let the store know that we have a modified object. If we restored the
       # object from the DB, we don't mark it as modified.
@@ -231,13 +226,26 @@ module PEROBS
     end
 
     def _all_attributes
+      # Collect all persistent attributes from this class and all
+      # super classes into a single Array.
+      attributes = []
+      klass = self.class
+      while klass && klass.respond_to?(:attributes)
+        if (attrs = klass.attributes)
+          attributes += attrs
+        end
+        klass = klass.superclass
+      end
+
       # PEROBS objects that don't have persistent attributes declared don't
       # really make sense.
-      unless self.class.attributes
+      if attributes.empty?
         PEROBS.log.fatal "No persistent attributes have been declared for " +
-          "class #{self.class}. Use 'po_attr' to declare them."
+          "class #{self.class} or any parent class. Use 'attr_persist' " +
+          "to declare them."
       end
-      self.class.attributes
+
+      attributes
     end
 
   end

data/lib/perobs/ObjectBase.rb

@@ -86,6 +86,10 @@ module PEROBS
       _referenced_object == obj
     end
 
+    def eql?(obj)
+      _referenced_object._id == obj._id
+    end
+
     # BasicObject provides a equal?() method that prevents method_missing from
     # being called. So we have to pass the call manually to the referenced
     # object.
@@ -98,6 +102,13 @@ module PEROBS
       end
     end
 
+    # To allow POXReference objects to be used as Hash keys we need to
+    # implement this function. Conveniently, we can just use the PEROBS object
+    # ID since that is unique.
+    def hash
+      @id
+    end
+
     # Shortcut to access the _id() method of the referenced object.
     def _id
       @id
@@ -114,6 +125,20 @@ module PEROBS
   # common to all classes of persistent objects.
   class ObjectBase
 
+    # This is a list of the native Ruby classes that are supported for
+    # instance variable assignements in addition to other PEROBS objects.
+    if RUBY_VERSION < '2.2'
+      NATIVE_CLASSES = [
+        NilClass, Integer, Bignum, Fixnum, Float, String, Time,
+        TrueClass, FalseClass
+      ]
+    else
+      NATIVE_CLASSES = [
+        NilClass, Integer, Float, String, Time,
+        TrueClass, FalseClass
+      ]
+    end
+
     attr_reader :_id, :store, :myself
 
     # New PEROBS objects must always be created by calling # Store.new().
@@ -133,7 +158,8 @@ module PEROBS
       @store = p.store
       @_id = p.id
       @store._register_in_memory(self, @_id)
-      ObjectSpace.define_finalizer(self, ObjectBase._finalize(@store, @_id))
+      ObjectSpace.define_finalizer(
+        self, ObjectBase._finalize(@store, @_id, object_id))
       @_stash_map = nil
       # Allocate a proxy object for this object. User code should only operate
       # on this proxy, never on self.
@@ -144,8 +170,8 @@ module PEROBS
     # is done this way to prevent the Proc object hanging on to a reference to
     # self which would prevent the object from being collected. This internal
     # method is not intended for users to call.
-    def ObjectBase._finalize(store, id)
-      proc { store._collect(id) }
+    def ObjectBase._finalize(store, id, ruby_object_id)
+      proc { store._collect(id, ruby_object_id) }
     end
 
     # Library internal method to transfer the Object to a new store.
@@ -158,7 +184,8 @@ module PEROBS
       # Register the object as in-memory object with the new store.
       @store._register_in_memory(self, @_id)
       # Register the finalizer for the new store.
-      ObjectSpace.define_finalizer(self, ObjectBase._finalize(@store, @_id))
+      ObjectSpace.define_finalizer(
+        self, ObjectBase._finalize(@store, @_id, object_id))
       @myself = POXReference.new(@store, @_id)
     end
 
@@ -190,6 +217,25 @@ module PEROBS
       @store.db.put_object(db_obj, @_id)
     end
 
+    #
+    def _check_assignment_value(val)
+      if val.respond_to?(:is_poxreference?)
+        # References to other PEROBS::Objects must be handled somewhat
+        # special.
+        if @store != val.store
+          PEROBS.log.fatal 'The referenced object is not part of this store'
+        end
+      elsif val.is_a?(ObjectBase)
+        PEROBS.log.fatal 'A PEROBS::ObjectBase object escaped! ' +
+          'Have you used self() instead of myself() to get the reference ' +
+          'of the PEROBS object that you are trying to assign here?'
+      elsif !NATIVE_CLASSES.include?(val.class)
+        PEROBS.log.fatal "Assigning objects of class #{val.class} is not " +
+          "supported. Only PEROBS objects or one of the following classes " +
+          "are supported: #{NATIVE_CLASSES.join(', ')}"
+      end
+    end
+
     # Read an raw object with the specified ID from the backing store and
     # instantiate a new object of the specific type.
     def ObjectBase.read(store, id)
@@ -207,19 +253,16 @@ module PEROBS
     end
 
     # Restore the object state from the storage back-end.
-    # @param level [Fixnum] the transaction nesting level
+    # @param level [Integer] the transaction nesting level
     def _restore(level)
       # Find the most recently stored state of this object. This could be on
       # any previous stash level or in the regular object DB. If the object
-      # was created during the transaction, there is not previous state to
+      # was created during the transaction, there is no previous state to
       # restore to.
       data = nil
       if @_stash_map
         (level - 1).downto(0) do |lvl|
-          if @_stash_map[lvl]
-            data = @_stash_map[lvl]
-            break
-          end
+          break if (data = @_stash_map[lvl])
         end
       end
       if data

data/lib/perobs/PersistentObjectCache.rb

@@ -0,0 +1,142 @@
+# encoding: UTF-8
+#
+# = PersistentObjectCache.rb -- Persistent Ruby Object Store
+#
+# Copyright (c) 2016, 2017 by Chris Schlaeger <chris@taskjuggler.org>
+#
+# MIT License
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'perobs/PersistentObjectCacheLine'
+
+module PEROBS
+
+  class PersistentObjectCache
+
+    # This cache class manages the presence of objects that primarily live in
+    # a backing store but temporarily exist in memory as well. To work with
+    # these objects, direct references must be only very short lived. Indirect
+    # references can be done via a unique ID that the object must provide. Due
+    # to the indirect references the Ruby garbage collector can collect these
+    # objects. To reduce the read and write latencies of the backing store
+    # this class keeps a subset of the objects in memory which prevents them
+    # from being collected. All references to the objects must be resolved via
+    # the get() method to prevent duplicate instances in memory of the same
+    # in-store object. The cache uses a least-recently-used (LRU) scheme to
+    # cache objects.
+    # @param size [Integer] Minimum number of objects to be cached at a time
+    # @param flush_delay [Integer] Determines how often non-forced flushes are
+    #        ignored in a row before the flush is really done. If flush_delay
+    #        is smaller than 0 non-forced flushed will always be ignored.
+    # @param klass [Class] The class of the objects to be cached. Objects must
+    #        provide a uid() method that returns a unique ID for every object.
+    # @param collection [] The object collection the objects belong to. It
+    #        must provide a ::load method.
+    def initialize(size, flush_delay, klass, collection)
+      @size = size
+      @klass = klass
+      @collection = collection
+      @flush_delay = @flush_counter = flush_delay
+      @flush_times = 0
+
+      clear
+    end
+
+    # Insert an object into the cache.
+    # @param object [Object] Object to cache
+    # @param modified [Boolean] True if the object was modified, false otherwise
+    def insert(object, modified = true)
+      unless object.is_a?(@klass)
+        raise ArgumentError, "You can insert only #{@klass} objects in this " +
+          "cache. You have tried to insert a #{object.class} instead."
+      end
+
+      if modified
+        @modified_entries[object.uid] = object
+      else
+        @unmodified_entries[object.uid % @size] = object
+      end
+
+      nil
+    end
+
+    # Retrieve a object reference from the cache.
+    # @param uid [Integer] uid of the object to retrieve.
+    # @param ref [Object] optional reference to be used by the load method
+    def get(uid, ref = nil)
+      # First check if it's a modified object.
+      if (object = @modified_entries[uid])
+        return object
+      end
+
+      # Then check the unmodified object list.
+      if (object = @unmodified_entries[uid % @size]) && object.uid == uid
+        return object
+      end
+
+      # If we don't have it in memory we need to load it.
+      @klass::load(@collection, uid, ref)
+    end
+
+    # Remove a object from the cache.
+    # @param uid [Integer] unique ID of object to remove.
+    def delete(uid)
+      @modified_entries.delete(uid)
+
+      index = uid % @size
+      if (object = @unmodified_entries[index]) && object.uid == uid
+        @unmodified_entries[index] = nil
+      end
+    end
+
+    # Write all excess modified objects into the backing store. If now is true
+    # all modified objects will be written.
+    # @param now [Boolean]
+    def flush(now = false)
+      if now || (@flush_delay >= 0 && (@flush_counter -= 1) <= 0)
+        @modified_entries.each do |id, object|
+          object.save
+          # Add the object to the unmodified object cache. We might still need
+          # it again soon.
+          @unmodified_entries[object.uid % @size] = object
+        end
+        @modified_entries = ::Hash.new
+        @flush_counter = @flush_delay
+      end
+      @flush_times += 1
+    end
+
+    # Remove all entries from the cache.
+    def clear
+      # This Array stores all unmodified entries. It has a fixed size and uses
+      # a % operation to compute the index from the object ID.
+      @unmodified_entries = ::Array.new(@size)
+
+      # This Hash stores all modified entries. It can grow and shrink as
+      # needed. A flush operation writes all modified objects into the backing
+      # store.
+      @modified_entries = ::Hash.new
+    end
+
+  end
+
+end
+

data/lib/perobs/PersistentObjectCacheLine.rb

@@ -0,0 +1,99 @@
+# encoding: UTF-8
+#
+# = PersistentObjectCacheLine.rb -- Persistent Ruby Object Store
+#
+# Copyright (c) 2016, 2017 by Chris Schlaeger <chris@taskjuggler.org>
+#
+# MIT License
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+module PEROBS
+
+  class PersistentObjectCacheLine
+
+    # Utility class to store persistent objects and their
+    # modified/not-modified state.
+    class Entry < Struct.new(:obj, :modified)
+    end
+
+    # This defines the minimum size of the cache line. If it is too large, the
+    # time to find an entry will grow too much. If it is too small the number
+    # of cache lines will be too large and create more store overhead. By
+    # running benchmarks it turned out that 8 is a pretty good compromise.
+    WATERMARK = 8
+
+    def initialize
+      @entries = []
+    end
+
+    def insert(object, modified)
+      if (index = @entries.find_index{ |e| e.obj.uid == object.uid })
+        # We have found and removed an existing entry for this particular
+        # object. If the modified flag is set, ensure that the entry has it
+        # set as well.
+        entry = @entries.delete_at(index)
+        entry.modified = true if modified && !entry.modified
+      else
+        # There is no existing entry for this object. Create a new one.
+        entry = Entry.new(object, modified)
+      end
+
+      # Insert the entry at the beginning of the line.
+      @entries.unshift(entry)
+    end
+
+    def get(uid)
+      if (index = @entries.find_index{ |e| e.obj.uid == uid })
+        if index > 0
+          # Move the entry to the front.
+          @entries.unshift(@entries.delete_at(index))
+        end
+        @entries.first
+      else
+        nil
+      end
+    end
+
+    # Delete the entry that matches the given UID
+    # @param uid [Integer]
+    def delete(uid)
+      @entries.delete_if { |e| e.obj.uid == uid }
+    end
+
+    # Save all modified entries and delete all but the most recently added.
+    def flush(now)
+      if now || @entries.length > WATERMARK
+        @entries.each do |e|
+          if e.modified
+            e.obj.save
+            e.modified = false
+          end
+        end
+
+        # Delete all but the first WATERMARK entry.
+        @entries = @entries[0..WATERMARK - 1] if @entries.length > WATERMARK
+      end
+    end
+
+  end
+
+end
+