logging 2.0.0 → 2.3.0

data/lib/logging/appender.rb

@@ -9,11 +9,6 @@ module Logging
 # Each subclass should provide a +write+ method that will write log
 # messages to the logging destination.
 #
-# A private +sync+ method is provided for use by subclasses. It is used to
-# synchronize writes to the logging destination, and can be used by
-# subclasses to synchronize the closing or flushing of the logging
-# destination.
-#
 class Appender
 
   attr_reader :name, :layout, :level, :filters
@@ -114,7 +109,7 @@ class Appender
   #
   # Set the level for this appender; log events below this level will be
   # ignored by this appender. The level can be either a +String+, a
-  # +Symbol+, or a +Fixnum+. An +ArgumentError+ is raised if this is not
+  # +Symbol+, or an +Integer+. An +ArgumentError+ is raised if this is not
   # the case.
   #
   # There are two special levels -- "all" and "off". The former will
@@ -138,7 +133,7 @@ class Appender
   def level=( level )
     lvl = case level
           when String, Symbol; ::Logging::level_num(level)
-          when Fixnum; level
+          when Integer; level
           when nil; 0
           else
             raise ArgumentError,
@@ -251,26 +246,21 @@ class Appender
     self
   end
 
+  # Save off the original `to_s` for use in tests
+  alias_method :_to_s, :to_s
+
   # call-seq:
-  #     inspect    => string
+  #     to_s => string
   #
   # Returns a string representation of the appender.
   #
-  def inspect
-    "<%s:0x%x name=\"%s\">" % [
-        self.class.name.sub(%r/^Logging::/, ''),
-        self.object_id,
-        self.name
-    ]
+  def to_s
+    "<%s name=\"%s\">" % [self.class.name.sub(%r/^Logging::/, ''), self.name]
   end
 
-  # Returns the current Encoding for the appender or nil if an encoding has
-  # not been set.
-  #
-  def encoding
-    return @encoding if defined? @encoding
-    @encoding = Object.const_defined?(:Encoding) ? Encoding.default_external : nil
-  end
+  # Returns the current Encoding for the appender. The default external econding
+  # will be used if none is explicitly set.
+  attr_reader :encoding
 
   # Set the appender encoding to the given value. The value can either be an
   # Encoding instance or a String or Symbol referring to a valid encoding.
@@ -283,9 +273,9 @@ class Appender
   # Raises ArgumentError if the value is not a valid encoding.
   def encoding=( value )
     if value.nil?
-      @encoding = nil
+      @encoding = Encoding.default_external
     else
-      @encoding = Object.const_defined?(:Encoding) ? Encoding.find(value.to_s) : nil
+      @encoding = Encoding.find(value.to_s)
     end
   end
 
@@ -329,17 +319,6 @@ private
     nil
   end
 
-  # call-seq:
-  #    sync { block }
-  #
-  # Obtains an exclusive lock, runs the block, and releases the lock when
-  # the block completes. This method is re-entrant so that a single thread
-  # can call +sync+ multiple times without hanging the thread.
-  #
-  def sync( &block )
-    @mutex.synchronize(&block)
-  end
-
 end  # class Appender
 end  # module Logging
 

data/lib/logging/appenders/buffering.rb

@@ -27,6 +27,10 @@ module Logging::Appenders
     # flush_period.
     attr_reader :flush_period
 
+    # When set, the buffer will be flushed using an asynchronous Thread. That
+    # is, the main program thread will not be blocked during writes.
+    attr_reader :async
+
     # Messages will be written in chunks. This controls the number of messages
     # to pull from the buffer for each write operation. The default is to pull
     # all messages from the buffer at once.
@@ -39,20 +43,21 @@ module Logging::Appenders
       @buffer = []
       @immediate = []
       @auto_flushing = 1
-      @flush_period = @periodic_flusher = nil
+      @async = false
+      @flush_period = @async_flusher = nil
 
       super(*args, &block)
     end
 
