needle 0.5.0 → 0.6.0

data/lib/needle/{models → lifecycle}/proxy.rb

@@ -14,20 +14,28 @@
 # =============================================================================
 #++
 
-require 'thread'
+require 'needle/thread'
 
 module Needle
-  module Models
+  module Lifecycle
 
     # A proxy class to aid in deferred instantiation of service points. This is
     # used primarily by the "deferred" service models.
     class Proxy
 
-      # Create a new proxy that wraps the given service point.
-      def initialize( container, &callback )
-        @container = container
-        @callback = callback
-        @mutex = Mutex.new
+      # Create a new proxy object that wraps the object returned by either the
+      # +proc_obj+ or +callback+. (Only one of +proc_obj+ or +callback+ should
+      # be specified.)
+      def initialize( proc_obj=nil, *args, &callback )
+        if proc_obj && callback
+          raise ArgumentError, "only specify argument OR block, not both"
+        end
+
+        @callback = proc_obj || callback or
+          raise ArgumentError, "callback required"
+
+        @args = args
+        @mutex = QueryableMutex.new
         @instantiation_failed = false
         @instance = nil
       end
@@ -39,7 +47,7 @@ module Needle
           @mutex.synchronize do
             unless @instance || @instantiation_failed
               begin
-                @instance = @callback.call( @container )
+                @instance = @callback.call( *@args )
               rescue Exception
                 @instantiation_failed = true
                 raise

data/lib/needle/lifecycle/singleton.rb

@@ -0,0 +1,63 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Needle dependency injection
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Needle
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# needle website : http://needle.rubyforge.org
+# project website: http://rubyforge.org/projects/needle
+# =============================================================================
+#++
+
+require 'needle/pipeline/element'
+require 'needle/thread'
+
+module Needle
+  module Lifecycle
+
+    # The instantiation pipeline element that enforces the singleton
+    # multiplicity.
+    class Singleton < Needle::Pipeline::Element
+      set_default_priority 100
+
+      # Creates the mutex to use and sets the cached reference to +nil+.
+      def initialize_element
+        @mutex = QueryableMutex.new
+        @cached = nil
+        @is_cached = false
+      end
+
+      # Returns the cached reference, if it has been previously cached.
+      # Otherwise, invokes the next element in the pipeline and caches the
+      # result. The cached reference is returned.
+      def call( *args )
+        unless @is_cached
+          @mutex.synchronize do
+            unless @is_cached
+              @cached = succ.call( *args )
+              @is_cached = true
+            end
+          end
+        end
+
+        @cached
+      end
+
+      # Resets the cached singleton instance, so that the next time it is
+      # requested it is re-constructed.
+      def reset!
+        @mutex.synchronize do
+          @cached = nil
+          @is_cached = false
+        end
+      end
+
+    end
+
+  end
+end

data/lib/needle/lifecycle/threaded.rb

@@ -0,0 +1,58 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Needle dependency injection
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Needle
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# needle website : http://needle.rubyforge.org
+# project website: http://rubyforge.org/projects/needle
+# =============================================================================
+#++
+
+require 'needle/pipeline/element'
+
+module Needle
+  module Lifecycle
+
+    # The instantiation pipeline element that enforces the singleton
+    # multiplicity, on a per-thread basis.
+    class Threaded < Needle::Pipeline::Element
+      set_default_priority 100
+
+      # Returns a Hash of threaded services that are cached by the current
+      # thread.
+      def service_cache
+        Thread.current[ :threaded_services ] ||= Hash.new
+      end
+
+      # Returns the cached reference, if it has been previously cached for
+      # the current thread. Otherwise, invokes the next element in the pipeline
+      # and caches the result. The cached reference is returned.
+      def call( *args )
+        cache = service_cache
+        name = service_point.fullname
+
+        unless cache.has_key?( name )
+          service = succ.call( *args )
+          cache[ name ] = service
+        end
+
+        cache[ name ]
+      end
+
+      # Resets the cached singleton instance, so that the next time it is
+      # requested it is re-constructed.
+      def reset!
+        cache = service_cache
+        cache.delete service_point.fullname
+      end
+
+    end
+
+  end
+end

data/lib/needle/pipeline/collection.rb

