Class: Lumberjack::Device::Buffer

Inherits:
Device
  • Object
show all
Defined in:
lib/lumberjack/device/buffer.rb

Overview

A buffered logging device that wraps another logging device. Entries are buffered in memory until the buffer size is reached or the device is flushed.

Examples:

Create a buffered device that flushes every 5 entries

device = Lumberjack::Device::Buffer.new(Lumberjack::Device::LogFile.new("logfile.log"), buffer_size: 5)

Create a buffered device that automatically flushes every 10 seconds

device = Lumberjack::Device::Buffer.new("/var/log/app.log", buffer_size: 10, flush_seconds: 10)

Create a buffered device with a before_flush callback

before_flush = -> { puts "Flushing log buffer" }
device = Lumberjack::Device::Buffer.new(device, buffer_size: 10, before_flush: before_flush)

Defined Under Namespace

Classes: EntryBuffer

Instance Method Summary collapse

Constructor Details

#initialize(wrapped_device, options = {}) ⇒ Buffer

Initialize a new buffered logging device that wraps another device.

Parameters:

  • wrapped_device (Lumberjack::Device, String, Symbol, IO) —

    The underlying device to wrap. This can be any valid device specification that Lumberjack::Device.open_device accepts. Options not related to buffering will be passed to the underlying device constructor.

  • options (Hash) (defaults to: {}) —

    Options for the buffer and the underlying device.

Options Hash (options):

  • :buffer_size (Integer) —

    The number of entries to buffer before flushing. Default is 0 (no buffering).

  • :flush_seconds (Integer) —

    If specified, a background thread will flush the buffer every N seconds.

  • :before_flush (Proc) —

    A callback that will be called before each flush. The callback should respond to call and take no arguments. The callback is invoked outside of the buffer lock, so it may be called concurrently from multiple threads flushing at the same time; it must be thread safe if it modifies any shared state.



140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/lumberjack/device/buffer.rb', line 140

def initialize(wrapped_device, options = {})
  buffer_options = [:buffer_size, :flush_seconds, :before_flush]
  device_options = options.reject { |k, _| buffer_options.include?(k) }
  device = Device.open_device(wrapped_device, device_options)

  @buffer = EntryBuffer.new(device, options[:buffer_size] || 0, options[:before_flush])

  flush_seconds = options[:flush_seconds]
  self.class.send(:create_flusher_thread, flush_seconds, @buffer) if flush_seconds.is_a?(Numeric) && flush_seconds > 0

  # Add a finalizer to ensure flush is called before the object is destroyed
  ObjectSpace.define_finalizer(self, self.class.send(:create_finalizer, @buffer))
end

Instance Method Details

#buffer_size ⇒ Object 



154
155
156
 
# File 'lib/lumberjack/device/buffer.rb', line 154

def buffer_size
  @buffer.size
end

#buffer_size=(value) ⇒ void

This method returns an undefined value.

Set the buffer size. The underlying device will only be written to when the buffer size is exceeded.

Parameters:

  • value (Integer) —

    The number of entries to buffer before flushing.



163
164
165
166
 
# File 'lib/lumberjack/device/buffer.rb', line 163

def buffer_size=(value)
  @buffer.size = value
  @buffer.flush
end

#close ⇒ void

This method returns an undefined value.

Close the device.



179
180
181
182
183
184
185
 
# File 'lib/lumberjack/device/buffer.rb', line 179

def close
  @buffer.close
  @buffer.device.close

  # Remove the finalizer since we've already flushed
  ObjectSpace.undefine_finalizer(self)
end

#closed? ⇒ Boolean

Return true if the buffer has been closed.

Returns:

  • (Boolean) 


188
189
190
 
# File 'lib/lumberjack/device/buffer.rb', line 188

def closed?
  @buffer.closed?
end

#dev ⇒ IO

Return the underlying stream. Provided for API compatibility with Logger devices.

Returns:

  • (IO) —

    The underlying stream.



210
211
212
 
# File 'lib/lumberjack/device/buffer.rb', line 210

def dev
  @buffer.device.dev
end

#empty? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


220
221
222
 
# File 'lib/lumberjack/device/buffer.rb', line 220

def empty?
  @buffer.empty?
end

#flush ⇒ void

This method returns an undefined value.

Flush the buffer to the underlying device.



195
196
197
 
# File 'lib/lumberjack/device/buffer.rb', line 195

def flush
  @buffer.flush
end

#last_flushed_at ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



215
216
217
 
# File 'lib/lumberjack/device/buffer.rb', line 215

def last_flushed_at
  @buffer.last_flushed_at
end

#reopen(logdev = nil) ⇒ Object

Reopen the underlying device, optionally with a new log destination.



200
201
202
203
204
205
 
# File 'lib/lumberjack/device/buffer.rb', line 200

def reopen(logdev = nil)
  flush
  @buffer.device.reopen(logdev)
  @buffer.reopen
  ObjectSpace.define_finalizer(self, self.class.send(:create_finalizer, @buffer))
end

#write(entry) ⇒ void

This method returns an undefined value.

Write an entry to the underlying device.

Parameters:

  • entry (LogEntry, String) —

    The entry to write.



172
173
174
 
# File 'lib/lumberjack/device/buffer.rb', line 172

def write(entry)
  @buffer << entry
end