needle 1.1.0 → 1.2.0

data/benchmarks/instantiation.rb

@@ -31,3 +31,42 @@ end
 
 puts "* this benchmark forced the proxy to instantiate its wrapped service"
 puts
+
+class S2
+  def initialize
+    @h = Hash.new
+    @h[:one] = :two
+    @h[:two] = :three
+    @h[:three] = :four
+    10.times { @h[:one] }
+  end
+
+  def value
+    @h
+  end
+end
+
+registry = Needle::Registry.new
+registry.register( :immediate, :model=>:prototype ) { S2.new }
+registry.register( :deferred, :model=>:prototype_deferred ) { S2.new }
+
+puts
+puts "--------------------------------------------------------------------"
+puts "Direct vs. Immediate vs. Deferred instantiation (non-trivial)"
+puts "#{ITERATIONS} iterations"
+puts
+
+Benchmark.bm(10) do |x|
+  GC.disable
+  x.report( "direct:" ) { ITERATIONS.times { S2.new } }
+  GC.start
+  x.report( "immediate:" ) { ITERATIONS.times { registry.immediate } }
+  GC.start
+  x.report( "deferred:" ) { ITERATIONS.times { registry.deferred } }
+  GC.start
+  x.report( "deferred*:" ) { ITERATIONS.times { registry.deferred.value } }
+  GC.enable
+end
+
+puts "* this benchmark forced the proxy to instantiate its wrapped service"
+puts

data/doc/faq/faq.yml

@@ -19,6 +19,14 @@
   - "service?": >-
       A _service_ is the instantiation of a service point.
 
+  - "parameterized service?": >-
+      A _parameterized_ service is a service that allows contextual parameters
+      to be passed to the service when it is created. Such services are
+      typically used in conjunction with the @multiton@ service model, but
+      the only real requirement is that they _not_ be used with a service model
+      that does not support multiple parameters (like @singleton@ or
+      @threaded@).
+
   - "service model?": >-
       A _service model_ is a description of the lifecycle of a service. By
       default, all services are _singletons_, meaning that every time you ask
@@ -99,8 +107,8 @@
       thing, but evaluates the block within the context of the builder.
 
   - "register a service?": >-
-      The first way to register a service is by calling #register on the registry
-      (or a namespace):
+      The first way to register a service is by calling #register on the
+      registry (or a namespace):
 
 
       <pre>
@@ -108,11 +116,11 @@
       </pre>
 
 
