mdbx 0.1.0.pre.20201217111933 → 0.1.0

data/ext/mdbx_ext/mdbx_ext.c

@@ -14,12 +14,18 @@ Init_mdbx_ext()
 {
 	rmdbx_mMDBX = rb_define_module( "MDBX" );
 
-	/* The backend library version. */
 	VALUE version = rb_str_new_cstr( mdbx_version.git.describe );
+	/* The backend MDBX library version. */
 	rb_define_const( rmdbx_mMDBX, "LIBRARY_VERSION", version );
 
+	/* A generic exception class for internal Database errors. */
 	rmdbx_eDatabaseError = rb_define_class_under( rmdbx_mMDBX, "DatabaseError", rb_eRuntimeError );
-	rmdbx_eRollback      = rb_define_class_under( rmdbx_mMDBX, "Rollback", rb_eRuntimeError );
+
+	/*
+	 * Raising an MDBX::Rollback exception from within a transaction
+	 * discards all changes and closes the transaction.
+	 */
+	rmdbx_eRollback = rb_define_class_under( rmdbx_mMDBX, "Rollback", rb_eRuntimeError );
 
 	rmdbx_init_database();
 }

data/ext/mdbx_ext/mdbx_ext.h

@@ -4,9 +4,43 @@
 
 #include "mdbx.h"
 
-#ifndef MDBX_EXT_0_9_2
-#define MDBX_EXT_0_9_2
+#ifndef MDBX_EXT_0_9_3
+#define MDBX_EXT_0_9_3
 
+#define RMDBX_TXN_ROLLBACK 0
+#define RMDBX_TXN_COMMIT 1
+
+/*
+ * A struct encapsulating an instance's DB
+ * state and settings.
+ */
+struct rmdbx_db {
+	MDBX_env *env;
+	MDBX_dbi dbi;
+	MDBX_txn *txn;
+	MDBX_cursor *cursor;
+
+    struct {
+       int env_flags;
+       int mode;
+       int open;
+       int max_collections;
+       int max_readers;
+       uint64_t max_size;
+    } settings;
+
+    struct {
+       int open;
+       int retain_txn;
+    } state;
+
+	char *path;
+	char *subdb;
+};
+typedef struct rmdbx_db rmdbx_db_t;
+
+static const rb_data_type_t rmdbx_db_data;
+extern void rmdbx_free( void *db ); /* forward declaration for the allocator */
 
 /* ------------------------------------------------------------
  * Globals
@@ -23,7 +57,11 @@ extern VALUE rmdbx_eRollback;
  * ------------------------------------------------------------ */
 extern void Init_rmdbx ( void );
 extern void rmdbx_init_database ( void );
+extern void rmdbx_open_txn( rmdbx_db_t*, int );
+extern void rmdbx_close_txn( rmdbx_db_t*, int );
+
+extern VALUE rmdbx_gather_stats( rmdbx_db_t* );
 
 
-#endif /* define MDBX_EXT_0_9_2 */
+#endif /* define MDBX_EXT_0_9_3 */
 

data/ext/mdbx_ext/stats.c

