module Stud::Buffer

@author Alex Dean

Implements a generic framework for accepting events which are later flushed in batches. Flushing occurs whenever :max_items or :max_interval (seconds) has been reached.

Including class must implement flush, which will be called with all accumulated items either when the output buffer fills (:max_items) or when a fixed amount of time (:max_interval) passes.

batch_receive and flush

General receive/flush can be implemented in one of two ways.

batch_receive(event) / flush(events)

flush will receive an array of events which were passed to buffer_receive.

batch_receive('one')
batch_receive('two')

will cause a flush invocation like

flush(['one', 'two'])

batch_receive(event, group) / flush(events, group)

flush() will receive an array of events, plus a grouping key.

batch_receive('one',   :server => 'a')
batch_receive('two',   :server => 'b')
batch_receive('three', :server => 'a')
batch_receive('four',  :server => 'b')

will result in the following flush calls

flush(['one', 'three'], {:server => 'a'})
flush(['two', 'four'],  {:server => 'b'})

Grouping keys can be anything which are valid Hash keys. (They don’t have to be hashes themselves.) Strings or Fixnums work fine. Use anything which you’d like to receive in your flush method to help enable different handling for various groups of events.

on_flush_error

Including class may implement on_flush_error, which will be called with an Exception instance whenever buffer_flush encounters an error.

on_full_buffer_receive

Including class may implement on_full_buffer_receive, which will be called whenever buffer_receive is called while the buffer is full.

on_full_buffer_receive will receive a Hash like {:pending => 30, :outgoing => 20} which describes the internal state of the module at the moment.

final flush

Including class should call buffer_flush(:final => true) during a teardown/shutdown routine (after the last call to buffer_receive) to ensure that all accumulated messages are flushed.