lmdb 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1e16a42693e5150e076829337a0d44feb46bc3f3
-  data.tar.gz: ce0bc77de0cf3c7e17df2522c8eab69e760e1221
+  metadata.gz: 92f31229585bce51aaa1f94fab800c5f98488869
+  data.tar.gz: e57e72dac8a031aeb3163c917252160b2c3c21c2
 SHA512:
-  metadata.gz: e02924de6a59386ec215b45baf321a6d098d818900f7816a3805185ab5b7441427cc5af866d2d8141eecfd1d166a659ebc2a87d5ae7626a9a574bd4d1bd4bf44
-  data.tar.gz: 3ee55c5879fd385e53d25eeffd694dab0de03c5b152fe07562f9b631de25ccd90f09ae886a1d30b7f9abd6ea3a8da3fedac0b1f9d69dbffc3874bfad18570dd9
+  metadata.gz: c7fe9fba9eae7efe4c0a15387906dd006e7f1f9659b8df9b8d7459386e9ea833df4b32e3df8d131d060299d6e948212d26dca9cb2b593d3f9106d55530b4c1b8
+  data.tar.gz: fc1108b3f94451fd44b29b9f37a30d0cd6641c8c5193552751f970ed46b67f91da32a7da3b044d4443371e515d781b537f6cc2df975169ea1beb6e50bc338514

data/.gitignore

@@ -6,3 +6,5 @@
 Makefile
 tmp/
 Gemfile.lock
+doc/
+.yardoc/

data/CHANGES

@@ -1,3 +1,7 @@
+0.4.1
+
+  * Fix #10
+
 0.4.0
 
   * Print warnings if open LMDB objects are found during garbage collection

data/CONTRIBUTORS

@@ -1,3 +1,6 @@
 Daniel Mendler <mail@daniel-mendler.de>
 Dimitrij Denissenko <dimitrij.denissenko@blacksquaremedia.com>
 Evgeniy Dolzhenko <evgeniy.dolzhenko@blacksquaremedia.com>
+Julien Ammous <schmurfy@gmail.com>
+Nathaniel Pierce <nwpierce@gmail.com>
+Richard Golding <golding@chrysaetos.org>

data/README.md

@@ -6,7 +6,7 @@
 Ruby bindings for the amazing OpenLDAP's Lightning Memory-Mapped Database (LMDB)
 http://symas.com/mdb/
 
-### Installation
+## Installation
 
 Install via rubygems:
 
@@ -14,9 +14,18 @@ Install via rubygems:
 gem install lmdb
 ```
 
-### API
+## Links
 
-~~~ ruby
+* Source: <http://github.com/minad/lmdb>
+* Bugs:   <http://github.com/minad/lmdb/issues>
+* Tests and benchmarks: <http://travis-ci.org/minad/lmdb>
+* API documentation:
+    * Latest Gem: <http://rubydoc.info/gems/lmdb/frames>
+    * GitHub master: <http://rubydoc.info/github/minad/lmdb/master/frames>
+
+## API
+
+```ruby
 require 'lmdb'
 
 env = LMDB.new(path)
@@ -32,13 +41,11 @@ env.transaction do
 end
 
 env.close
-~~~
+```
 
-For details take a look at the specs. If you want to have a simpler interface
-to LMDB databases please consider using [Moneta](https://github.com/minad/moneta).
-The Moneta gem provides an LMDB adapter which uses this gem.
+If you want to have a simpler interface to LMDB databases please consider using [Moneta](https://github.com/minad/moneta). The Moneta gem provides an LMDB adapter which uses this gem.
 
-### Licence (MIT)
+## Licence (MIT)
 
 ```
 Copyright (c) 2013 Daniel Mendler

data/ext/lmdb_ext/extconf.rb

@@ -5,6 +5,7 @@ $CFLAGS = '-std=c99 -Wall -g'
 # Embed lmdb if we cannot find it
 if enable_config("bundled-lmdb", false) || !(find_header('lmdb.h') && have_library('lmdb', 'mdb_env_create'))
   $INCFLAGS << " -I$(srcdir)/liblmdb"
+  $VPATH ||= []
   $VPATH << "$(srcdir)/liblmdb"
   $srcs = Dir.glob("#{$srcdir}/{,liblmdb/}*.c").map {|n| File.basename(n) }
 end

data/ext/lmdb_ext/lmdb_ext.c

@@ -29,11 +29,58 @@ static void transaction_mark(Transaction* transaction) {
         rb_gc_mark(transaction->env);
 }
 
+/**
+ * Commit a transaction in process.  Any subtransactions of this
+ * transaction will be committed as well.
+ *
+ * One does not normally need to call commit explicitly; a
+ * commit is performed automatically when the block supplied to
+ * {Environment#transaction} exits normally.
+ *
+ * @note After committing a transaction, no further database operations
+ *    should be done in the block.  Any cursors created in the context
+ *    of the transaction will no longer be valid.
+ *
+ * @example Single transaction
+ *    env.transaction do |txn|
+ *      # ... modify the databases ...
+ *      txn.commit
+ *    end
+ *
+ * @example Child transactions
+ *    env.transaction do |txn1|
+ *      env.transaction.do |txn2|
+ *         txn1.commit      # txn1 and txn2 are both committed
+ *      end
+ *    end
+ */
 static VALUE transaction_commit(VALUE self) {
         transaction_finish(self, 1);
         return Qnil;
 }
 
