perobs 3.0.2 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 985e62db6b84f509a3b390ce11ac96f4215de5ea
-  data.tar.gz: f6747e42300df5c9b55c1a5bbc6adf9822165b7b
+  metadata.gz: a988f009b1b97bc8da2b2bcfeb65399284a07032
+  data.tar.gz: 4346d5cdbec5b4154741f0a41d3f526985803912
 SHA512:
-  metadata.gz: 7ed1499555741de10e6810f62041ffc879a738f488f5ce09860bddae21ed12cf999a8d4303361227a3798f3f389bd6cb9584e71e809b26d0f82fa7cdc6a28544
-  data.tar.gz: 2c56287162c7ae376ecdc091e55655fd37e4985e22914a4e21d74f28eb0c3e054ca543fb7092485ea09605b8a0ad4cc33f13dc96fa19ffcdf5137921c5b145ae
+  metadata.gz: 639673c10faa5082c742258ee9848f5e951c6d1ec7fc9f03ec7066260ea5042b6c8b90020df6fa506b8be54cc5fd9793a0939f80ef1da726c27832c8a2eb8c85
+  data.tar.gz: 92e63145a1fc9b6e76dbdf6f4cdebfb5a8935bfcbd93a9634e22c12f874b945b656a17fe93aa03a7a3189a00371d2e2abd8d411862ad0ad51b0c364f7b7dc027

data/README.md

@@ -30,7 +30,7 @@ classes:
 
 When you derive your own class from PEROBS::Object you need to
 specify which instance variables should be persistent. By using
-po_attr you can provide a list of symbols that describe the instance
+'attr_persist' you can provide a list of symbols that declare the instance
 variables to persist. This will also create getter and setter methods
 for these instance varables.  You can set default values in the
 constructor . The constructor of PEROBS::ObjectBase derived objects
@@ -61,13 +61,14 @@ almost every Ruby data type. YAML is much slower than JSON and Marshal
 is not guaranteed to be compatible between Ruby versions.
 
 Once you have created a store you can assign objects to it. All
-persistent objects must be created with Store.new(). This is
-necessary as you will only deal with proxy objects in your code.
-Except for the member methods, you will never deal with the objects
-directly. Instead Store.new() returns a POXReference object that acts
-as a transparent proxy. This proxy is needed as your code never knows
-if the actual object is really loaded into the memory or not. PEROBS
-will handle this transparently for you.
+persistent objects must be created with Store.new(). The Store object
+is available via the @store instance variable provided by the parent
+class. This is necessary as you will only deal with proxy objects in
+your code.  Except for the member methods, you will never deal with
+the objects directly. Instead Store.new() returns a POXReference
+object that acts as a transparent proxy. This proxy is needed as your
+code never knows if the actual object is really loaded into the memory
+or not. PEROBS will handle this transparently for you.
 
 A build-in cache keeps access latencies to recently used objects low
 and lazily flushes modified objects into the persistend back-end when
@@ -92,19 +93,19 @@ require 'perobs'
 
 class Person < PEROBS::Object
 
-  po_attr :name, :mother, :father, :kids, :spouse, :status
+  attr_persist :name, :mother, :father, :kids, :spouse, :status
 
   def initialize(p, name)
     super(p)
-    attr_init(:name, name)
-    attr_init(:kids, store.new(PEROBS::Array))
-    attr_init(:status, :single)
+    self.name = name
+    self.kids = @store.new(PEROBS::Array)
+    self.status = :single
   end
 
   def restore
     # Use block version of attr_init() to avoid creating unneded
     # objects. The block is only called when @father doesn't exist yet.
-    attr_init(:father) do { store.new(Person, 'Dad') }
+    attr_init(:father) do { @store.new(Person, 'Dad') }
   end
 
   def merry(spouse)
@@ -136,7 +137,7 @@ contains the 3 Person objects.
 ### Accessing persistent instance variables
 
 All instance variables that should be persisted must be declared with
