Module: LMDB

Defined in:: ext/lmdb_ext/lmdb_ext.c,
lib/lmdb/version.rb,
lib/lmdb/database.rb,
ext/lmdb_ext/lmdb_ext.c

Overview

The LMDB module presents a Ruby API to the OpenLDAP Lightning Memory-mapped Database (LMDB).

Defined Under Namespace

Classes: Cursor, Database, Environment, Error, Transaction

Constant Summary collapse

VERSION =

'0.5.3'.freeze

LIB_VERSION =

rb_str_new2(MDB_VERSION_STRING)

Class Method Summary collapse

.new(path, opts) {|env| ... } ⇒ Environment

Open an LMDB database environment.

Class Method Details

.new(path, opts) {|env| ... } ⇒ `Environment`

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 LMDB::Environment#flags as well as the options documented here.

Examples:

Open environment and pass options

env = LMDB.new "dbdir", :maxdbs => 30, :mapasync => true, :writemap => true

Pass environment to block

LMDB.new "dbdir" do |env|
  # ...
end

Parameters:

path (String) —

the path to the files containing the database
opts (Hash) —

options for the database environment

Options Hash (opts):

:mode (Number) —

The Posix permissions to set on created files.
:maxreaders (Number) —

The maximum number of concurrent threads that can be executing transactions at once. Default is 126.
:maxdbs (Number) —

The maximum number of named databases in the environment. Not needed if only one database is being used.
:mapsize (Number) —

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.

Yields:

(env) —

The block to be executed with the environment. The environment is closed afterwards.

Yield Parameters:

env (Environment) —

The environment

Returns:

(Environment)

See Also:

#close
LMDB::Environment#flags

# File 'ext/lmdb_ext/lmdb_ext.c', line 498

static VALUE environment_new(int argc, VALUE *argv, VALUE klass) {
        VALUE path, option_hash;

#ifdef RB_SCAN_ARGS_KEYWORDS
        rb_scan_args_kw(RB_SCAN_ARGS_LAST_HASH_KEYWORDS,
                        argc, argv, "1:", &path, &option_hash);
#else
        rb_scan_args(argc, argv, "1:", &path, &option_hash);
#endif

        EnvironmentOptions options = {
                .flags = MDB_NOTLS,
                .maxreaders = -1,
                .maxdbs = 128,
                .mapsize = 0,
                .mode = 0755,
        };
        if (!NIL_P(option_hash))
                rb_hash_foreach(option_hash, environment_options, (VALUE)&options);

        MDB_env* env;
        check(mdb_env_create(&env));

        Environment* environment;
        VALUE venv = Data_Make_Struct(cEnvironment, Environment, environment_mark, environment_free, environment);
        environment->env = env;
        environment->thread_txn_hash = rb_hash_new();
        environment->txn_thread_hash = rb_hash_new();

        if (options.maxreaders > 0)
                check(mdb_env_set_maxreaders(env, options.maxreaders));
        if (options.mapsize > 0)
                check(mdb_env_set_mapsize(env, options.mapsize));

        check(mdb_env_set_maxdbs(env, options.maxdbs <= 0 ? 1 : options.maxdbs));
        VALUE expanded_path = rb_file_expand_path(path, Qnil);
        check(mdb_env_open(env, StringValueCStr(expanded_path), options.flags, options.mode));

        if (rb_block_given_p())
                return rb_ensure(rb_yield, venv, environment_close, venv);

        return venv;
}