+/**
+ * Abort a transaction in process. Any subtransactions of this
+ * transaction will be aborted as well.
+ *
+ * @note After aborting a transaction, no further database operations
+ *    should be done in the block.  Any cursors created in the context
+ *    of the transaction will no longer be valid.
+ *
+ * @example Single transaction
+ *    env.transaction do |txn|
+ *      # ... modify the databases ...
+ *      txn.abort
+ *      # modifications are rolled back
+ *    end
+ *
+ * @example Child transactions
+ *    env.transaction do |txn1|
+ *      env.transaction.do |txn2|
+ *         txn1.abort      # txn1 and txn2 are both aborted
+ *      end
+ *    end
+ */
 static VALUE transaction_abort(VALUE self) {
         transaction_finish(self, 0);
         return Qnil;
@@ -140,6 +187,15 @@ static void environment_mark(Environment* environment) {
         rb_gc_mark(environment->txn_thread_hash);
 }
 
+/**
+ * @overload close
+ *   Close an environment, completing all IOs and cleaning up database
+ *   state if needed.
+ *   @example
+ *      env = LMDB.new('abc')
+ *      # ...various operations on the environment...
+ *      env.close
+ */
 static VALUE environment_close(VALUE self) {
         ENVIRONMENT(self, environment);
         mdb_env_close(environment->env);
@@ -162,6 +218,17 @@ static VALUE stat2hash(const MDB_stat* stat) {
         return ret;
 }
 
+/**
+ * @overload stat
+ *   Return useful statistics about an environment.
+ *   @return [Hash] the statistics
+ *   * +:psize+ Size of a database page
+ *   * +:depth+ Depth (height) of the B-tree
+ *   * +:branch_pages+ Number of internal (non-leaf) pages
+ *   * +:leaf_pages+ Number of leaf pages
+ *   * +:overflow_pages+ Number of overflow pages
+ *   * +:entries+ Number of data items
+ */
 static VALUE environment_stat(VALUE self) {
         ENVIRONMENT(self, environment);
         MDB_stat stat;
@@ -169,6 +236,17 @@ static VALUE environment_stat(VALUE self) {
         return stat2hash(&stat);
 }
 
+/**
+ * @overload info
+ *   Return useful information about an environment.
+ *   @return [Hash]
+ *   * +:mapaddr+ The memory address at which the database is mapped, if fixed
+ *   * +:mapsize+ The size of the data memory map
+ *   * +:last_pgno+ ID of the last used page
+ *   * +:last_txnid+ ID of the last committed transaction
+ *   * +:maxreaders+ Max reader slots in the environment
+ *   * +:numreaders+ Max readers slots in the environment
+ */
 static VALUE environment_info(VALUE self) {
         MDB_envinfo info;
 
@@ -189,12 +267,37 @@ static VALUE environment_info(VALUE self) {
         return ret;
 }
 
+/**
+ * @overload copy(path)
+ *   Create a copy (snapshot) of an environment.  The copy can be used
+ *   as a backup.  The copy internally uses a read-only transaction to
+ *   ensure that the copied data is serialized with respect to database
+ *   updates.
+ *   @param [String] path The directory in which the copy will
+ *       reside. This directory must already exist and be writable but
+ *       must otherwise be empty.
+ *   @return nil
+ *   @raise [Error] when there is an error creating the copy.
+ */
 static VALUE environment_copy(VALUE self, VALUE path) {
         ENVIRONMENT(self, environment);
         check(mdb_env_copy(environment->env, StringValueCStr(path)));
         return Qnil;
 }
 
+/**
+ * @overload sync(force)
+ *   Flush the data buffers to disk.
+ *
+ *   Data is always written to disk when {Transaction#commit} is called, but
+ *   the operating system may keep it buffered. MDB always flushes the
+ *   OS buffers upon commit as well, unless the environment was opened
+ *   with +:nosync+ or in part +:nometasync+.
+ *   @param [Boolean] force If true, force a synchronous
+ *     flush. Otherwise if the environment has the +:nosync+ flag set
+ *     the flushes will be omitted, and with +:mapasync+ they will be
+ *     asynchronous.
+ */
 static VALUE environment_sync(int argc, VALUE *argv, VALUE self) {
         ENVIRONMENT(self, environment);
 
@@ -229,6 +332,40 @@ static int environment_options(VALUE key, VALUE value, EnvironmentOptions* optio
         return 0;
 }
 
+/**
+ * @overload new(path, opts)
+ *   Open an LMDB database environment.
+ *   The database environment is the root object for all operations on
+ *   a collection of databases.  It has to be opened first, before
+ *   individual databases can be opened or created in the environment.
+ *   The database should be closed when it is no longer needed.
+ *
+ *   The options hash on this method includes all the flags listed in
+ *   {Environment#flags} as well as the options documented here.
+ *   @return [Environment]
+ *   @param [String] path the path to the files containing the database
+ *   @param [Hash] opts options for the database environment
+ *   @option opts [Number] :mode The Posix permissions to set on created files.
+ *   @option opts [Number] :maxreaders The maximum number of concurrent threads
+ *       that can be executing transactions at once.  Default is 126.
+ *   @option opts [Number] :maxdbs The maximum number of named databases in the
+ *       environment.  Not needed if only one database is being used.
+ *   @option opts [Number] :mapsize The size of the memory map to be allocated
+ *       for this environment, in bytes.  The memory map size is the
+ *       maximum total size of the database.  The size should be a
+ *       multiple of the OS page size.  The default size is about
+ *       10MiB.
+ *   @yield [env] The block to be executed with the environment. The environment is closed afterwards.
+ *   @yieldparam env [Environment] The environment
+ *   @see #close
+ *   @see Environment#flags
+ *   @example Open environment and pass options
+ *      env = LMDB.new "dbdir", :maxdbs => 30, :mapasync => true, :writemap => true
+ *   @example Pass environment to block
+ *      LMDB.new "dbdir" do |env|
+ *        # ...
+ *      end
+ */
 static VALUE environment_new(int argc, VALUE *argv, VALUE klass) {
         VALUE path, option_hash;
         rb_scan_args(argc, argv, "1:", &path, &option_hash);
@@ -266,6 +403,23 @@ static VALUE environment_new(int argc, VALUE *argv, VALUE klass) {
         return venv;
 }
 
+/**
+ * @overload flags
+ *   Return the flags that are set in this environment.
+ *   @return [Array] Array of flag symbols
+ *   The environment flags are:
+ *   * +:fixedmap+ Use a fixed address for the mmap region.
+ *   * +:nosubdir+ By default, MDB creates its environment in a directory whose pathname is given in +path+, and creates its data and lock files under that directory. With this option, path is used as-is for the database main data file. The database lock file is the path with "-lock" appended.
+ *   * +:nosync+ Don't flush system buffers to disk when committing a transaction. This optimization means a system crash can corrupt the database or lose the last transactions if buffers are not yet flushed to disk. The risk is governed by how often the system flushes dirty buffers to disk and how often {Environment#sync} is called. However, if the filesystem preserves write order and the +:writemap+ flag is not used, transactions exhibit ACI (atomicity, consistency, isolation) properties and only lose D (durability). That is, database integrity is maintained, but a system crash may undo the final transactions. Note that +:nosync + :writemap+ leaves the system with no hint for when to write transactions to disk, unless {Environment#sync} is called. +:mapasync + :writemap+ may be preferable.
+ *   * +:rdonly+ Open the environment in read-only mode. No write operations will be allowed. MDB will still modify the lock file - except on read-only filesystems, where MDB does not use locks.
+ *   * +:nometasync+ Flush system buffers to disk only once per transaction, omit the metadata flush. Defer that until the system flushes files to disk, or next  non-MDB_RDONLY commit or {Environment#sync}. This optimization maintains database integrity, but a system crash may undo the last committed transaction. That is, it preserves the ACI (atomicity, consistency, isolation) but not D (durability) database property.
+ *   * +:writemap+ Use a writeable memory map unless +:rdonly+ is set. This is faster and uses fewer mallocs, but loses protection from application bugs like wild pointer writes and other bad updates into the database. Incompatible with nested transactions.
+ *   * +:mapasync+ When using +:writemap+, use asynchronous flushes to disk. As with +:nosync+, a system crash can then corrupt the database or lose the last transactions. Calling {Environment#sync} ensures on-disk database integrity until next commit.
+ *   * +:notls+ Don't use thread-local storage.
+ *   @example
+ *       env = LMDB.new "abc", :writemap => true, :nometasync => true
+ *       env.flags           #=> [:writemap, :nometasync]
+ */
 static VALUE environment_flags(VALUE self) {
         unsigned int flags;
         ENVIRONMENT(self, environment);
@@ -279,6 +433,11 @@ static VALUE environment_flags(VALUE self) {
         return ret;
 }
 
+/**
+ * @overload path
+ *   Return the path to the database environment files
+ *   @return [String] the path that was used to open the environment.
+ */
 static VALUE environment_path(VALUE self) {
         const char* path;
         ENVIRONMENT(self, environment);
@@ -303,16 +462,45 @@ static VALUE environment_change_flags(int argc, VALUE* argv, VALUE self, int set
         return Qnil;
 }
 
+/**
+ * @overload set_flags(flags)
+ *   Set one or more flags in the environment. The available flags are defined in {Environment#flags}.
+ *   @see Environment#flags
+ *   @param [Array] flags Array of flag names (symbols) to set
+ *   @return nil
+ *   @raise [Error] if an invalid flag name is specified
+ *   @example
+ *    env.set_flags :nosync, :writemap
+ */
 static VALUE environment_set_flags(int argc, VALUE* argv, VALUE self) {
         environment_change_flags(argc, argv, self, 1);
         return Qnil;
 }
 
+/**
+ * @overload clear_flags(flags)
+ *   Clear one or more flags in the environment. The available flags are defined in {Environment#flags}.
+ *   @see Environment#flags
+ *   @param [Array] flags Array of flag names (symbols) to clear
+ *   @return nil
+ *   @raise [Error] if an invalid flag name is specified
+ *   @example
+ *     env.clear_flags :nosync, :writemap
+ */
 static VALUE environment_clear_flags(int argc, VALUE* argv, VALUE self) {
         environment_change_flags(argc, argv, self, 0);
         return Qnil;
 }
 
+/**
+ * @overload active_txn
+ *   @return [Transaction] the current active transaction on this thread in the environment.
+ *   @example
+ *      env.transaction do |t|
+ *        active = env.active_txn
+ *        # active should equal t
+ *      end
+ */
 static VALUE environment_active_txn(VALUE self) {
         ENVIRONMENT(self, environment);
         return rb_hash_aref(environment->thread_txn_hash, rb_thread_current());
@@ -353,6 +541,34 @@ static MDB_txn* need_txn(VALUE self) {
         return txn;
 }
 
+/**
+ * @overload transaction(readonly)
+ *   Begin a transaction.  Takes a block to run the body of the
+ *   transaction.  A transaction commits when it exits the block successfully.
+ *   A transaction aborts when it raises an exception or calls
+ *   {Transaction#abort}.
+ *   @param [Boolean] readonly This transaction will not perform any
+ *      write operations
+ *   @note Transactions can be nested.
+ *   @yield [txn] The block to be executed with the body of the transaction.
+ *   @yieldparam txn [Transaction] An optional transaction argument
+ *   @example
+ *      db = env.database "mydata"
+ *      env.transaction do |txn1|
+ *        db['a'] = 1
+ *        env.transaction do |txn2|
+ *          # txn2 is nested in txn1
+ *          db['a'] = 2
+ *          db['a']                    #=> 2
+ *          txn2.abort
+ *        end
+ *        db['a']                      #=> 1
+ *        env.transaction do
+ *          db['a'] = 3
+ *        end
+ *      end
+ *      db['a']                        #=> 3
+ */
 static VALUE environment_transaction(int argc, VALUE *argv, VALUE self) {
         rb_need_block();
 
@@ -373,6 +589,43 @@ static void database_mark(Database* database) {
 #undef METHOD
 #undef FILE
 
+/**
+ * @overload database(name, options)
+ *   Opens a database within the environment.
+ *
+ *   Note that a database is opened or created within a transaction.  If
+ *   the open creates a new database, the database is not available for
+ *   other operations in other transactions until the transaction that
+ *   is creating the database commits.  If the transaction creating the
+ *   database aborts, the database is not created.
+ *   @return [Database] newly-opened database
+ *   @raise [Error] if there is an error opening the database
+ *   @param [String] name Optional name for the database to be opened.
+ *   @param [Hash] options Options for the database.
+ *   @option options [Boolean] :reversekey Keys are strings to be
+ *       compared in reverse order, from the end of the strings to the
+ *       beginning. By default, Keys are treated as strings and
+ *       compared from beginning to end.
+ *   @option options [Boolean] :dupsort Duplicate keys may be used in
+ *       the database. (Or, from another perspective, keys may have
+ *       multiple data items, stored in sorted order.) By default keys
+ *       must be unique and may have only a single data item.
+ *   @option options [Boolean] :integerkey Keys are binary integers in
+ *       native byte order.
+ *   @option options [Boolean] :dupfixed This flag may only be used in
+ *       combination with +:dupsort+. This option tells the library
+ *       that the data items for this database are all the same size,
+ *       which allows further optimizations in storage and retrieval.
+ *   @option options [Boolean] :integerdup This option specifies that
+ *       duplicate data items are also integers, and should be sorted
+ *       as such.
+ *   @option options [Boolean] :reversedup This option specifies that
+ *       duplicate data items should be compared as strings in reverse
+ *       order.
+ *   @option options [Boolean] :create Create the named database if it
+ *       doesn't exist. This option is not allowed in a read-only
+ *       transaction or a read-only environment.
+ */
 static VALUE environment_database(int argc, VALUE *argv, VALUE self) {
         ENVIRONMENT(self, environment);
         if (!active_txn(self))
@@ -396,6 +649,17 @@ static VALUE environment_database(int argc, VALUE *argv, VALUE self) {
         return vdb;
 }
 
+/**
+ * @overload stat
+ *   Return useful statistics about a database.
+ *   @return [Hash] the statistics
+ *   * +:psize+ Size of a database page
+ *   * +:depth+ Depth (height) of the B-tree
+ *   * +:branch_pages+ Number of internal (non-leaf) pages
+ *   * +:leaf_pages+ Number of leaf pages
+ *   * +:overflow_pages+ Number of overflow pages
+ *   * +:entries+ Number of data items
+ */
 static VALUE database_stat(VALUE self) {
         DATABASE(self, database);
         if (!active_txn(database->env))
@@ -406,6 +670,12 @@ static VALUE database_stat(VALUE self) {
         return stat2hash(&stat);
 }
 
+/**
+ * @overload drop
+ *   Remove a database from the environment.
+ *   @return nil
+ *   @note The drop happens transactionally.
+ */
 static VALUE database_drop(VALUE self) {
         DATABASE(self, database);
         if (!active_txn(database->env))
@@ -414,6 +684,12 @@ static VALUE database_drop(VALUE self) {
         return Qnil;
 }
 
+/**
+ * @overload clear
+ *    Empty out the database
+ *    @return nil
+ *    @note The clear happens transactionally.
+ */
 static VALUE database_clear(VALUE self) {
         DATABASE(self, database);
         if (!active_txn(database->env))
@@ -422,6 +698,15 @@ static VALUE database_clear(VALUE self) {
         return Qnil;
 }
 
+/**
+ * @overload get(key)
+ *   Retrieves one value associated with this key.
+ *   This function retrieves key/data pairs from the database.  If the
+ *   database supports duplicate keys (+:dupsort+) then the first data
+ *   item for the key will be returned. Retrieval of other items
+ *   requires the use of {#cursor}.
+ *   @param key The key of the record to retrieve.
+ */
 static VALUE database_get(VALUE self, VALUE vkey) {
         DATABASE(self, database);
         if (!active_txn(database->env))
@@ -445,6 +730,33 @@ static VALUE database_get(VALUE self, VALUE vkey) {
 #undef METHOD
 #undef FILE
 
+/**
+ * @overload put(key, value, options)
+ *   Stores items into a database.
+ *   This function stores key/value pairs in the database. The default
+ *   behavior is to enter the new key/value pair, replacing any
+ *   previously existing key if duplicates are disallowed, or adding a
+ *   duplicate data item if duplicates are allowed (+:dupsort+).
+ *   @param key The key of the record to set
+ *   @param value The value to insert for this key
+ *   @option options [Boolean] :nodupdata Enter the new key/value
+ *       pair only if it does not already appear in the database. This
+ *       flag may only be specified if the database was opened with
+ *       +:dupsort+. The function will raise an {Error} if the
+ *       key/data pair already appears in the database.
+ *   @option options [Boolean] :nooverwrite Enter the new key/value
+ *       pair only if the key does not already appear in the
+ *       database. The function will raise an {Error] if the key
+ *       already appears in the database, even if the database
+ *       supports duplicates (+:dupsort+).
+ *   @option options [Boolean] :append Append the given key/data pair
+ *       to the end of the database. No key comparisons are
+ *       performed. This option allows fast bulk loading when keys are
+ *       already known to be in the correct order. Loading unsorted
+ *       keys with this flag will cause data corruption.
+ *   @option options [Boolean] :appenddup As above, but for sorted dup
+ *       data.
+ */
 static VALUE database_put(int argc, VALUE *argv, VALUE self) {
         DATABASE(self, database);
         if (!active_txn(database->env))
@@ -470,6 +782,21 @@ static VALUE database_put(int argc, VALUE *argv, VALUE self) {
         return Qnil;
 }
 
+/**
+ * @overload delete(key, value=nil)
+ *
+ * Deletes records from the database.  This function removes
+ * key/data pairs from the database. If the database does not support
+ * sorted duplicate data items (+:dupsort+) the value parameter is
+ * ignored. If the database supports sorted duplicates and the value
+ * parameter is +nil+, all of the duplicate data items for the key will
+ * be deleted. Otherwise, if the data parameter is non-nil only the
+ * matching data item will be deleted.
+ *
+ * @param key The key of the record to delete.
+ * @param value The optional value of the record to delete.
+ * @raise [Error] if the specified key/value pair is not in the database.
+ */
 static VALUE database_delete(int argc, VALUE *argv, VALUE self) {
         DATABASE(self, database);
         if (!active_txn(database->env))
@@ -515,6 +842,10 @@ static void cursor_mark(Cursor* cursor) {
         rb_gc_mark(cursor->db);
 }
 
+/**
+ * @overload close
+ *  Close a cursor.  The cursor must not be used again after this call.
+ */
 static VALUE cursor_close(VALUE self) {
         CURSOR(self, cursor);
         mdb_cursor_close(cursor->cur);
@@ -522,6 +853,20 @@ static VALUE cursor_close(VALUE self) {
         return Qnil;
 }
 
+/**
+ * @overload cursor
+ *   Create a cursor to iterate through a database.
+ *
+ *   @see Cursor
+ *   @yield [cursor] A block to be executed with the cursor
+ *   @yieldparam cursor [Cursor] The cursor to be used to iterate
+ *   @example
+ *    db = env.database "abc"
+ *    db.cursor do |c|
+ *      key, value = c.next
+ *      puts "#{key}: #{value}"
+ *    end
+ */
 static VALUE database_cursor(VALUE self) {
         DATABASE(self, database);
         if (!active_txn(database->env))
@@ -549,6 +894,13 @@ static VALUE database_cursor(VALUE self) {
         return vcur;
 }
 
+/**
+ * @overload first
+ *    Position the cursor to the first record in the database, and
+ *    return its value.
+ *    @return [Array,nil] The [key, value] pair for the first record, or
+ *        nil if no record
+ */
 static VALUE cursor_first(VALUE self) {
         CURSOR(self, cursor);
         MDB_val key, value;
@@ -557,6 +909,13 @@ static VALUE cursor_first(VALUE self) {
         return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size));
 }
 
+/**
+ * @overload last
+ *    Position the cursor to the last record in the database, and
+ *    return its value.
+ *    @return [Array,nil] The [key, value] pair for the last record, or
+ *        nil if no record.
+ */
 static VALUE cursor_last(VALUE self) {
         CURSOR(self, cursor);
         MDB_val key, value;
@@ -565,6 +924,13 @@ static VALUE cursor_last(VALUE self) {
         return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size));
 }
 
+/**
+ * @overload prev
+ *    Position the cursor to the previous record in the database, and
+ *    return its value.
+ *    @return [Array,nil] The [key, value] pair for the previous record, or
+ *        nil if no previous record.
+ */
 static VALUE cursor_prev(VALUE self) {
         CURSOR(self, cursor);
         MDB_val key, value;
@@ -576,6 +942,13 @@ static VALUE cursor_prev(VALUE self) {
         return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size));
 }
 
+/**
+ * @overload next
+ *    Position the cursor to the next record in the database, and
+ *    return its value.
+ *    @return [Array,nil] The [key, value] pair for the next record, or
+ *        nil if no next record.
+ */
 static VALUE cursor_next(VALUE self) {
         CURSOR(self, cursor);
         MDB_val key, value;
@@ -587,6 +960,12 @@ static VALUE cursor_next(VALUE self) {
         return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size));
 }
 
+/**
+ * @overload set(key)
+ *   Set the cursor to a specified key
+ *   @param key The key to which the cursor should be positioned
+ *   @return [Array] The [key, value] pair to which the cursor now points.
+ */
 static VALUE cursor_set(VALUE self, VALUE vkey) {
         CURSOR(self, cursor);
         MDB_val key, value;
@@ -598,6 +977,12 @@ static VALUE cursor_set(VALUE self, VALUE vkey) {
         return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size));
 }
 
+/**
+ * @overload set_range(key)
+ *   Set the cursor at the first key greater than or equal to a specified key.
+ *   @param key The key to which the cursor should be positioned
+ *   @return [Array] The [key, value] pair to which the cursor now points.
+ */
 static VALUE cursor_set_range(VALUE self, VALUE vkey) {
         CURSOR(self, cursor);
         MDB_val key, value;
@@ -609,6 +994,12 @@ static VALUE cursor_set_range(VALUE self, VALUE vkey) {
         return rb_assoc_new(rb_str_new(key.mv_data, key.mv_size), rb_str_new(value.mv_data, value.mv_size));
 }
 
+/**
+ * @overload get
+ *    Return the value of the record to which the cursor points.
+ *    @return [Array] The [key, value] pair for the current record.
+ */
+
 static VALUE cursor_get(VALUE self) {
         CURSOR(self, cursor);
 
@@ -626,6 +1017,37 @@ static VALUE cursor_get(VALUE self) {
 #undef METHOD
 #undef FILE
 
+/**
+ * @overload put(key, value, options)
+ *   Store by cursor.  This function stores key/data pairs into the
+ *   database. If the function fails for any reason, the state of
+ *   the cursor will be unchanged. If the function succeeds and an
+ *   item is inserted into the database, the cursor is always
+ *   positioned to refer to the newly inserted item.
+ *   @return nil
+ *   @param key The key of the record to set
+ *   @param value The value to insert for this key
+ *   @option options [Boolean] :current Overwrite the data of the
+ *       key/data pair to which the cursor refers with the specified
+ *       data item. The +key+ parameter is ignored.
+ *   @option options [Boolean] :nodupdata Enter the new key/value
+ *       pair only if it does not already appear in the database. This
+ *       flag may only be specified if the database was opened with
+ *       +:dupsort+. The function will raise an {Error} if the
+ *       key/data pair already appears in the database.
+ *   @option options [Boolean] :nooverwrite Enter the new key/value
+ *       pair only if the key does not already appear in the
+ *       database. The function will raise an {Error] if the key
+ *       already appears in the database, even if the database
+ *       supports duplicates (+:dupsort+).
+ *   @option options [Boolean] :append Append the given key/data pair
+ *       to the end of the database. No key comparisons are
+ *       performed. This option allows fast bulk loading when keys are
+ *       already known to be in the correct order. Loading unsorted
+ *       keys with this flag will cause data corruption.
+ *   @option options [Boolean] :appenddup As above, but for sorted dup
+ *       data.
+ */
 static VALUE cursor_put(int argc, VALUE* argv, VALUE self) {
         CURSOR(self, cursor);
 
@@ -655,6 +1077,14 @@ static VALUE cursor_put(int argc, VALUE* argv, VALUE self) {
 #undef METHOD
 #undef FILE
 
+/**
+ * @overload delete(options)
+ *    Delete current key/data pair.
+ *    This function deletes the key/data pair to which the cursor refers.
+  *    @option options [Boolean] :nodupdata Delete all of the data
+ *        items for the current key. This flag may only be specified
+ *        if the database was opened with +:dupsort+.
+ */
 static VALUE cursor_delete(int argc, VALUE *argv, VALUE self) {
         CURSOR(self, cursor);
 
@@ -669,6 +1099,13 @@ static VALUE cursor_delete(int argc, VALUE *argv, VALUE self) {
         return Qnil;
 }
 
+/**
+ * @overload count
+ *    Return count of duplicates for current key.  This call is only
+ *    valid on databases that support sorted duplicate data items
+ *    +:dupsort+.
+ *    @return [Number] count of duplicates
+ */
 static VALUE cursor_count(VALUE self) {
         CURSOR(self, cursor);
         size_t count;
@@ -679,6 +1116,12 @@ static VALUE cursor_count(VALUE self) {
 void Init_lmdb_ext() {
         VALUE mLMDB;
 
+        /**
+         * Document-module: LMDB
+         *
+         * The LMDB module presents a Ruby API to the OpenLDAP Lightning Memory-mapped Database (LMDB).
+         * @see http://symas.com/mdb/
+         */
         mLMDB = rb_define_module("LMDB");
         rb_define_const(mLMDB, "LIB_VERSION", rb_str_new2(MDB_VERSION_STRING));
         rb_define_singleton_method(mLMDB, "new", environment_new, -1);
@@ -689,11 +1132,40 @@ void Init_lmdb_ext() {
         VERSION_CONST(PATCH)
 #undef VERSION_CONST
 
+        /**
+         * Document-class: LMDB::Error
+         *
+         * A general class of exceptions raised within the LMDB gem.
+         */
         cError = rb_define_class_under(mLMDB, "Error", rb_eRuntimeError);
 #define ERROR(name) cError_##name = rb_define_class_under(cError, #name, cError);
 #include "errors.h"
 #undef ERROR
 
+        /**
+         * Document-class: LMDB::Environment
+         *
+         * The Environment is the root object for all LMDB operations.
+         *
+         * An LMDB "environment" is a collection of one or more "databases"
+         * (key-value tables), along with transactions to modify those
+         * databases and cursors to iterate through them.
+         *
+         * An environment -- and its collection of databases -- is normally
+         * stored in a directory.  That directory will contain two files:
+         * * +data.mdb+: all the records in all the databases in the environment
+         * * +lock.mdb+: state of transactions that may be going on in the environment.
+         *
+         * An environment can contain multiple databases.  Each of the
+         * databases has a string name ("mydatabase", "db.3.1982").  You use
+         * the database name to open the database within the environment.
+         *
+         * @example The normal pattern for using LMDB in Ruby
+         *    env = LMDB.new "databasedir"
+         *    db = env.database "databasename"
+         *    # ... do things to the database ...
+         *    env.close
+         */
         cEnvironment = rb_define_class_under(mLMDB, "Environment", rb_cObject);
         rb_define_singleton_method(cEnvironment, "new", environment_new, -1);
         rb_define_method(cEnvironment, "database", environment_database, -1);
@@ -709,6 +1181,31 @@ void Init_lmdb_ext() {
         rb_define_method(cEnvironment, "path", environment_path, 0);
         rb_define_method(cEnvironment, "transaction", environment_transaction, -1);
 
+        /**
+         * Document-class: LMDB::Database
+         *
+         * An LMDB Database is a table of key-value pairs.  It is stored as
+         * part of the {Environment}.
+         *
+         * By default, each key in a Database maps to one value.  However, a
+         * Database can be configured at creation to allow duplicate keys, in
+         * which case one key will map to multiple values.
+         *
+         * A Database stores the keys in a sorted order.  The order can also
+         * be set with options when the database is created.
+         *
+         * The basic operations on a database are to {#put}, {#get}, and
+         * {#delete} records.  One can also iterate through the records in a
+         * database using a {Cursor}.
+         *
+         * @example Typical usage
+         *    env = LMDB.new "databasedir"
+         *    db = env.database "databasename"
+         *    db.put "key1", "value1"
+         *    db.put "key2", "value2"
+         *    db.get "key1"              #=> "value1"
+         *    env.close
+         */
         cDatabase = rb_define_class_under(mLMDB, "Database", rb_cObject);
         rb_undef_method(rb_singleton_class(cDatabase), "new");
         rb_define_method(cDatabase, "stat", database_stat, 0);
@@ -719,11 +1216,94 @@ void Init_lmdb_ext() {
         rb_define_method(cDatabase, "delete", database_delete, -1);
         rb_define_method(cDatabase, "cursor", database_cursor, 0);
 
+        /**
+         * Document-class: LMDB::Transaction
+         *
+         * The LMDB environment supports transactional reads and updates.  By
+         * default, these provide the standard ACID (atomicity, consistency,
+         * isolation, durability) behaviors.
+         *
+         * Transactions can be committed or aborted.  When a transaction is
+         * committed, all its effects take effect in the database atomically.
+         * When a transaction is aborted, none of its effects take effect.
+         *
+         * Transactions span the entire environment.  All the updates made in
+         * the course of an update transaction -- writing records across all
+         * databases, creating databases, and destroying databases -- are
+         * either completed atomically or rolled back.
+         *
+         * Transactions can be nested.  A child transaction can be started
+         * within a parent transaction.  The child transaction can commit or
+         * abort, at which point the effects of the child become visible to
+         * the parent transaction or not.  If the parent aborts, all of the
+         * changes performed in the context of the parent -- including the
+         * changes from a committed child transaction -- are rolled back.
+         *
+         * To create a transaction, call {Environment#transaction} and supply
+         * a block for the code to execute in that transaction.
+         *
+         * @example Typical usage
+         *    env = LMDB.new "databasedir"
+         *    db1 = env.database "database1"
+         *    env.transaction do |parent|
+         *      db2 = env.database "database2", :create => true
+         *                            #=> creates a new database, but it isn't
+         *                            #=> yet committed to storage
+         *      db1['x']              #=> nil
+         *      env.transaction do |child1|
+         *        db2['a'] = 'b'
+         *        db1['x'] = 'y'
+         *      end
+         *                            #=> first child transaction commits
+         *                            #=> changes are visible within the parent transaction
+         *                            #=> but are not yet permanent
+         *      db1['x']              #=> 'y'
+         *      db2['a']              #=> 'a'
+         *      env.transaction do |child2|
+         *        db2['a'] = 'def'
+         *        db1['x'] = 'ghi'
+         *        child2.abort
+         *                            #=> second child transaction aborts and rolls
+         *                            #=> back its changes
+         *      end
+         *      db1['x']              #=> 'y'
+         *      db2['a']              #=> 'a'
+         *    end
+         *                            #=> parent transaction commits and writes database2
+         *                            #=> and the updates from transaction child1 to
+         *                            #=> storage.
+         */
         cTransaction = rb_define_class_under(mLMDB, "Transaction", rb_cObject);
         rb_undef_method(rb_singleton_class(cTransaction), "new");
         rb_define_method(cTransaction, "commit", transaction_commit, 0);
         rb_define_method(cTransaction, "abort", transaction_abort, 0);
 
+        /**
+         * Document-class: LMDB::Cursor
+         *
+         * A Cursor points to records in a database, and is used to iterate
+         * through the records in the database.
+         *
+         * Cursors are created in the context of a transaction, and should
+         * only be used as long as that transaction is active.  In other words,
+         * after you {Transaction#commit} or {Transaction#abort} a transaction,
+         * the cursors created while that transaction was active are no longer
+         * usable.
+         *
+         * To create a cursor, call {Database#cursor} and pass it a block for
+         * that should be performed using the cursor.
+         *
+         * @example Typical usage
+         *    env = LMDB.new "databasedir"
+         *    db = env.database "databasename"
+         *    db.cursor do |cursor|
+         *      rl = cursor.last           #=> content of the last record
+         *      r1 = cursor.first          #=> content of the first record
+         *      r2 = cursor.next           #=> content of the second record
+         *      cursor.put "x", "y", current: true
+         *                                 #=> replaces the second record with a new value "y"
+         *    end
+         */
         cCursor = rb_define_class_under(mLMDB, "Cursor", rb_cObject);
         rb_undef_method(rb_singleton_class(cCursor), "new");
         rb_define_method(cCursor, "close", cursor_close, 0);
@@ -734,7 +1314,7 @@ void Init_lmdb_ext() {
         rb_define_method(cCursor, "prev", cursor_prev, 0);
         rb_define_method(cCursor, "set", cursor_set, 1);
         rb_define_method(cCursor, "set_range", cursor_set_range, 1);
-        rb_define_method(cCursor, "put", cursor_put, 0);
+        rb_define_method(cCursor, "put", cursor_put, -1);
         rb_define_method(cCursor, "count", cursor_count, 0);
-        rb_define_method(cCursor, "delete", cursor_delete, 0);
+        rb_define_method(cCursor, "delete", cursor_delete, -1);
 }

data/lib/lmdb/database.rb

@@ -2,6 +2,14 @@ module LMDB
   class Database
     include Enumerable
 
+    # Iterate through the records in a database
+    # @yield [i] Gives a record [key, value] to the block
+    # @yieldparam [Array] i The key, value pair for each record
+    # @example
+    #    db.each do |record|
+    #      key, value = record
+    #      puts "at #{key}: #{value}"
+    #    end
     def each
       cursor do |c|
         while i = c.next
@@ -10,15 +18,30 @@ module LMDB
       end
     end
 
+    # Retrieve the value of a record from a database
+    # @param key the record key to retrieve
+    # @return value of the record for that key, or nil if there is
+    #      no record with that key
+    # @see #get(key)
     def [](key)
       get(key)
     end
 
+    # Set (write or update) a record in a database.
+    # @param key key for the record
+    # @param value the value of the record
+    # @return returns the value of the record
+    # @see #put(key, value)
+    # @example
+    #      db['a'] = 'b'     #=> 'b'
+    #      db['b'] = 1234    #=> 1234
+    #      db['a']           #=> 'b'
     def []=(key, value)
       put(key, value)
       value
     end
 
+    # @return the number of records in this database
     def size
       stat[:entries]
     end

data/lib/lmdb/version.rb

@@ -1,3 +1,3 @@
 module LMDB
-  VERSION = '0.4.0'
+  VERSION = '0.4.1'
 end

metadata

@@ -1,55 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: lmdb
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Daniel Mendler
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-05 00:00:00.000000000 Z
+date: 2014-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake-compiler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - <=
+    - - "<="
       - !ruby/object:Gem::Version
         version: 0.8.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - <=
+    - - "<="
       - !ruby/object:Gem::Version
         version: 0.8.2
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: lmdb is a Ruby binding to OpenLDAP Lightning MDB.
@@ -59,8 +59,8 @@ extensions:
 - ext/lmdb_ext/extconf.rb
 extra_rdoc_files: []
 files:
-- .gitignore
-- .travis.yml
+- ".gitignore"
+- ".travis.yml"
 - CHANGES
 - CONTRIBUTORS
 - Gemfile
@@ -101,17 +101,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.2.0
 signing_key: 
 specification_version: 4
 summary: Ruby bindings to Lightning MDB