pod4 0.10.6 → 1.0.0

data/lib/pod4/basic_model.rb

@@ -1,8 +1,8 @@
-require 'octothorpe'
+require "octothorpe"
 
-require_relative 'metaxing'
-require_relative 'errors'
-require_relative 'alert'
+require_relative "metaxing"
+require_relative "errors"
+require_relative "alert"
 
 
 module Pod4
@@ -20,17 +20,15 @@ module Pod4
   class BasicModel
     extend Metaxing
 
-    
     # The value of the ID field on the record
     attr_reader :model_id
 
     # one of Model::STATII
     attr_reader :model_status
 
-    # Valid values for @model_status: :error :warning :okay :deleted or :empty
+    # Valid values for @model_status: :error :warning :okay :deleted or :unknown
     STATII = %i|error warning okay deleted empty|
 
-
     class << self
 
       ##
@@ -44,27 +42,23 @@ module Pod4
         raise NotImplemented, "no call to set_interface in the model"
       end
 
-    end
-    ##
-
+    end # of class << self
 
     ##
     # Initialize a model by passing it a unique id value.
     # Override this to set initial values for your column attributes.
     #
     def initialize(id=nil)
-      @model_status = :empty
+      @model_status = :unknown
       @model_id     = id
       @alerts       = []
     end
 
-
     ##
     # Syntactic sugar; same as self.class.interface, which returns the interface instance.
     #
     def interface; self.class.interface; end
 
-
     ##
     # Return the list of alerts. 
     #
@@ -72,11 +66,10 @@ module Pod4
     #
     def alerts; @alerts.dup; end
 
-
     ##
     # Clear down the alerts.
     #
-    # Note that set model_status to :okay. Theoretically it might need to be :empty or :deleted,
+    # Note that we set model_status to :okay. Theoretically it might need to be :unknown or :deleted,
     # but if you are calling clear_alerts before a call to `read` or after a call to `delete`, then
     # you have more problems than I can solve.
     #
@@ -85,7 +78,6 @@ module Pod4
       @model_status = :okay
     end
 
-
     ##
     # Raise a Pod4 exception for the model if any alerts are status :error; otherwise do
     # nothing.
@@ -100,13 +92,10 @@ module Pod4
       raise ValidationError.from_alert(al) if al && al.type == :error
       self
     end
-
     alias :or_die :raise_exceptions
 
-
     private
 
-    
     ##
     # Add a Pod4::Alert to the model instance @alerts attribute
     #
@@ -123,10 +112,8 @@ module Pod4
       st = @alerts.sort.first.type
       @model_status = st if %i|error warning|.include?(st)
     end
-
     
-  end
-  ##
+  end # of BasicModel
 
 
 end

data/lib/pod4/connection.rb

@@ -0,0 +1,67 @@
+require_relative 'interface'
+
+
+module Pod4
+
+
+  class Connection
+
+    attr_reader   :interface_class
+    attr_accessor :data_layer_options
+
+    ##
+    # Intitialise a Connection. You must pass a Pod4::Interface class. The connection object will
+    # only accept calls from instances of this class.
+    #
+    # `conn = Pod4::Connection.new(interface: MyInterface)`
+    #
+    def initialize(args)
+      raise ArgumentError, "Connection#new needs a Hash" unless args.is_a? Hash
+      raise ArgumentError, "You must pass a Pod4::Interface" \
+        unless args[:interface] \
+            && args[:interface].is_a?(Class) \
+            && args[:interface].ancestors.include?(Interface)
+
+      @interface_class    = args[:interface]
+      @data_layer_options = nil
+      @client             = nil
+      @options            = nil
+    end
+
+    ##
+    # When an interface wants a connection, it calls connection.client. If the connection does
+    # not have one, it asks the interface for one....
+    #
+    # Interface is an instance of whatever class you passed to Connection when you initialised
+    # it. That is: when an interface wants a connection, it passes `self`.
+    #
+    def client(interface)
+      fail_bad_interfaces(interface)
+      @client ||= interface.new_connection(@data_layer_options)
+      @client
+    end
+
+    ##
+    # Close the connection.  
+    # In the case of a single connection, this is probably not going to get used much. But.
+    #
+    def close(interface)
+      fail_bad_interfaces(interface)
+      interface.close_connection 
+      @client = nil
+      return self
+    end
+
+    private
+
+    def fail_bad_interfaces(f)
+      raise ArgumentError, "That's not a #@interface_class", caller \
+        unless f.kind_of?(@interface_class)
+
+    end
+
+  end # of Connection
+
+
+end
+

