activesupport 3.1.0 → 5.0.0

data/lib/active_support/notifications/instrumenter.rb

@@ -1,40 +1,57 @@
-require 'active_support/secure_random'
-require 'active_support/core_ext/module/delegation'
+require 'securerandom'
 
 module ActiveSupport
   module Notifications
+    # Instrumenters are stored in a thread local.
     class Instrumenter
       attr_reader :id
 
       def initialize(notifier)
-        @id = unique_id
+        @id       = unique_id
         @notifier = notifier
       end
 
       # Instrument the given block by measuring the time taken to execute it
       # and publish it. Notice that events get sent even if an error occurs
-      # in the passed-in block
+      # in the passed-in block.
       def instrument(name, payload={})
-        started = Time.now
-
+        # some of the listeners might have state
+        listeners_state = start name, payload
         begin
-          yield
+          yield payload
         rescue Exception => e
           payload[:exception] = [e.class.name, e.message]
+          payload[:exception_object] = e
           raise e
         ensure
-          @notifier.publish(name, started, Time.now, @id, payload)
+          finish_with_state listeners_state, name, payload
         end
       end
 
+      # Send a start notification with +name+ and +payload+.
+      def start(name, payload)
+        @notifier.start name, @id, payload
+      end
+
+      # Send a finish notification with +name+ and +payload+.
+      def finish(name, payload)
+        @notifier.finish name, @id, payload
+      end
+
+      def finish_with_state(listeners_state, name, payload)
+        @notifier.finish name, @id, payload, listeners_state
+      end
+
       private
-        def unique_id
-          ::SecureRandom.hex(10)
-        end
+
+      def unique_id
+        SecureRandom.hex(10)
+      end
     end
 
     class Event
-      attr_reader :name, :time, :end, :transaction_id, :payload, :duration
+      attr_reader :name, :time, :transaction_id, :payload, :children
+      attr_accessor :end
 
       def initialize(name, start, ending, transaction_id, payload)
         @name           = name
@@ -42,12 +59,32 @@ module ActiveSupport
         @time           = start
         @transaction_id = transaction_id
         @end            = ending
-        @duration       = 1000.0 * (@end - @time)
+        @children       = []
+        @duration       = nil
+      end
+
+      # Returns the difference in milliseconds between when the execution of the
+      # event started and when it ended.
+      #
+      #   ActiveSupport::Notifications.subscribe('wait') do |*args|
+      #     @event = ActiveSupport::Notifications::Event.new(*args)
+      #   end
+      #
+      #   ActiveSupport::Notifications.instrument('wait') do
+      #     sleep 1
+      #   end
+      #
+      #   @event.duration # => 1000.138
+      def duration
+        @duration ||= 1000.0 * (self.end - time)
+      end
+
+      def <<(event)
+        @children << event
       end
 
       def parent_of?(event)
-        start = (time - event.time) * 1000
-        start <= 0 && (start + duration >= event.duration)
+        @children.include? event
       end
     end
   end

data/lib/active_support/notifications.rb

@@ -1,46 +1,157 @@
+require 'active_support/notifications/instrumenter'
+require 'active_support/notifications/fanout'
+require 'active_support/per_thread_registry'
+
 module ActiveSupport
-  # Notifications provides an instrumentation API for Ruby. To instrument an
-  # action in Ruby you just need to do:
+  # = Notifications
+  #
+  # <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 first executes the block and then 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.
   #
-  #   @events = []
+  #   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 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
-  #     render :text => "Foo"
+  # That code returns right away, you are just subscribing to "render" events.
+  # The block is saved and will be called 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 }
+  #   event.payload   # => { extra: :information }
+  #
+  # 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 <tt>:exception</tt> with an array of two elements as value: a string with
+  # the name of the exception class, and the exception message.
   #
-  # When subscribing to Notifications, you can pass a pattern, to only consume
-  # events that match the pattern:
+  # 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.
   #
-  #   ActiveSupport::Notifications.subscribe(/render/) do |event|
-  #     @render_events << event
+  # It is also possible to pass an object which responds to <tt>call</tt> method
+  # as the second parameter 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
   #
-  # 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.
+  # and even pass no argument to <tt>subscribe</tt>, 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)
+  #
+  # You can also unsubscribe by passing the name of the subscriber object. Note
+  # that this will unsubscribe all subscriptions with the given name:
+  #
+  #   ActiveSupport::Notifications.unsubscribe("render")
+  #
+  # == Default Queue
+  #
+  # Notifications ships with a queue implementation that consumes and publishes events
+  # to all log subscribers. 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
 
@@ -49,7 +160,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?
@@ -57,18 +168,42 @@ 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)
+        subscriber = subscribe(*args, &callback)
+        yield
+      ensure
+        unsubscribe(subscriber)
       end
 
-      def unsubscribe(args)
-        notifier.unsubscribe(args)
-        @instrumenters.clear
+      def unsubscribe(subscriber_or_name)
+        notifier.unsubscribe(subscriber_or_name)
       end
 
       def instrumenter
