activesupport 1.2.4 → 8.1.2

data/lib/active_support/notifications/instrumenter.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+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)
+        unless notifier.respond_to?(:build_handle)
+          notifier = LegacyHandle::Wrapper.new(notifier)
+        end
+
+        @id       = unique_id
+        @notifier = notifier
+      end
+
+      class LegacyHandle # :nodoc:
+        class Wrapper # :nodoc:
+          def initialize(notifier)
+            @notifier = notifier
+          end
+
+          def build_handle(name, id, payload)
+            LegacyHandle.new(@notifier, name, id, payload)
+          end
+
+          delegate :start, :finish, to: :@notifier
+        end
+
+        def initialize(notifier, name, id, payload)
+          @notifier = notifier
+          @name = name
+          @id = id
+          @payload = payload
+        end
+
+        def start
+          @listener_state = @notifier.start @name, @id, @payload
+        end
+
+        def finish
+          @notifier.finish(@name, @id, @payload, @listener_state)
+        end
+      end
+
+      # Given a block, instrument it by measuring the time taken to execute
+      # and publish it. Without a block, simply send a message via the
+      # notifier. Notice that events get sent even if an error occurs in the
+      # passed-in block.
+      def instrument(name, payload = {})
+        handle = build_handle(name, payload)
+        handle.start
+        begin
+          yield payload if block_given?
+        rescue Exception => e
+          payload[:exception] = [e.class.name, e.message]
+          payload[:exception_object] = e
+          raise e
+        ensure
+          handle.finish
+        end
+      end
+
+      # Returns a "handle" for an event with the given +name+ and +payload+.
+      #
+      # #start and #finish must each be called exactly once on the returned object.
+      #
+      # Where possible, it's best to use #instrument, which will record the
+      # start and finish of the event and correctly handle any exceptions.
+      # +build_handle+ is a low-level API intended for cases where using
+      # +instrument+ isn't possible.
+      #
+      # See ActiveSupport::Notifications::Fanout::Handle.
+      def build_handle(name, payload)
+        @notifier.build_handle(name, @id, payload)
+      end
+
+      def new_event(name, payload = {}) # :nodoc:
+        Event.new(name, nil, nil, @id, payload)
+      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
+    end
+
+    class Event
+      attr_reader :name, :transaction_id
+      attr_accessor :payload
+
+      def initialize(name, start, ending, transaction_id, payload)
+        @name           = name
+        @payload        = payload.dup
+        @time           = start ? start.to_f * 1_000.0 : start
+        @transaction_id = transaction_id
+        @end            = ending ? ending.to_f * 1_000.0 : ending
+        @cpu_time_start = 0.0
+        @cpu_time_finish = 0.0
+        @allocation_count_start = 0
+        @allocation_count_finish = 0
+        @gc_time_start = 0
+        @gc_time_finish = 0
+      end
+
+      def time
+        @time / 1000.0 if @time
+      end
+
+      def end
+        @end / 1000.0 if @end
+      end
+
+      def record # :nodoc:
+        start!
+        begin
+          yield payload if block_given?
+        rescue Exception => e
+          payload[:exception] = [e.class.name, e.message]
+          payload[:exception_object] = e
+          raise e
+        ensure
+          finish!
+        end
+      end
+
+      # Record information at the time this event starts
+      def start!
+        @time = now
+        @cpu_time_start = now_cpu
+        @gc_time_start = now_gc
+        @allocation_count_start = now_allocations
+      end
+
+      # Record information at the time this event finishes
+      def finish!
+        @cpu_time_finish = now_cpu
+        @gc_time_finish = now_gc
+        @end = now
+        @allocation_count_finish = now_allocations
+      end
+
+      # Returns the CPU time (in milliseconds) passed between the call to
+      # #start! and the call to #finish!.
+      def cpu_time
+        @cpu_time_finish - @cpu_time_start
+      end
+
+      # Returns the idle time (in milliseconds) passed between the call to
+      # #start! and the call to #finish!.
+      def idle_time
+        diff = duration - cpu_time
+        diff > 0.0 ? diff : 0.0
+      end
+
+      # Returns the number of allocations made between the call to #start! and
+      # the call to #finish!.
+      def allocations
+        @allocation_count_finish - @allocation_count_start
+      end
+
+      # Returns the time spent in GC (in milliseconds) between the call to #start!
+      # and the call to #finish!
+      def gc_time
+        (@gc_time_finish - @gc_time_start) / 1_000_000.0
+      end
+
+      # Returns the difference in milliseconds between when the execution of the
+      # event started and when it ended.
+      #
+      #   ActiveSupport::Notifications.subscribe('wait') do |event|
+      #     @event = event
+      #   end
+      #
+      #   ActiveSupport::Notifications.instrument('wait') do
+      #     sleep 1
+      #   end
+      #
+      #   @event.duration # => 1000.138
+      def duration
+        @end - @time
+      end
+
+      private
+        def now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+        end
+
+        begin
+          Process.clock_gettime(Process::CLOCK_THREAD_CPUTIME_ID, :float_millisecond)
+
+          def now_cpu
+            Process.clock_gettime(Process::CLOCK_THREAD_CPUTIME_ID, :float_millisecond)
+          end
+        rescue
+          def now_cpu
+            0.0
+          end
+        end
+
+        if GC.respond_to?(:total_time)
+          def now_gc
+            GC.total_time
+          end
+        else
+          def now_gc
+            0
+          end
+        end
+
+        if GC.stat.key?(:total_allocated_objects)
+          def now_allocations
+            GC.stat(:total_allocated_objects)
+          end
+        else # Likely on JRuby, TruffleRuby
+          def now_allocations
+            0
+          end
+        end
+    end
+  end
+end

