-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Lightning MDB bindings -- -- LMDB is a read-optimized Berkeley DB replacement developed by Symas -- for the OpenLDAP project. LMDB has impressive performance -- characteristics and a friendly BSD-style Open LDAP license. See -- http://symas.com/mdb/. -- -- This library has Haskell bindings to the LMDB library. You must -- install the lmdb development files before installing this library, -- e.g. `sudo apt-get install liblmdb-dev` works for Ubuntu 14.04. -- -- For now, only a low level interface is provided, and the author is -- moving on to use LMDB rather than further develop its bindings. If a -- higher level API is desired, please consider contributing, or develop -- a separate package. @package lmdb @version 0.2.2 -- | This module is a thin wrapper above lmdb.h. -- -- Provisions for performance, convenience, or safety: -- -- -- -- Some functions come in two forms based on safe vs. -- unsafe FFI bindings. Unsafe FFI bindings are unsuitable for -- databases with user-defined comparison operations. (Though, if you -- plan to load a database with MDB_APPEND or MDB_APPENDDUP, you can use -- an unsafe dbi for just that portion.) -- -- Despite these provisions, developers must still be cautious: -- -- -- -- A slightly higher level API is planned, mostly to provide safer and -- more convenient access compared to raw MDB_val objects. -- -- Features not implemented: -- -- module Database.LMDB.Raw -- | Version information for LMDB. Two potentially different versions can -- be obtained: lmdb_version returns the version at the time of binding -- (via C preprocessor macros) and lmdb_dyn_version returns a version for -- the bound library. -- -- These bindings to Haskell will refuse to open the database when the -- dynamic version of LMDB is different in the major or minor fields. data LMDB_Version LMDB_Version :: {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> !String -> LMDB_Version v_major :: LMDB_Version -> {-# UNPACK #-} !Int v_minor :: LMDB_Version -> {-# UNPACK #-} !Int v_patch :: LMDB_Version -> {-# UNPACK #-} !Int v_text :: LMDB_Version -> !String -- | Version of LMDB when the Haskell-LMDB binding was compiled. lmdb_version :: LMDB_Version -- | Version of LMDB linked to the current Haskell process. lmdb_dyn_version :: IO LMDB_Version -- | LMDB_Error is the exception type thrown in case a function from the -- LMDB API does not return successfully. Clients should be prepared to -- catch exceptions from any LMDB operation. data LMDB_Error LMDB_Error :: String -> String -> Either Int MDB_ErrCode -> LMDB_Error e_context :: LMDB_Error -> String e_description :: LMDB_Error -> String e_code :: LMDB_Error -> Either Int MDB_ErrCode -- | Error codes from MDB. Note, however, that this API for MDB will mostly -- use exceptions for any non-successful return codes. This is mostly -- included because I feel the binding would be incomplete otherwise. -- -- (The MDB_SUCCESS return value is excluded.) data MDB_ErrCode MDB_KEYEXIST :: MDB_ErrCode MDB_NOTFOUND :: MDB_ErrCode MDB_PAGE_NOTFOUND :: MDB_ErrCode MDB_CORRUPTED :: MDB_ErrCode MDB_PANIC :: MDB_ErrCode MDB_VERSION_MISMATCH :: MDB_ErrCode MDB_INVALID :: MDB_ErrCode MDB_MAP_FULL :: MDB_ErrCode MDB_DBS_FULL :: MDB_ErrCode MDB_READERS_FULL :: MDB_ErrCode MDB_TLS_FULL :: MDB_ErrCode MDB_TXN_FULL :: MDB_ErrCode MDB_CURSOR_FULL :: MDB_ErrCode MDB_PAGE_FULL :: MDB_ErrCode MDB_MAP_RESIZED :: MDB_ErrCode MDB_INCOMPATIBLE :: MDB_ErrCode MDB_BAD_RSLOT :: MDB_ErrCode MDB_BAD_TXN :: MDB_ErrCode MDB_BAD_VALSIZE :: MDB_ErrCode -- | Opaque structure for LMDB environment. -- -- The environment additionally contains an MVar to enforce at most one -- lightweight Haskell thread is writing at a time. This is necessary so -- long as LMDB uses a long-lived mutex for writes, as in v0.9.10. data MDB_env -- | Handle for a database in the environment. data MDB_dbi -- | Handle for a database in the environment. -- -- This variation is associated with unsafe FFI calls, with -- reduced overhead but no user-defined comparisons. I expect most code -- using LMDB could use this variation. data MDB_dbi' -- | Opaque structure for LMDB transaction. data MDB_txn -- | Identifier for a transaction. data MDB_txnid -- | Opaque structure for LMDB cursor. data MDB_cursor -- | Opaque structure for a cursor on an MDB_dbi' object. Cursors in this -- case also use the unsafe FFI calls. data MDB_cursor' -- | A value stored in the database. Be cautious; committing the -- transaction that obtained a value should also invalidate it; avoid -- capturing MDB_val in a lazy value. A safe interface similar to STRef -- could be provided by another module. data MDB_val mv_size :: MDB_val -> CSize mv_data :: MDB_val -> (Ptr Word8) data MDB_stat ms_psize :: MDB_stat -> CUInt ms_depth :: MDB_stat -> CUInt ms_branch_pages :: MDB_stat -> CSize ms_leaf_pages :: MDB_stat -> CSize ms_overflow_pages :: MDB_stat -> CSize ms_entries :: MDB_stat -> CSize data MDB_envinfo me_mapaddr :: MDB_envinfo -> (Ptr ()) me_mapsize :: MDB_envinfo -> CSize me_last_pgno :: MDB_envinfo -> CSize me_last_txnid :: MDB_envinfo -> MDB_txnid me_maxreaders :: MDB_envinfo -> CUInt me_numreaders :: MDB_envinfo -> CUInt -- | User-defined comparison functions for keys. type MDB_cmp_func = Ptr MDB_val -> Ptr MDB_val -> IO CInt wrapCmpFn :: MDB_cmp_func -> IO (FunPtr MDB_cmp_func) -- | Environment flags from lmdb.h -- -- Note: MDB_NOTLS is implicit and enforced for this binding. data MDB_EnvFlag MDB_FIXEDMAP :: MDB_EnvFlag MDB_NOSUBDIR :: MDB_EnvFlag MDB_NOSYNC :: MDB_EnvFlag MDB_RDONLY :: MDB_EnvFlag MDB_NOMETASYNC :: MDB_EnvFlag MDB_WRITEMAP :: MDB_EnvFlag MDB_MAPASYNC :: MDB_EnvFlag MDB_NOLOCK :: MDB_EnvFlag MDB_NORDAHEAD :: MDB_EnvFlag MDB_NOMEMINIT :: MDB_EnvFlag data MDB_DbFlag MDB_REVERSEKEY :: MDB_DbFlag MDB_DUPSORT :: MDB_DbFlag MDB_INTEGERKEY :: MDB_DbFlag MDB_DUPFIXED :: MDB_DbFlag MDB_INTEGERDUP :: MDB_DbFlag MDB_REVERSEDUP :: MDB_DbFlag MDB_CREATE :: MDB_DbFlag data MDB_cursor_op MDB_FIRST :: MDB_cursor_op MDB_FIRST_DUP :: MDB_cursor_op MDB_GET_BOTH :: MDB_cursor_op MDB_GET_BOTH_RANGE :: MDB_cursor_op MDB_GET_CURRENT :: MDB_cursor_op MDB_GET_MULTIPLE :: MDB_cursor_op MDB_LAST :: MDB_cursor_op MDB_LAST_DUP :: MDB_cursor_op MDB_NEXT :: MDB_cursor_op MDB_NEXT_DUP :: MDB_cursor_op MDB_NEXT_MULTIPLE :: MDB_cursor_op MDB_NEXT_NODUP :: MDB_cursor_op MDB_PREV :: MDB_cursor_op MDB_PREV_DUP :: MDB_cursor_op MDB_PREV_NODUP :: MDB_cursor_op MDB_SET :: MDB_cursor_op MDB_SET_KEY :: MDB_cursor_op MDB_SET_RANGE :: MDB_cursor_op data MDB_WriteFlag MDB_NOOVERWRITE :: MDB_WriteFlag MDB_NODUPDATA :: MDB_WriteFlag MDB_CURRENT :: MDB_WriteFlag MDB_APPEND :: MDB_WriteFlag MDB_APPENDDUP :: MDB_WriteFlag -- | compiled write flags, corresponding to a [WriteFlag] list. Used -- because writes are frequent enough that we want to avoid building from -- a list on a per-write basis. data MDB_WriteFlags -- | compile a list of write flags. compileWriteFlags :: [MDB_WriteFlag] -> MDB_WriteFlags -- | Allocate an environment object. This doesn't open the environment. -- -- After creation, but before opening, please use: -- -- mdb_env_set_mapsize mdb_env_set_maxreaders mdb_env_set_maxdbs -- -- Then, just after opening, you should create a transaction to open all -- the databases (MDB_dbi and MDB_dbi' values) your application will use. -- -- The typical use case would then involve keeping all these open until -- your application either shuts down or crashes. -- -- In addition to normal LMDB errors, this operation may throw an -- MDB_VERSION_MISMATCH if the Haskell LMDB bindings don't match the -- dynamic version. If this happens, you'll need to rebuild the lmdb -- Haskell package. mdb_env_create :: IO MDB_env -- | open or build a database in the filesystem. The named directory must -- already exist and be writeable. Before opening, be sure to at least -- apply mdb_env_set_mapsize. -- -- After opening the environment, you should open the databases: -- -- Create the environment. Open a transaction. Open all DBI handles the -- app will need. Commit the transaction. Use those DBI handles in -- subsequent transactions mdb_env_open :: MDB_env -> FilePath -> [MDB_EnvFlag] -> IO () -- | Copy the environment to an empty (but existing) directory. -- -- Note: the LMDB copy operation temporarily grabs the writer mutex. -- Unfortunately, this greatly complicates the binding to Haskell. This -- interface, mdb_env_copy, conservatively blocks all writers in the same -- process for the entire duration of copy. -- -- Recommendation: Don't use this function in the same process with -- writers. Consider use of the mdb_copy command line utility if -- you need hot copies. mdb_env_copy :: MDB_env -> FilePath -> IO () -- | obtain statistics for environment mdb_env_stat :: MDB_env -> IO MDB_stat -- | obtain ad-hoc information about the environment. mdb_env_info :: MDB_env -> IO MDB_envinfo -- | Initiate synchronization of environment with disk. However, if the -- MDB_NOSYNC or MDB_MAPASYNC flags are active, this won't wait for the -- operation to finish. Cf. mdb_env_sync_flush. mdb_env_sync :: MDB_env -> IO () -- | Force buffered writes to disk before returning. mdb_env_sync_flush :: MDB_env -> IO () -- | Close the environment. The MDB_env object should not be used by any -- operations during or after closing. mdb_env_close :: MDB_env -> IO () -- | Set flags for the environment. mdb_env_set_flags :: MDB_env -> [MDB_EnvFlag] -> IO () -- | Unset flags for the environment. mdb_env_unset_flags :: MDB_env -> [MDB_EnvFlag] -> IO () -- | View the current set of flags for the environment. mdb_env_get_flags :: MDB_env -> IO [MDB_EnvFlag] -- | Obtain filesystem path for this environment. mdb_env_get_path :: MDB_env -> IO FilePath -- | Set the memory map size, in bytes, for this environment. This -- determines the maximum size for the environment and databases, but -- typically only a small fraction of the database is in memory at any -- given moment. -- -- It is not a problem to set this to a very large number, hundreds of -- gigabytes or even terabytes, assuming a sufficiently large address -- space. It should be set to a multiple of page size. -- -- The default map size is 1MB, intentionally set low to force developers -- to select something larger. mdb_env_set_mapsize :: MDB_env -> Int -> IO () -- | Set the maximum number of concurrent readers. mdb_env_set_maxreaders :: MDB_env -> Int -> IO () -- | Get the maximum number of concurrent readers. mdb_env_get_maxreaders :: MDB_env -> IO Int -- | Set the maximum number of named databases. LMDB is designed to support -- a small handful of databases. mdb_env_set_maxdbs :: MDB_env -> Int -> IO () -- | Key sizes in LMDB are determined by a compile-time constant, -- defaulting to 511 bytes. This function returns the maximum. mdb_env_get_maxkeysize :: MDB_env -> IO Int -- | Begin a new transaction, possibly read-only, with a possible parent. -- -- mdb_txn_begin env parent bReadOnly -- -- A read-write transaction should be tethered to a specific Haskell -- thread, which MUST be a bound thread (via forkOS or -- runInBoundThread). A read only transaction is not so constrained. -- -- The hierarchical transactions are useful for read-write transactions. -- They allow trying something out then aborting if it doesn't work. But -- only one child should be active at a time, all in the same OS thread. -- -- An attempt to grab a writer transaction may block, potentially for a -- very long time. It's the responsibility of the software architects to -- ensure there is no need for long-running write operations. mdb_txn_begin :: MDB_env -> Maybe MDB_txn -> Bool -> IO MDB_txn -- | Access environment for a transaction. mdb_txn_env :: MDB_txn -> MDB_env -- | Commit a transaction. Don't use the transaction after this. mdb_txn_commit :: MDB_txn -> IO () -- | Abort a transaction. Don't use the transaction after this. mdb_txn_abort :: MDB_txn -> IO () -- | Open a database that supports user-defined comparisons, but has -- slightly more FFI overhead for reads and writes. -- -- LMDB supports a small set of named databases, plus one main -- database using the null argument for the database name. mdb_dbi_open :: MDB_txn -> Maybe String -> [MDB_DbFlag] -> IO MDB_dbi -- | database statistics mdb_stat :: MDB_txn -> MDB_dbi -> IO MDB_stat -- | review flags from database mdb_dbi_flags :: MDB_txn -> MDB_dbi -> IO [MDB_DbFlag] -- | close the database handle. -- -- Note: the normal use-case for LMDB is to open all the database handles -- up front, then hold onto them until the application is closed or -- crashed. In that case, you don't need to bother with closing database -- handles. mdb_dbi_close :: MDB_env -> MDB_dbi -> IO () -- | remove the database and close the handle; don't use MDB_dbi after this mdb_drop :: MDB_txn -> MDB_dbi -> IO () -- | clear contents of database, reset to empty mdb_clear :: MDB_txn -> MDB_dbi -> IO () -- | Set a user-defined key comparison function for a database. mdb_set_compare :: MDB_txn -> MDB_dbi -> FunPtr MDB_cmp_func -> IO () -- | Set a user-defined data comparison operator for MDB_DUPSORT databases. mdb_set_dupsort :: MDB_txn -> MDB_dbi -> FunPtr MDB_cmp_func -> IO () mdb_dbi_open' :: MDB_txn -> Maybe String -> [MDB_DbFlag] -> IO MDB_dbi' mdb_stat' :: MDB_txn -> MDB_dbi' -> IO MDB_stat mdb_dbi_flags' :: MDB_txn -> MDB_dbi' -> IO [MDB_DbFlag] mdb_dbi_close' :: MDB_env -> MDB_dbi' -> IO () mdb_drop' :: MDB_txn -> MDB_dbi' -> IO () mdb_clear' :: MDB_txn -> MDB_dbi' -> IO () -- | Access a value by key. Returns Nothing if the key is not found. mdb_get :: MDB_txn -> MDB_dbi -> MDB_val -> IO (Maybe MDB_val) -- | Add a (key,value) pair to the database. -- -- Returns False on MDB_KEYEXIST, and True on MDB_SUCCESS. Any other -- return value from LMDB results in an exception. The MDB_KEYEXIST -- result can be returned only if certain write flags are enabled. mdb_put :: MDB_WriteFlags -> MDB_txn -> MDB_dbi -> MDB_val -> MDB_val -> IO Bool -- | Delete a given key, or a specific (key,value) pair in case of -- MDB_DUPSORT. This function will return False on a MDB_NOTFOUND result, -- and True on MDB_SUCCESS. -- -- Note: Ideally, LMDB would match the value even without MDB_DUPSORT. -- But it doesn't. Under the hood, the data is replaced by a null ptr if -- MDB_DUPSORT is not enabled (v0.9.10). mdb_del :: MDB_txn -> MDB_dbi -> MDB_val -> Maybe MDB_val -> IO Bool -- | Allocate space for data under a given key. This space must be filled -- before the write transaction commits. The idea here is to avoid an -- extra allocation. -- -- mdb_reserve flags txn dbi key byteCount -- -- Note: not safe to use with MDB_DUPSORT. Note: MDB_KEYEXIST will result -- in an exception here. mdb_reserve :: MDB_WriteFlags -> MDB_txn -> MDB_dbi -> MDB_val -> Int -> IO MDB_val mdb_get' :: MDB_txn -> MDB_dbi' -> MDB_val -> IO (Maybe MDB_val) mdb_put' :: MDB_WriteFlags -> MDB_txn -> MDB_dbi' -> MDB_val -> MDB_val -> IO Bool mdb_del' :: MDB_txn -> MDB_dbi' -> MDB_val -> Maybe MDB_val -> IO Bool mdb_reserve' :: MDB_WriteFlags -> MDB_txn -> MDB_dbi' -> MDB_val -> Int -> IO MDB_val -- | compare two values as keys in a database mdb_cmp :: MDB_txn -> MDB_dbi -> MDB_val -> MDB_val -> IO Ordering -- | compare two values as data in an MDB_DUPSORT database mdb_dcmp :: MDB_txn -> MDB_dbi -> MDB_val -> MDB_val -> IO Ordering mdb_cmp' :: MDB_txn -> MDB_dbi' -> MDB_val -> MDB_val -> IO Ordering mdb_dcmp' :: MDB_txn -> MDB_dbi' -> MDB_val -> MDB_val -> IO Ordering -- | open a cursor for the database. mdb_cursor_open :: MDB_txn -> MDB_dbi -> IO MDB_cursor -- | Low-level mdb_cursor_get operation, with direct control of how -- pointers to values are allocated, whether an argument is a nullPtr, -- and so on. -- -- In this case, False is returned for MDB_NOTFOUND (in which case the -- cursor should not be moved), and True is returned for MDB_SUCCESS. Any -- other return value from LMDB will result in an exception. -- -- Depending on the MDB_cursor_op, additional values may be returned via -- the pointers. At the moment mdb_cursor_get :: MDB_cursor_op -> MDB_cursor -> Ptr MDB_val -> Ptr MDB_val -> IO Bool -- | Low-level mdb_cursor_put operation. -- -- As with mdb_put, this returns True on MDB_SUCCESS and False for -- MDB_KEYEXIST, and otherwise throws an exception. mdb_cursor_put :: MDB_WriteFlags -> MDB_cursor -> MDB_val -> MDB_val -> IO Bool -- | Delete the value at the cursor. mdb_cursor_del :: MDB_WriteFlags -> MDB_cursor -> IO () -- | Close a cursor. don't use after this. In general, cursors should be -- closed before their associated transaction is commited or aborted. mdb_cursor_close :: MDB_cursor -> IO () -- | Access transaction associated with a cursor. mdb_cursor_txn :: MDB_cursor -> MDB_txn -- | Access the database associated with a cursor. mdb_cursor_dbi :: MDB_cursor -> MDB_dbi -- | count number of duplicate data items at cursor's current location. mdb_cursor_count :: MDB_cursor -> IO Int mdb_cursor_open' :: MDB_txn -> MDB_dbi' -> IO MDB_cursor' mdb_cursor_get' :: MDB_cursor_op -> MDB_cursor' -> Ptr MDB_val -> Ptr MDB_val -> IO Bool mdb_cursor_put' :: MDB_WriteFlags -> MDB_cursor' -> MDB_val -> MDB_val -> IO Bool mdb_cursor_del' :: MDB_WriteFlags -> MDB_cursor' -> IO () mdb_cursor_close' :: MDB_cursor' -> IO () mdb_cursor_txn' :: MDB_cursor' -> MDB_txn mdb_cursor_dbi' :: MDB_cursor' -> MDB_dbi' mdb_cursor_count' :: MDB_cursor' -> IO Int -- | Dump entries from reader lock table (for human consumption) mdb_reader_list :: MDB_env -> IO String -- | Check for stale readers, and return number of stale readers cleared. mdb_reader_check :: MDB_env -> IO Int -- | Abort a read-only transaction, but don't destroy it. Keep it available -- for mdb_txn_renew. mdb_txn_reset :: MDB_txn -> IO () -- | Renew a read-only transaction that was previously _reset. mdb_txn_renew :: MDB_txn -> IO () -- | utility function: prepare pointers suitable for mdb_cursor_get. withKVPtrs :: MDB_val -> MDB_val -> (Ptr MDB_val -> Ptr MDB_val -> IO a) -> IO a -- | variation on withKVPtrs with nullable value. withKVOptPtrs :: MDB_val -> Maybe MDB_val -> (Ptr MDB_val -> Ptr MDB_val -> IO a) -> IO a instance Typeable LMDB_Error instance Eq LMDB_Version instance Ord LMDB_Version instance Show LMDB_Version instance Ord MDB_txnid instance Eq MDB_txnid instance Show MDB_txnid instance Eq MDB_stat instance Ord MDB_stat instance Show MDB_stat instance Eq MDB_envinfo instance Ord MDB_envinfo instance Show MDB_envinfo instance Eq MDB_EnvFlag instance Ord MDB_EnvFlag instance Bounded MDB_EnvFlag instance Ix MDB_EnvFlag instance Show MDB_EnvFlag instance Eq MDB_DbFlag instance Ord MDB_DbFlag instance Bounded MDB_DbFlag instance Ix MDB_DbFlag instance Show MDB_DbFlag instance Eq MDB_WriteFlag instance Ord MDB_WriteFlag instance Bounded MDB_WriteFlag instance Ix MDB_WriteFlag instance Show MDB_WriteFlag instance Eq MDB_cursor_op instance Ord MDB_cursor_op instance Bounded MDB_cursor_op instance Ix MDB_cursor_op instance Show MDB_cursor_op instance Eq MDB_ErrCode instance Ord MDB_ErrCode instance Bounded MDB_ErrCode instance Ix MDB_ErrCode instance Show MDB_ErrCode instance Eq LMDB_Error instance Ord LMDB_Error instance Show LMDB_Error instance Storable MDB_envinfo instance Storable MDB_stat instance Storable MDB_val instance Exception LMDB_Error