# mmtkvdb

`mmtkvdb` is a crate for Rust which provides a memory-mapped key-value
database. It uses LMDB and links with an existing `liblmdb` on the system.

## Safety

Because of how memory-mapped I/O is being used and also because of certain
assumptions of the underlying LMDB API, opening environments and databases
requires `unsafe` Rust (i.e. the programmer must ensure that certain
preconditions are met that cannot be enforced by the compiler to avoid
undefined behavior). If you aim to program in safe Rust only, this Rust
library is not suitable for you.

## API Documentation

For documentation on how to use this crate, refer to the example in
`src/lib.rs`.

## License

See contained `LICENSE` file (MIT License).

## Changelog

* 2023-03-20: Version 0.16.0
    * Documented that `Storable::cmp_bytes_unchecked` of the unsafe `Storable`
      trait must never unwind (as this might leave the LMDB environment in an
      invalid state)
    * Removed `ToOwned` bound from `Storable` trait because it was not needed
    * Methods `nosync`, `mapasync`, and `nordahead` as well as corresponding
      getter methods have been added to `EnvBuilder` to allow better
      configuration of the environment
    * Minor performance improvements
        * Avoid unnecessary upgrading of a `Weak` by storing a unique
          identifier of the environment in each `DbBackend`
        * Replaced mutex `CursorBackend::closed` with an `AtomicBool` using
          `Relaxed` loads and stores to increase performance (`free`/`malloc`
          performs the necessary synchronization)
    * Minor documentation improvements
    * Code cleanup in benchmark and changed some benchmark settings
* 2023-03-17: Version 0.15.0
    * Several deprecated items have been removed:
        * `DbOptions`
        * `Env::open_dbs`
        * `EnvRw::create_dbs`
        * `EnvRef::open_or_create_dbs`
        * `Txn::cursor_search_key_get_key`
    * `EnvRw::drop_db` requires `&mut self`
    * `Env::clear_stale_readers` returns `std::io::Result<usize>`
    * Improved documentation in regard to use of `unsafe`
* 2023-03-16: Version 0.14.1
    * Critical bug fixes:
        * Opening the same database twice (in the same process) might have
          caused UB. This has been fixed.
        * LMDB databases might have been closed twice if an error occurred
          during opening, which might have caused UB in that case. This has
          been fixed.
        * Method `Txn::cursor_get_current_value_count` must only be called for
          databases with `KeysDuplicate`. This is enforced by the methods
          signature now and could have been resulting in UB previously.
        * A memory leak in `EnvRw::drop_db` has been fixed and code has been
          cleaned up and properly documented to avoid this in the future.
        * Write transactions which created a cursor but never wrote any data
          might have resulted in `mdb_cursor_close` being called after
          `mdb_dbi_close`, which is not allowed for write transaction by LMDB's
          API specification. This has been fixed.
    * All LMDB databases get closed explicitly now before the LMDB environment
      is closed.
    * Missing implementations for `Send` and `Sync` have been added for
      `EnvRo`, `EnvRw`, `Db`, and `Cursor`.
    * Deprecations:
        * A warning has been added to the documentation, stating that
          `EnvRw::drop_db` will require `&mut self` in future.
        * Methods for opening several databases at once (with the same types)
          have been deprecated. The methods opening a single database should be
          used instead.
    * Improved "Safety" sections in public API documentation
    * Code cleanup in regard to safety:
        * Use `unsafe_op_in_unsafe_fn` lint and added corresponding `unsafe`
          blocks
        * Added `SAFETY` comments in `src/lib.rs`
        * Correctly marked some private functions as `unsafe` and documented
          their use properly
* 2023-03-10: Version 0.14.0
    * `TxnRo` is now `!Sync` (but still `Send`); users are expected to use a
      mutex where synchronization is required
    * Deprecated `Txn::cursor_search_key_get_key`
    * Improved documentation regarding return values of cursor methods
    * Added benchmarks

For older changes, refer to the `CHANGELOG.md` file.