data/lib/pod4/connection_pool.rb

@@ -0,0 +1,154 @@
+require "time"
+require "thread"
+
+require_relative "interface"
+require_relative "connection"
+require_relative "errors"
+
+
+module Pod4
+
+
+  class ConnectionPool < Connection
+
+    PoolItem = Struct.new(:client, :thread_id)
+
+    class Pool
+      def initialize
+        @items = []
+        @mutex = Mutex.new
+      end
+
+      def <<(cl)
+        @mutex.synchronize do
+          @items << PoolItem.new(cl, Thread.current.object_id)
+        end
+      end
+
+      def get_current 
+        @items.find{|x| x.thread_id == Thread.current.object_id }
+      end
+
+      def get_free
+        @mutex.synchronize do
+          pi = @items.find{|x| x.thread_id.nil? }
+          pi.thread_id = Thread.current.object_id if pi
+          pi
+        end
+      end
+
+      def release
+        pi = get_current
+        pi.thread_id = nil if pi
+      end
+
+      def drop
+        @items.delete_if{|x| x.thread_id == Thread.current.object_id }
+      end
+
+      def size 
+        @items.size
+      end
+
+      def _dump
+        @mutex.synchronize do
+          @items
+        end
+      end
+    end # of Pool
+    
+    attr_reader :max_clients, :max_wait
+
+    DEFAULT_MAX_CLIENTS = 10
+
+    ##
+    # As Connection, but with some options you can set.
+    #
+    # * max_clients -- if this many clients are assigned to threads, wait until one is freed.
+    # pass nil for no maximum.  Tries to default to something sensible. 
+    #
+    # * max_wait -- throw a Pod4::PoolTimeout if you wait more than this time in seconds.
+    # Pass nil to wait forever. Default is nil, because you would need to handle that timeout.
+    #
+    def initialize(args)
+      super(args)
+
+      @max_clients = args[:max_clients] || DEFAULT_MAX_CLIENTS
+      @max_wait    = args[:max_wait]
+      @pool        = Pool.new
+    end
+
+    ##
+    # Return a client for the interface to use.
+    #
+    # Return the client we gave this thread before. 
+    # Failing that, assign a free one from the pool.
+    # Failing that, ask the interface to give us a new client.
+    #
+    # Note: The interface passes itself in case we want to call it back to get a new client; but
+    # clients are assigned to a _thread_. Every interface in a given thread gets the same pool
+    # item, the same client object.
+    #
+    def client(interface)
+      time = Time.now
+      cl   = nil
+
+      # NB: We are constrained to use loop in order for our test to work
+      loop do
+        if (pi = @pool.get_current)
+          cl = pi.client
+          break
+        end
+
+        if (pi = @pool.get_free)
+          cl = pi.client
+          break
+        end
+
+        if @max_clients && @pool.size >= @max_clients 
+          raise Pod4::PoolTimeout if @max_wait && (Time.now - time > @max_wait)
+          sleep 1
+          next
+        end
+
+        cl = interface.new_connection(@data_layer_options)
+        @pool << cl
+        break
+      end # of loop
+
+      cl
+    end
+
+    ##
+    # De-assign the client for the current thread from that thread.
+    #
+    # We never ask the interface to close the connection to the database.  There is no advantage in
+    # doing that for us.
+    #
+    # Note: The interface passes itself in case we want to call it back to actually close the
+    # client; but clients are assigned to a _thread_.
+    #
+    def close(interface)
+      @pool.release
+    end
+
+    ##
+    # Remove the client object entirely -- for example, because the connection to the database has
+    # expired.
+    #
+    def drop(interface)
+      @pool.drop
+    end
+
+    ##
+    # Dump the internal pool (for test purposes only)
+    #
+    def _pool
+      @pool._dump
+    end
+
+  end # of ConnectionPool
+
+
+end
+