-'po_attr'. This will create the instance variable, a getter and setter
+'attr_persist'. This will create the instance variable, a getter and setter
 method for it. These getter and setter methods are the recommended way
 to access instance variables both from ouside of the instances as well
 as from within. To access the setter or getter method from within an
@@ -166,8 +167,8 @@ object to another object.
 ### Caveats and known issues
 
 PEROBS is currently not thread-safe. You cannot simultaneously access
-the database from multiple application. You must provide your own
-locking mechanism to prevent this from happening.
+the database from multiple application. The library uses locks to
+ensure that only one Store object is accessing the database at a time.
 
 ## Installation
 
@@ -187,7 +188,7 @@ Or install it yourself as:
 
 ## Copyright and License
 
-Copyright (c) 2015, 2016 by Chris Schlaeger <chris@taskjuggler.org>
+Copyright (c) 2015, 2016, 2017 by Chris Schlaeger <chris@taskjuggler.org>
 
 PEROBS and all accompanying files are licensed under this MIT License
 

data/lib/perobs/BTree.rb

@@ -27,7 +27,7 @@
 
 require 'perobs/LockFile'
 require 'perobs/EquiBlobsFile'
-require 'perobs/BTreeNodeCache'
+require 'perobs/PersistentObjectCache'
 require 'perobs/BTreeNode'
 
 module PEROBS
@@ -40,7 +40,7 @@ module PEROBS
   # have N + 1 references to child nodes instead.
   class BTree
 
-    attr_reader :order, :nodes
+    attr_reader :order, :nodes, :node_cache
 
     # Create a new BTree object.
     # @param dir [String] Directory to store the tree file
@@ -64,7 +64,7 @@ module PEROBS
       # This EquiBlobsFile contains the nodes of the BTree.
       @nodes = EquiBlobsFile.new(@dir, @name,
                                  BTreeNode::node_bytes(@order))
-      @node_cache = BTreeNodeCache.new
+      @node_cache = PersistentObjectCache.new(512, BTreeNode, self)
 
       # This BTree implementation uses a write cache to improve write
       # performance of multiple successive read/write operations. This also
@@ -89,8 +89,10 @@ module PEROBS
 
       @node_cache.clear
       @nodes.open
-      set_root(new_node(nil, @nodes.total_entries == 0 ?
-                             nil : @nodes.first_entry))
+      node = @nodes.total_entries == 0 ?
+        BTreeNode::create(self) :
+        BTreeNode::load(self, @nodes.first_entry)
+      set_root(node)
     end
 
     # Close the tree file.
@@ -104,7 +106,7 @@ module PEROBS
     def clear
       @node_cache.clear
       @nodes.clear
-      set_root(new_node(nil))
+      set_root(BTreeNode::create(self))
     end
 
     # Erase the backing store of the BTree. This method should only be called
@@ -112,6 +114,7 @@ module PEROBS
     # all stored data from the BTree.
     def erase
       @nodes.erase
+      @root = nil
       @dirty_flag.forced_unlock
     end
 
@@ -132,7 +135,6 @@ module PEROBS
     def set_root(node)
       @root = node
       @nodes.first_entry = node.node_address
-      @node_cache.set_root(node)
     end
 
     # Insert a new value into the tree using the key as a unique index. If the
@@ -178,17 +180,6 @@ module PEROBS
       @root.each(&block)
     end
 
-    # Mark the given node as being modified. This will cause the dirty_flag
-    # lock to be taken and the @is_dirty flag to be set.
-    # @param node [BTreeNode] node to mark
-    def mark_node_as_modified(node)
-      unless @is_dirty
-        @dirty_flag.lock
-        @is_dirty = true
-      end
-      @node_cache.mark_as_modified(node)
-    end
-
     # Delete the node at the given address in the BTree file.
     # @param address [Integer] address in file
     def delete_node(address)
@@ -201,32 +192,6 @@ module PEROBS
       @root.to_s
     end
 
