oinky 0.1.0

data/LICENSE

@@ -0,0 +1,22 @@
+This project is distributed under the MIT License
+
+Copyright (c) 2012, Jacob Lacouture
+
+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.md

@@ -0,0 +1,141 @@
+## What is Oinky?
+
+Oinky is an in-memory relational database library that supports fast serialization and deserialization.  It is a tool for transforming the representation of data between the application (as a database) and network or storage (as a string of bytes).  It is a database (like sqlite), but also an encoder (like Protocol Buffers).
+
+The implementation is C++, and currently includes bindings for C and Ruby.
+
+## Applications
+
+Oinky is a general purpose serialization library.  It has tons of potential applications.  Many excellent serialization libraries exist, but complex data structures like graphs can be cumbersome to encode with the best of them.  Oinky's relational facility makes it well suited to such tasks, as relational schemas can naturally and efficiently represent data of arbitrary topology.
+
+### Microsharding
+
+Microsharding is a scheme for deploying quasi-relational databases over distributed key-value storage platforms.  Oinky provides the relational adapter.  The rationale behind microsharding is described in more detail in a [blog post][blog].
+
+[blog]: http://jkub.github.com/2012/03/21/microsharding/
+
+## Sample
+
+The following sample is inspired by the Sequel sample at [http://sequel.rubyforge.org][sequel]
+
+[sequel]: http://sequel.rubyforge.org "The Sequel Database Library"
+
+    require 'oinky'
+
+    db = Oinky::DB.new
+
+    db.atomic {
+      db.create_table(:items) { |tbl|
+        tbl.add_column(:id, :int32, 0)
+        tbl.add_column(:name, :string, '')
+        tbl.add_column(:price, :int32, 0)
+
+        tbl.add_index(:name=>'by_name', :unique=>true, :columns=>[:name])
+      }
+    }
+
+    items = db[:items]
+
+    items.insert_row(:name => 'abc', :price => (rand * 100).to_i)
+    items.insert_row(:name => 'def', :price => (rand * 100).to_i)
+    items.insert_row(:name => 'ghi', :price => (rand * 100).to_i)
+
+    # print out the number of records
+    puts "Item count: #{items.row_count}"
+
+    puts "Items table contains:"
+    items.each{ |row|
+      # row is a hash of colname=>value
+      puts row.inspect
+    }
+
+    # print out the average over a specific column
+    avg = items.each.average(:price)
+    puts "The average price is: #{avg}"
+
+    # Using a lambda explicitly to compute something more complex 
+    # (and ideally less useless).
+    db[:items].each.average(lambda {|r| r[:price] + r[:name].size} )
+
+    # Serialize
+    str = db.serialize
+    puts "The serialized database consumes #{str.length} bytes"
+
+    # Create a clone
+    db2 = Oinky::DB.mount(str)
+
+    db2.alter_table(:items) { |tbl|
+      tbl.add_index(:name=>'by_price', :unique=>false, :columns=>[:price])
+    }
+
+    puts "Items by price:"
+    db2[:items].indices[:by_price].each {|row|
+      puts row.inspect
+    }
+
+    str2 = db2.serialize
+    puts "With the price index, the serialized database consumes #{str2.length} bytes"
+
+
+## Implementation
+
+See the [design][design] document for an overview of behavior and implementation.
+
+[design]: http://github.com/oinky/oinky/blob/master/doc/design.md "Design"
+
+
+### Performance
+
+Oinky is designed to perform very well in specific scenarios.  Design tradeoffs and performance properties are covered in the [performance document][perf].
+
+[perf]: http://github.com/oinky/oinky/blob/master/doc/performance.md "Performance"
+
+### Status
+
+Oinky is fast and stable, but very new.  The interface is raw, and the library is unsupported by the tools and ORMs that help make relational schemas so compelling in the first place.  
+
+Nevertheless, Oinky is highly functional as it is, and offers open-ended opportunities for improvement.
+
+## Installation
+
+Oinky is configured with autoconf and depends on the [boost C++ libraries][boost].  First you'll need to make sure boost and autotools are installed.  Then you can generate the configure script as follows.
+
+    ./boostrap.sh
+    
+If boost is installed in a nonstandard location, you'll need to provide that location to the *configure* script.  Additionally, building the ruby gem is optional, as it depends on ruby and rake.  The following command illustrates the available options.
+
+    ./configure --with-boost-include-path=/usr/local/boost_1_47_0 \
+        --with-boost-lib-path=/usr/local/boost_1_47_0/stage/lib \
+        --enable-rubygem=yes --with-asserts=yes
+
+Once you've configured, *make* will build the C library.  *make install* will install the headers and C library.  *make check* will build and run some sanity tests.
+
+### Ruby
+
+Before installing the gem, you'll need to build it in (project_root)/lib/rubygem
+
+The gem installer accepts the boost arguments in the same format as the *configure* script.
+
+    gem install oinky-0.1.0.gem -- --with-boost-include-path=/usr/local/boost_1_47_0 \
+        --with-boost-lib-path=/usr/local/boost_1_47_0/stage/lib
+
+[boost]: http://www.boost.org/ "The Boost C++ Libraries"
+
+The gem requires Ruby 1.9.x.  Though the gem is built with FFI and is theoretically portable, only MRI currently works, due to differences in the FFI interface under JRuby and RBX.
+
+### Platforms
+
+Oinky has been successfully built and tested on 64 bit OSX and 32/64 bit Linux with clang++(2.1) and g++(4.4 and 4.6) and boost versions 1.46 and 1.47.  Various older compilers and boost versions have caused issues, though many may work.  Oinky implements architecture-dependent byte-order conversion, but it's only been minimally tested.
+
+## Support
+
+There is a [mailing list][group] where discussion may occur.
+
+[group]: http://groups.google.com/group/oinky "The oinky mailing list"
+
+## License
+
+Oinky is published under the terms of the MIT license.  See the LICENSE file.
+
+
+

data/ext/extconf.rb

@@ -0,0 +1,79 @@
+require 'mkmf'
+
+# We may need to be told where the boost headers/libs are
+dir_config('boost')
+# The above assumes that the final dir component of all include dirs is 
+# 'include' which is not always the case, so we have to do this:
+
+boostinc = nil
+boostlib = nil
+
+iprefix = '--with-boost-include-path='
+lprefix = '--with-boost-lib-path='
+withasserts = '--with-asserts=yes'
+
+ARGV.each { |s|
+  if s[0..iprefix.size-1] == iprefix
+    boostinc = s[iprefix.size..-1]
+    newflags = " -I" + File.join(boostinc,'boost/tr1/tr1') + " -I" + boostinc + ' '
+    # Give the specified boost include path precedence over any default.
+    $INCFLAGS = newflags + $INCFLAGS
+  elsif s[0..lprefix.size-1] == lprefix
+    boostlib = s[lprefix.size..-1]
+    newflags = " -L" + boostlib + ' '
+    $LDFLAGS = newflags + $LDFLAGS
+  elsif s == withasserts
+    $CFLAGS += ' -DDEBUG'
+  end
+}
+
+$LDFLAGS += " -lboost_system"
+
+# -flat_namespace causes HORRIBLE THINGS, so we have to remove it.
+$DLDFLAGS = $DLDFLAGS.split(/\s/).select{ |str| /flat_namespace/ !~ str } * ' '
+
+if boostinc
+  puts "Using #{boostinc} as boost header path."
+end
+if boostlib
+  puts "Using #{boostlib} as boost lib path."
+end
+
+unless boostinc or boostlib
+  puts "
+Specify #{iprefix}<ipath> or #{lprefix}<lpath> to set 
+    boost include and lib paths respectively, or use --with-boost-dir=<path>
+    to set include and lib paths to <path>/include and <path>/lib.
+
+If you're doing a gem install, try:
+  gem install oinky -- --with-boost-include-path=<boostinc> --with-boost-lib-path=<boostlib>
+"
+end
+
+puts "You may enable asserts in the C extension as follows:
+  gem install oinky -- --with-asserts=yes
+"
+
+=begin
+#Is this bug 4924, which has been open 9 months?
+#http://www.ruby-forum.com/topic/1994312#1007218
+
+# This is the one boost lib we link to (for now)
+#have_library('boost_system', 'boost::datetime::now')
+# This is a TR1 library.  Oinky will actually use the compiler's tr1 library if 
+# it's available, but this will be available as a backup if that's not available.
+if boostinc
+  find_header('boost/tr1/tr1/unordered_map', [boostinc])
+  find_header('boost/type_traits.hpp', [boostinc])
+else
+  have_header('boost/tr1/tr1/unordered_map')
+  have_header('boost/type_traits.hpp')
+end
+=end
+
+
+# Give the gem-local Oinky implementation preference over any default installed version.
+$INCFLAGS = ' -I./include ' + $INCFLAGS
+
+create_makefile("liboinky_c")
+

data/ext/include/oinky.h

@@ -0,0 +1,424 @@
+//  This source is distributed under the terms of the MIT License.  Refer 
+//  to the 'LICENSE' file for details.
+//  
+//  Copyright (c) Jacob Lacouture, 2012
+
+#ifndef OINKY_H_INCLUDED
+#define OINKY_H_INCLUDED
+
+#include <stdint.h>
+#include <string.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+//  This is the C header for Oinky.  To use this header, you must bind to the 
+//  appropriate Oinky library.  The C++ header requires no library.
+//
+//  I don't expect anyone to use the C library directly.  The only reason this
+//  exists is to provide simpler bindings for scripting languages (eg: Ruby FFI)
+
+typedef struct _oinky_db_handle_t           oinky_db_handle_t;
+typedef struct _oinky_table_handle_t        oinky_table_handle_t;
+typedef struct _oinky_index_handle_t        oinky_index_handle_t;
+typedef struct _oinky_column_handle_t       oinky_column_handle_t;
+typedef struct _oinky_column_selector_t     oinky_column_selector_t;
+typedef struct _oinky_index_row_cursor_t    oinky_index_row_cursor_t;
+typedef struct _oinky_table_row_cursor_t    oinky_table_row_cursor_t;
+
+typedef struct _oinky_datetime_t {
+    uint64_t value;
+} oinky_datetime_t;
+
+typedef uint64_t oinky_savepoint_t;
+
+typedef struct  _oinky_db_string {
+    size_t length;
+    const char *bytes;
+} oinky_db_string;
+
+typedef enum _oinky_column_type_code_t
+{
+    nky_Variant = 0,
+    
+    //  The rest are identical to value_type_code
+    nky_Bit = 1,
+    nky_Int8 = 2,
+    nky_Int16 = 3,
+    nky_Int32 = 4,
+    nky_Int64 = 5,
+    nky_Datetime = 6,
+    nky_String = 7,
+    //  more inline types
+    nky_Uint8 = 8,
+    nky_Uint16 = 9,
+    nky_Uint32 = 10,
+    nky_Uint64 = 11,
+    nky_Float32 = 12,
+    nky_Float64 = 13
+} oinky_column_type_code_t;
+
+//  conditioning on platform may become necessary.
+typedef double float64_t;
+typedef float float32_t;
+        
+typedef struct  _oinky_db_variant {
+    union {
+        oinky_db_string string_value;
+        int64_t int_value;
+        uint64_t uint_value;
+        float64_t f64_value;
+        float32_t f32_value;
+        oinky_datetime_t dt_value;
+    } value;
+    oinky_column_type_code_t type;
+} oinky_db_variant;
+
+inline oinky_db_string nky_string_from_immediate(const char *str) {
+    oinky_db_string s = {strlen(str), str};
+    return s;
+}
+inline oinky_db_variant nky_variant_from_immediate_s(const char *str) {
+    oinky_db_variant v;
+    v.value.string_value = nky_string_from_immediate(str);
+    v.type = nky_String;
+    return v;
+}
+inline oinky_db_variant nky_variant_from_immediate_dbs(oinky_db_string str) {
+    oinky_db_variant v;
+    v.value.string_value = str;
+    v.type = nky_String;
+    return v;
+}
+inline oinky_db_variant nky_variant_from_immediate_dt(oinky_datetime_t dt) {
+    oinky_db_variant v;
+    v.value.dt_value = dt;
+    v.type = nky_Datetime;
+    return v;
+}
+//int
+inline oinky_db_variant nky_variant_from_immediate_i64(int64_t x) {
+    oinky_db_variant v;
+    v.value.int_value = x;
+    v.type = nky_Int64;
+    return v;
+}
+inline oinky_db_variant nky_variant_from_immediate_i32(int32_t x) {
+    oinky_db_variant v;
+    v.value.int_value = x;
+    v.type = nky_Int32;
+    return v;
+}
+inline oinky_db_variant nky_variant_from_immediate_i16(int16_t x) {
+    oinky_db_variant v;
+    v.value.int_value = x;
+    v.type = nky_Int16;
+    return v;
+}
+inline oinky_db_variant nky_variant_from_immediate_i8(int8_t x) {
+    oinky_db_variant v;
+    v.value.int_value = x;
+    v.type = nky_Int8;
+    return v;
+}
+//uint
+inline oinky_db_variant nky_variant_from_immediate_ui64(uint64_t x) {
+    oinky_db_variant v;
+    v.value.uint_value = x;
+    v.type = nky_Uint64;
+    return v;
+}
+inline oinky_db_variant nky_variant_from_immediate_ui32(uint32_t x) {
+    oinky_db_variant v;
+    v.value.uint_value = x;
+    v.type = nky_Uint32;
+    return v;
+}
+inline oinky_db_variant nky_variant_from_immediate_ui16(uint16_t x) {
+    oinky_db_variant v;
+    v.value.uint_value = x;
+    v.type = nky_Uint16;
+    return v;
+}
+inline oinky_db_variant nky_variant_from_immediate_ui8(uint8_t x) {
+    oinky_db_variant v;
+    v.value.uint_value = x;
+    v.type = nky_Uint8;
+    return v;
+}
+
+inline oinky_db_variant nky_variant_from_immediate_bit(int x) {
+    oinky_db_variant v;
+    v.value.int_value = x ? 1 : 0;
+    v.type = nky_Bit;
+    return v;
+}
+
+//float
+inline oinky_db_variant nky_variant_from_immediate_f64(float64_t x) {
+    oinky_db_variant v;
+    v.value.f64_value = x;
+    v.type = nky_Float64;
+    return v;
+}
+inline oinky_db_variant nky_variant_from_immediate_f32(float32_t x) {
+    oinky_db_variant v;
+    v.value.f32_value = x;
+    v.type = nky_Float32;
+    return v;
+}
+
+//  We still want to export these.
+oinky_db_variant _nky_variant_from_immediate_s(const char *str);
+oinky_db_variant _nky_variant_from_immediate_dt(oinky_datetime_t dt);
+oinky_db_variant _nky_variant_from_immediate_i64(int64_t x);
+oinky_db_variant _nky_variant_from_immediate_i32(int32_t x);
+oinky_db_variant _nky_variant_from_immediate_i16(int16_t x);
+oinky_db_variant _nky_variant_from_immediate_i8(int8_t x);
+oinky_db_variant _nky_variant_from_immediate_ui64(uint64_t x);
+oinky_db_variant _nky_variant_from_immediate_ui32(uint32_t x);
+oinky_db_variant _nky_variant_from_immediate_ui16(uint16_t x);
+oinky_db_variant _nky_variant_from_immediate_ui8(uint8_t x);
+oinky_db_variant _nky_variant_from_immediate_f64(float64_t x);
+oinky_db_variant _nky_variant_from_immediate_f32(float32_t x);
+oinky_db_variant _nky_variant_from_immediate_bit(int x);
+
+typedef struct _oinky_column_def {
+    oinky_db_string column_name;
+    oinky_column_type_code_t column_type;
+    oinky_db_variant default_value;
+} oinky_column_def;
+
+typedef struct _oinky_index_column_def {
+    oinky_db_string column_name;
+    char sort_ascending;
+} oinky_index_column_def;
+
+typedef enum 
+{
+    nky_success = 0,
+
+    nky_implementation_bug = -1,
+    nky_no_resources = -2,
+    nky_invalid_argument = -5,
+    nky_unknown_exception = -6,
+    nky_row_format_mismatch = -8,
+    nky_column_type_mismatch = -9,
+    nky_object_deleted = -10,
+    nky_object_exists = -11,
+    nky_index_entry_not_unique = -12,
+    nky_version_mismatch = -13,
+    nky_unsupported_operation = -14,
+    nky_object_still_referenced = -15,
+    nky_incomparable_value_types = -16,
+    nky_column_not_indexable = -17,
+    nky_object_not_found = -18,
+    nky_buffer_overflow = -19,
+    nky_buffer_underflow = -20,
+    nky_bad_encoding = -21,
+    nky_cursor_out_of_range = -22,
+    nky_limit_exceeded = -23
+} oinky_error;
+
+const char *convert_oinky_error(oinky_error err);
+
+//  This is the structure that represents the datetime in a way the client can
+//  understand it, as opposed to the opaque int64 type with which we represent
+//  it in storage.
+struct nky_datetime_unpacked {
+    int32_t years_since_1900;
+    uint8_t months_since_january;
+    uint8_t days_since_first_of_month;
+    uint8_t hours_since_midnight;
+    uint8_t minutes_since_hour;
+    uint8_t seconds_since_minute;
+    uint32_t microseconds_since_second;
+};
+
+oinky_error nky_pack_datetime(oinky_datetime_t *dt, nky_datetime_unpacked unpacked);
+oinky_error nky_unpack_datetime(oinky_datetime_t dt, nky_datetime_unpacked *unpacked);
+
+//##############
+//  Managing DB instances
+
+//  Allocate a new, empty DB instance.  This must be freed with oinky_db_free.
+//  Returns NULL on error.
+oinky_db_handle_t *oinky_db_new();
+
+//  Create a new DB instance from serialized bytes.  The new handle will 
+//  continue to access the given buffer until it is destroyed and the caller
+//  should manage the lifetimes of both the DB handle and bytestring appropriately.
+oinky_error oinky_db_mount(oinky_db_handle_t **handle, size_t bufferlen, const char *bytes);
+
+//  Destroy and deallocate an oinky DB instance.
+void oinky_db_free(oinky_db_handle_t *db);
+
+//  Compute the number of bytes required to serialize the given database.
+oinky_error oinky_db_prepare_pack(oinky_db_handle_t *db, size_t *required_bytes);
+//  Serialize the database to the given buffer.
+oinky_error oinky_db_complete_pack(oinky_db_handle_t *db, size_t bufferlen, char *buffer);
+
+//  Create a savepoint and save the marker at the given address.
+oinky_error oinky_db_create_savepoint(oinky_db_handle_t *db, oinky_savepoint_t *sp);
+oinky_error oinky_db_savepoint_rollback(oinky_db_handle_t *db, oinky_savepoint_t sp);
+
+//##############
+//  Stats/Properties
+
+int oinky_db_is_modified_since(oinky_db_handle_t *db, oinky_savepoint_t sp);
+size_t oinky_table_count(oinky_db_handle_t *db);
+size_t oinky_tbl_column_count(oinky_table_handle_t *table);
+size_t oinky_idx_column_count(oinky_index_handle_t *index);
+size_t oinky_tbl_index_count(oinky_table_handle_t *table);
+size_t oinky_tbl_row_count(oinky_table_handle_t *table);
+size_t oinky_idx_row_count(oinky_index_handle_t *index);
+oinky_db_string oinky_table_name(oinky_table_handle_t *table);
+oinky_db_string oinky_index_name(oinky_index_handle_t *index);
+
+
+//##############
+//  Navigating the DB hierarchy
+//
+//  These really shouldn't be necessary.  Unlike the C++ API, which is designed
+//  for usability, this interface should be minimal.
+//
+//oinky_db_handle_t *oinky_db_from_table_handle(oinky_table_handle_t *table);
+//oinky_table_handle_t *oinky_table_from_index_handle(oinky_index_handle_t *index);
+//oinky_table_handle_t *oinky_table_from_column_handle(oinky_column_handle_t *column);
+//oinky_index_handle_t *oinky_index_from_cursor(oinky_index_row_cursor_t *cursor);
+
+
+
+//##############
+//  Enumerating objects
+
+//  These methods do not allocate.  The caller should invoke one of the counting
+//  routines above to determine how many handles there are, and then allocate
+//  an array to receive the handles, and then pass it to one of these routines
+//  which will fill the array with pointers.
+//
+//  Both routines return the number of handles saved.  If the array is not big
+//  enough to receive all the handles, only the first <array_size> handles
+//  are returned.  Enumeration always starts at the first handle.  To retrieve
+//  the last handle, an array must be supplied which is large enough to receive
+//  all handles.
+//
+//  Tables and indices are enumerated in order by name.
+size_t oinky_db_get_table_handles(oinky_db_handle_t *db, oinky_table_handle_t **handle_array, size_t array_size);
+size_t oinky_table_get_index_handles(oinky_table_handle_t *table, oinky_index_handle_t **handle_array, size_t array_size);
+size_t oinky_table_get_column_defs(oinky_table_handle_t *table, oinky_column_def *def_array, size_t array_size);
+oinky_error oinky_index_get_definition(oinky_index_handle_t *index, oinky_db_string *name, char *is_unique, oinky_index_column_def *def_array, size_t array_size);
+
+//##############
+//  Schema Modification
+oinky_error oinky_db_create_table(oinky_db_handle_t *db, const char *name, oinky_table_handle_t **handle);
+oinky_error oinky_db_drop_table(oinky_db_handle_t *db, oinky_db_string tblname);
+oinky_error oinky_table_add_column(oinky_table_handle_t *table, oinky_column_def defn);
+oinky_error oinky_table_drop_column(oinky_table_handle_t *table, oinky_db_string colname);
+oinky_error oinky_table_drop_index(oinky_table_handle_t *table, oinky_db_string idxname);
+
+oinky_error oinky_table_add_index(
+    oinky_table_handle_t *table, 
+    const char *idxname, 
+    char unique, 
+    size_t col_count, 
+    const oinky_index_column_def *coldefs, 
+    oinky_index_handle_t **ih);
+
+//##############
+//  Data Access
+
+oinky_error oinky_table_make_column_selector(oinky_table_handle_t *table, size_t col_count, char **colnames, oinky_column_selector_t **selector);
+oinky_error oinky_table_delete_column_selector(oinky_table_handle_t *table, oinky_column_selector_t *selector);
+
+//  Update the columns (identified by column_selector) at the row (identified by cursor) with the given values.
+oinky_error oinky_table_update_row_at_index_cursor(oinky_table_handle_t *table, oinky_index_row_cursor_t *cursor, oinky_column_selector_t *selector, size_t col_count, const oinky_db_variant *values);
+oinky_error oinky_table_update_row_at_table_cursor(oinky_table_handle_t *table, oinky_table_row_cursor_t *cursor, oinky_column_selector_t *selector, size_t col_count, const oinky_db_variant *values);
+
+//  Delete the row identified by the cursor.
+oinky_error oinky_table_delete_row_at_index_cursor(oinky_table_handle_t *table, oinky_index_row_cursor_t *cursor);
+oinky_error oinky_table_delete_row_at_table_cursor(oinky_table_handle_t *table, oinky_table_row_cursor_t *cursor);
+
+oinky_error oinky_table_insert_row(oinky_table_handle_t *table, oinky_column_selector_t *selector, size_t col_count, const oinky_db_variant *values);
+
+//##############
+//  Index cursors
+
+//  Create a cursor at the beginning of the index.
+oinky_error oinky_index_cursor_new(oinky_index_handle_t *index, oinky_index_row_cursor_t **crs);
+oinky_error oinky_index_cursor_clone(oinky_index_handle_t *index, oinky_index_row_cursor_t *src, oinky_index_row_cursor_t **newcrs);
+void oinky_index_cursor_free(oinky_index_handle_t *index, oinky_index_row_cursor_t *crs);
+oinky_error oinky_index_cursor_get_values(oinky_index_row_cursor_t *crs, oinky_column_selector_t *selector, size_t vcount, oinky_db_variant *out_values, size_t *out_value_count);
+
+oinky_error oinky_index_cursor_seek_last(oinky_index_handle_t *index, oinky_index_row_cursor_t *crs);
+oinky_error oinky_index_cursor_seek_first(oinky_index_handle_t *index, oinky_index_row_cursor_t *crs);
+
+//  Moves the given cursor to a position in the index defined by the given set of values.
+//    lower_bound and upper_bound are equivalent to their STL meanings.
+oinky_error oinky_index_cursor_seek_lower_bound(oinky_index_handle_t *index, oinky_index_row_cursor_t *crs, size_t seq_len, const oinky_db_variant *value_seq);
+oinky_error oinky_index_cursor_seek_upper_bound(oinky_index_handle_t *index, oinky_index_row_cursor_t *crs, size_t seq_len, const oinky_db_variant *value_seq);
+//  If found, returns success and sets cursor to element.  If not found, 
+//  return ObjectNotFound and sets cursor to end (state == 1).  Analogous
+//  to STL find.
+oinky_error oinky_index_cursor_seek_exact(oinky_index_handle_t *index, oinky_index_row_cursor_t *crs, size_t seq_len, const oinky_db_variant *value_seq);
+//  increment/decrement
+oinky_error oinky_index_cursor_seek_next(oinky_index_handle_t *index, oinky_index_row_cursor_t *crs);
+oinky_error oinky_index_cursor_seek_prev(oinky_index_handle_t *index, oinky_index_row_cursor_t *crs);
+
+//  Returns -1 if cursor is before beginning of sequence,
+//  0 if it is on a valid element,
+//  and 1 if it is beyond the end of the sequence.
+int8_t oinky_index_cursor_state(oinky_index_handle_t *index, oinky_index_row_cursor_t *crs);
+
+//##############
+//  Table cursors
+
+//  Create a cursor at the beginning of the table.
+oinky_error oinky_table_cursor_new(oinky_table_handle_t *table, oinky_table_row_cursor_t **crs);
+oinky_error oinky_table_cursor_clone(oinky_table_handle_t *table, oinky_table_row_cursor_t *src, oinky_table_row_cursor_t **newcrs);
+void oinky_table_cursor_free(oinky_table_handle_t *table, oinky_table_row_cursor_t *crs);
+oinky_error oinky_table_cursor_get_values(oinky_table_row_cursor_t *crs, oinky_column_selector_t *selector, size_t vcount, oinky_db_variant *out_values, size_t *out_value_count);
+
+oinky_error oinky_table_cursor_seek_last(oinky_table_handle_t *table, oinky_table_row_cursor_t *crs);
+oinky_error oinky_table_cursor_seek_first(oinky_table_handle_t *table, oinky_table_row_cursor_t *crs);
+
+//  increment/decrement
+oinky_error oinky_table_cursor_seek_next(oinky_table_handle_t *table, oinky_table_row_cursor_t *crs);
+oinky_error oinky_table_cursor_seek_prev(oinky_table_handle_t *table, oinky_table_row_cursor_t *crs);
+
+//  Returns -1 if cursor is before beginning of sequence,
+//  0 if it is on a valid element,
+//  and 1 if it is beyond the end of the sequence.
+int8_t oinky_table_cursor_state(oinky_table_handle_t *table, oinky_table_row_cursor_t *crs);
+
+
+//uint32 oinky_get_column_handles(oinky_table_handle_t **handle_array, unsigned array_size);
+/*
+//  Invoke the callback with a handle for each table.  Enumeration stops when
+//  the callback returns false, or the set of tables is exhausted.
+//  Tables are enumerated in order by name.
+typedef bool (oinky_each_table_cb*)(oinky_db_handle_t *db, oinky_table_handle_t *table, void *cb_ctx);
+void oinky_enum_tables(oinky_db_handle_t *db, oinky_each_table_cb cb, void *cb_ctx);
+
+//  Invoke the callback with a handle for each index.  Same semantics as
+//  table enumeration
+typedef bool (oinky_each_index_cb*)(oinky_table_handle_t *db, oinky_index_handle_t *index, void *cb_ctx);
+void oinky_enum_indices(oinky_table_handle_t *db, oinky_each_index_cb cb, void *cb_ctx);
+
+//  Invoke the callback with a handle for each column.  Same semantics as
+//  table enumeration
+typedef bool (oinky_each_column_cb*)(oinky_table_handle_t *db, oinky_column_handle_t *column, void *cb_ctx);
+void oinky_enum_columns(oinky_table_handle_t *db, oinky_each_column_cb cb, void *cb_ctx);
+*/
+
+//  Test support
+void oinky_debug_break();
+
+#ifdef __cplusplus
+} //extern "C" {
+#endif
+
+//#ifndef OINKY_H_INCLUDED
+#endif
+