cbuffer 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.rvmrc

data/Gemfile

@@ -0,0 +1,2 @@
+source 'http://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011, Duncan Robertson, British Broadcasting Corporation
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.org

@@ -0,0 +1,42 @@
+* CBuffer
+
+** Overview
+
+A circular buffer, cyclic buffer or ring buffer is a data structure that uses 
+a single, fixed-size buffer as if it were connected end-to-end. This structure 
+lends itself easily to buffering data streams. This library impliments such a 
+buffer.
+
+** Installation
+
+: gem install cbuffer
+
+** Usage
+
+: require 'cbuffer'
+:
+: a = CBuffer.new 5 => <CBuffer @size=5> 
+: a.put 1 => false 
+: a.put 2 => false 
+: a.put "Duncan" => false 
+: a.put 999 => false 
+: a.get => 1 
+: a.get => 2 
+: a.get => "Duncan" 
+: a.put "xxx" => false 
+: a.get => 999
+
+** Todo
+
+- threading support 
+- fetch items by index
+- view onto items
+
+** Contributing
+- Fork the project
+- Send a pull request
+- Don't touch the .gemspec, I'll do that when I release a new version
+
+** Author
+
+[[http://whomwah.com][Duncan Robertson]] - BBC R&D

data/Rakefile

@@ -0,0 +1,19 @@
+require 'rake/testtask'
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+desc "Run tests"
+Rake::TestTask.new do |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.test_files = FileList['test/test_*.rb']
+  t.verbose = true
+end
+
+desc "Run benchmark"
+task :benchmark do
+  ruby "test/benchmark.rb"
+end
+
+task :default => [:test]

data/cbuffer.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "cbuffer/version"
+
+Gem::Specification.new do |s|
+  s.name        = "cbuffer"
+  s.version     = CBuffer::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Duncan Robertson"]
+  s.email       = ["duncan.robertson@bbc.co.uk"]
+  s.homepage    = "https://github.com/bbcrd/CBuffer"
+  s.summary     = %q{A simple implementation of a circular buffer}
+  s.description = %q{A circular buffer, cyclic buffer or ring buffer is a data structure that uses a single, fixed-size buffer as if it were connected end-to-end. This structure lends itself easily to buffering data streams. This library impliments such a buffer.}
+  
+  s.required_rubygems_version = Gem::Requirement.new('>= 1.3.6')
+
+  s.add_development_dependency "rake"
+  s.add_development_dependency("bundler", ">= 1.0.0")
+
+  s.has_rdoc      = false
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/cbuffer.rb

@@ -0,0 +1,47 @@
+class CBuffer
+  class BufferFull < StandardError; end
+
+  def initialize(capacity)
+    @capacity = capacity
+    @f = @b = @fc = 0
+    @buffer = Array.new(capacity)
+  end
+
+  def get
+    return if empty?
+    element = @buffer[@b]
+    @buffer[@b] = nil
+    @b = (@b + 1) % @capacity
+    @fc = @fc - 1
+    element
+  end
+
+  def put(element)
+    raise BufferFull if full?
+    @buffer[@f] = element
+    @f = (@f + 1) % @capacity
+    @fc = @fc + 1
+    full?
+  end
+
+  def full?
+    @f == @b && @fc != 0
+  end
+
+  def empty?
+    @f == @b && @fc == 0
+  end
+
+  def size
+    @capacity
+  end
+
+  def clear
+    @buffer = Array.new(@capacity)
+    @f = @b = @fc = 0
+  end
+
+  def to_s
+    "<#{self.class} @size=#{@capacity}>"
+  end
+end

data/lib/cbuffer/version.rb

@@ -0,0 +1,3 @@
+module CBuffer
+  VERSION = "0.1.0"
+end

data/test/benchmark.rb

@@ -0,0 +1,63 @@
+require_relative '../lib/cbuffer.rb'
+require "benchmark"
+
+# Comparing a circular buffer implimentation for creating
+# a fixed size FIFO message queue to doing the same with 
+# an Array. As you can see, the circualr buffer approach
+# is much faster when it comes to writing to the queue.
+
+#                     user     system      total        real
+#Put: Array       0.480000   0.010000   0.490000 (  0.488787)
+#Put: CBuffer     0.010000   0.000000   0.010000 (  0.009931)
+#                     user     system      total        real
+#Get: Array       0.010000   0.000000   0.010000 (  0.004768)
+#Get: CBuffer     0.010000   0.000000   0.010000 (  0.007814)
+
+SAMPLE_SIZE=10000
+
+class ABuffer < Array
+  def initialize(size)
+    @ring_size = size
+    super( size )
+  end
+
+  def put(element)
+    if length == @ring_size
+      shift
+    end
+    push element
+  end
+
+  def get(offset=0)
+    self[ -1 + offset ]
+  end
+end
+
+def pushing
+  ary = ABuffer.new(SAMPLE_SIZE)
+  buf = CBuffer.new(SAMPLE_SIZE)
+
+  Benchmark.bm(15) do |x|
+    x.report("Put: Array")   { (1..SAMPLE_SIZE).each { |i| ary.put(i) } }
+    x.report("Put: CBuffer") { (1..SAMPLE_SIZE).each { |i| buf.put(i) } }
+  end
+end
+
+def pulling
+  ary = ABuffer.new(SAMPLE_SIZE)
+  (1..SAMPLE_SIZE).each { |i| ary.put(i) }
+  buf = CBuffer.new(SAMPLE_SIZE)
+  (1..SAMPLE_SIZE).each { |i| buf.put(i) }
+
+  Benchmark.bm(15) do |x|
+    x.report("Get: Array")   { (1..SAMPLE_SIZE).each { |i| ary.get } }
+    x.report("Get: CBuffer") { (1..SAMPLE_SIZE).each { |i| buf.get } }
+  end
+end
+
+def init
+  pushing
+  pulling
+end
+
+init

data/test/helper.rb

@@ -0,0 +1,3 @@
+require 'test/unit'
+
+require_relative '../lib/cbuffer.rb'

data/test/test_cbuffer.rb

@@ -0,0 +1,117 @@
+require 'helper'
+
+class TestCBuffer < Test::Unit::TestCase
+  def test_simple
+    b = CBuffer.new(7)
+    assert b.empty?
+    b.put "one"
+    b.put "two"
+    b.put "three"
+    assert_equal "one", b.get
+    b.put "four"
+    assert_equal "two", b.get
+    b.put "five"
+    b.put "six"
+    b.put "seven"
+    assert_equal "three", b.get
+    b.put "eight"
+    b.put "nine"
+    b.put nil 
+    assert_equal "four", b.get
+    assert_equal "five", b.get
+    assert_equal "six", b.get
+    assert_equal "seven", b.get
+    assert_equal "eight", b.get
+    assert_equal "nine", b.get
+    assert_equal nil, b.get
+  end
+
+  def test_circularness
+    b = CBuffer.new(5)
+    b.put 1 # [1,nil,nil,nil,nil]
+    b.put 2 # [1,2,nil,nil,nil]
+    b.put 3 # [1,2,3,nil,nil]
+    b.get   # [nil,2,3,nil,nil]
+    b.put 4 # [nil,2,3,4,nil]
+    b.put 5 # [nil,2,3,4,5]
+    b.put 6 # [6,2,3,4,5]
+    assert_raise(CBuffer::BufferFull) {
+      b.put(3)
+    }
+    b.get   # [6, nil, 3, 4, 5]
+    b.put 7 # [6,7,3,4,5]
+    assert_raise(CBuffer::BufferFull) {
+      b.put(8)
+    }
+  end
+
+  def test_buffer_overload
+    b = CBuffer.new(3)
+    assert_raise(CBuffer::BufferFull) {
+      b.put(1)
+      b.put(2)
+      b.put(3)
+      b.put(4)
+    }
+  end
+
+  def test_buffer_overload_with_nil
+    b = CBuffer.new(3)
+    assert_raise(CBuffer::BufferFull) {
+      b.put 1
+      b.put 2
+      b.put 3
+      b.put nil
+    }
+  end
+  
+  def test_clear_buffer
+    b = CBuffer.new(3)
+    b.put(1)
+    b.put(2)
+    b.put(8)
+    assert_raise(CBuffer::BufferFull) {
+      b.put(nil)
+    }
+    b.clear
+    assert b.empty?
+  end
+
+  def test_example_used_in_readme
+    b = CBuffer.new(4)
+    b.put({ :item => "one" })
+    b.put({ :item => "two" })
+    b.put({ :item => "three" })
+    assert_equal({:item => "one"}, b.get)
+    assert_equal({:item => "two"}, b.get)
+    b.put(nil)
+    b.put({ :item => "four" })
+    assert_equal({:item => "three"}, b.get)
+    assert_equal(nil, b.get)
+    assert_equal({ :item => "four" }, b.get)
+  end
+
+  def test_again
+    b = CBuffer.new(5)
+    assert !b.put(1)
+    assert !b.put(2)
+    assert !b.put(3)
+    assert !b.put(4)
+    assert b.put(5)
+    assert_equal 1, b.get
+    assert_equal 2, b.get
+    assert_equal 3, b.get
+    assert_equal 4, b.get
+    assert_equal 5, b.get
+    assert_equal nil, b.get
+    assert_equal nil, b.get
+    assert !b.put(1)
+    assert !b.put(2)
+    assert !b.put(3)
+    assert !b.put(4)
+    assert_equal 1, b.get
+    assert_equal 2, b.get
+    assert_equal 3, b.get
+    assert_equal 4, b.get
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: cbuffer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Duncan Robertson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-08-09 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70139950427700 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70139950427700
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: &70139950427160 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *70139950427160
+description: A circular buffer, cyclic buffer or ring buffer is a data structure that
+  uses a single, fixed-size buffer as if it were connected end-to-end. This structure
+  lends itself easily to buffering data streams. This library impliments such a buffer.
+email:
+- duncan.robertson@bbc.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.org
+- Rakefile
+- cbuffer.gemspec
+- lib/cbuffer.rb
+- lib/cbuffer/version.rb
+- test/benchmark.rb
+- test/helper.rb
+- test/test_cbuffer.rb
+homepage: https://github.com/bbcrd/CBuffer
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: A simple implementation of a circular buffer
+test_files:
+- test/benchmark.rb
+- test/helper.rb
+- test/test_cbuffer.rb