-    # Close the message buffer by flushing all log events to the appender. If a
-    # periodic flusher thread is running, shut it down and allow it to exit.
+    # Close the message buffer by flushing all log events to the appender. If an
+    # async flusher thread is running, shut it down and allow it to exit.
     #
     def close( *args )
       flush
 
-      if @periodic_flusher
-        @periodic_flusher.stop
-        @periodic_flusher = nil
+      if @async_flusher
+        @async_flusher.stop
+        @async_flusher = nil
         Thread.pass
       end
 
@@ -60,11 +65,11 @@ module Logging::Appenders
     end
 
     # Reopen the connection to the underlying logging destination. In addition
-    # if the appender is configured for periodic flushing, then the flushing
+    # if the appender is configured for asynchronous flushing, then the flushing
     # thread will be stopped and restarted.
     #
     def reopen
-      _setup_periodic_flusher
+      _setup_async_flusher
       super
     end
 
@@ -74,7 +79,7 @@ module Logging::Appenders
       return self if @buffer.empty?
 
       ary = nil
-      sync {
+      @mutex.synchronize {
         ary = @buffer.dup
         @buffer.clear
       }
@@ -95,7 +100,7 @@ module Logging::Appenders
     # Clear the underlying buffer of all log events. These events will not be
     # appended to the logging destination; they will be lost.
     def clear!
-      sync { @buffer.clear }
+      @mutex.synchronize { @buffer.clear }
     end
 
     # Configure the levels that will trigger an immediate flush of the
@@ -194,21 +199,43 @@ module Logging::Appenders
     # manually if so desired.
     #
     def flush_period=( period )
-      period =
+      @flush_period =
         case period
         when Integer, Float, nil; period
-        when String;
+        when String
           num = _parse_hours_minutes_seconds(period) || _parse_numeric(period)
-          num = ArgumentError.new("unrecognized flush period: #{period.inspect}") if num.nil?
+          raise ArgumentError.new("unrecognized flush period: #{period.inspect}") if num.nil?
           num
-        else ArgumentError.new("unrecognized flush period: #{period.inspect}") end
+        else
+          raise ArgumentError.new("unrecognized flush period: #{period.inspect}")
+        end
 
-      raise period if Exception === period
-      @flush_period = period
+      if !@flush_period.nil? && @flush_period <= 0
+        raise ArgumentError,
+          "flush_period must be greater than zero: #{period.inspect}"
+      end
+
+      _setup_async_flusher
+    end
+
+    # Returns `true` if an asynchronous flush period has been defined for the
+    # appender.
+    def flush_period?
+      !@flush_period.nil?
+    end
 
-      _setup_periodic_flusher
+    # Enable or disable asynchronous logging via a dedicated logging Thread.
+    # Pass in `true` to enable and `false` to disable.
+    #
+    # bool - A boolean value
+    #
+    def async=( bool )
+      @async = bool ? true : false
+      _setup_async_flusher
     end
 
+    alias_method :async?, :async
+
   protected
 
     # Configure the buffering using the arguments found in the give options
@@ -223,12 +250,12 @@ module Logging::Appenders
       self.immediate_at  = opts.fetch(:immediate_at, '')
       self.auto_flushing = opts.fetch(:auto_flushing, true)
       self.flush_period  = opts.fetch(:flush_period, nil)
+      self.async         = opts.fetch(:async, false)
       self.write_size    = opts.fetch(:write_size, DEFAULT_BUFFER_SIZE)
     end
 
-    # Returns true if the _event_ level matches one of the configured
-    # immediate logging levels. Otherwise returns false.
-    #
+    # Returns `true` if the `event` level matches one of the configured
+    # immediate logging levels. Otherwise returns `false`.
     def immediate?( event )
       return false unless event.respond_to? :level
       @immediate[event.level]
@@ -240,14 +267,15 @@ module Logging::Appenders
     # call-seq:
     #    write( event )
     #
-    # Writes the given _event_ to the logging destination. The _event_ can
+    # Writes the given `event` to the logging destination. The `event` can
     # be either a LogEvent or a String. If a LogEvent, then it will be
     # formatted using the layout given to the appender when it was created.
     #
-    # The _event_ will be formatted and then buffered until the
+    # The `event` will be formatted and then buffered until the
     # "auto_flushing" level has been reached. At this time the canonical_write
     # method will be used to log all events stored in the buffer.
     #
+    # Returns this appender instance
     def write( event )
       str = event.instance_of?(::Logging::LogEvent) ?
             layout.format(event) : event.to_s
@@ -256,12 +284,21 @@ module Logging::Appenders
       if @auto_flushing == 1
         canonical_write(str)
       else
-        sync {
-          str = str.force_encoding(encoding) if encoding && str.encoding != encoding
+        str = str.force_encoding(encoding) if encoding && str.encoding != encoding
+        @mutex.synchronize {
           @buffer << str
         }
-        @periodic_flusher.signal if @periodic_flusher
-        flush if @buffer.length >= @auto_flushing || immediate?(event)
+        flush_now = @buffer.length >= @auto_flushing || immediate?(event)
+
+        if flush_now
+          if async?
+            @async_flusher.signal(flush_now)
+          else
+            self.flush
+          end
+        elsif @async_flusher && flush_period?
+          @async_flusher.signal
+        end
       end
 
       self
@@ -270,9 +307,14 @@ module Logging::Appenders
     # Attempt to parse an hours/minutes/seconds value from the string and return
     # an integer number of seconds.
     #
+    # str - The input String to parse for time values.
+    #
+    # Examples
+    #
     #   _parse_hours_minutes_seconds("14:12:42")  #=> 51162
     #   _parse_hours_minutes_seconds("foo")       #=> nil
     #
+    # Returns a Numeric or `nil`
     def _parse_hours_minutes_seconds( str )
       m = %r/^\s*(\d{2,}):(\d{2}):(\d{2}(?:\.\d+)?)\s*$/.match(str)
       return if m.nil?
@@ -281,49 +323,60 @@ module Logging::Appenders
     end
 
     # Convert the string into a numeric value. If the string does not
-    # represent a valid Integer or Float then +nil+ is returned.
+    # represent a valid Integer or Float then `nil` is returned.
+    #
+    # str - The input String to parse for Numeric values.
+    #
+    # Examples
     #
     #   _parse_numeric("10")   #=> 10
     #   _parse_numeric("1.0")  #=> 1.0
     #   _parse_numeric("foo")  #=> nil
     #
+    # Returns a Numeric or `nil`
     def _parse_numeric( str )
       Integer(str) rescue (Float(str) rescue nil)
     end
 
-    # Using the flush_period, create a new PeriodicFlusher attached to this
+    # Using the flush_period, create a new AsyncFlusher attached to this
     # appender. If the flush_period is nil, then no action will be taken. If a
-    # PeriodicFlusher already exists, it will be stopped and a new one will be
+    # AsyncFlusher already exists, it will be stopped and a new one will be
     # created.
     #
-    def _setup_periodic_flusher
-      # stop and remove any existing periodic flusher instance
-      if @periodic_flusher
-        @periodic_flusher.stop
-        @periodic_flusher = nil
+    # Returns `nil`
+    def _setup_async_flusher
+      # stop and remove any existing async flusher instance
+      if @async_flusher
+        @async_flusher.stop
+        @async_flusher = nil
         Thread.pass
       end
 
-      # create a new periodic flusher if we have a valid flush period
-      if @flush_period
+      # create a new async flusher if we have a valid flush period
+      if @flush_period || async?
         @auto_flushing = DEFAULT_BUFFER_SIZE unless @auto_flushing > 1
-        @periodic_flusher = PeriodicFlusher.new(self, @flush_period)
-        @periodic_flusher.start
+        @async_flusher = AsyncFlusher.new(self, @flush_period)
+        @async_flusher.start
+        Thread.pass
       end
+
+      nil
     end
 
     # :stopdoc:
 
-    # The PeriodicFlusher contains an internal run loop that will periodically
+    # The AsyncFlusher contains an internal run loop that will periodically
     # wake up and flush any log events contained in the message buffer of the
-    # owning appender instance. The PeriodicFlusher relies on a _signal_ from
+    # owning appender instance. The AsyncFlusher relies on a `signal` from
     # the appender in order to wakeup and perform the flush on the appender.
-    #
-    class PeriodicFlusher
+    class AsyncFlusher
 
-      # Create a new PeriodicFlusher instance that will call the +flush+
-      # method on the given _appender_. The +flush+ method will be called
-      # every _period_ seconds, but only when the message buffer is non-empty.
+      # Create a new AsyncFlusher instance that will call the `flush`
+      # method on the given `appender`. The `flush` method will be called
+      # every `period` seconds, but only when the message buffer is non-empty.
+      #
+      # appender - The Appender instance to periodically `flush`
+      # period   - The Numeric sleep period or `nil`
       #
       def initialize( appender, period )
         @appender = appender
@@ -334,10 +387,12 @@ module Logging::Appenders
         @thread = nil
         @waiting = nil
         @signaled = false
+        @immediate = 0
       end
 
       # Start the periodic flusher's internal run loop.
       #
+      # Returns this flusher instance
       def start
         return if @thread
 
@@ -345,57 +400,75 @@ module Logging::Appenders
           begin
             break if Thread.current[:stop]
             _wait_for_signal
-            sleep @period unless Thread.current[:stop]
+            _try_to_sleep
             @appender.flush
           rescue => err
-            ::Logging.log_internal {"PeriodicFlusher for appender #{@appender.inspect} encountered an error"}
+            ::Logging.log_internal {"AsyncFlusher for appender #{@appender.inspect} encountered an error"}
             ::Logging.log_internal_error(err)
           end
-        }; @thread = nil }
+        }}
 
         self
       end
 