data/lib/pod4/errors.rb

@@ -94,6 +94,26 @@ module Pod4
   end
 
 
+  ##
+  # Raised if ConnectionPool times out waiting for a client to become free.
+  # This can only happen if your pool has a maximum number of clients set, and a max_wait value
+  # set; and if all the clients are currently in use.
+  #
+  class PoolTimeout < Pod4Error
+    attr_reader :field
+
+    def self.from_alert(alert)
+      self.new(alert.message, alert.field)
+    end
+
+    def initialize(message=nil, field=nil)
+      super(message || $! && $!.message)
+      @field = field.to_s.to_sym
+    end
+
+  end
+
+
 
 end
 

data/lib/pod4/interface.rb

@@ -38,9 +38,15 @@ module Pod4
     # A field name in the data source, the name of the unique ID field.
     #
     def id_fld
-      raise NotImplemented, "Interface needs to define an 'id_fld' method"
+      raise NotImplemented, "Interface has no 'id_fld' method (use `set_id_fld`?)"
     end
 
+    ##
+    # true if id_fld autoincrements
+    #
+    def id_ai
+      raise NotImplemented, "Interface has no 'id_ai' method (use `set_id_fld`?)"
+    end
 
     ##
     # Individual implementations are likely to have very different initialize methods, which will
@@ -51,7 +57,6 @@ module Pod4
       raise NotImplemented, "Interface needs to define an 'initialize' method"
     end
 
-
     ##
     # List accepts a parameter as selection criteria, and returns an array of Octothorpes. Exactly
     # what the selection criteria look like will vary from interface to interface. So will the
@@ -61,46 +66,63 @@ module Pod4
     # Note that list should ALWAYS return an array; never nil.
     #
     def list(selection=nil)
-      raise NotImplemented, "Interface needs to define 'list' method"
+      raise NotImplemented, "Interface needs to define a 'list' method"
     end
 
-
     ##
     # Create accepts a record parameter (Hash or OT, but again, the format of this will vary)
     # representing a record, and creates the record.  Should return the ID for the new record.
     #
     def create(record)
-      raise NotImplemented, "Interface needs to define 'create' method"
+      raise NotImplemented, "Interface needs to define a 'create' method"
     end
 
-
     ##
     # Read accepts an ID, and returns an Octothorpe representing the unique record for that ID. If
     # there is no record matching the ID then it returns an empty Octothorpe.
     #
     def read(id)
-      raise NotImplemented, "Interface needs to define 'read' method"
+      raise NotImplemented, "Interface needs to define a 'read' method"
     end
 
-
     ##
     # Update accepts an ID and a record parameter. It updates the record on the data source that
     # matches the ID using the record parameter.  It returns self.
     #
     def update(id, record)
-      raise NotImplemented, "Interface needs to define 'update' method"
+      raise NotImplemented, "Interface needs to define a 'update' method"
     end
 
-
     ##
     # delete removes the record with the given ID. returns self.
     #
     def delete(id)
-      raise NotImplemented, "Interface needs to define 'delete' method"
+      raise NotImplemented, "Interface needs to define a 'delete' method"
     end
 
+    ##
+    # Called by a Connection object to start a database connection
+    #
+    def new_connection(args)
+      raise NotImplemented, "Interface needs to define a 'new_connection' method"
+    end
+
+    ##
+    # Called by a Connection Object to close the connection.
+    #
+    def close_connection(conn)
+      raise NotImplemented, "Interface needs to define a 'close_connection' method"
+    end
+
+    ##
+    # For testing purposes you should expose a _connection method that returns the Connection
+    # object the Interface uses
+    #
+    def _connection
+      raise NotImplemented, "Interface needs to define a '_connection' method"
+    end
 
-  end
+  end # of Interface
 
 
 end