-        Thread.current[:"instrumentation_#{notifier.object_id}"] ||= Instrumenter.new(notifier)
+        InstrumentationRegistry.instance.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
 

data/lib/active_support/number_helper/number_converter.rb

@@ -0,0 +1,182 @@
+require 'active_support/core_ext/big_decimal/conversions'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/hash/keys'
+require 'active_support/i18n'
+require 'active_support/core_ext/class/attribute'
+
+module ActiveSupport
+  module NumberHelper
+    class NumberConverter # :nodoc:
+      # Default and i18n option namespace per class
+      class_attribute :namespace
+
+      # Does the object need a number that is a valid float?
+      class_attribute :validate_float
+
+      attr_reader :number, :opts
+
+      DEFAULTS = {
+        # Used in number_to_delimited
+        # These are also the defaults for 'currency', 'percentage', 'precision', and 'human'
+        format: {
+          # Sets the separator between the units, for more precision (e.g. 1.0 / 2.0 == 0.5)
+          separator: ".",
+          # Delimits thousands (e.g. 1,000,000 is a million) (always in groups of three)
+          delimiter: ",",
+          # Number of decimals, behind the separator (the number 1 with a precision of 2 gives: 1.00)
+          precision: 3,
+          # If set to true, precision will mean the number of significant digits instead
+          # of the number of decimal digits (1234 with precision 2 becomes 1200, 1.23543 becomes 1.2)
+          significant: false,
+          # If set, the zeros after the decimal separator will always be stripped (eg.: 1.200 will be 1.2)
+          strip_insignificant_zeros: false
+        },
+
+        # Used in number_to_currency
+        currency: {
+          format: {
+            format: "%u%n",
+            negative_format: "-%u%n",
+            unit: "$",
+            # These five are to override number.format and are optional
+            separator: ".",
+            delimiter: ",",
+            precision: 2,
+            significant: false,
+            strip_insignificant_zeros: false
+          }
+        },
+
+        # Used in number_to_percentage
+        percentage: {
+          format: {
+            delimiter: "",
+            format: "%n%"
+          }
+        },
+
+        # Used in number_to_rounded
+        precision: {
+          format: {
+            delimiter: ""
+          }
+        },
+
+        # Used in number_to_human_size and number_to_human
+        human: {
+          format: {
+            # These five are to override number.format and are optional
+            delimiter: "",
+            precision: 3,
+            significant: true,
+            strip_insignificant_zeros: true
+          },
+          # Used in number_to_human_size
+          storage_units: {
+            # Storage units output formatting.
+            # %u is the storage unit, %n is the number (default: 2 MB)
+            format: "%n %u",
+            units: {
+              byte: "Bytes",
+              kb: "KB",
+              mb: "MB",
+              gb: "GB",
+              tb: "TB"
+            }
+          },
+          # Used in number_to_human
+          decimal_units: {
+            format: "%n %u",
+            # Decimal units output formatting
+            # By default we will only quantify some of the exponents
+            # but the commented ones might be defined or overridden
+            # by the user.
+            units: {
+              # femto: Quadrillionth
+              # pico: Trillionth
+              # nano: Billionth
+              # micro: Millionth
+              # mili: Thousandth
+              # centi: Hundredth
+              # deci: Tenth
+              unit: "",
+              # ten:
+              #   one: Ten
+              #   other: Tens
+              # hundred: Hundred
+              thousand: "Thousand",
+              million: "Million",
+              billion: "Billion",
+              trillion: "Trillion",
+              quadrillion: "Quadrillion"
+            }
+          }
+        }
+      }
+
+      def self.convert(number, options)
+        new(number, options).execute
+      end
+
+      def initialize(number, options)
+        @number = number
+        @opts   = options.symbolize_keys
+      end
+
+      def execute
+        if !number
+          nil
+        elsif validate_float? && !valid_float?
+          number
+        else
+          convert
+        end
+      end
+
+      private
+
+        def options
+          @options ||= format_options.merge(opts)
+        end
+
+        def format_options #:nodoc:
+          default_format_options.merge!(i18n_format_options)
+        end
+
+        def default_format_options #:nodoc:
+          options = DEFAULTS[:format].dup
+          options.merge!(DEFAULTS[namespace][:format]) if namespace
+          options
+        end
+
+        def i18n_format_options #:nodoc:
+          locale = opts[:locale]
+          options = I18n.translate(:'number.format', locale: locale, default: {}).dup
+
+          if namespace
+            options.merge!(I18n.translate(:"number.#{namespace}.format", locale: locale, default: {}))
+          end
+
+          options
+        end
+
+        def translate_number_value_with_default(key, i18n_options = {}) #:nodoc:
+          I18n.translate(key, { default: default_value(key), scope: :number }.merge!(i18n_options))
+        end
+
+        def translate_in_locale(key, i18n_options = {})
+          translate_number_value_with_default(key, { locale: options[:locale] }.merge(i18n_options))
+        end
+
+        def default_value(key)
+          key.split('.').reduce(DEFAULTS) { |defaults, k| defaults[k.to_sym] }
+        end
+
+        def valid_float? #:nodoc:
+          Float(number)
+        rescue ArgumentError, TypeError
+          false
+        end
+    end
+  end
+end