-    # Create a new BTreeNode. If the node_address is not nil, the node data is
-    # read from the backing store. The parent and is_leaf arguments are
-    # ignored in this case.
-    # @param parent [BTreeNode] parent node
-    # @param node_address [Integer or nil] address of the node to create
-    # @param is_leaf[Boolean] True if node is a leaf node, false otherweise
-    def new_node(parent, node_address = nil, is_leaf = true)
-      node = BTreeNode.new(self, parent, node_address, is_leaf)
-      @node_cache.insert(node)
-
-      node
-    end
-
-    # Return the BTreeNode that matches the given node address. If a blob
-    # address and size are given, a new node is created instead of being read
-    # from the file.
-    # @param node_address [Integer] Address of the node in the BTree file
-    # @return [BTreeNode]
-    def get_node(node_address)
-      if (node = @node_cache[node_address])
-        return node
-      end
-
-      new_node(nil, node_address)
-    end
-
   end
 
 end

data/lib/perobs/BTreeNode.rb

@@ -40,7 +40,6 @@ module PEROBS
   class BTreeNode
 
     attr_reader :node_address, :parent, :is_leaf, :keys, :values, :children
-    attr_accessor :dirty
 
     # Create a new BTreeNode object for the given tree with the given parent
     # or recreate the node with the given node_address from the backing store.
@@ -53,44 +52,118 @@ module PEROBS
     #        backing store
     # @param is_leaf [Boolean] true if the node should be a leaf node, false
     #        if not
-    def initialize(tree, parent = nil, node_address = nil, is_leaf = true)
+    def initialize(tree, node_address = nil, parent = nil, is_leaf = true,
+                   keys = [], values = [], children = [])
       @tree = tree
-      @parent = nil
       if node_address == 0
         PEROBS.log.fatal "Node address may not be 0"
       end
       @node_address = node_address
-      @keys = []
+      @parent = parent ? BTreeNodeLink.new(tree, parent) : nil
+      @keys = keys
       if (@is_leaf = is_leaf)
-        @values = []
-      else
+        @values = values
         @children = []
+      else
+        @children = children
+        @values = []
       end
 
-      if node_address
-        unless node_address.is_a?(Integer)
-          PEROBS.log.fatal "node_address is not Integer: #{node_address.class}"
-        end
+      ObjectSpace.define_finalizer(
+        self, BTreeNode._finalize(@tree, @node_address, object_id))
+      @tree.node_cache.insert(self, false)
+    end
 
-        # This must be an existing node. Try to read it and fill the instance
-        # variables.
-        unless read_node
-          PEROBS.log.fatal "SpaceTree node at address #{node_address} " +
-            "does not exist"
-        end
+    # This method generates the destructor for the objects of this class. It
+    # 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 BTreeNode::_finalize(tree, node_address, ruby_object_id)
+      proc { tree.node_cache._collect(node_address, ruby_object_id) }
+    end
+
+    # Create a new SpaceTreeNode. This method should be used for the creation
+    # of new nodes instead of calling the constructor directly.
+    # @param tree [BTree] The tree the new node should belong to
+    # @param parent [BTreeNode] The parent node
+    # @param is_leaf [Boolean] True if the node has no children, false
+    #        otherwise
+    def BTreeNode::create(tree, parent = nil, is_leaf = true)
+      unless parent.nil? || parent.is_a?(BTreeNode) ||
+             parent.is_a?(BTreeNodeLink)
+        PEROBS.log.fatal "Parent node must be a BTreeNode but is of class " +
+          "#{parent.class}"
+      end
+
+      address = tree.nodes.free_address
+      node = BTreeNode.new(tree, address, parent, is_leaf)
+      # This is a new node. Make sure the data is written to the file.
+      tree.node_cache.insert(node)
+
+      node
+    end
+
+    # Restore a node from the backing store at the given address and tree.
+    # @param tree [BTree] The tree the node belongs to
+    # @param node_address [Integer] The address in the blob file.
+    def BTreeNode::load(tree, address)
+      unless address.is_a?(Integer)
+        PEROBS.log.fatal "address is not Integer: #{address.class}"
+      end
+
+      unless (bytes = tree.nodes.retrieve_blob(address))
+        PEROBS.log.fatal "SpaceTree node at address #{address} " +
+          "does not exist"
+      end
+
+      unless Zlib::crc32(bytes) != 0
+        PEROBS.log.fatal "Checksum failure in BTreeNode entry @#{address}"
+      end
+      ary = bytes.unpack(BTreeNode::node_bytes_format(tree))
+      # Read is_leaf
+      if ary[0] != 0 && ary[0] != 1
+        PEROBS.log.fatal "First byte of a BTreeNode entry must be 0 or 1"
+      end
+      is_leaf = ary[0] == 0 ? false : true
+      # This is the number of keys this node has.
+      key_count = ary[1]
+      data_count = ary[2]
+      # Read the parent node address
+      parent = ary[3] == 0 ? nil : BTreeNodeLink.new(tree, ary[3])
+      # Read the keys
+      keys = ary[4, key_count]
+
+      children = nil
+      values = nil
+      if is_leaf
+        # Read the values
+        values = ary[4 + tree.order, data_count]
       else
