oklahoma_mixer 0.1.0

data/AUTHORS.rdoc

@@ -0,0 +1 @@
+<b>James Edward Gray II</b>::  {james@graysoftinc.com}[mailto:james@graysoftinc.com]

data/CHANGELOG.rdoc

@@ -0,0 +1,7 @@
+= Change Log
+
+Below is a complete listing of changes for each revision of Oklahoma Mixer.
+
+== 0.1.0
+
+* Initial public release with Hash Database support

data/INSTALL.rdoc

@@ -0,0 +1,22 @@
+= Installing Oklahoma Mixer
+
+RubyGems is the preferred install method for Oklahoma Mixer.
+
+== Installing the Gem
+
+Oklahoma Mixer is intended to be installed via the
+RubyGems[http://rubyforge.org/projects/rubygems/] system.  To get the latest
+version, simply enter the following into your command prompt:
+
+	$ sudo gem install oklahoma_mixer
+
+You must have RubyGems[http://rubyforge.org/projects/rubygems/] installed for
+the above to work.
+
+== Running the Tests
+
+If you would like to run Oklahoma Mixer's test suite on your system and you have
+Rake installed, just issue the following command from the root of the project
+directory:
+
+  $ rake

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 James Edward Gray II
+
+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.rdoc

@@ -0,0 +1,48 @@
+= What is Oklahoma Mixer?
+
+Oklahoma Mixer is a Ruby FFI interface to the C library for Tokyo Cabinet.  It allows you to use the key-value store from Ruby.
+
+== Why not just use rufus-tokyo?
+
+There is already a Ruby FFI interface to Tokyo Cabinet and more called {rufus-tokyo}[http://github.com/jmettraux/rufus-tokyo].  I am a huge fan of rufus-tokyo and have contributed to that project.  I have learned a ton from working with rufus-tokyo and that code was my inspiration for this library.
+
+That said, I did want to change some things that would require big changes in rufus-tokyo.  Here are the things I plan to do differently with Oklahoma Mixer:
+
+* Tokyo Cabinet's B+Tree Database has some neat features, like custom ordering
+  functions, that are hard to expose through rufus-tokyo due to the way it is
+  designed.  I would have had to rewrite pretty much that entire section of the
+  library anyway to add these features.
+* There are some places where rufus-tokyo uses more memory than it absolutely
+  must or slows itself down a bit with extra iterations of the data.  Again,
+  this is a result of how it is designed.  It allows more code reuse at the cost
+  of some efficiency.  I wanted to improve performance in those areas.
+* I'm working on some higher level abstractions for Tokyo Cabinet that I
+  eventually plan to include in this library.  These extra tools are the reason
+  I needed to make these changes and additions.
+* Finally, rufus-tokyo paved the way to a Ruby-like interface for Tokyo Cabinet.
+  Previous choices were scary in comparison.  I wanted to push that movement
+  even further though and get an even more Hash- and File-like interface, where
+  possible.
+
+It's important to note though that rufus-tokyo does do some things better and it always will.  Its advantages are:
+
+* It offers a nice Ruby interface over a raw C extension which is faster than
+  using FFI.  I have no intention of duplicating that interface, so rufus-tokyo
+  will remain the right choice for raw speed when using MRI.
+* For now, rufus-tokyo is more full featured.  It provides interfaces for Tokyo
+  Tyrant and Tokyo Dystopia.  I would like to add these eventually, but I'm
+  starting with just Tokyo Cabinet.
+* It offers a pure Ruby interface for communicating with Tokyo Tyrant without
+  needing the C libraries installed.  I won't be copying that either, so it will
+  remain the right choice for a no dependency install.
+* For now, it's more mature.  A lot of developers have used it and contributed
+  to it.  It's probably the safer library to trust for production applications
+  at this time.
+
+== Why did you call it Oklahoma Mixer?
+
+When I was in Japan, people would ask where I was from.  When I would tell them, "Oklahoma, U.S.A.," they often replied with, "Ah, I know the Oklahoma Mixer."  Some would even dance a little when they said it.
+
+It turns out Oklahoma Mixer is a song in Japan.  I had to track it down in a music store.  It's kind of a camp song medley, including things like the Hokey Pokey.  I'm not too sure what that has to do with Oklahoma, but at least they had heard of where I'm from.
+
+On a more practical side, this interface to Tokyo Cabinet is from Oklahoma.  I intend it to _mix_ together all of the great features of that library in some exciting new ways.  Thus, Oklahoma Mixer it is.

data/Rakefile

@@ -0,0 +1,61 @@
+require "rake/testtask"
+require "rake/rdoctask"
+require "rubygems"
+require "rake/gempackagetask"
+
+desc "Default task:  run all tests"
+task :default => :test
+
+Rake::TestTask.new do |test|
+  test.libs    << "test"
+  test.pattern =  "test/*_test.rb"
+  test.warning =  true
+  test.verbose =  true
+end
+
+Rake::RDocTask.new do |rdoc|
+	rdoc.main               = "README.rdoc"
+	rdoc.rdoc_dir           = "doc/html"
+	rdoc.title              = "Oklahoma Mixer Documentation"
+	rdoc.rdoc_files.include   *%w[ README.rdoc  INSTALL.rdoc
+	                               TODO.rdoc    CHANGELOG.rdoc
+	                               AUTHORS.rdoc MIT-LICENSE
+	                               lib/ ]
+end
+
+spec = Gem::Specification.new do |spec|
+	spec.name    = "oklahoma_mixer"
+	spec.version = File.read(
+                   File.join(File.dirname(__FILE__), *%w[lib oklahoma_mixer.rb])
+                 )[/^\s*VERSION\s*=\s*(['"])(\d\.\d\.\d)\1/, 2]
+
+	spec.platform = Gem::Platform::RUBY
+	spec.summary  = "An full featured and robust FFI interface to Tokyo Cabinet."
+
+	spec.test_files = Dir.glob("test/*_test.rb")
+	spec.files      = Dir.glob("{lib,test}/**/*.rb") +
+	                  Dir.glob("*.rdoc")             +
+	                  %w[MIT-LICENSE Rakefile]
+
+	spec.has_rdoc         = true
+	spec.extra_rdoc_files = %w[ README.rdoc  INSTALL.rdoc
+	                            TODO.rdoc    CHANGELOG.rdoc
+	                            AUTHORS.rdoc MIT-LICENSE ]
+	spec.rdoc_options     << "--title" << "Oklahoma Mixer Documentation" <<
+	                         "--main"  << "README.rdoc"
+
+	spec.add_dependency("ffi", ">= 0.5.4")
+	spec.add_development_dependency("rake")
+
+	spec.author      = "James Edward Gray II"
+	spec.email       = "james@graysoftinc.com"
+	spec.homepage    = "http://github.com/JEG2/oklahoma_mixer"
+	spec.description = <<END_DESC
+Oklahoma Mixer is a intended to be an all inclusive wrapper for Tokyo Cabinet.
+It provides Rubyish interfaces for all database types and supports the full
+range of features provided.
+END_DESC
+end
+Rake::GemPackageTask.new(spec) do |pkg|
+  # do nothing:  the spec is all we need
+end

data/TODO.rdoc

@@ -0,0 +1,11 @@
+= To Do List
+
+The following is a list of planned expansions for Oklahoma Mixer in the order I
+intend to address them.
+
+1. Add support for B+Tree and Fixed-length Databases
+2. Add support for Table Databases
+3. Ensure Ruby 1.9 compatibility
+4. Add support for Tokyo Tyrant
+5. Add support for Tokyo Dystopia
+6. Include some higher level abstractions like mixed tables, queues, and shards

data/lib/oklahoma_mixer/array_list/c.rb

@@ -0,0 +1,15 @@
+module OklahomaMixer
+  class ArrayList
+    module C  # :nodoc:
+      extend OklahomaMixer::Utilities::FFIDSL
+
+      prefix :tclist
+      
+      def_new_and_del_funcs
+      
+      func :name    => :shift,
+           :args    => [:pointer, :pointer],
+           :returns => :pointer
+    end
+  end
+end

data/lib/oklahoma_mixer/array_list.rb

@@ -0,0 +1,23 @@
+module OklahomaMixer
+  class ArrayList  # :nodoc:
+    def initialize(pointer = C.new)
+      @pointer = pointer
+    end
+    
+    def shift
+      C.read_from_func(:shift, @pointer)
+    end
+    
+    include Enumerable
+    
+    def each
+      while value = shift
+        yield value
+      end
+    end
+
+    def free
+      C.del(@pointer)
+    end
+  end
+end

data/lib/oklahoma_mixer/error.rb

@@ -0,0 +1,6 @@
+module OklahomaMixer
+  module Error
+    class TransactionError < RuntimeError; end
+    class CabinetError     < RuntimeError; end
+  end
+end

data/lib/oklahoma_mixer/extensible_string/c.rb

@@ -0,0 +1,18 @@
+module OklahomaMixer
+  class ExtensibleString
+    module C  # :nodoc:
+      extend OklahomaMixer::Utilities::FFIDSL
+
+      prefix :tcxstr
+      
+      def_new_and_del_funcs
+
+      func :name    => :ptr,
+           :args    => :pointer,
+           :returns => :pointer
+      func :name    => :size,
+           :args    => :pointer,
+           :returns => :int
+    end
+  end
+end

data/lib/oklahoma_mixer/extensible_string.rb

@@ -0,0 +1,27 @@
+module OklahomaMixer
+  class ExtensibleString  # :nodoc:
+    def initialize(pointer = C.new)
+      @pointer = pointer
+    end
+    
+    attr_reader :pointer
+    
+    def to_s
+      data_pointer.get_bytes(0, data_size)
+    end
+    
+    def free
+      C.del(@pointer)
+    end
+    
+    private
+    
+    def data_pointer
+      C.ptr(@pointer)
+    end
+    
+    def data_size
+      C.size(@pointer)
+    end
+  end
+end

data/lib/oklahoma_mixer/hash_database/c.rb

@@ -0,0 +1,128 @@
+module OklahomaMixer
+  class HashDatabase
+    module C  # :nodoc:
+      extend OklahomaMixer::Utilities::FFIDSL
+
+      MODES = enum :HDBOREADER,  1 << 0,
+                   :HDBOWRITER,  1 << 1,
+                   :HDBOCREAT,   1 << 2,
+                   :HDBOTRUNC,   1 << 3,
+                   :HDBONOLCK,   1 << 4,
+                   :HDBOLCKNB,   1 << 5,
+                   :HDBOTSYNC,   1 << 6
+      OPTS  = enum :HDBTLARGE,   1 << 0,
+                   :HDBTDEFLATE, 1 << 1,
+                   :HDBTBZIP,    1 << 2,
+                   :HDBTTCBS,    1 << 3
+      
+      prefix :tchdb
+      
+      def_new_and_del_funcs
+      func :name    => :open,
+           :args    => [:pointer, :string, MODES],
+           :returns => :bool
+      func :name    => :sync,
+           :args    => :pointer,
+           :returns => :bool
+      func :name    => :fsiz,
+           :args    => :pointer,
+           :returns => :uint64
+      func :name    => :copy,
+           :args    => [:pointer, :string],
+           :returns => :bool
+      func :name    => :defrag,
+           :args    => [:pointer, :int64],
+           :returns => :bool
+
+      func :name    => :ecode,
+           :args    => :pointer,
+           :returns => :int
+      func :name    => :errmsg,
+           :args    => :int,
+           :returns => :string
+
+      func :name    => :setmutex,
+           :args    => :pointer,
+           :returns => :bool
+      func :name    => :tune,
+           :args    => [:pointer, :int64, :int8, :int8, OPTS],
+           :returns => :bool
+      func :name    => :setcache,
+           :args    => [:pointer, :int32],
+           :returns => :bool
+      func :name    => :setxmsiz,
+           :args    => [:pointer, :int64],
+           :returns => :bool
+      func :name    => :setdfunit,
+           :args    => [:pointer, :int32],
+           :returns => :bool
+      func :name    => :optimize,
+           :args    => [:pointer, :int64, :int8, :int8, OPTS],
+           :returns => :bool
+
+      func :name    => :put,
+           :args    => [:pointer, :pointer, :int, :pointer, :int],
+           :returns => :bool
+      func :name    => :putkeep,
+           :args    => [:pointer, :pointer, :int, :pointer, :int],
+           :returns => :bool
+      func :name    => :putcat,
+           :args    => [:pointer, :pointer, :int, :pointer, :int],
+           :returns => :bool
+      func :name    => :putasync,
+           :args    => [:pointer, :pointer, :int, :pointer, :int],
+           :returns => :bool
+      call :name    => :TCPDPROC,
+           :args    => [:pointer, :int, :pointer, :pointer],
+           :returns => :pointer
+      func :name    => :putproc,
+           :args    => [:pointer, :pointer, :int, :pointer, :int, :TCPDPROC,
+                        :pointer],
+           :returns => :bool
+      func :name    => :addint,
+           :args    => [:pointer, :pointer, :int, :int],
+           :returns => :int
+      func :name    => :adddouble,
+           :args    => [:pointer, :pointer, :int, :double],
+           :returns => :double
+      func :name    => :out,
+           :args    => [:pointer, :pointer, :int],
+           :returns => :bool
+      func :name    => :get,
+           :args    => [:pointer, :pointer, :int, :pointer],
+           :returns => :pointer
+      func :name    => :vanish,
+           :args    => :pointer,
+           :returns => :bool
+      func :name    => :vanish,
+           :args    => :pointer,
+           :returns => :bool
+      func :name    => :fwmkeys,
+           :args    => [:pointer, :pointer, :int, :int],
+           :returns => :pointer
+      func :name    => :rnum,
+           :args    => :pointer,
+           :returns => :uint64
+
+      func :name    => :iterinit,
+           :args    => [:pointer],
+           :returns => :bool
+      func :name    => :iternext,
+           :args    => [:pointer, :pointer],
+           :returns => :pointer
+      func :name    => :iternext3,
+           :args    => [:pointer, :pointer, :pointer],
+           :returns => :bool
+
+      func :name    => :tranbegin,
+           :args    => :pointer,
+           :returns => :bool
+      func :name    => :trancommit,
+           :args    => :pointer,
+           :returns => :bool
+      func :name    => :tranabort,
+           :args    => :pointer,
+           :returns => :bool
+    end
+  end
+end