@@ -0,0 +1,191 @@
+/* vim: set noet sta sw=4 ts=4 :
+ *
+ * Expose a bunch of mdbx internals to ruby.
+ * This is all largely stolen from mdbx_stat.c.
+ *
+ * Entry point is rmdbx_stats() in database.c.
+ *
+ */
+
+#include "mdbx_ext.h"
+
+
+/*
+ * Metadata specific to the mdbx build.
+ */
+void
+rmdbx_gather_build_stats( VALUE stat )
+{
+	rb_hash_aset( stat, ID2SYM(rb_intern("build_compiler")),
+			rb_str_new_cstr(mdbx_build.compiler) );
+	rb_hash_aset( stat, ID2SYM(rb_intern("build_flags")),
+			rb_str_new_cstr(mdbx_build.flags) );
+	rb_hash_aset( stat, ID2SYM(rb_intern("build_options")),
+			rb_str_new_cstr(mdbx_build.options) );
+	rb_hash_aset( stat, ID2SYM(rb_intern("build_target")),
+			rb_str_new_cstr(mdbx_build.target) );
+	return;
+}
+
+
+/*
+ * Metadata for the database file.
+ */
+void
+rmdbx_gather_datafile_stats(
+	VALUE environ,
+	MDBX_stat mstat,
+	MDBX_envinfo menvinfo )
+{
+	VALUE datafile = rb_hash_new();
+	rb_hash_aset( environ, ID2SYM(rb_intern("datafile")), datafile );
+
+	rb_hash_aset( datafile, ID2SYM(rb_intern("size_current")),
+			INT2NUM(menvinfo.mi_geo.current) );
+	rb_hash_aset( datafile, ID2SYM(rb_intern("pages")),
+			INT2NUM(menvinfo.mi_geo.current / mstat.ms_psize) );
+
+	if ( menvinfo.mi_geo.lower != menvinfo.mi_geo.upper ) {
+		rb_hash_aset( datafile, ID2SYM(rb_intern("type")),
+			rb_str_new_cstr("dynamic") );
+		rb_hash_aset( datafile, ID2SYM(rb_intern("size_lower")),
+			INT2NUM( menvinfo.mi_geo.lower ) );
+		rb_hash_aset( datafile, ID2SYM(rb_intern("size_upper")),
+			LONG2FIX( menvinfo.mi_geo.upper ) );
+		rb_hash_aset( datafile, ID2SYM(rb_intern("growth_step")),
+			INT2NUM( menvinfo.mi_geo.grow ) );
+		rb_hash_aset( datafile, ID2SYM(rb_intern("shrink_threshold")),
+			INT2NUM( menvinfo.mi_geo.shrink ) );
+	}
+	else {
+		rb_hash_aset( datafile, ID2SYM(rb_intern("type")),
+			rb_str_new_cstr("fixed") );
+	}
+
+	return;
+}
+
+
+/*
+ * Metadata for the database environment.
+ */
+void
+rmdbx_gather_environment_stats(
+	VALUE stat,
+	MDBX_stat mstat,
+	MDBX_envinfo menvinfo )
+{
+	VALUE environ  = rb_hash_new();
+	rb_hash_aset( stat, ID2SYM(rb_intern("environment")), environ );
+
+	rb_hash_aset( environ, ID2SYM(rb_intern("pagesize")),
+			INT2NUM(mstat.ms_psize) );
+	rb_hash_aset( environ, ID2SYM(rb_intern("last_txnid")),
+			INT2NUM(menvinfo.mi_recent_txnid) );
+	rb_hash_aset( environ, ID2SYM(rb_intern("last_reader_txnid")),
+			INT2NUM(menvinfo.mi_latter_reader_txnid) );
+	rb_hash_aset( environ, ID2SYM(rb_intern("max_readers")),
+			INT2NUM(menvinfo.mi_maxreaders) );
+	rb_hash_aset( environ, ID2SYM(rb_intern("readers_in_use")),
+			INT2NUM(menvinfo.mi_numreaders) );
+
+	rmdbx_gather_datafile_stats( environ, mstat, menvinfo );
+
+	return;
+}
+
+
+/*
+ * Callback iterator for pulling each reader's current state.
+ * See: https://erthink.github.io/libmdbx/group__c__statinfo.html#gad1ab5cf54d4a9f7d4c2999078920e8b0
+ *
+ */
+int
+reader_list_callback(
+	void *ctx,
+	int num,
+	int slot,
+	mdbx_pid_t pid,
+	mdbx_tid_t thread,
+	uint64_t txnid,
+	uint64_t lag,
+	size_t bytes_used,
+	size_t bytes_retired )
+{
+	VALUE reader = rb_hash_new();
+
+	rb_hash_aset( reader, ID2SYM(rb_intern("slot")),
+			INT2NUM( slot ) );
+	rb_hash_aset( reader, ID2SYM(rb_intern("pid")),
+			LONG2FIX( pid ) );
+	rb_hash_aset( reader, ID2SYM(rb_intern("thread")),
+			LONG2FIX( thread ) );
+	rb_hash_aset( reader, ID2SYM(rb_intern("txnid")),
+			LONG2FIX( txnid ) );
+	rb_hash_aset( reader, ID2SYM(rb_intern("lag")),
+			LONG2FIX( lag ) );
+	rb_hash_aset( reader, ID2SYM(rb_intern("bytes_used")),
+			LONG2FIX( bytes_used ) );
+	rb_hash_aset( reader, ID2SYM(rb_intern("bytes_retired")),
+			LONG2FIX( bytes_retired ) );
+
+	rb_ary_push( (VALUE)ctx, reader );
+
+	return 0;
+}
+
+
+/*
+ * Metadata for current reader slots.
+ * Initialize an array and populate it with each reader's statistics.
+*/
+void
+rmdbx_gather_reader_stats(
+	rmdbx_db_t *db,
+	VALUE stat,
+	MDBX_stat mstat,
+	MDBX_envinfo menvinfo )
+{
+	VALUE readers = rb_ary_new();
+
+    mdbx_reader_list( db->env, reader_list_callback, (void*)readers );
+	rb_hash_aset( stat, ID2SYM(rb_intern("readers")), readers );
+
+	return;
+}
+
+
+/*
+ * Build and return a hash of various statistic/metadata
+ * for the open +db+ handle.
+ */
+VALUE
+rmdbx_gather_stats( rmdbx_db_t *db )
+{
+	VALUE stat = rb_hash_new();
+
+	int rc;
+	MDBX_stat mstat;
+	MDBX_envinfo menvinfo;
+
+	rmdbx_gather_build_stats( stat );
+
+	rmdbx_open_txn( db, MDBX_TXN_RDONLY );
+    rc = mdbx_env_info_ex( db->env, db->txn, &menvinfo, sizeof(menvinfo) );
+	if ( rc != MDBX_SUCCESS )
+		rb_raise( rmdbx_eDatabaseError, "mdbx_env_info_ex: (%d) %s", rc, mdbx_strerror(rc) );
+
+    rc = mdbx_env_stat_ex( db->env, db->txn, &mstat, sizeof(mstat) );
+	if ( rc != MDBX_SUCCESS )
+		rb_raise( rmdbx_eDatabaseError, "mdbx_env_stat_ex: (%d) %s", rc, mdbx_strerror(rc) );
+	rmdbx_close_txn( db, RMDBX_TXN_ROLLBACK );
+
+	rmdbx_gather_environment_stats( stat, mstat, menvinfo );
+	rmdbx_gather_reader_stats( db, stat, mstat, menvinfo );
+
+	/* TODO: database and subdatabase stats */
+
+	return stat;
+}
+
+

