The lmdb Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The lmdb Reference Manual

This is the lmdb Reference Manual, version 0.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:15:47 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

LMDB

Build Status

Common Lisp bindings to LMDB.

Overview

LMDB is really fast. Here's how much faster SQLite got when they ported the B-tree code to use LMDB.

This is implemented as a wrapper over the liblmdb library.

Usage

;; Create an environment
(let ((env (lmdb:make-environment #p"/some/directory/")))
  (lmdb:with-environment (env)
    ;; Create a transaction
    (let ((txn (lmdb:make-transaction env)))
      (lmdb:begin-transaction txn))
      ;; Create a database access object
      (let ((db (lmdb:make-database txn "db")))
        (lmdb:with-database (db)
          (lmdb:put db 1 2))
          (let ((vec (lmdb:get db 1)))
            (print vec)))))

License

Copyright (c) 2015–2016 Fernando Borretti

Licensed under the MIT License.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 lmdb

Maintainer

Fernando Borretti <eudoxiahp@gmail.com>

Author

Fernando Borretti <eudoxiahp@gmail.com>

Home Page

https://github.com/antimer/lmdb

Source Control

(:git "git@github.com:antimer/lmdb.git")

Bug Tracker

https://github.com/antimer/lmdb/issues

License

MIT

Description

Bindings to LMDB.

Long Description

# LMDB

[![Build Status](https://travis-ci.org/antimer/lmdb.svg?branch=master)](https://travis-ci.org/antimer/lmdb)

Common Lisp bindings to [LMDB](http://symas.com/mdb/).

# Overview

LMDB is really fast. [Here’s][sql] how much faster SQLite got when they ported
the B-tree code to use LMDB.

This is implemented as a wrapper over the [liblmdb][liblmdb] library.

# Usage

~~~lisp
;; Create an environment
(let ((env (lmdb:make-environment #p"/some/directory/")))
(lmdb:with-environment (env)
;; Create a transaction
(let ((txn (lmdb:make-transaction env)))
(lmdb:begin-transaction txn))
;; Create a database access object
(let ((db (lmdb:make-database txn "db")))
(lmdb:with-database (db)
(lmdb:put db 1 2))
(let ((vec (lmdb:get db 1)))
(print vec)))))
~~~

# License

Copyright (c) 2015–2016 Fernando Borretti

Licensed under the MIT License.

[sql]: https://github.com/LMDB/sqlightning
[liblmdb]: https://github.com/antimer/liblmdb

Version

0.1

Dependencies
Source

lmdb.asd (file)

Component

src (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 lmdb/src

Parent

lmdb (system)

Location

src/

Component

lmdb.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 lmdb.asd

Location

lmdb.asd

Systems

lmdb (system)


Previous: , Up: Lisp files   [Contents][Index]

4.1.2 lmdb/src/lmdb.lisp

Parent

src (module)

Location

src/lmdb.lisp

Packages

lmdb

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

5.1 lmdb

The high-level LMDB interface.

Source

lmdb.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Macros

Macro: do-pairs (DB KEY VALUE) &body BODY

Iterate over every key/value pair in the database.

Package

lmdb

Source

lmdb.lisp (file)

Macro: with-cursor (CURSOR) &body BODY

Execute the body and close the cursor.

Package

lmdb

Source

lmdb.lisp (file)

Macro: with-database (DATABASE) &body BODY

Execute the body and close the database.

Package

lmdb

Source

lmdb.lisp (file)

Macro: with-environment (ENV) &body BODY

Open the @cl:param(env), execute @cl:param(body) and ensure the environment is closed.

Package

lmdb

Source

lmdb.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Functions

Function: abort-transaction TRANSACTION

Abort the transaction. The transaction pointer is freed.

@begin(deflist)
@term(Thread Safety)

@def(The LMDB documentation doesn’t say specifically, but assume it can only be called by the transaction-creating thread.)

@end(deflist)

Package

lmdb

Source

lmdb.lisp (file)

Function: begin-transaction TRANSACTION

Begin the transaction.

@begin(deflist)
@term(Thread Safety)

@def(A transaction may only be used by a single thread.)

@end(deflist)

Package

lmdb

Source

lmdb.lisp (file)

Function: close-cursor CURSOR

Close a cursor.

Package

lmdb

Source

lmdb.lisp (file)

Function: close-database DATABASE

Close the database.

@begin(deflist)
@term(Thread Safety)

@def(Despair.

From the LMDB documentation,

@quote(This call is not mutex protected. Handles should only be closed by a single thread, and only if no other threads are going to reference the database handle or one of its cursors any further. Do not close a handle if an existing transaction has modified its database. Doing so can cause misbehavior from database corruption to errors like MDB_BAD_VALSIZE (since the DB name is gone).))

@end(deflist)

Package

lmdb

Source

lmdb.lisp (file)

Function: close-environment ENVIRONMENT

Close the environment connection and free the memory.

@begin(deflist)
@term(Thread Safety)

@def(Only a single thread may call this function. All environment-dependent objects, such as transactions and databases, must be closed before calling this function. Attempts to use those objects are closing the environment will result in a segmentation fault.)

@end(deflist)

Package

lmdb

Source

lmdb.lisp (file)

Function: commit-transaction TRANSACTION

Commit the transaction. The transaction pointer is freed.

@begin(deflist)
@term(Thread Safety)

@def(The LMDB documentation doesn’t say specifically, but assume it can only be called by the transaction-creating thread.)

@end(deflist)

Package

lmdb

Source

lmdb.lisp (file)

Function: cursor-get CURSOR OPERATION

Extract data using a cursor.

The @cl:param(operation) argument specifies the operation.

Package

lmdb

Source

lmdb.lisp (file)

Function: del DATABASE KEY &optional DATA

Delete this key from the database. Returns @c(t) if the key was found, @c(nil) otherwise.

Package

lmdb

Source

lmdb.lisp (file)

Function: environment-info ENVIRONMENT

Return information about the environment.

Package

lmdb

Source

lmdb.lisp (file)

Function: environment-statistics ENVIRONMENT

Return statistics about the environment.

Package

lmdb

Source

lmdb.lisp (file)

Function: get DATABASE KEY

Get a value from the database.

Package

lmdb

Source

lmdb.lisp (file)

Function: make-cursor DATABASE

Create a cursor object.

Package

lmdb

Source

lmdb.lisp (file)

Function: make-database TRANSACTION NAME &key CREATE

Create a database object.

Package

lmdb

Source

lmdb.lisp (file)

Function: make-environment DIRECTORY &key MAX-DATABASES MAPSIZE

Create an environment object.

Before an environment can be used, it must be opened with @c(open-environment).

Package

lmdb

Source

lmdb.lisp (file)

Function: make-transaction ENVIRONMENT &optional PARENT

Create a transaction object.

Package

lmdb

Source

lmdb.lisp (file)

Function: open-cursor CURSOR

Open a cursor.

Package

lmdb

Source

lmdb.lisp (file)

Function: open-database DATABASE

Open a database.

@begin(deflist)
@term(Thread Safety)

@def(A transaction that opens a database must finish (either commit or abort) before another transaction may open it. Multiple concurrent transactions cannot open the same database.)

@end(deflist)

Package

lmdb

Source

lmdb.lisp (file)

Function: open-environment ENVIRONMENT

Open the environment connection.

@begin(deflist)
@term(Thread Safety)

@def(No special considerations.)

@end(deflist)

Package

lmdb

Source

lmdb.lisp (file)

Function: put DATABASE KEY VALUE

Add a value to the database.

Package

lmdb

Source

lmdb.lisp (file)

Function: version-string ()

Return the version string.

Package

lmdb

Source

lmdb.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.3 Generic functions

Generic Function: transaction-environment OBJECT
Package

lmdb

Methods
Method: transaction-environment (TRANSACTION transaction)

The environment this transaction belongs to.

Source

lmdb.lisp (file)

Generic Function: transaction-parent OBJECT
Package

lmdb

Methods
Method: transaction-parent (TRANSACTION transaction)

The parent transaction, if any.

Source

lmdb.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.4 Conditions

Condition: lmdb-error ()

The base class of all LMDB errors.

Package

lmdb

Source

lmdb.lisp (file)

Direct superclasses

condition (condition)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.5 Classes

Class: cursor ()

A cursor.

Package

lmdb

Source

lmdb.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: handle

The pointer to the cursor object.

Initargs

:handle

Readers

%handle (generic function)

Slot: database

The database the cursor belongs to.

Type

lmdb:database

Initargs

:database

Readers

cursor-database (generic function)

Class: database ()

A database.

Package

lmdb

Source

lmdb.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: handle

The DBI handle.

Initargs

:handle

Readers

%handle (generic function)

Slot: transaction

The transaction this database belongs to.

Type

lmdb:transaction

Initargs

:transaction

Readers

database-transaction (generic function)

Slot: name

The database name.

Type

string

Initargs

:name

Readers

database-name (generic function)

Slot: create

Whether or not to create the database if it doesn’t exist.

Type

boolean

Initargs

:create

Readers

database-create-p (generic function)

Class: environment ()

Environment handle.

Package

lmdb

Source

lmdb.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: handle

The pointer to the environment handle.

Initargs

:handle

Readers

%handle (generic function)

Slot: directory

The directory where environment files are stored.

Initargs

:directory

Readers

environment-directory (generic function)

Slot: max-databases

The maximum number of named databases.

Type

integer

Initargs

:max-dbs

Initform

1

Readers

environment-max-dbs (generic function)

Class: transaction ()

A transaction.

Package

lmdb

Source

lmdb.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: handle

The pointer to the transaction.

Initargs

:handle

Readers

%handle (generic function)

Slot: env

The environment this transaction belongs to.

Type

lmdb:environment

Initargs

:environment

Readers

transaction-environment (generic function)

Slot: parent

The parent transaction, if any.

Type

(or lmdb:transaction null)

Initargs

:parent

Readers

transaction-parent (generic function)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Special variables

Special Variable: +eacces+
Package

lmdb

Source

lmdb.lisp (file)

Special Variable: +eagain+
Package

lmdb

Source

lmdb.lisp (file)

Special Variable: +enoent+
Package

lmdb

Source

lmdb.lisp (file)

Special Variable: +permissions+

The Unix permissions to use for the database.

Package

lmdb

Source

lmdb.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Macros

Macro: with-empty-value (VALUE) &body BODY
Package

lmdb

Source

lmdb.lisp (file)

Macro: with-val (RAW-VALUE DATA) &body BODY
Package

lmdb

Source

lmdb.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Functions

Function: %make-value &key (SIZE SIZE) (DATA DATA)
Package

lmdb

Source

lmdb.lisp (file)

Function: convert-data DATA

Convert Lisp data to a format LMDB likes. Supported types are integers, floats, booleans and strings. Returns a (size . array) pair.

Package

lmdb

Source

lmdb.lisp (file)

Function: copy-value INSTANCE
Package

lmdb

Source

lmdb.lisp (file)

Function: handle OBJECT

Return the handle from an environment, transaction or database.

Package

lmdb

Source

lmdb.lisp (file)

Function: integer-to-octets BIGNUM &aux N-BITS
Package

lmdb

Source

lmdb.lisp (file)

Function: make-value DATA

Create a value object.

Package

lmdb

Source

lmdb.lisp (file)

Function: raw-value-to-vector RAW-VALUE
Package

lmdb

Source

lmdb.lisp (file)

Function: unknown-error ERROR-CODE
Package

lmdb

Source

lmdb.lisp (file)

Function: value-data INSTANCE
Function: (setf value-data) VALUE INSTANCE
Package

lmdb

Source

lmdb.lisp (file)

Function: value-p OBJECT
Package

lmdb

Source

lmdb.lisp (file)

Function: value-size INSTANCE
Function: (setf value-size) VALUE INSTANCE
Package

lmdb

Source

lmdb.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.4 Generic functions

Generic Function: %handle OBJECT
Package

lmdb

Methods
Method: %handle (CURSOR cursor)

The pointer to the cursor object.

Source

lmdb.lisp (file)

Method: %handle (DATABASE database)

The DBI handle.

Source

lmdb.lisp (file)

Method: %handle (TRANSACTION transaction)

The pointer to the transaction.

Source

lmdb.lisp (file)

Method: %handle (ENVIRONMENT environment)

The pointer to the environment handle.

Source

lmdb.lisp (file)

Generic Function: cursor-database OBJECT
Package

lmdb

Methods
Method: cursor-database (CURSOR cursor)

The database the cursor belongs to.

Source

lmdb.lisp (file)

Generic Function: database-create-p OBJECT
Package

lmdb

Methods
Method: database-create-p (DATABASE database)

Whether or not to create the database if it doesn’t exist.

Source

lmdb.lisp (file)

Generic Function: database-name OBJECT
Package

lmdb

Methods
Method: database-name (DATABASE database)

The database name.

Source

lmdb.lisp (file)

Generic Function: database-transaction OBJECT
Package

lmdb

Methods
Method: database-transaction (DATABASE database)

The transaction this database belongs to.

Source

lmdb.lisp (file)

Generic Function: environment-directory OBJECT
Package

lmdb

Methods
Method: environment-directory (ENVIRONMENT environment)

The directory where environment files are stored.

Source

lmdb.lisp (file)

Generic Function: environment-max-dbs OBJECT
Package

lmdb

Methods
Method: environment-max-dbs (ENVIRONMENT environment)

The maximum number of named databases.

Source

lmdb.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.5 Structures

Structure: value ()

A value is a generic representation of keys and values.

Package

lmdb

Source

lmdb.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: size
Type

fixnum

Initform

0

Readers

value-size (function)

Writers

(setf value-size) (function)

Slot: data
Readers

value-data (function)

Writers

(setf value-data) (function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   M  
Index Entry  Section

F
File, Lisp, lmdb.asd: The lmdb<dot>asd file
File, Lisp, lmdb/src/lmdb.lisp: The lmdb/src/lmdb<dot>lisp file

L
Lisp File, lmdb.asd: The lmdb<dot>asd file
Lisp File, lmdb/src/lmdb.lisp: The lmdb/src/lmdb<dot>lisp file
lmdb.asd: The lmdb<dot>asd file
lmdb/src: The lmdb/src module
lmdb/src/lmdb.lisp: The lmdb/src/lmdb<dot>lisp file

M
Module, lmdb/src: The lmdb/src module

Jump to:   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
A   B   C   D   E   F   G   H   I   M   O   P   R   T   U   V   W  
Index Entry  Section

%
%handle: Internal generic functions
%handle: Internal generic functions
%handle: Internal generic functions
%handle: Internal generic functions
%handle: Internal generic functions
%make-value: Internal functions

(
(setf value-data): Internal functions
(setf value-size): Internal functions

A
abort-transaction: Exported functions

B
begin-transaction: Exported functions

C
close-cursor: Exported functions
close-database: Exported functions
close-environment: Exported functions
commit-transaction: Exported functions
convert-data: Internal functions
copy-value: Internal functions
cursor-database: Internal generic functions
cursor-database: Internal generic functions
cursor-get: Exported functions

D
database-create-p: Internal generic functions
database-create-p: Internal generic functions
database-name: Internal generic functions
database-name: Internal generic functions
database-transaction: Internal generic functions
database-transaction: Internal generic functions
del: Exported functions
do-pairs: Exported macros

E
environment-directory: Internal generic functions
environment-directory: Internal generic functions
environment-info: Exported functions
environment-max-dbs: Internal generic functions
environment-max-dbs: Internal generic functions
environment-statistics: Exported functions

F
Function, %make-value: Internal functions
Function, (setf value-data): Internal functions
Function, (setf value-size): Internal functions
Function, abort-transaction: Exported functions
Function, begin-transaction: Exported functions
Function, close-cursor: Exported functions
Function, close-database: Exported functions
Function, close-environment: Exported functions
Function, commit-transaction: Exported functions
Function, convert-data: Internal functions
Function, copy-value: Internal functions
Function, cursor-get: Exported functions
Function, del: Exported functions
Function, environment-info: Exported functions
Function, environment-statistics: Exported functions
Function, get: Exported functions
Function, handle: Internal functions
Function, integer-to-octets: Internal functions
Function, make-cursor: Exported functions
Function, make-database: Exported functions
Function, make-environment: Exported functions
Function, make-transaction: Exported functions
Function, make-value: Internal functions
Function, open-cursor: Exported functions
Function, open-database: Exported functions
Function, open-environment: Exported functions
Function, put: Exported functions
Function, raw-value-to-vector: Internal functions
Function, unknown-error: Internal functions
Function, value-data: Internal functions
Function, value-p: Internal functions
Function, value-size: Internal functions
Function, version-string: Exported functions

G
Generic Function, %handle: Internal generic functions
Generic Function, cursor-database: Internal generic functions
Generic Function, database-create-p: Internal generic functions
Generic Function, database-name: Internal generic functions
Generic Function, database-transaction: Internal generic functions
Generic Function, environment-directory: Internal generic functions
Generic Function, environment-max-dbs: Internal generic functions
Generic Function, transaction-environment: Exported generic functions
Generic Function, transaction-parent: Exported generic functions
get: Exported functions

H
handle: Internal functions

I
integer-to-octets: Internal functions

M
Macro, do-pairs: Exported macros
Macro, with-cursor: Exported macros
Macro, with-database: Exported macros
Macro, with-empty-value: Internal macros
Macro, with-environment: Exported macros
Macro, with-val: Internal macros
make-cursor: Exported functions
make-database: Exported functions
make-environment: Exported functions
make-transaction: Exported functions
make-value: Internal functions
Method, %handle: Internal generic functions
Method, %handle: Internal generic functions
Method, %handle: Internal generic functions
Method, %handle: Internal generic functions
Method, cursor-database: Internal generic functions
Method, database-create-p: Internal generic functions
Method, database-name: Internal generic functions
Method, database-transaction: Internal generic functions
Method, environment-directory: Internal generic functions
Method, environment-max-dbs: Internal generic functions
Method, transaction-environment: Exported generic functions
Method, transaction-parent: Exported generic functions

O
open-cursor: Exported functions
open-database: Exported functions
open-environment: Exported functions

P
put: Exported functions

R
raw-value-to-vector: Internal functions

T
transaction-environment: Exported generic functions
transaction-environment: Exported generic functions
transaction-parent: Exported generic functions
transaction-parent: Exported generic functions

U
unknown-error: Internal functions

V
value-data: Internal functions
value-p: Internal functions
value-size: Internal functions
version-string: Exported functions

W
with-cursor: Exported macros
with-database: Exported macros
with-empty-value: Internal macros
with-environment: Exported macros
with-val: Internal macros

Jump to:   %   (  
A   B   C   D   E   F   G   H   I   M   O   P   R   T   U   V   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   +  
C   D   E   H   M   N   P   S   T  
Index Entry  Section

+
+eacces+: Internal special variables
+eagain+: Internal special variables
+enoent+: Internal special variables
+permissions+: Internal special variables

C
create: Exported classes

D
data: Internal structures
database: Exported classes
directory: Exported classes

E
env: Exported classes

H
handle: Exported classes
handle: Exported classes
handle: Exported classes
handle: Exported classes

M
max-databases: Exported classes

N
name: Exported classes

P
parent: Exported classes

S
size: Internal structures
Slot, create: Exported classes
Slot, data: Internal structures
Slot, database: Exported classes
Slot, directory: Exported classes
Slot, env: Exported classes
Slot, handle: Exported classes
Slot, handle: Exported classes
Slot, handle: Exported classes
Slot, handle: Exported classes
Slot, max-databases: Exported classes
Slot, name: Exported classes
Slot, parent: Exported classes
Slot, size: Internal structures
Slot, transaction: Exported classes
Special Variable, +eacces+: Internal special variables
Special Variable, +eagain+: Internal special variables
Special Variable, +enoent+: Internal special variables
Special Variable, +permissions+: Internal special variables

T
transaction: Exported classes

Jump to:   +  
C   D   E   H   M   N   P   S   T  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   D   E   L   P   S   T   V  
Index Entry  Section

C
Class, cursor: Exported classes
Class, database: Exported classes
Class, environment: Exported classes
Class, transaction: Exported classes
Condition, lmdb-error: Exported conditions
cursor: Exported classes

D
database: Exported classes

E
environment: Exported classes

L
lmdb: The lmdb system
lmdb: The lmdb package
lmdb-error: Exported conditions

P
Package, lmdb: The lmdb package

S
Structure, value: Internal structures
System, lmdb: The lmdb system

T
transaction: Exported classes

V
value: Internal structures

Jump to:   C   D   E   L   P   S   T   V