activesupport 3.2.22.5 → 4.0.0

data/lib/active_support/notifications.rb

@@ -1,19 +1,24 @@
+require 'active_support/notifications/instrumenter'
+require 'active_support/notifications/fanout'
+require 'active_support/per_thread_registry'
+
 module ActiveSupport
   # = Notifications
   #
-  # +ActiveSupport::Notifications+ provides an instrumentation API for Ruby.
+  # <tt>ActiveSupport::Notifications</tt> provides an instrumentation API for
+  # Ruby.
   #
   # == Instrumenters
   #
   # To instrument an event you just need to do:
   #
-  #   ActiveSupport::Notifications.instrument("render", :extra => :information) do
-  #     render :text => "Foo"
+  #   ActiveSupport::Notifications.instrument('render', extra: :information) do
+  #     render text: 'Foo'
   #   end
   #
   # That executes the block first and notifies all subscribers once done.
   #
-  # In the example above "render" is the name of the event, and the rest is called
+  # In the example above +render+ is the name of the event, and the rest is called
   # the _payload_. The payload is a mechanism that allows instrumenters to pass
   # extra information to subscribers. Payloads consist of a hash whose contents
   # are arbitrary and generally depend on the event.
@@ -21,46 +26,83 @@ module ActiveSupport
   # == Subscribers
   #
   # You can consume those events and the information they provide by registering
-  # a subscriber. For instance, let's store all "render" events in an array:
+  # a subscriber.
+  #
+  #   ActiveSupport::Notifications.subscribe('render') do |name, start, finish, id, payload|
+  #     name    # => String, name of the event (such as 'render' from above)
+  #     start   # => Time, when the instrumented block started execution
+  #     finish  # => Time, when the instrumented block ended execution
+  #     id      # => String, unique ID for this notification
+  #     payload # => Hash, the payload
+  #   end
+  #
+  # For instance, let's store all "render" events in an array:
   #
   #   events = []
   #
-  #   ActiveSupport::Notifications.subscribe("render") do |*args|
+  #   ActiveSupport::Notifications.subscribe('render') do |*args|
   #     events << ActiveSupport::Notifications::Event.new(*args)
   #   end
   #
   # That code returns right away, you are just subscribing to "render" events.
-  # The block will be called asynchronously whenever someone instruments "render":
+  # The block is saved and will be called whenever someone instruments "render":
   #
-  #   ActiveSupport::Notifications.instrument("render", :extra => :information) do
-  #     render :text => "Foo"
+  #   ActiveSupport::Notifications.instrument('render', extra: :information) do
+  #     render text: 'Foo'
   #   end
   #
   #   event = events.first
   #   event.name      # => "render"
   #   event.duration  # => 10 (in milliseconds)
-  #   event.payload   # => { :extra => :information }
+  #   event.payload   # => { extra: :information }
   #
-  # The block in the +subscribe+ call gets the name of the event, start
+  # The block in the <tt>subscribe</tt> call gets the name of the event, start
   # timestamp, end timestamp, a string with a unique identifier for that event
   # (something like "535801666f04d0298cd6"), and a hash with the payload, in
   # that order.
   #
   # If an exception happens during that particular instrumentation the payload will
-  # have a key +:exception+ with an array of two elements as value: a string with
+  # have a key <tt>:exception</tt> with an array of two elements as value: a string with
   # the name of the exception class, and the exception message.
   #
-  # As the previous example depicts, the class +ActiveSupport::Notifications::Event+
+  # As the previous example depicts, the class <tt>ActiveSupport::Notifications::Event</tt>
   # is able to take the arguments as they come and provide an object-oriented
   # interface to that data.
   #
+  # It is also possible to pass an object as the second parameter passed to the
+  # <tt>subscribe</tt> method instead of a block:
+  #
+  #   module ActionController
+  #     class PageRequest
+  #       def call(name, started, finished, unique_id, payload)
+  #         Rails.logger.debug ['notification:', name, started, finished, unique_id, payload].join(' ')
+  #       end
+  #     end
+  #   end
+  #
+  #   ActiveSupport::Notifications.subscribe('process_action.action_controller', ActionController::PageRequest.new)
+  #
+  # resulting in the following output within the logs including a hash with the payload:
+  #
+  #   notification: process_action.action_controller 2012-04-13 01:08:35 +0300 2012-04-13 01:08:35 +0300 af358ed7fab884532ec7 {
+  #      controller: "Devise::SessionsController",
+  #      action: "new",
+  #      params: {"action"=>"new", "controller"=>"devise/sessions"},
+  #      format: :html,
+  #      method: "GET",
+  #      path: "/login/sign_in",
+  #      status: 200,
+  #      view_runtime: 279.3080806732178,
+  #      db_runtime: 40.053
+  #    }
+  #
   # You can also subscribe to all events whose name matches a certain regexp:
   #
   #   ActiveSupport::Notifications.subscribe(/render/) do |*args|
   #     ...
   #   end
   #
-  # and even pass no argument to +subscribe+, in which case you are subscribing
+  # and even pass no argument to <tt>subscribe</tt>, in which case you are subscribing
   # to all events.
   #
   # == Temporary Subscriptions
@@ -105,12 +147,6 @@ module ActiveSupport
   # to log subscribers in a thread. You can use any queue implementation you want.
   #
   module Notifications
-    autoload :Instrumenter, 'active_support/notifications/instrumenter'
-    autoload :Event, 'active_support/notifications/instrumenter'
-    autoload :Fanout, 'active_support/notifications/fanout'
-
-    @instrumenters = Hash.new { |h,k| h[k] = notifier.listening?(k) }
-
     class << self
       attr_accessor :notifier
 
@@ -119,7 +155,7 @@ module ActiveSupport
       end
 
       def instrument(name, payload = {})
-        if @instrumenters[name]
+        if notifier.listening?(name)
           instrumenter.instrument(name, payload) { yield payload if block_given? }
         else
           yield payload if block_given?
@@ -127,9 +163,7 @@ module ActiveSupport
       end
 
       def subscribe(*args, &block)
-        notifier.subscribe(*args, &block).tap do
-          @instrumenters.clear
-        end
+        notifier.subscribe(*args, &block)
       end
 
       def subscribed(callback, *args, &block)
@@ -141,11 +175,30 @@ module ActiveSupport
 
       def unsubscribe(args)
         notifier.unsubscribe(args)
-        @instrumenters.clear
       end
 
       def instrumenter
-        Thread.current[:"instrumentation_#{notifier.object_id}"] ||= Instrumenter.new(notifier)
+        InstrumentationRegistry.instrumenter_for(notifier)
+      end
+    end
+
+    # This class is a registry which holds all of the +Instrumenter+ objects
+    # in a particular thread local. To access the +Instrumenter+ object for a
+    # particular +notifier+, you can call the following method:
+    #
+    #   InstrumentationRegistry.instrumenter_for(notifier)
+    #
+    # The instrumenters for multiple notifiers are held in a single instance of
+    # this class.
+    class InstrumentationRegistry # :nodoc:
+      extend ActiveSupport::PerThreadRegistry
+
+      def initialize
+        @registry = {}
+      end
+
+      def instrumenter_for(notifier)
+        @registry[notifier] ||= Instrumenter.new(notifier)
       end
     end