-        unless parent.nil? || parent.is_a?(BTreeNode) ||
-               parent.is_a?(BTreeNodeLink)
-          PEROBS.log.fatal "Parent node must be a BTreeNode but is of class " +
-            "#{parent.class}"
+        # Read the child addresses
+        children = []
+        data_count.times do |i|
+          child_address = ary[4 + tree.order + i]
+          unless child_address > 0
+            PEROBS.log.fatal "Child address must be larger than 0"
+          end
+          children << BTreeNodeLink.new(tree, child_address)
         end
-
-        # This is a new node. Make sure the data is written to the file.
-        @node_address = @tree.nodes.free_address
-        self.parent = parent
       end
+
+      node = BTreeNode.new(tree, address, parent, is_leaf, keys, values,
+                           children)
+      tree.node_cache.insert(node, false)
+
+      node
+    end
+
+    # @return [String] The format used for String.pack.
+    def BTreeNode::node_bytes_format(tree)
+      # This does not include the 4 bytes for the CRC32 checksum
+      "CSSQQ#{tree.order}Q#{tree.order + 1}"
     end
 
+    # @return [Integer] The number of bytes needed to store a node.
     def BTreeNode::node_bytes(order)
       1 + # is_leaf
       2 + # actual key count
@@ -101,6 +174,16 @@ module PEROBS
       4 # CRC32 checksum
     end
 
+    # Save the node into the blob file.
+    def save
+      write_node
+    end
+
+    # The node address uniquely identifies a BTreeNode.
+    def uid
+      @node_address
+    end
+
     # Insert or replace the given value by using the key as unique address.
     # @param key [Integer] Unique key to retrieve the value
     # @param value [Integer] value to insert
@@ -186,14 +269,14 @@ module PEROBS
     def split_node
       unless @parent
         # The node is the root node. We need to create a parent node first.
-        self.parent = @tree.new_node(nil, nil, false)
+        self.parent = BTreeNode::create(@tree, nil, false)
         @parent.set_child(0, self)
         @tree.set_root(@parent)
       end
 
       # Create the new sibling that will take the 2nd half of the
       # node content.
-      sibling = @tree.new_node(@parent, nil, @is_leaf)
+      sibling = BTreeNode::create(@tree, @parent, @is_leaf)
       # Determine the index of the middle element that gets moved to the
       # parent. The order must be an uneven number, so adding 1 will get us
       # the middle element.
@@ -229,7 +312,6 @@ module PEROBS
         PEROBS.log.fatal "Cannot insert into a full BTreeNode"
       end
 
-      mark_as_modified
       i = search_key_index(key)
       if @keys[i] == key
         # Overwrite existing entries
@@ -248,6 +330,7 @@ module PEROBS
           @children.insert(i + 1, BTreeNodeLink.new(@tree, value_or_child))
         end
       end
+      @tree.node_cache.insert(self)
     end
 
     # Remove the element at the given index.
@@ -256,7 +339,6 @@ module PEROBS
       first_key = @keys[0]
       removed_value = nil
 
-      mark_as_modified
       # Delete the key at the specified index.
       unless @keys.delete_at(index)
         PEROBS.log.fatal "Could not remove element #{index} from BTreeNode " +
