iotaz 0.1.0

data/lib/iotaz/ObjectPool.rb

@@ -0,0 +1,299 @@
+#!/usr/bin/env ruby
+#
+#--
+# Copyright � Peter Wood, 2005
+# 
+# The contents of this file are subject to the Mozilla Public License Version
+# 1.1 (the "License"); you may not use this file except in compliance with the
+# License. You may obtain a copy of the License at 
+#
+# http://www.mozilla.org/MPL/
+# 
+# Software distributed under the License is distributed on an "AS IS" basis,
+# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
+# the specificlanguage governing rights and  limitations under the License.
+# 
+# The Original Code is the FireRuby extension for the Ruby language.
+# 
+# The Initial Developer of the Original Code is Peter Wood. All Rights 
+# Reserved.
+#++
+#
+
+require 'thread'
+
+module Iotaz
+   #
+   # This class represents an object within an object pool and shouldn't really
+   # be used outside of this context.
+   #
+   class PoolObject
+      #
+      # This is the constructor for the PoolObject class.
+      #
+      # ==== Parameters
+      # object::  The object to be held within the pool.
+      #
+      def initialize(object)
+         @object    = object
+         @reserved  = false
+         @timestamp = Time.new
+      end
+      
+      
+      #
+      # This method reserves a pool object.
+      #
+      def reserve
+         if @reserve
+            raise IotazError.new('Reserve called on reserved pool object.')
+         end
+         @reserved  = true
+         @timestamp = Time.new
+      end
+      
+      
+      #
+      # This method releases a previously reserved pool object.
+      #
+      def release
+         if @reserve == false
+            raise IotazError.new('Release called on unreserved pool object.')
+         end
+         @reserved  = false
+         @timestamp = Time.new
+      end
+      
+      
+      # Class attribute accessor.
+      attr_reader :object, :reserved, :timestamp
+   end # End of the PoolObject class.
+   
+   
+   #
+   # This class represents a simple object pool. It should be noted that this
+   # class starts a thread of it's own to monitor for idle resources if an
+   # idle period is set. Note also that the idle period and the idle test
+   # interval cannot be reduced to less than 60 seconds each. The pool is
+   # considered immutable after it is created.
+   #
+   class ObjectPool
+      # A definition for the minimum idle period setting.
+      MIN_IDLE       = 60
+      
+      # A definition for the minimum idle checking interval.
+      MIN_INTERVAL     = 60
+      
+      
+      #
+      # This is the constructor for the ObjectPool class.
+      #
+      # ==== Parameters
+      # factory::   A reference to the object that will be used to manufacture
+      #             and destroy the resource objects. This object must have
+      #             methods called create and destroy.
+      # maximum::   The maximum amount of objects the pool is permitted to have
+      #             available.
+      # minimum::   The minimum amount of objects that the pool is permitted
+      #             to have available. Defaults to zero.
+      # idle::      The minimum amount of time, in seconds, that a resource my
+      #             be idle before being destroyed. If set to -1, the default
+      #             value then the resource objects will never be destroyed.
+      # interval::  The period, in seconds between checks for idle entries.
+      #             Defaults to 600 seconds (10 minutes).
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a problem occurs with the settings for
+      #               the object pool.
+      #
+      def initialize(factory, maximum, minimum=0, idle=-1, interval=600)
+         if maximum.kind_of?(Integer) == false or maximum < minimum
+            raise IotazError.new('Invalid object pool maximum setting specified.')
+         end
+         
+         @factory   = factory
+         @objects   = []
+         @maximum   = maximum
+         @minimum   = minimum
+         @mutex     = Mutex.new
+         @thread    = nil
+         @blocked   = []
+         if idle >= 0
+            @idle = idle > MIN_IDLE ? idle : MIN_IDLE
+         else
+            @idle = -1
+         end
+         @interval = interval > MIN_INTERVAL ? interval : MIN_INTERVAL
+         
+         start_thread if idle != -1
+         
+         # Add the minimum number of resources.
+         @minimum.times do
+            @objects.push(PoolObject.new(@factory.create))
+         end
+      end
+      
+      
+      #
+      # This method obtains an object from the pool. If there isn't a free
+      # object in the pool one will be manufactured unless the pool has
+      # reached maximum capacity. The calling thread will block until a
+      # resource has become available. The method also accepts a block
+      # which delimits the lease time that the acquired object is given.
+      # The acquired object is passed as a parameter to the block and is
+      # automatically released when the block exits. If a block is given
+      # then the method always returns nil.
+      #
+      # ==== Parameters
+      # wait::  A boolean flag to indicate whether the thread will wait for
+      #         the resource to become available if one isn't immediately
+      #         available.
+      #
+      # ==== Exceptions
+      # IotazError::   Generated whenever the caller has indicated that they are
+      #                not prepared to wait for a pool object and a pool object is
+      #                not immediately available.
+      # Exception::    If a block is given and, during it's execution, an
+      #                exception is raised it will be thrown out of the method
+      #                call as is.
+      #
+      def acquire(wait=true)
+         resource = nil
+         while resource == nil
+            @mutex.synchronize do
+               resource = @objects.find {|object| object.reserved == false}
+               if resource == nil
+                  if @objects.size < @maximum
+                     resource = PoolObject.new(@factory.create)
+                     resource.reserve
+                     @objects.push(resource)
+                     resource = resource.object
+                  else
+                     @blocked.push(Thread.current) if wait
+                  end
+               else
+                  resource.reserve
+                  resource = resource.object
+               end
+            end
+            if resource == nil and wait == false
+               raise IotazError.new('Pooled object not available.')
+            end
+            Thread.stop if resource == nil and wait == true
+         end
+         
+         if block_given?
+            begin
+               yield(resource)
+            rescue Exception => error
+               raise error
+            ensure
+               release(resource)
+               resource = nil
+            end
+         end
+         
+         resource
+      end
+      
+      
+      #
+      # This method returns an object to the pool. This method will also
+      # restart any threads waiting for pool resources.
+      #
+      # ==== Parameters
+      # object::  A reference to the object instance being returned to the
+      #           pool.
+      #
+      def release(object)
+         @mutex.synchronize do
+            resource = @objects.find {|entry| entry.object == object}
+            if resource != nil
+               resource.release
+               @blocked.each do |thread|
+                  thread.run
+               end
+               @blocked = []
+            end
+         end
+      end
+      
+      
+      #
+      # This method initiates the thread that monitors the pool for idle
+      # resources.
+      #
+      def start_thread
+         @mutex.synchronize do
+            if @therad == nil
+               @thread = Thread.new do
+                  idle_sweep
+                  sleep(@interval)
+               end
+            end
+         end
+      end
+      
+      
+      #
+      # This method cleans up the resources associated with a pool and shuts
+      # down it's monitor thread. The method should be called before the
+      # application using the pool terminates.
+      #
+      def shutdown
+         @mutex.synchronize do
+            @thread.exit if @thread != nil
+            @objects.each do |entry|
+               @factory.destroy(entry.object)
+            end
+         end
+      end
+      
+      
+      #
+      # This method returns the number of objects currently held within a
+      # an object pool.
+      #
+      def size
+         @objects.size
+      end
+      
+      
+      #
+      # This method returns the number of objects currently available within
+      # an object pool.
+      #
+      def available
+         total = 0
+         @mutex.synchronize do
+            @objects.each {|entry| total += 1 if entry.reserved == false}
+         end
+         total
+      end
+      
+      
+      #
+      # This method is used internally by the pool to remove idle entries
+      #
+      def idle_sweep
+         @mutex.synchronize do
+            @objects.delete_if do |entry|
+               result = false
+               if Time.new.to_i - entry.timestamp.to_i >= @interval and
+                  @objects.size > @minimum
+                  @factory.destroy(entry.object)
+                  result = true
+               end
+               result
+            end
+         end
+      end
+
+
+      # Class attribute accessor.
+      attr_reader :factory, :minimum, :maximum, :idle, :interval
+      
+      # Method access alterations.
+      private :start_thread, :idle_sweep
+   end # End of the ObjectPool class.
+end # End of the Iotaz module.