-      The (first) parameter to #register is the name of the service, and the block
-      should return the implementation of the service. If needed, the block can
-      accept two parameters--the container that the service is being registered
-      with, and an object that represents the service being defined (called a "service
-      point"):
+      The (first) parameter to #register is the name of the service, and the
+      block should return the implementation of the service. If needed, the
+      block can accept two parameters--the container that the service is being
+      registered with, and an object that represents the service being defined
+      (called a "service point"):
 
 
       <pre>
@@ -122,9 +130,9 @@
       </pre>
 
 
-      You can also use Container#define and Container#define! to register services.
-      These approaches are friendlier if you are needing to register several services
-      at once.
+      You can also use Container#define and Container#define! to register
+      services.  These approaches are friendlier if you are needing to register
+      several services at once.
 
 
       <pre>
@@ -140,18 +148,18 @@
       </pre>
 
 
-      Container#define yields a new "builder" object to the block. Messages sent to the
-      builder are interpreted as service names, and if a block is sent with the message,
-      a new service is registered under that name.
+      Container#define yields a new "builder" object to the block. Messages
+      sent to the builder are interpreted as service names, and if a block is
+      sent with the message, a new service is registered under that name.
 
       
-      Container#define! does likewise, except it evaluates the block within the context
-      of the builder object.
+      Container#define! does likewise, except it evaluates the block within the
+      context of the builder object.
 
 
-      If you do not pass a block to #define, it will return the builder object, so you
-      could do something like the following if you only need to define one or two
-      services:
+      If you do not pass a block to #define, it will return the builder object,
+      so you could do something like the following if you only need to define
+      one or two services:
 
 
       <pre>
@@ -169,13 +177,13 @@
       </pre>
 
 
-      (This last is the same as calling #define without arguments, but is more readable
-      if you intend to use the builder object multiple times.)
+      (This last is the same as calling #define without arguments, but is more
+      readable if you intend to use the builder object multiple times.)
       
   - "reference a service?": >-
-      Referencing a service can be done in either of two ways. The first is to treat the
-      container (i.e., registry) as a hash, passing the name of the service as an argument
-      to Container#[]:
+      Referencing a service can be done in either of two ways. The first is to
+      treat the container (i.e., registry) as a hash, passing the name of the
+      service as an argument to Container#[]:
 
 
       <pre>
@@ -184,8 +192,8 @@
       </pre>
 
 
-      A more convenient (but slightly more peril-fraught) approach is to send the name of
-      the method to the registry as a message:
+      A more convenient (but slightly more peril-fraught) approach is to send
+      the name of the method to the registry as a message:
 
 
       <pre>
@@ -193,9 +201,9 @@
       </pre>
 
 
-      Be aware that this latter approach will only work when the service name does not
-      conflict with the name of an existing method on the container. For example, if
-      you were to do:
+      Be aware that this latter approach will only work when the service name
+      does not conflict with the name of an existing method on the container.
+      For example, if you were to do:
 
 
       <pre>
@@ -204,15 +212,17 @@
       </pre>
 
 
-      You would get the hash value of the registry object, instead of the value value
-      of the service (which would be "hello, world").
+      You would get the hash value of the registry object, instead of the value
+      value of the service (which would be "hello, world").
 
   - "select a service model for a service (i.e., change the default model of lifecycle management)?": >-
-      By default, a service will be managed as a singleton, i.e., every request of that service
-      will return the same object instance. This is the _singleton_ service model.
+      By default, a service will be managed as a singleton, i.e., every request
+      of that service will return the same object instance. This is the
+      _singleton_ service model.
 
 
-      To select a different service model, pass it as an option when you register the service:
+      To select a different service model, pass it as an option when you
+      register the service:
 
 
       <pre>
@@ -226,8 +236,9 @@
       </pre>
 
   - "create a namespace?": >-
-      Namespaces allow you to organize your services into hierarchical packages. You can create
-      namespaces in a few ways. The first (and simplest) is to just call Container#namespace:
+      Namespaces allow you to organize your services into hierarchical
+      packages. You can create namespaces in a few ways. The first (and
+      simplest) is to just call Container#namespace:
 
 
       <pre>
@@ -235,9 +246,9 @@
       </pre>
 
 
-      This will create a namespace in the registry, called stuff. If you send a block as well,
-      the block will be invoked (with the new namespace yielded to it) the first time the
-      namespace is requested:
+      This will create a namespace in the registry, called stuff. If you send a
+      block as well, the block will be invoked (with the new namespace yielded
+      to it) the first time the namespace is requested:
 
 
       <pre>
@@ -251,8 +262,9 @@
         end
       </pre>
 
-      Because it is so common to immediately define services on the new namespace, there
-      are some convenience methods to make this more...convenient.
+      Because it is so common to immediately define services on the new
+      namespace, there are some convenience methods to make this more...
+      convenient.
 
 
       <pre>
@@ -270,19 +282,21 @@
       </pre>
 
 
-      The first one, above, creates the namespace and calls Container#define!. The second
-      creates the namespace and calls Container#define. In both cases, _the namespace is
-      created immediately_, unlike Container#namespace which only creates the namespace
-      when it is first requested.
+      The first one, above, creates the namespace and calls Container#define!.
+      The second creates the namespace and calls Container#define. In both
+      cases, _the namespace is created immediately_, unlike Container#namespace
+      which only creates the namespace when it is first requested.
 
 
-      Lastly, note that namespace's are just special services. Thus, you can pass options
-      to the namespace methods just as you can with Container#register and friends.
+      Lastly, note that namespace's are just special services. Thus, you can
+      pass options to the namespace methods just as you can with
+      Container#register and friends.
 
   - "write log messages?": >-
-      You can obtain a new logger instance from the @:logs@ service. Once you have a
-      logger instance, you can invoke the #debug, #info, #warn, #error, and #fatal methods
-      on the instance to log messages of the corresponding severity.
+      You can obtain a new logger instance from the @:logs@ and @:log_for@
+      services. Once you have a logger instance, you can invoke the #debug,
+      #info, #warn, #error, and #fatal methods on the instance to log messages
+      of the corresponding severity.
 
 
       <pre>
@@ -290,16 +304,22 @@
         logger.debug "This is a debug message"
         logger.info "This is an informational message"
         ...
+        logger2 = registry.log_for( "another logger name" )
+        ...
       </pre>
 
 
-      Log messages are written, by default, to a file called "needle.log", in the same
-      directory that the application was invoked from.
+      The two approaches shown above are identical--the second approach (using
+      the @log_for@ service) is just a convenience for @logs.get@.
+
+
+      Log messages are written, by default, to a file called "needle.log", in
+      the same directory that the application was invoked from.
 
 
-      You can also use a logging interceptor to automatically log all external method
-      invocations on a service. This includes method entry and exit, as well as any
-      exceptions that are raised inside the method.
+      You can also use a logging interceptor to automatically log all external
+      method invocations on a service. This includes method entry and exit, as
+      well as any exceptions that are raised inside the method.
 
 
       <pre>
@@ -311,17 +331,19 @@
       </pre>
 
 
-      See the chapter in the "User's Manual":http://needle.rubyforge.org about logging
-      for more information on how to use and configure loggers.
+      See the chapter in the "User's Manual":http://needle.rubyforge.org about
+      logging for more information on how to use and configure loggers.
 
   - "exclude methods from being intercepted?": >-
-      Only interceptors that explicitly support exclusion of methods can help you here.
-      Fortunately, the LoggingInterceptor is one of them. (If you write your own interceptor
-      and would like similar functionality, see the IncludeExclude module.)
+      Only interceptors that explicitly support exclusion of methods can help
+      you here.  Fortunately, the LoggingInterceptor is one of them. (If you
+      write your own interceptor and would like similar functionality, see the
+      IncludeExclude module.)
 
 
-      In the case of the LoggingInterceptor, just pass an array of patterns (matching
-      method names and/or arities) as the "exclude" option, when declaring the interceptor:
+      In the case of the LoggingInterceptor, just pass an array of patterns
+      (matching method names and/or arities) as the "exclude" option, when
+      declaring the interceptor:
 
 
       <pre>
@@ -332,13 +354,13 @@
       </pre>
 
 
-      The above will exclude from interception any method named 'foo', or any invocation
-      of 'bar' with more than 4 arguments, or any method invocation with fewer than two
-      arguments.
+      The above will exclude from interception any method named 'foo', or any
+      invocation of 'bar' with more than 4 arguments, or any method invocation
+      with fewer than two arguments.
 
 
-      You can also give an array of patterns to _include_. These cause methods to be
-      explicitly intercepted even if they match an exclude pattern:
+      You can also give an array of patterns to _include_. These cause methods
+      to be explicitly intercepted even if they match an exclude pattern:
 
 
       <pre>
@@ -353,14 +375,14 @@
       </pre>
 
 
-      This would result in the call to #baz being intercepted, even though it matches
-      an exclude pattern (@*(<2)@).
+      This would result in the call to #baz being intercepted, even though it
+      matches an exclude pattern (@*(<2)@).
 
   - "include services defined in another library?": >-
-      This requires that the other library be implemented in such a way that it expects
-      to be "included" by other libraries/applications. For example, Needle encourages
-      the use of a method called @register_services@, which accepts a container as a
-      parameter:
+      This requires that the other library be implemented in such a way that it
+      expects to be "included" by other libraries/applications. For example,
+      Needle encourages the use of a method called @register_services@, which
+      accepts a container as a parameter:
 
 
       <pre>
@@ -375,14 +397,15 @@
       </pre>
 
 
-      If the library has been implemented in this way, you can simply do a require of
-      the library and then invoke the @register_services@ method.
+      If the library has been implemented in this way, you can simply do a
+      require of the library and then invoke the @register_services@ method.
 
 
-      There is a convenience method in Container for doing this. Just call Container#require,
-      passing the file to require and a string (or symbol) identifying the name of the
-      module that contains the registration method. You can also pass a symbol as the third
-      parameter naming the registration method, but it defaults to @:register_services@.
+      There is a convenience method in Container for doing this. Just call
+      Container#require, passing the file to require and a string (or symbol)
+      identifying the name of the module that contains the registration method.
+      You can also pass a symbol as the third parameter naming the registration
+      method, but it defaults to @:register_services@.
 
 
       <pre>
@@ -395,8 +418,8 @@
       </pre>
 
 
-      The definition context (i.e., the "builder" object) also supports the require method,
-      so you can do:
+      The definition context (i.e., the "builder" object) also supports the
+      require method, so you can do:
 
 
       <pre>
@@ -418,13 +441,14 @@
         * will be used multiple times for different situations
 
 
-        For example, if you have a GUI library, a "button" service could be a prototype,
-        because you will likely have many buttons in an application, with each button
-        being an independent instance.
+        For example, if you have a GUI library, a "button" service could be a
+        prototype, because you will likely have many buttons in an application,
+        with each button being an independent instance.
       
     - "Like, :singleton?": >-
-        The singleton service model is the default, so you should rarely need to explicitly
-        specify it as a model. It is appropriate for services that:
+        The singleton service model is the default, so you should rarely need
+        to explicitly specify it as a model. It is appropriate for services
+        that:
 
 
         * guard some specific functionality
@@ -432,26 +456,37 @@
         * represent state that is global across an application
 
     - "Like, :threaded?": >-
-        Threaded is similar to singleton, but it allows one unique instance of the service
-        _per thread_. Thus, it is appropriate to the same situations as singleton, but
-        specific to a thread, instead of an application. This is useful for web applications
-        that are run in a single virtual machine, and which share a single registry.
+        Threaded is similar to singleton, but it allows one unique instance of
+        the service _per thread_. Thus, it is appropriate to the same
+        situations as singleton, but specific to a thread, instead of an
+        application. This is useful for web applications that are run in a
+        single virtual machine, and which share a single registry.
 
     - "Like, deferred?": >-
-        Deferred models use a proxy to enforce lazy initialization of the service. A service
-        using a deferred service model (ie, @:prototype_deferred@, @:singleton_deferred@, or
-        @:threaded_deferred@) will not be instantiated until the first time a method is invoked
-        on the service.
+        Deferred models use a proxy to enforce lazy initialization of the
+        service. A service using a deferred service model (ie,
+        @:prototype_deferred@, @:multiton_deferred@, @:singleton_deferred@, or
+        @:threaded_deferred@) will not be instantiated until the first time a
+        method is invoked on the service.
 
 
-        This makes a deferred model appropriate when a service is expensive to instantiate, since
-        you can wait to do the expensive initialization until it is really needed. Applications
-        will start up faster when their dependences use deferred instantiation.
+        This makes a deferred model appropriate when a service is expensive to
+        instantiate, since you can wait to do the expensive initialization
+        until it is really needed. Applications will start up faster when their
+        dependences use deferred instantiation.
 
     - "Like, initialize?": >-
-        This is useful when you have a method that you want to be invoked automatically after
-        a service has been instantiated. Consider the case where a service is initialized
-        primarily using setters, but requires some logic to be executed to complete the
-        initialization phase. In this case, you could always explicitly invoke the initialization
-        method(s) in the constructor block, but if many services use the same initialization
-        method, it can be more convenient to use an "initialize" service model.
+        This is useful when you have a method that you want to be invoked
+        automatically after a service has been instantiated. Consider the case
+        where a service is initialized primarily using setters, but requires
+        some logic to be executed to complete the initialization phase. In this
+        case, you could always explicitly invoke the initialization method(s)
+        in the constructor block, but if many services use the same
+        initialization method, it can be more convenient to use an "initialize"
+        service model.
+
+    - "Like, multiton?": >-
+        Multitons are useful for factories, where you have a class that
+        differentiates its instances based on some construction parameters that
+        need to be determined at runtime. Thus, multitons are always used with
+        parameterized services.