Awesome

Sparkey

Ruby FFI bindings to Spotify's Sparkey key-value store.

Installation

Requirements

• libsparkey (Github)

Add this line to your application's Gemfile:

gem 'sparkey'

And then execute:

$ bundle

Or install it yourself as:

$ gem install sparkey

Design

This gem aims to expose all of Sparkey's native functionality to Ruby via FFI bindings.

Additionally, it provides higher-level abstractions around the native functionality to provide a more idiomatic Ruby interface.

Low Level

Sparkey::Native is intended to expose the raw C functions from Sparkey to Ruby via FFI and nothing more.

Use this interface if you are adding Ruby classes and methods to expose new Sparkey functionality. A solid understanding of the FFI API will be required.

Sparkey::Native should wrap all available functions from sparkey.h. If you find one missing please submit a Pull Request.

Mid Level

This gem exposes Ruby-ish versions of most of Sparkey's public data structures and their related functions.

Use these interfaces if you need more control over the specific behavior of Sparkey than the Sparkey::Store API provides.

High Level

The Sparkey::Store API provides a very small interface for using Sparkey as a generic key-value store.

Use the Sparkey::Store API if you only need a fast persistent key-value store and don't want to delve into Sparkey specifics.

Usage

  require "sparkey"

  # Creates or overwrites the Sparkey file.
  sparkey = Sparkey.create("sparkey_store")

  # Opens an existing Sparkey file.
  # sparkey = Sparkey.open("sparkey_store")

  sparkey.put("first", "Hello")
  sparkey.put("second", "World")
  sparkey.put("third", "Goodbye")
  sparkey.flush

  puts sparkey.size
  #=> 3

  puts sparkey.get("second")
  #=> "World"

  sparkey.put("fourth", "Again")
  sparkey.delete("second")
  sparkey.delete("third")
  sparkey.flush

  puts sparkey.size
  #=> 2

  collector = Hash.new
  sparkey.each do |key, value|
    collector[key] = value
  end

  sparkey.close

  puts collector
  #=> { "first" => "Hello", "fourth" => "Again" }

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Ensure all tests pass (rake test)
5. Push to the branch (git push origin my-new-feature)
6. Create new Pull Request