lib/active_support/notifications.rb in activesupport-3.1.12 vs lib/active_support/notifications.rb in activesupport-3.2.0.rc1

@@ -1,38 +1,104 @@
 module ActiveSupport
-  # Notifications provides an instrumentation API for Ruby. To instrument an
-  # action in Ruby you just need to do:
+  # = Notifications
   #
-  #   ActiveSupport::Notifications.instrument(:render, :extra => :information) do
+  # +ActiveSupport::Notifications+ 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"
   #   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
+  # 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.
+  #
+  # == Subscribers
+  #
   # You can consume those events and the information they provide by registering
-  # a log subscriber. For instance, let's store all instrumented events in an array:
+  # a subscriber. For instance, let's store all "render" events in an array:
   #
-  #   @events = []
+  #   events = []
   #
-  #   ActiveSupport::Notifications.subscribe do |*args|
-  #     @events << ActiveSupport::Notifications::Event.new(*args)
+  #   ActiveSupport::Notifications.subscribe("render") do |*args|
+  #     events << ActiveSupport::Notifications::Event.new(*args)
   #   end
   #
-  #   ActiveSupport::Notifications.instrument(:render, :extra => :information) do
+  # That code returns right away, you are just subscribing to "render" events.
+  # The block will be called asynchronously whenever someone instruments "render":
+  #
+  #   ActiveSupport::Notifications.instrument("render", :extra => :information) do
   #     render :text => "Foo"
   #   end
   #
-  #   event = @events.first
-  #   event.name      # => :render
+  #   event = events.first
+  #   event.name      # => "render"
   #   event.duration  # => 10 (in milliseconds)
   #   event.payload   # => { :extra => :information }
   #
-  # When subscribing to Notifications, you can pass a pattern, to only consume
-  # events that match the pattern:
+  # The block in the +subscribe+ 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.
   #
-  #   ActiveSupport::Notifications.subscribe(/render/) do |event|
-  #     @render_events << event
+  # 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
+  # the name of the exception class, and the exception message.
+  #
+  # As the previous example depicts, the class +ActiveSupport::Notifications::Event+
+  # is able to take the arguments as they come and provide an object-oriented
+  # interface to that data.
+  #
+  # 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
+  # to all events.
+  #
+  # == Temporary Subscriptions
+  #
+  # Sometimes you do not want to subscribe to an event for the entire life of
+  # the application. There are two ways to unsubscribe.
+  #
+  # === Subscribe While a Block Runs
+  #
+  # You can subscribe to some event temporarily while some block runs. For
+  # example, in
+  #
+  #   callback = lambda {|*args| ... }
+  #   ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
+  #     ...
+  #   end
+  #
+  # the callback will be called for all "sql.active_record" events instrumented
+  # during the execution of the block. The callback is unsubscribed automatically
+  # after that.
+  #
+  # === Manual Unsubscription
+  #
+  # The +subscribe+ method returns a subscriber object:
+  #
+  #   subscriber = ActiveSupport::Notifications.subscribe("render") do |*args|
+  #     ...
+  #   end
+  #
+  # To prevent that block from being called anymore, just unsubscribe passing
+  # that reference:
+  #
+  #   ActiveSupport::Notifications.unsubscribe(subscriber)
+  #
+  # == Default Queue
+  #
   # Notifications ships with a queue implementation that consumes and publish events
   # to log subscribers in a thread. You can use any queue implementation you want.
   #
   module Notifications
     autoload :Instrumenter, 'active_support/notifications/instrumenter'
@@ -58,9 +124,16 @@
 
       def subscribe(*args, &block)
         notifier.subscribe(*args, &block).tap do
           @instrumenters.clear
         end
+      end
+
+      def subscribed(callback, *args, &block)
+        subscriber = subscribe(*args, &callback)
+        yield
+      ensure
+        unsubscribe(subscriber)
       end
 
       def unsubscribe(args)
         notifier.unsubscribe(args)
         @instrumenters.clear