data/lib/active_support/notifications.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require "active_support/notifications/instrumenter"
+require "active_support/notifications/fanout"
+
+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 plain: '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 subscriber.
+  #
+  #   ActiveSupport::Notifications.subscribe('render') do |event|
+  #     event.name          # => "render"
+  #     event.duration      # => 10 (in milliseconds)
+  #     event.payload       # => { extra: :information }
+  #     event.allocations   # => 1826 (objects)
+  #   end
+  #
+  # +Event+ objects record CPU time and allocations. If you don't need this
+  # it's also possible to pass a block that accepts five arguments:
+  #
+  #   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 the instrumenter that fired the event
+  #     payload # => Hash, the payload
+  #   end
+  #
+  # Here, the +start+ and +finish+ values represent wall-clock time. If you are
+  # concerned about accuracy, you can register a monotonic subscriber.
+  #
+  #   ActiveSupport::Notifications.monotonic_subscribe('render') do |name, start, finish, id, payload|
+  #     name    # => String, name of the event (such as 'render' from above)
+  #     start   # => Float, monotonic time when the instrumented block started execution
+  #     finish  # => Float, monotonic time when the instrumented block ended execution
+  #     id      # => String, unique ID for the instrumenter that fired the event
+  #     payload # => Hash, the payload
+  #   end
+  #
+  # For instance, let's store all "render" events in an array:
+  #
+  #   events = []
+  #
+  #   ActiveSupport::Notifications.subscribe('render') do |event|
+  #     events << event
+  #   end
+  #
+  # 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 plain: 'Foo'
+  #   end
+  #
+  #   event = events.first
+  #   event.name          # => "render"
+  #   event.duration      # => 10 (in milliseconds)
+  #   event.payload       # => { extra: :information }
+  #   event.allocations   # => 1826 (objects)
+  #
+  # 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.
+  # The <tt>:exception_object</tt> key of the payload will have the exception
+  # itself as the value:
+  #
+  #   event.payload[:exception]         # => ["ArgumentError", "Invalid value"]
+  #   event.payload[:exception_object]  # => #<ArgumentError: Invalid value>
+  #
+  # As the earlier 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.
+  #
+  # 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
+  #
+  # 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 {|event| ... }
+  #   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.
+  #
+  # To record +started+ and +finished+ values with monotonic time,
+  # specify the optional <tt>:monotonic</tt> option to the
+  # <tt>subscribed</tt> method. The <tt>:monotonic</tt> option is set
+  # to +false+ by default.
+  #
+  #   callback = lambda {|name, started, finished, unique_id, payload| ... }
+  #   ActiveSupport::Notifications.subscribed(callback, "sql.active_record", monotonic: true) do
+  #     ...
+  #   end
+  #
+  # === Manual Unsubscription
+  #
+  # The +subscribe+ method returns a subscriber object:
+  #
+  #   subscriber = ActiveSupport::Notifications.subscribe("render") do |event|
+  #     ...
+  #   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")
+  #
+  # Subscribers using a regexp or other pattern-matching object will remain subscribed
+  # to all events that match their original pattern, unless those events match a string
+  # passed to +unsubscribe+:
+  #
+  #   subscriber = ActiveSupport::Notifications.subscribe(/render/) { }
+  #   ActiveSupport::Notifications.unsubscribe('render_template.action_view')
+  #   subscriber.matches?('render_template.action_view') # => false
+  #   subscriber.matches?('render_partial.action_view') # => true
+  #
+  # == 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
+    class << self
+      attr_accessor :notifier
+
+      def publish(name, *args)
+        notifier.publish(name, *args)
+      end
+
+      def publish_event(event) # :nodoc:
+        notifier.publish_event(event)
+      end
+
+      def instrument(name, payload = {})
+        if notifier.listening?(name)
+          instrumenter.instrument(name, payload) { yield payload if block_given? }
+        else
+          yield payload if block_given?
+        end
+      end
+
+      # Subscribe to a given event name with the passed +block+.
+      #
+      # You can subscribe to events by passing a String to match exact event
+      # names, or by passing a Regexp to match all events that match a pattern.
+      #
+      # If the block passed to the method only takes one argument,
+      # it will yield an +Event+ object to the block:
+      #
+      #   ActiveSupport::Notifications.subscribe(/render/) do |event|
+      #     @event = event
+      #   end
+      #
+      # Otherwise the +block+ will receive five arguments with information
+      # about the event:
+      #
+      #   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 the instrumenter that fired the event
+      #     payload # => Hash, the payload
+      #   end
+      #
+      # Raises an error if invalid event name type is passed:
+      #
+      #   ActiveSupport::Notifications.subscribe(:render) {|event| ...}
+      #   #=> ArgumentError (pattern must be specified as a String, Regexp or empty)
+      #
+      def subscribe(pattern = nil, callback = nil, &block)
+        notifier.subscribe(pattern, callback, monotonic: false, &block)
+      end
+
+      # Performs the same functionality as #subscribe, but the +start+ and
+      # +finish+ block arguments are in monotonic time instead of wall-clock
+      # time. Monotonic time will not jump forward or backward (due to NTP or
+      # Daylights Savings). Use +monotonic_subscribe+ when accuracy of time
+      # duration is important. For example, computing elapsed time between
+      # two events.
+      def monotonic_subscribe(pattern = nil, callback = nil, &block)
+        notifier.subscribe(pattern, callback, monotonic: true, &block)
+      end
+
+      def subscribed(callback, pattern = nil, monotonic: false, &block)
+        subscriber = notifier.subscribe(pattern, callback, monotonic: monotonic)
+        yield
+      ensure
+        unsubscribe(subscriber)
+      end
+
+      def unsubscribe(subscriber_or_name)
+        notifier.unsubscribe(subscriber_or_name)
+      end
+
+      def instrumenter
+        registry[notifier] ||= Instrumenter.new(notifier)
+      end
+
+      private
+        def registry
+          ActiveSupport::IsolatedExecutionState[:active_support_notifications_registry] ||= {}
+        end
+    end
+
+    self.notifier = Fanout.new
+  end
+end

