/usr/lib/ruby/vendor_ruby/active_support/notifications.rb is in ruby-activesupport-3.2 3.2.16-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | module ActiveSupport
# = Notifications
#
# +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 subscriber. For instance, let's store all "render" events in an array:
#
# events = []
#
# 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":
#
# 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 }
#
# 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.
#
# 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.
#
# WARNING: The instrumentation framework is designed for long-running subscribers,
# use this feature sparingly because it wipes some internal caches and that has
# a negative impact on performance.
#
# === 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'
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
def publish(name, *args)
notifier.publish(name, *args)
end
def instrument(name, payload = {})
if @instrumenters[name]
instrumenter.instrument(name, payload) { yield payload if block_given? }
else
yield payload if block_given?
end
end
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
end
def instrumenter
Thread.current[:"instrumentation_#{notifier.object_id}"] ||= Instrumenter.new(notifier)
end
end
self.notifier = Fanout.new
end
end
|