@@ -0,0 +1,133 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Needle dependency injection
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Needle
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# needle website : http://needle.rubyforge.org
+# project website: http://rubyforge.org/projects/needle
+# =============================================================================
+#++
+
+require 'needle/pipeline/element'
+
+module Needle
+  module Pipeline
+
+    # Represents a collection of pipeline elements. Elements may be added to
+    # the pipeline, and then returned as a single object representing thechain
+    # of pipeline elements.
+    class Collection
+
+      # Wraps a block as a new pipeline element. When the element is invoked,
+      # control is delegated to the block.
+      class BlockElement < Element
+        
+        set_default_priority 0
+
+        # Create a new pipeline element around the given block.
+        def initialize( point, name, priority, options, block )
+          super( point, name, priority, options )
+          @block = block
+        end
+
+        # Invoke the block. The block must accept as many parameters as the
+        # pipeline expects, plus 1 (the first parameter is always this
+        # BlockElement instance).
+        def call( *args )
+          @block.call( self, *args )
+        end
+
+      end
+
+      # Create a new pipeline element collection, initially empty.
+      def initialize( service_point )
+        @elements = []
+        @service_point = service_point
+      end
+
+      # Add a new pipeline element to this collection. If the first parameter
+      # is a symbol or a string, it is taken to be the name of the element to
+      # add. If no explicit implementation is given, then the implementation is
+      # looked up in the <tt>:pipeline_elements</tt> service, using the given
+      # name.
+      #
+      # After the first parameter, if the next parameter is numeric, it is taken
+      # to mean the priority of the element. This overrides whatever default
+      # priority is given for the selected element.
+      #
+      # If the next parameter responds to the <tt>:new</tt> message, it is taken
+      # to be an explicit implementation of the element. This is only valid if
+      # a block is not given. If a block is given, then it is always taken to be
+      # the implementation of the element.
+      #
+      # If the last parameter is a Hash, it is taken to be a map of options that
+      # should be passed to the element when it is instantiated.
+      #
+      # This returns +self+, so that #add calls may be chained.
+      def add( *args, &block )
+        name = priority = nil
+        options = {}
+        klass = nil
+        element = nil
+
+        if [ Symbol, String ].any? { |i| args.first.is_a?( i ) }
+          name = args.shift.to_s.intern
+        end
+        priority = args.shift if args.first.is_a?( Numeric )
+        klass = args.shift if args.first.respond_to?( :new ) && block.nil?
+        options = args.shift if args.first.is_a?( Hash )
+
+        raise ArgumentError,
+          "bad argument list #{args.inspect}" unless args.empty?
+
+        if block
+          element = BlockElement.new( @service_point, name, priority,
+            options, block )
+        else
+          klass ||= @service_point.container[:pipeline_elements].fetch( name )
+          element = klass.new( @service_point, name, priority, options )
+        end
+
+        @elements << element
+        self
+      end
+
+      # Returns the first pipeline element with the given name, or +nil+ if no
+      # such element exists.
+      def get( name )
+        name = name.to_s.intern
+        @elements.find { |el| name == el.name }
+      end
+
+      # Builds a linked list of the elements, with the last element being the
+      # block (or block-like) object given by the parameter. Higher-priority
+      # elements will be closer to the head of the list.
+      def chain_to( block )
+        head = tail = nil
+        @elements.sort.reverse.each do |el|
+          if head
+            tail.succ = el
+            tail = el
+          else
+            head = tail = el
+          end
+        end
+
+        if tail
+          tail.succ = block
+          return head
+        else
+          return block
+        end
+      end
+
+    end
+
+  end
+end

data/lib/needle/pipeline/element.rb

@@ -0,0 +1,85 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Needle dependency injection
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Needle
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# needle website : http://needle.rubyforge.org
+# project website: http://rubyforge.org/projects/needle
+# =============================================================================
+#++
+
+module Needle
+  module Pipeline
+
+    # The base class of instantiation pipeline elements. All subclasses
+    # MUST implement is the #call method, to define the logic that instances of
+    # that pipeline element should perform when invoked.
+    class Element
+      include Comparable
+
+      # The service definition that this element belongs to.
+      attr_reader :service_point
+      
+      # The name of this element (may be +nil+).
+      attr_reader :name
+      
+      # The priority of this element, used to determine ordering. Higher ordered
+      # elements are invoked before lower-ordered elements.
+      attr_reader :priority
+
+      # The hash of options that were given to this element.
+      attr_reader :options
+
+      # The next element in the chain. This value is only valid during pipeline
+      # execution--its value should not be relied upon at any other time.
+      attr_accessor :succ
+
+      class << self
+        # The default priority to use for elements of this type.
+        attr_reader :default_priority
+
+        # Set the default priority for elements of this type. Subclasses may
+        # use this method to set their default priority.
+        def set_default_priority( priority )
+          @default_priority = priority
+        end
+      end
+
+      set_default_priority 0
+
+      # Create a new element instance with the given name and priority. This
+      # will call #initialize_element, so that subclasses only need to
+      # implement that method if they have any initialization logic to perform.
+      def initialize( point, name=nil, priority=nil, options={} )
+        @service_point = point
+        @name, @priority = name, ( priority || self.class.default_priority )
+        @options = options
+        initialize_element
+      end
+
+      # Invoked by the constructor to perform any subclass-specific
+      # initialization logic.
+      def initialize_element
+      end
+
+      # Orders elements by their priority.
+      def <=>( element )
+        priority <=> element.priority
+      end
+
+      # Invoke this element's logic.
+      def call( *args )
+        raise NotImplementedError
+      end
+
+      alias :[] :call
+    end
+
+  end
+end