data/lib/mdbx.rb

@@ -10,11 +10,7 @@ require 'mdbx_ext'
 module MDBX
 
 	# The version of this gem.
-	#
-	# Note: the MDBX library version this gem was built
-	# against can be found in the 'LIBRARY_VERSION' constant.
-	#
-	VERSION = '0.0.1'
+	VERSION = '0.1.0'
 
 end # module MDBX
 

data/lib/mdbx/database.rb

@@ -5,20 +5,91 @@
 require 'mdbx' unless defined?( MDBX )
 
 
-# TODO: rdoc
+# The primary class for interacting with an MDBX database.
 #
 class MDBX::Database
 
+	### call-seq:
+	###    MDBX::Database.open( path ) => db
+	###    MDBX::Database.open( path, options ) => db
+	###
 	### Open an existing (or create a new) mdbx database at filesystem
-	### +path+.  In block form, the database is automatically closed.
+	### +path+.  In block form, the database is automatically closed
+	### when the block exits.
 	###
-	###    MDBX::Database.open( path ) -> db
-	###    MDBX::Database.open( path, options ) -> db
 	###    MDBX::Database.open( path, options ) do |db|
-	###        db[ 'key' ] #=> value
-	###    end
+	###        db[ 'key' ] = value
+	###    end # closed!
+	###
+	### Passing options modify various database behaviors.  See the libmdbx
+	### documentation for detailed information.
+	###
+	### ==== Options
+	###
+	### Unless otherwise mentioned, option keys are symbols, and values
+	### are boolean.
+	###
+	### [:mode]
+	###   Whe creating a new database, set permissions to this 4 digit
+	###   octal number.  Defaults to `0644`.  Set to `0` to never automatically
+	###   create a new file, only opening existing databases.
+	###
+	### [:max_collections]
+	###   Set the maximum number of "subdatabase" collections allowed. By
+	###   default, collection support is disabled.
+	###
+	### [:max_readers]
+	###   Set the maximum number of allocated simultaneous reader slots.
+	###
+	### [:max_size]
+	###   Set an upper boundary (in bytes) for the database map size.
+	###   The default is 10485760 bytes.
+	###
+	### [:nosubdir]
+	###   When creating a new database, don't put the data and lock file
+	###   under a dedicated subdirectory.
+	###
+	### [:readonly]
+	###   Reject any write attempts while using this database handle.
+	###
+	### [:exclusive]
+	###   Access is restricted to the first opening process. Other attempts
+	###   to use this database (even in readonly mode) are denied.
+	###
+	### [:compat]
+	###   Skip compatibility checks when opening an in-use database with
+	###   unknown or mismatched flag values.
+	###
+	### [:writemap]
+	###   Trade safety for speed for databases that fit within available
+	###   memory. (See MDBX documentation for details.)
 	###