@@ -269,6 +351,7 @@ module PEROBS
         # The corresponding child has can be found at 1 index higher.
         @children.delete_at(index + 1)
       end
+      @tree.node_cache.insert(self)
 
       # Find the lower and upper siblings and the index of the key for this
       # node in the parent node.
@@ -301,7 +384,6 @@ module PEROBS
       end
 
       dest_node.keys[dst_idx, count] = @keys[src_idx, count]
-      dest_node.dirty = true
       if @is_leaf
         # For leaves we copy the keys and corresponding values.
         dest_node.values[dst_idx, count] = @values[src_idx, count]
@@ -313,11 +395,12 @@ module PEROBS
           dest_node.set_child(dst_idx + i, @children[src_idx + i])
         end
       end
+      @tree.node_cache.insert(dest_node)
     end
 
     def parent=(p)
       @parent = p ? BTreeNodeLink.new(@tree, p) : nil
-      mark_as_modified
+      @tree.node_cache.insert(self)
     end
 
     def set_child(index, child)
@@ -327,17 +410,17 @@ module PEROBS
       else
         @children[index] = nil
       end
-      mark_as_modified
+      @tree.node_cache.insert(self)
     end
 
     def trim(idx)
-      mark_as_modified
       @keys = @keys[0..idx - 1]
       if @is_leaf
         @values = @values[0..idx - 1]
       else
         @children = @children[0..idx]
       end
+      @tree.node_cache.insert(self)
     end
 
     # Search the keys of the node that fits the given key. The result is
@@ -598,8 +681,6 @@ module PEROBS
     end
 
     def write_node
-      return unless @dirty
-
       ary = [
         @is_leaf ? 1 : 0,
         @keys.size,
@@ -620,66 +701,13 @@ module PEROBS
         ary += @children.map{ |c| c.node_address } +
           ::Array.new(@tree.order + 1 - @children.size, 0)
       end
-      bytes = ary.pack(node_bytes_format)
+      bytes = ary.pack(BTreeNode::node_bytes_format(@tree))
       bytes += [ Zlib::crc32(bytes) ].pack('L')
       @tree.nodes.store_blob(@node_address, bytes)
-      @dirty = false
-    end
-
-    def mark_as_modified
-      @tree.mark_node_as_modified(self)
-      @dirty = true
     end
 
     private
 
-    def read_node
-      return false unless (bytes = @tree.nodes.retrieve_blob(@node_address))
-
-      unless Zlib::crc32(bytes) != 0
-        PEROBS.log.error "Checksum failure in BTreeNode entry @#{node_address}"
-        return false
-      end
-      ary = bytes.unpack(node_bytes_format)
-      # Read is_leaf
-      if ary[0] != 0 && ary[0] != 1
-        PEROBS.log.error "First byte of a BTreeNode entry must be 0 or 1"
-        return false
-      end
-      @is_leaf = ary[0] == 0 ? false : true
-      # This is the number of keys this node has.
-      key_count = ary[1]
-      data_count = ary[2]
-      # Read the parent node address
-      @parent = ary[3] == 0 ? nil : BTreeNodeLink.new(@tree, ary[3])
-      # Read the keys
-      @keys = ary[4, key_count]
-
-      if @is_leaf
-        # Read the values
-        @values = ary[4 + @tree.order, data_count]
-      else
-        # Read the child addresses
-        @children = []
-        data_count.times do |i|
-          address = ary[4 + @tree.order + i]
-          unless address > 0
-            PEROBS.log.fatal "Child address must not be 0"
-          end
-          @children << BTreeNodeLink.new(@tree, address)
-        end
-      end
-
-      @dirty = false
-
-      true
-    end
-
-    def node_bytes_format
-      # This does not include the 4 bytes for the CRC32 checksum
-      "CSSQQ#{@tree.order}Q#{@tree.order + 1}"
-    end
-
     def find_closest_siblings(key)
       # The root node has no siblings.
       return [ nil, nil, nil ] unless @parent