data/lib/needle/pipeline/interceptor.rb

@@ -0,0 +1,46 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Needle dependency injection
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Needle
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# needle website : http://needle.rubyforge.org
+# project website: http://rubyforge.org/projects/needle
+# =============================================================================
+#++
+
+require 'needle/interceptor-chain'
+require 'needle/pipeline/element'
+
+module Needle
+  module Pipeline
+
+    # The pipeline element that implements adding interceptors to a service.
+    class InterceptorElement < Element
+
+      set_default_priority 0
+
+      # The array of interceptors to be proxied onto the object.
+      attr_reader :interceptors
+
+      # Initializes the array of interceptors. It is initially empty.
+      def initialize_element
+        @interceptors = []
+      end
+
+      # Invokes the next element in the chain and adds the interceptors to
+      # the result, returning a proxy object wrapped by the interceptors.
+      def call( container, point, *args )
+        service = succ.call( container, point, *args )
+        InterceptorChainBuilder.build( point, service, @interceptors )
+      end
+
+    end
+
+  end
+end

data/lib/needle/registry.rb

@@ -16,9 +16,13 @@
 
 require 'needle/container'
 require 'needle/errors'
+require 'needle/lifecycle/deferred'
+require 'needle/lifecycle/initialize'
+require 'needle/lifecycle/singleton'
+require 'needle/lifecycle/threaded'
 require 'needle/log-factory'
 require 'needle/logging-interceptor'
-require 'needle/models'
+require 'needle/pipeline/interceptor'
 
 module Needle
 
@@ -42,7 +46,7 @@ module Needle
     # each names. By default, the name is empty.
     DEFAULT_REGISTRY_NAME = ""
 
-    # Instantiate a new Registry (via #new) and immediately invoke #register!
+    # Instantiate a new Registry (via #new) and immediately invoke #define!
     # using the given block.
     #
     # Usage:
@@ -55,13 +59,16 @@ module Needle
     #   adder = registry.add
     def self.new!( *parms, &block )
       raise NeedleError, "needs a block" if block.nil?
-      new( *parms ) { |reg| reg.register!( &block ) }
+      new( *parms ) { |reg| reg.define!( &block ) }
     end
 
     # Instantiate a new Registry. If the first parameter is a string, it will
     # be used as the name of this registry. If the next parameter is a Hash,
     # it will be used as the options to use when bootstrapping the registry.
-    # (This includes options used to initialize the logger factory.
+    #
+    # The options hash may include options used to initialize the logger
+    # factory. The logger factory options should be in another hash, keyed
+    # by the value <tt>:logs</tt>.
     #
     # If a block is given, the constructed registry instance is yielded to it.
     #
@@ -74,6 +81,12 @@ module Needle
     #   registry = Needle::Registry.new do |reg|
     #     reg.register( :add ) { Adder.new }
     #   end