data/lib/active_support/number_helper/number_converter.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "bigdecimal/util"
+require "active_support/core_ext/big_decimal/conversions"
+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 (e.g.: 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
+        @options = nil
+      end
+
+      def execute
+        if !number
+          nil
+        elsif validate_float? && !valid_bigdecimal
+          number
+        else
+          convert
+        end
+      end
+
+      private
+        def options
+          @options ||= format_options.merge(opts)
+        end
+
+        def format_options
+          default_format_options.merge!(i18n_format_options)
+        end
+
+        def default_format_options
+          options = DEFAULTS[:format].dup
+          options.merge!(DEFAULTS[namespace][:format]) if namespace
+          options
+        end
+
+        def i18n_format_options
+          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)
+          I18n.translate(key, default: default_value(key), scope: :number, **i18n_options)
+        end
+
+        def translate_in_locale(key, **i18n_options)
+          translate_number_value_with_default(key, locale: options[:locale], **i18n_options)
+        end
+
+        def default_value(key)
+          key.split(".").reduce(DEFAULTS) { |defaults, k| defaults[k.to_sym] }
+        end
+
+        def valid_bigdecimal
+          case number
+          when Float, Rational
+            number.to_d(0)
+          when String
+            BigDecimal(number, exception: false)
+          else
+            number.to_d rescue nil
+          end
+        end
+    end
+  end
+end