data/lib/active_support/number_helper/number_to_currency_converter.rb

@@ -0,0 +1,44 @@
+require 'active_support/core_ext/numeric/inquiry'
+
+module ActiveSupport
+  module NumberHelper
+    class NumberToCurrencyConverter < NumberConverter # :nodoc:
+      self.namespace = :currency
+
+      def convert
+        number = self.number.to_s.strip
+        format = options[:format]
+
+        if number.to_f.negative?
+          format = options[:negative_format]
+          number = absolute_value(number)
+        end
+
+        rounded_number = NumberToRoundedConverter.convert(number, options)
+        format.gsub('%n'.freeze, rounded_number).gsub('%u'.freeze, options[:unit])
+      end
+
+      private
+
+        def absolute_value(number)
+          number.respond_to?(:abs) ? number.abs : number.sub(/\A-/, '')
+        end
+
+        def options
+          @options ||= begin
+            defaults = default_format_options.merge(i18n_opts)
+            # Override negative format if format options are given
+            defaults[:negative_format] = "-#{opts[:format]}" if opts[:format]
+            defaults.merge!(opts)
+          end
+        end
+
+        def i18n_opts
+          # Set International negative format if it does not exist
+          i18n = i18n_format_options
+          i18n[:negative_format] ||= "-#{i18n[:format]}" if i18n[:format]
+          i18n
+        end
+    end
+  end
+end

data/lib/active_support/number_helper/number_to_delimited_converter.rb

@@ -0,0 +1,28 @@
+module ActiveSupport
+  module NumberHelper
+    class NumberToDelimitedConverter < NumberConverter #:nodoc:
+      self.validate_float = true
+
+      DEFAULT_DELIMITER_REGEX = /(\d)(?=(\d\d\d)+(?!\d))/
+
+      def convert
+        parts.join(options[:separator])
+      end
+
+      private
+
+        def parts
+          left, right = number.to_s.split('.'.freeze)
+          left.gsub!(delimiter_pattern) do |digit_to_delimit|
+            "#{digit_to_delimit}#{options[:delimiter]}"
+          end
+          [left, right].compact
+        end
+
+        def delimiter_pattern
+          options.fetch(:delimiter_pattern, DEFAULT_DELIMITER_REGEX)
+        end
+
+    end
+  end
+end

data/lib/active_support/number_helper/number_to_human_converter.rb

@@ -0,0 +1,68 @@
+module ActiveSupport
+  module NumberHelper
+    class NumberToHumanConverter < NumberConverter # :nodoc:
+      DECIMAL_UNITS = { 0 => :unit, 1 => :ten, 2 => :hundred, 3 => :thousand, 6 => :million, 9 => :billion, 12 => :trillion, 15 => :quadrillion,
+        -1 => :deci, -2 => :centi, -3 => :mili, -6 => :micro, -9 => :nano, -12 => :pico, -15 => :femto }
+      INVERTED_DECIMAL_UNITS = DECIMAL_UNITS.invert
+
+      self.namespace      = :human
+      self.validate_float = true
+
+      def convert # :nodoc:
+        @number = Float(number)
+
+        # for backwards compatibility with those that didn't add strip_insignificant_zeros to their locale files
+        unless options.key?(:strip_insignificant_zeros)
+          options[:strip_insignificant_zeros] = true
+        end
+
+        units = opts[:units]
+        exponent = calculate_exponent(units)
+        @number = number / (10 ** exponent)
+
+        until (rounded_number = NumberToRoundedConverter.convert(number, options)) != NumberToRoundedConverter.convert(1000, options)
+          @number = number / 1000.0
+          exponent += 3
+        end
+        unit = determine_unit(units, exponent)
+        format.gsub('%n'.freeze, rounded_number).gsub('%u'.freeze, unit).strip
+      end
+
+      private
+
+        def format
+          options[:format] || translate_in_locale('human.decimal_units.format')
+        end
+
+        def determine_unit(units, exponent)
+          exp = DECIMAL_UNITS[exponent]
+          case units
+          when Hash
+            units[exp] || ''
+          when String, Symbol
+            I18n.translate("#{units}.#{exp}", :locale => options[:locale], :count => number.to_i)
+          else
+            translate_in_locale("human.decimal_units.units.#{exp}", count: number.to_i)
+          end
+        end
+
+        def calculate_exponent(units)
+          exponent = number != 0 ? Math.log10(number.abs).floor : 0
+          unit_exponents(units).find { |e| exponent >= e } || 0
+        end
+
+        def unit_exponents(units)
+          case units
+          when Hash
+            units
+          when String, Symbol
+            I18n.translate(units.to_s, :locale => options[:locale], :raise => true)
+          when nil
+            translate_in_locale("human.decimal_units.units", raise: true)
+          else
+            raise ArgumentError, ":units must be a Hash or String translation scope."
+          end.keys.map { |e_name| INVERTED_DECIMAL_UNITS[e_name] }.sort_by(&:-@)
+        end
+    end
+  end
+end