data/lib/iotaz/Persistent.rb

@@ -0,0 +1,155 @@
+#!/usr/bin/env ruby
+#
+#--
+# Copyright (C) Peter Wood, 2005
+#     
+# The contents of this file are subject to the Mozilla Public License Version
+# 1.1 (the "License"); you may not use this file except in compliance with the
+# License. You may obtain a copy of the License at 
+#
+# http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS IS" basis,
+# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
+# the specificlanguage governing rights and  limitations under the License.
+#
+# The Original Code is the FireRuby extension for the Ruby language.
+#
+# The Initial Developer of the Original Code is Peter Wood. All Rights
+# Reserved.     
+#++
+#
+
+module Iotaz
+   module Persistent
+      # Module constants.
+      @@code = [%q{@@iotaz_meta_data = Iotaz::IotazMetaData.new(self)},
+                %q{def self.class_basename(source)
+                      name  = source.instance_of?(String) ? source : source.name
+                      index = name.rindex("::")
+                      if index != nil
+                         index += 2
+                         name  = name[index, name.length - index]
+                      end
+                      name
+                   end},
+                %q{def self.iotaz_meta_data
+                       @@iotaz_meta_data
+                   end},
+                %q{def self.persistent_attr(name, column=nil, readonly=false)
+                      attr :"#{name}", true
+                      private :"#{name}=" if readonly
+                      name = name.id2name if name.class == Symbol
+                      attribute = Attribute.new(name, column)
+                      @@iotaz_meta_data.add_attribute(attribute)
+                   end},
+                %q{def self.sequence_attr(name, column=nil, key=true,
+                                          source=nil, readonly=true,
+                                          create=true, update=false)
+                      attr :"#{name}", true
+                      private :"#{name}=" if readonly
+                      name = name.id2name if name.class == Symbol
+                      events = ""
+                      if create == true and update == false
+                         events = 'INSERT'
+                      elsif create == false and update == true
+                         events = 'UPDATE'
+                      else
+                          events = 'INSERT,UPDATE'
+                      end
+                      generator = source
+                      if source == nil
+                         generator = "#{class_basename(self)}_ID_SQ".upcase
+                      end
+                      attribute = GeneratedAttribute.new(name, 'SEQUENCE',
+                                                         events, generator,
+                                                         column)
+                      @@iotaz_meta_data.add_attribute(attribute, key)
+                   end},
+                %q{def self.date_attr(name, column=nil, create=true,
+                                      update=false, value='TODAY',
+                                      readonly=true)
+                      attr :"#{name}", true
+                      private :"#{name}=" if readonly
+                      name = name.id2name if name.class == Symbol
+                      events = ""
+                      if create == true and update == false
+                         events = 'INSERT'
+                      elsif create == false and update == true
+                         events = 'UPDATE'
+                      else
+                          events = 'INSERT,UPDATE'
+                      end
+                      attribute = GeneratedAttribute.new(name, 'DATE', events,
+                                                         value, column)
+                      @@iotaz_meta_data.add_attribute(attribute)
+                   end},
+                %q{def self.time_attr(name, column=nil, create=true,
+                                      update=false, readonly=true)
+                      attr :"#{name}", true
+                      private :"#{name}=" if readonly
+                      name = name.id2name if name.class == Symbol
+                      events = ""
+                      if create == true and update == false
+                         events = 'INSERT'
+                      elsif create == false and update == true
+                         events = 'UPDATE'
+                      else
+                          events = 'INSERT,UPDATE'
+                      end
+                      attribute = GeneratedAttribute.new(name, 'TIME', events,
+                                                         'NOW', column)
+                      @@iotaz_meta_data.add_attribute(attribute)
+                   end},
+                %q{def self.timestamp_attr(name, column=nil, create=true,
+                                           update=false, readonly=true)
+                      attr :"#{name}", true
+                      private :"#{name}=" if readonly
+                      name = name.id2name if name.class == Symbol
+                      events = ""
+                      if create == true and update == false
+                         events = 'INSERT'
+                      elsif create == false and update == true
+                         events = 'UPDATE'
+                      else
+                          events = 'INSERT,UPDATE'
+                      end
+                      attribute = GeneratedAttribute.new(name, 'TIMESTAMP',
+                                                         events, 'NOW', column)
+                      @@iotaz_meta_data.add_attribute(attribute)
+                   end},
+                %q{def self.table_name=(name)
+                      @@iotaz_meta_data.table = name
+                   end}]
+      
+      
+      #
+      # This method gets invoked whenever this module is used to extend an
+      # existing class or module.
+      #
+      # ==== Parameters
+      # target::  A reference to the class or module that is being extended.
+      #
+      def Persistent.extend_object(target)
+         @@code.each do |entry|
+            target.module_eval(entry)
+         end
+      end
+      
+      
+      #
+      # This method gets invoked whenever this module is included into another
+      # module or class.
+      #
+      # ==== Parameters
+      # target::  A reference to the class or module including the Persistent
+      #           module.
+      #
+      def Persistent.append_features(target)
+         super(target)
+         @@code.each do |entry|
+            target.module_eval(entry)
+         end
+      end
+   end # End of the Persistent module
+end # End of the Iotaz module.