-      # Stop the periodic flusher's internal run loop.
+      # Stop the async flusher's internal run loop.
       #
+      # Returns this flusher instance
       def stop
         return if @thread.nil?
         @thread[:stop] = true
         signal if waiting?
+        @thread = nil
         self
       end
 
-      # Signal the periodic flusher. This will wake up the run loop if it is
+      # Signal the async flusher. This will wake up the run loop if it is
       # currently waiting for something to do. If the signal method is never
-      # called, the periodic flusher will never perform the flush action on
+      # called, the async flusher will never perform the flush action on
       # the appender.
       #
-      def signal
+      # immediate - Set to `true` if the sleep period should be skipped
+      #
+      # Returns this flusher instance
+      def signal( immediate = nil )
         return if Thread.current == @thread   # don't signal ourselves
         return if @signaled                   # don't need to signal again
 
         @mutex.synchronize {
           @signaled = true
+          @immediate += 1 if immediate
           @cv.signal
         }
         self
       end
 
-      # Returns +true+ if the flusher is waiting for a signal. Returns +false+
+      # Returns `true` if the flusher is waiting for a signal. Returns `false`
       # if the flusher is somewhere in the processing loop.
-      #
       def waiting?
         @waiting
       end
 
+      # Returns `true` if the flusher should immeidately write the buffer to the
+      # IO destination.
+      def immediate?
+        @immediate > 0
+      end
+
     private
 
+      def _try_to_sleep
+        return if Thread.current[:stop]
+        return if immediate?
+        sleep @period unless @period.nil?
+      end
+
       def _wait_for_signal
         @mutex.synchronize {
           begin
             # wait on the condition variable only if we have NOT been signaled
             unless @signaled
               @waiting = true
+              @immediate -= 1 if immediate?
               @cv.wait(@mutex)
               @waiting = false
             end
@@ -406,9 +479,7 @@ module Logging::Appenders
       ensure
         @waiting = false
       end
-    end  # class PeriodicFlusher
+    end
     # :startdoc:
-
-  end  # Buffering
-end  # Logging::Appenders
-
+  end
+end