|mapsize => INT||
The size of the memory map to use for this environment.
The size of the memory map is also the maximum size of the database. The value should be chosen as large as possible, to accommodate future growth of the database. The size should be a multiple of the OS page size.
The default is 1048576 bytes (1 MB).
|maxreaders => INT||
The maximum number of threads/reader slots for the environment.
This defines the number of slots in the lock table that is used to track readers in the environment.
The default is 126.
|maxdbs => INT||
The maximum number of named databases for the environment.
This option is only needed if multiple databases will be used in the environment. Simpler applications that use the environment as a single unnamed database can ignore this option.
The default is 0, i.e. no named databases allowed.
|mode => INT||The UNIX permissions to set on created files. This parameter is ignored on Windows. It defaults to 0600|
|flags => ENVFLAGS||
Set special options for this environment. This option, if provided,
can be specified by ORing the following flags:
$Env->copy ( $path ) Copy an LMDB environment to the specified $path $Env->copyfd ( HANDLE ) Copy an LMDB environment to the specified <B>HANDLEB>. $status = $Env->stat Returns a HASH reference with statistics for the main, unnamed, database in the environment, the HASH contains the following keys:
<B>psizeB> Size of a database page. <B>depthB> Depth (height) of the B-Tree <B>branch_pagesB> Number of internal (non-leaf) pages <B>overflow_pagesB> Number of overflow pages <B>entriesB> Number of data items $info = $Env->info Returns a HASH reference with information about the environment, $info, with the following keys:
<B>mapaddrB> Address of map, if fixed <B>mapsizeB> Size of the data memory map <B>last_pgnoB> ID of the last used page <B>last_txnidB> ID of the last committed transaction <B>maxreadersB> Max reader slots in the environment <B>numreadersB> Max reader slot used in the environment $Env->sync ( BOOL ) Flush the data buffers to disk.
Data is always written to disk when $Txn->commit() is called, but the operating system may keep it buffered. LMDB always flushes the OS buffers upon commit as well, unless the environment was opened with MDB_NOSYNC or in part MDB_NOMETASYNC.
If BOOL is TRUE force a synchronous flush. Otherwise if the environment has the MDB_NOSYNC flag set the flushes will be omitted, and with MDB_MAPASYNC they will be asynchronous.
$Env->set_flags ( BITMASK, BOOL ) As noted above, some environment flags can be changed at any time.
BITMASK is the flags to change, bitwise ORed together. BOOL TRUE set the flags, FALSE clears them.
$Env->get_flags ( $flags ) Returns in $flags the environment flags. $Env->get_path ( $path ) Returns in $path the path that was used in LMDB::Env->new(...) $Env->get_maxreaders ( $readers ) Returns in $readers the maximum number of threads/reader slots for the environment $mks = $Env->get_maxkeysize Returns the maximum size of a key for the environment. $Txn = $Env->BeginTxn ( [ $tflags ] ) Returns a new Transaction. A simple wrapper over the constructor of LMDB::Txn.
In LMDB every operation (read or write) on a Database needs to be inside a <B>transactionB>. This class wraps an LMDB transaction.
You must terminate the transaction by either the abort or commit methods. After a transaction is terminated, you should not call any other method on it, except env.
If you let an object of this class get out of scope, by default the transaction will be aborted.
$Txn = LMDB::Txn->new ( $Env [, $tflags ] )
$Txn->abort Abort the transaction, terminating the transaction. $Txn->commit Commit the transaction, terminating the transaction. $Txn->reset Reset a read-only transaction.
Abort the transaction like $Txn->abort(), but keep the transaction handle in the inactive state so $Txn->renew() may reactivate the handle.
The reader table lock is released, but the table slot stays tied to its thread or Transaction. Use $Txn->abort() to discard a reseted handle, and to free its lock table slot if MDB_NOTLS is in use.
$Txn->renew Renew a read-only transaction.
This acquires a new reader lock for a transaction handle that had been inactivated by $Txn->reset(). It must be called before an inactive (reseted) transaction may be used again.
In this Perl implementation if you call $Txn->renew() in an active Transaction the method internally calls $Txn->reset() for you.
$Env = $Txn->env Returns the environment (an LMDB::Env object) that created the transaction, if it is still alive, or undef if called on a terminated transaction. $SubTxn = $Txn->SubTxn ( [ $tflags ] ) Creates and returns a sub transaction (also known as a nested transaction).
Nested transactions are useful for combining components that create and commit transactions. No modifications are permanently stored until the highest level parent transaction is committed. Nested transactions can be aborted without aborting the parent transaction and only the changes made in the nested transaction will be rolled-back.
Aborting the parent transaction will abort and terminate all outstanding nested transactions. Committing the parent transaction will similarly commit and terminate all outstanding nested transactions.
Unlike some other databases, in LMDB changes made inside nested transactions are not visible to the parent transaction until the nested transaction is committed. In other words, transactions are always isolated, even when they are nested.
$Txn->AutoCommit ( [ BOOL ] ) When BOOL is provided, it sets the behavior of the transaction when going out of scope: BOOL TRUE makes arrangements for the transaction to be auto committed and BOOL FALSE returns to the default behavior: to be aborted.
If you dont provide BOOL, you are only interested in knowing the current value of this option, which is returned in every case.
$DB = $Txn->OpenDB ( [ DBOPTIONS ] ) $DB = $Txn->OpenDB ( [ $dbname [, DBFLAGS ]] ) This method opens a Database in the environment and returns a LMDB_File object that encapsulates both the Transaction and the Database handler.
This is a convenience shortcut for LMDB_File->new( $Txn, $Txn->open(...) ) for use when you want to use the hi-level LMDB_Files OO approach.
<B>dbnameB> => $dbname <B>flagsB> => DBFLAGS $dbi = $Txn->open ( [ $dbname [, DBFLAGS ]] ) This method open a Database in the environment and returns the low level Database handler, an integer.
MDB_REVERSEKEY Keys are strings to be compared in reverse order MDB_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. MDB_INTEGERKEY Keys are binary integers in native byte order. MDB_DUPFIXED This flag may only be used in combination with #MDB_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. When all data items are the same size, the #MDB_GET_MULTIPLE and #MDB_NEXT_MULTIPLE cursor operations may be used to retrieve multiple items at once. MDB_INTEGERDUP This option specifies that duplicate data items are also integers, and should be sorted as such. MDB_REVERSEDUP This option specifies that duplicate data items should be compared as strings in reverse order. MDB_CREATE Create the named database if it doesnt exist. This option is not allowed in a read-only transaction or a read-only environment.
After successfully commit the transaction that created the Database, it will remains opened in the Environment so you can reuse $dbi in other transactions.
If you will need to use that Database handler in more than one transaction or want to use a more traditional (in LMDBs point of view) approach, this the method you should use.
To operate in the opened database with the returned $dbi handler you can use the methods described bellow or call LMDB_File->new(...) to obtain a LMDB_File object to operate the database in a particular transaction.
$Txn->put ( $dbi, $key, $data [, WRITEFLAGS [, $length ] ) Store items into the database $dbi
Provided for when your main concern is the raw speed.
For details of the other arguments, please see the method of the same name in LMDB_File below.
$Txn->get ( $dbi, $key, $data ) Get items from the database $dbi
Provided for when your main concern is the raw speed.
For details of the other arguments, please see the method of the same name in LMDB_File below.
In the LMDB C API all Database operations need both an active Transaction and a Database handler. To simplify those operations and be syntax compatible with others *_File modules, this Perl API provides you a <B>LMDB_FileB> object that encapsulates both and implements some hi-level extensions.
LMDB_Files methods, in contrast to the LMDB::Txns ones of the same name, perform some checks before calling the low-level C API.
$DB = LMDB_File->new( $Txn, $dbi ) Associates a Transaction $Txn with a previously opened Database handler $dbi to use this OO API $DB = LMDB_File->open ( $Txn [, $dbname [, DBFLAGS ] ] ) An alternative to $Txn->OpenDB(...) for open a Database and associate it with a Transaction in one call.
$DB->put ( $key, $data [, WRITEFLAGS [, $length ] ] ) Store items into a database.
This function stores key/data pairs in the database. The default behavior is to enter the new key/data pair, replacing any previously existing key if duplicates are disallowed, or adding a duplicate data item if duplicates are allowed
$key is the key to store in the database and $data the data to store.
MDB_NODUPDATA Enter the new key/data pair only if it does not already appear in the database. This flag may only be specified if the database was opened with #MDB_DUPSORT. The function will fail with MDB_KEYEXIST if the key/data pair already appears in the database. MDB_NOOVERWRITE Enter the new key/data pair only if the key does not already appear in the database. MDB_RESERVE Reserve space for data of the given size in $length, but dont copy anything. Instead, return in $data a magical scalar with a pointer to the reserved space, which the caller can fill in later, but before the next update operation or the transaction ends. This saves an extra memcpy if the data is being generated later.
In this particular case, you need to pass the extra $length parameter to specify how many bytes to reserve.
Please read about the $DB->ReadMode method caveats bellow for details that apply to the magical scalar returned in $data in this case.
MDB_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.
MDB_APPENDDUP As above, but for sorted duplicated data. $DB->get ( $key, $data ) $data = $DB->get ( $key ) Get items from a database.
This method retrieves key/data pairs from the database.
If the database supports duplicate keys (#MDB_DUPSORT) then the first data item for the key will be returned. Retrieval of other items requires the use of the LMBD::Cursor->get() method.
In the simpler, more perlish one-argument form, the method returns the value associated with $key in the database or undef if no such value exists.
$DB->del ( $key [, $data ] ) Delete items from the database.
This function removes key/data pairs from the database.
If the database does not support sorted duplicate data items, (MDB_DUPSORT) the $data parameter is optional and is ignored.
If the database supports sorted duplicates and the $data parameter is undef or not provided, all of the duplicate data items for the $key will be deleted. Otherwise, if the $data parameter is provided only the matching data item will be deleted.
$DB->set_compare ( CODE ) Set a custom key comparison function referenced by CODE for a database.
The comparison function is called whenever it is necessary to compare a key specified by the application with a key currently stored in the database. If no comparison function is specified, and no special key flags were specified in LMDB_File->open(), the keys are compared lexically, with shorter keys collating before longer keys.
<B>Warning:B> This function must be called before any data access functions are used, otherwise data corruption may occur. The same comparison function must be used by every program accessing the database, every time the database is used.
$flags = $DB->flags Retrieve the DB flags for the associated database. $status = $DB->stat Returns a HASH reference with statistics for the associated database, the hash will contain the following keys:
<B>psizeB> Size of a database page. <B>depthB> Depth (height) of the B-Tree <B>branch_pagesB> Number of internal (non-leaf) pages <B>overflow_pagesB> Number of overflow pages <B>entriesB> Number of data items $DB->drop( [ REMOVE ] ) If REMOVE isnt provided or FALSE, the database is emptied. If REMOVE is TRUE the database is closed and removed from the Environment. $DB->Alive Returns a TRUE value if the associated transaction is still alive, i.e. not commited nor aborted yet, and FALSE otherwise. $Cursor = $DB->Cursor Creates a new LMDB::Cursor object to work in the database, see LMDB::Cursor $txn = $DB->Txn Returns the transaction, an LMDB::Txn object, associated with $DB.
$DB->Txn->commit; # Commit the current transaction.
If the method $DB->Alive has returned FALSE before, this method will return undef.
$dbi = $DB->dbi Returns the low level Database handler associated with $DB
You can use $DB->dbi as an lvalue to switch the associated Datbase hander:
$DB->dbi = $other_dbi;
$DB->ReadMode ( [ MODE ] ) This method allows you to modify the behavior of get (read) operations on the database.
The C documentation for the mdb_get function states that:
The memory pointed to by the returned values is owned by the database. The caller need not dispose of the memory, and may not modify it in any way. For values returned in a read-only transaction any modification attempts will cause a SIGSEGV.
So this module implements two modes of operation for its get methods and you can select between them with this method.
When MODE is 0 (or any FALSE value) a default safe mode is used in which the data value found in the database is copied to the scalar returned, so you can do anything you want to that scalar without side effects.
But when MODE is 1 (or, in the current implementation, any TRUE value) a sort of hack is used to avoid the memory copy and a magical scalar returned that hold only a pointer to the data value found. This is much faster and uses less memory, especially when used with large values.
In a environment opened with MDB_WRITEMAP and in a transaction without the MDB_RDONLY flag, you are allowed to modify the returned scalar, and the modifications are reflected to the associated memory block and preserved in the database when the transaction is commited. Otherwise the magical scalar is marked READ-ONLY and any attempt to modify it (other than reuse it in another $DB->get ), will cause perl to croak.
<B>CAVEATS:B> In a read-only transaction the value is valid only until the end of the transaction, and in a read-write transaction the value is valid only until the next write operation (because any write operation can potentially modify the in-memory btree). In the current implementation, you are responsible for the proper timing of usage.
<B>NOTE:B> In order to achieve the zero-copy behavior desired by setting ReadMode to TRUE, you must use the two-argument form of get ($DB->get ( $key, $data )), use the new $DB->Rget( $key ) or use the cursor get method described below.
$DB->UTF8 ( [ MODE ] ) Instructs LDMB_File to use the UTF-8 encoding for the associated database when MODE is 1 or revert to raw bytes when 0.
Returns the previous value.
By default, all values in LMDB are simple byte buffers of certain fixed length.
So if you are storing binary data in your database all works as expected: what you put is what you get.
But when you need to store some arbitrary Unicode text value, remember that internally perl stores your strings in either the native eight-bit character set or in UTF-8, and to warrant a consistent encoding in your database you should do something like:
For any value of $my_encoding, see Encode for the gory details.
When MODE is 1, all values that you put in the Database will be encoded in UTF-8, And all get calls will expect UTF-8 data and it will be verified and decoded. In this mode, if malformed data is found, a warning will be emitted, the decode attempt aborted and the raw bytes returned.
In this mode, a $foo->get(...) call interacts with the bytes pragma in a special way: In the lexical scope under the effects of use bytes, any get call skips the decode step, returning the fetched encoded UTF-8 data as bytes, i.e. with the internal perl UTF8 flag off, as expected by modules like JSON::XS.
To construct a cursor you should call the Cursor method of the LMDB_File class:
$cursor = $DB->Cursor
$cursor->get($key, $data, CURSOR_OP) This function retrieves key/data pairs from the database.
The variables $key and $data are used to return the values found.
MDB_FIRST Position at first key/data item. MDB_FIRST_DUP Position at first data item of current key. Only for MDB_DUPSORT MDB_GET_BOTH Position at key/data pair. Only for MDB_DUPSORT MDB_GET_BOTH_RANGE Position at key, nearest data. Only for MDB_DUPSORT MDB_GET_CURRENT Return key/data at current cursor position. MDB_GET_MULTIPLE Return all the duplicate data items at the current cursor position. Only for MDB_DUPFIXED MDB_LAST Position at last key/data item. MDB_LAST_DUP Position at last data item of current key. Only for MDB_DUPSORT MDB_NEXT Position at next data item. MDB_NEXT_DUP Position at next data item of current key. Only for MDB_DUPSORT MDB_NEXT_MULTIPLE Return all duplicate data items at the next cursor position. Only for MDB_DUPFIXED MDB_NEXT_NODUP Position at first data item of next key. MDB_PREV Position at previous data item. MDB_PREV_DUP Position at previous data item of current key. Only for MDB_DUPSORT MDB_PREV_NODUP Position at last data item of previous key. MDB_SET Position at specified key. MDB_SET_KEY Position at specified key, return key + data. MDB_SET_RANGE Position at first key greater than or equal to specified key. $cursor->put($key, $data, WRITEFLAGS) This function stores key/data pairs into the database.
If the function succeeds and an item is inserted into the database, the cursor is always positioned to refer to the newly inserted item.
If the function fails for any reason, the state of the cursor will undetermined.
$cursor->del( [ DELFLAGS ] ) This function deletes the key/data pair to which the cursor refers.
If the database was opened with MDB_DUPSORT, the optional parameter DELFLAGS can be MDB_NODUPDATA to deletes all of the data items for the current key.
At use time you can import into your namespace the following constants, grouped by their tags.
Environment flags CW:envflagsMDB_FIXEDMAP MDB_NOSUBDIR MDB_NOSYNC MDB_RDONLY MDB_NOMETASYNC MDB_WRITEMAP MDB_MAPASYNC MDB_NOTLS
Data base flags CW:dbflagsMDB_REVERSEKEY MDB_DUPSORT MDB_INTEGERKEY MDB_DUPFIXED MDB_INTEGERDUP MDB_REVERSEDUP MDB_CREATE
Write flags CW:writeflagsMDB_NOOVERWRITE MDB_NODUPDATA MDB_CURRENT MDB_RESERVE MDB_APPEND MDB_APPENDDUP MDB_MULTIPLE
All flags CW:flagsAll of :envflags, :dbflags and :writeflags
Cursor operations CW:cursor_opMDB_FIRST MDB_FIRST_DUP MDB_GET_BOTH MDB_GET_BOTH_RANGE MDB_GET_CURRENT MDB_GET_MULTIPLE MDB_NEXT MDB_NEXT_DUP MDB_NEXT_MULTIPLE MDB_NEXT_NODUP MDB_PREV MDB_PREV_DUP MDB_PREV_NODUP MDB_LAST MDB_LAST_DUP MDB_SET MDB_SET_KEY MDB_SET_RANGE
Error codes CW:errorMDB_SUCCESS MDB_KEYEXIST MDB_NOTFOUND MDB_PAGE_NOTFOUND MDB_CORRUPTED MDB_PANIC MDB_VERSION_MISMATCH MDB_INVALID MDB_MAP_FULL MDB_DBS_FULL MDB_READERS_FULL MDB_TLS_FULL MDB_TXN_FULL MDB_CURSOR_FULL MDB_PAGE_FULL MDB_MAP_RESIZED MDB_INCOMPATIBLE MDB_BAD_RSLOT MDB_LAST_ERRCODE
Version information CW:versionMDB_VERSION_FULL MDB_VERSION_MAJOR MDB_VERSION_MINOR MDB_VERSION_PATCH MDB_VERSION_STRING MDB_VERSION_DATE
The simplest interface to LMDB is using tie in perlfunc.
The TIE interface of LMDB_File can take several forms that depend on the data at hand.
The first two forms will create and/or open the Environment at $path, create a new Transaction and open a Database in the Transaction.
tie %hash, LMDB_File, $path [, $options ] The most simple form. tie %hash, LMDB_File, $path, $flags, $mode For compatibility with other DBM modules. tie %hash, LMDB_File, $Txn [, DBOPTIONS ] When you have a Transaction object $Txn at hand. tie %hash, LMDB_File, $Env [, DBOPTIONS ] When you have an Environment object $Env at hand. tie %hash, $DB When you have an opened Transaction encapsulated database.
If provided, $options must be a HASH reference with options for both the Environment and the database.
Salvador Ortiz Garcia, <email@example.com>
Copyright (C) 2013-2014 by Salvador Ortiz Garciá Copyright (C) 2013-2014 by Matiás Software Group, S.A. de C.V.
This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License version 2.0, see LICENSE.
|perl v5.20.3||LMDB_FILE (3)||2016-01-27|