+    #
+    # or
+    #
+    #   registry = Needle::Registry.new(
+    #     :logs => { :filename => "/dev/null" }
+    #   )
     def initialize( *parms )
       raise ArgumentError, "expected <= 2 arguments" if parms.length > 2
       name = ( parms.first.is_a?( String ) ? parms.shift :
@@ -95,11 +108,38 @@ module Needle
       "[#{super}]"
     end
 
-    # Bootstraps the service models, logger factory, and logging interceptor
-    # services into the current registry. This is only called when a new
-    # registry is created.
+    # Bootstraps the pipeline elements, service models, logger factory, and
+    # logging interceptor services into the current registry. This is only
+    # called when a new registry is created.
     def bootstrap( opts )
-      Models.register( self )
+      register( :pipeline_elements, :pipeline=>[] ) { Hash.new }
+      pipeline( :pipeline_elements ).add( :singleton,
+        Needle::Lifecycle::Singleton )
+
+      self[:pipeline_elements].update(
+        :singleton   => Needle::Lifecycle::Singleton,
+        :initialize  => Needle::Lifecycle::Initialize,
+        :deferred    => Needle::Lifecycle::Deferred,
+        :interceptor => Needle::Pipeline::InterceptorElement,
+        :threaded    => Needle::Lifecycle::Threaded
+      )
+
+      register( :service_models, :pipeline=>[:singleton] ) { Hash.new }
+      self[:service_models].update(
+        :prototype                     => [],
+        :prototype_initialize          => [ :initialize ],
+        :prototype_deferred            => [ :deferred ],
+        :prototype_deferred_initialize => [ :deferred, :initialize ],
+        :singleton                     => [ :singleton ],
+        :singleton_initialize          => [ :singleton, :initialize ],
+        :singleton_deferred            => [ :singleton, :deferred ],
+        :singleton_deferred_initialize => [ :singleton, :deferred, :initialize ],
+        :threaded                      => [ :threaded ],
+        :threaded_initialize           => [ :threaded, :initialize ],
+        :threaded_deferred             => [ :threaded, :deferred ],
+        :threaded_deferred_initialize  => [ :threaded, :deferred, :initialize ]
+      )
+
       register( :logs ) { LogFactory.new( opts[:logs] || {} ) }
       register( :logging_interceptor ) { LoggingInterceptor }
     end

data/lib/needle/service-point.rb

@@ -14,7 +14,8 @@
 # =============================================================================
 #++
 
-require 'needle/interceptor-chain'
+require 'needle/pipeline/collection'
+require 'needle/thread'
 
 module Needle
 
@@ -23,7 +24,7 @@ module Needle
   # particular, a service point also knows how to instantiate a service.
   #
   # A ServicePoint should never be directly instantiated. Instead, define
-  # services via the Container#register and Container#register! interfaces.
+  # services via the interfaces provided by Container.
   class ServicePoint
 
     # The name of this service point, as it is known to the container that it
@@ -33,40 +34,39 @@ module Needle
     # A reference to the container that contains this service point.
     attr_reader :container
 
+    # The reference to the instantiation pipeline used by this service point.
+    attr_reader :pipeline
+
     # Create a new service point that references the given container and has
     # the given name. The associated callback will be used to instantiate the
     # service on demand.
     #
     # The <tt>:model</tt> option is used to tell Needle which style of
     # life-cycle management should be used for the service. It defaults to
-    # <tt>:singleton</tt>. The model should either be a class (which implements
-    # the necessary interface to be a service model), a symbol (in which case
-    # it refers to a service model that has been registered in the root
-    # <tt>:service_models</tt> service), or a string (in which case it is
-    # internalized and converted to a symbol). All other values are converted
-    # to strings and then internalized.
+    # <tt>:singleton</tt>. The model must be a symbol that refers to a service
+    # model that has been registered in the root <tt>:service_models</tt>
+    # service.
+    #
+    # The <tt>:pipeline</tt> option is mutually exclusive with <tt>:model</tt>.
+    # It must be an array of symbols (or strings) that define the instantiation
+    # pipeline to use for this service. Each element must correspond to an entry
+    # in the <tt>:pipeline_elements</tt> service.
     def initialize( container, name, opts={}, &callback )
       @name = name
       @container = container
       @callback = callback
-      @interceptors = nil
-
-      model = opts[:model] || :singleton
-
-      case model
-        when Class then
-          model_factory = model
-        when Symbol then
-          model_factory = @container.root.service_models[model]
-        when String then
-          model = model.intern
-          model_factory = @container.root.service_models[model]
-        else
-          model = model.to_s.intern
-          model_factory = @container.root.service_models[model]
+      @pipeline = Needle::Pipeline::Collection.new self
+      @chain = nil
+      @mutex = QueryableMutex.new
+
+      if opts[:pipeline]
+        elements = opts[:pipeline]
+      else
+        model = opts[:model] || :singleton
+        elements = @container[:service_models][model]
       end
 
-      @model = model_factory.new( @container, opts ) { instantiate }
+      elements.each { |element| @pipeline.add element, opts }
     end
 
     # Returns the fully-qualified name of the service point, with the point's
@@ -79,30 +79,27 @@ module Needle
     # Adds the given interceptor definition to this service point. The
     # parameter should act like an instance of Interceptor.
     def interceptor( interceptor )
-      @interceptors ||= []
-      @interceptors.push interceptor
+      element = @pipeline.get( :interceptor )
+      unless element
+        @chain = nil
+        @pipeline.add( :interceptor )
+        element = @pipeline.get( :interceptor )
+      end
+      element.interceptors << interceptor
     end
 
     # Return the service instance represented by this service point. Depending
     # on the style of lifecycle management chosen for this service point, this
     # may or may not be a new instance for every invocation of this method.
     def instance
-      @model.instance
-    end
-    
-    # Do the dirty-work of instantiating this service point. This invokes the
-    # callback that was registered for this service point, installs any
-    # requested interceptors, and returns the new instance.
-    def instantiate
-      instance = @callback.call( @container )
-
-      if @interceptors
-        instance = InterceptorChainBuilder.build( self, instance, @interceptors )
+      unless @chain
+        @mutex.synchronize do
+          @chain = @pipeline.chain_to( @callback ) unless @chain
+        end
       end
 
-      instance
+      @chain.call( @container, self )
     end
-    private :instantiate
 
   end