-	### FIXME: options!
+	### [:no_threadlocal]
+	###   Parallelize read-only transactions across threads.  Writes are
+	###   always thread local. (See MDBX documentatoin for details.)
+	###
+	### [:no_readahead]
+	###   Disable all use of OS readahead.  Potentially useful for
+	###   random reads wunder low memory conditions.  Default behavior
+	###   is to dynamically choose when to use or omit readahead.
+	###
+	### [:no_memory_init]
+	###   Skip initializing malloc'ed memory to zeroes before writing.
+	###
+	### [:coalesce]
+	###   Attempt to coalesce items for the garbage collector,
+	###   potentialy increasing the chance of unallocating storage
+	###   earlier.
+	###
+	### [:lifo_reclaim]
+	###   Recycle garbage collected items via LIFO, instead of FIFO.
+	###   Depending on underlying hardware (disk write-back cache), this
+	###   could increase write performance.
+	###
+	### [:no_metasync]
+	###   A system crash may sacrifice the last commit for a potentially
+	###   large write performance increase.  Database integrity is
+	###   maintained.
 	###
 	def self::open( *args, &block )
 		db = new( *args )
@@ -42,16 +113,18 @@ class MDBX::Database
 	private_class_method :new
 
 
-	# The options used to instantiate this database.
+	# Options used when instantiating this database handle.
 	attr_reader :options
 
 	# The path on disk of the database.
 	attr_reader :path
 
 	# A Proc for automatically serializing values.
+	# Defaults to +Marshal.dump+.
 	attr_accessor :serializer
 
 	# A Proc for automatically deserializing values.
+	# Defaults to +Marshal.load+.
 	attr_accessor :deserializer
 
 
@@ -61,8 +134,200 @@ class MDBX::Database
 		return self.collection( nil )
 	end
 
-	# Allow for some common nomenclature.
 	alias_method :namespace, :collection
+	alias_method :size, :length
+	alias_method :each, :each_pair
+
+
+	#
+	# Transaction methods
+	#
+
+	### Open a new mdbx read/write transaction.  In block form,
+	### the transaction is automatically committed when the block ends.
+	###
+	### Raising a MDBX::Rollback exception from within the block
+	### automatically rolls the transaction back.
+	###
+	def transaction( commit: true, &block )
+		self.open_transaction( commit )
+		yield self if block_given?
+
+		return self
+
+	rescue MDBX::Rollback
+		commit = false
+		self.rollback
+	rescue
+		commit = false
+		self.rollback
+		raise
+	ensure
+		if block_given?
+			commit ? self.commit : self.rollback
+		end
+	end
+
+
+	### Open a new mdbx read only snapshot.  In block form,
+	### the snapshot is automatically closed when the block ends.
+	###
+	def snapshot( &block )
+		self.transaction( commit: false, &block )
+	end
+
+
+	### Close any open transaction, abandoning all changes.
+	###
+	def rollback
+		return self.close_transaction( false )
+	end
+	alias_method :abort, :rollback
+
+
+	### Close any open transaction, writing all changes.
+	###
+	def commit
+		return self.close_transaction( true )
+	end
+	alias_method :save, :commit
+
+
+	#
+	# Hash-alike methods
+	#
+
+	### Return the entirety of database contents as an Array of array
+	### pairs.
+	###
+	def to_a
+		self.snapshot do
+			return self.each_pair.to_a
+		end
+	end
+
+
+	### Return the entirety of database contents as a Hash.
+	###
+	def to_h
+		self.snapshot do
+			return self.each_pair.to_h
+		end
+	end
+
+
+	### Returns +true+ if the current collection has no data.
+	###
+	def empty?
+		return self.size.zero?
+	end
+
+
+	### Returns the value for the given key, if found.
+	### If key is not found and no block was given, returns nil.
+	### If key is not found and a block was given, yields key to the
+	### block and returns the block's return value.
+	###
+	def fetch( key, &block )
+		val = self[ key ]
+		if block_given?
+			return block.call( key ) if val.nil?
+		else
+			return val if val
+			raise KeyError, "key not found: %p" % [ key ]
+		end
+	end
+
+
+	### Deletes the entry for the given key and returns its associated
+	### value.  If no block is given and key is found, deletes the entry
+	### and returns the associated value.  If no block given and key is
+	### not found, returns nil.
+	###
+	### If a block is given and key is found, ignores the block, deletes
+	### the entry, and returns the associated value.  If a block is given
+	### and key is not found, calls the block and returns the block's
+	### return value.
+	###
+	def delete( key, &block )
+		val = self[ key ]
+		return block.call( key ) if block_given? && val.nil?
+
+		self[ key ] = nil
+		return val
+	end
+
+
+	### Returns a new Array containing all keys in the collection.
+	###
+	def keys
+		self.snapshot do
+			return self.each_key.to_a
+		end
+	end
+
+
+	### Returns a new Hash object containing the entries for the given
+	### keys.  Any given keys that are not found are ignored.
+	###
+	def slice( *keys )
+		self.snapshot do
+			return keys.each_with_object( {} ) do |key, acc|
+				val = self[ key ]
+				acc[ key ] = val if val
+			end
+		end
+	end
+
+
+	### Returns a new Array containing all values in the collection.
+	###
+	def values
+		self.snapshot do
+			return self.each_value.to_a
+		end
+	end
+
+
+	### Returns a new Array containing values for the given +keys+.
+	###
+	def values_at( *keys )
+		self.snapshot do
+			return keys.each_with_object( [] ) do |key, acc|
+				acc << self[ key ]
+			end
+		end
+	end
+
+
+	#
+	# Utility methods
+	#
+
+	### Return a hash of various metadata for the current database.
+	###
+	def statistics
+		raw = self.raw_stats
+
+		# Place build options in their own hash.
+		#
+		build_opts = raw.delete( :build_options ).split.each_with_object( {} ) do |opt, acc|
+			key, val = opt.split( '=' )
+			acc[ key.to_sym ] = Integer( val ) rescue val
+		end
+
+		stats = {
+			build: {
+				compiler: raw.delete( :build_compiler ),
+				flags:    raw.delete( :build_flags ),
+				options:  build_opts,
+				target:   raw.delete( :build_target )
+			}
+		}
+		stats.merge!( raw )
+
+		return stats
+	end
 
 end # class MDBX::Database