Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Linux Windows Mac
Build Status Build Status Build Status

Spreads.LMDB

Low-level zero-overhead and the fastest LMDB .NET wrapper with some additional native methods useful for Spreads.

Available on NuGet as Spreads.LMDB.

C# async/await support

LMDB's supported "normal" case is when a transaction is executed from a single thread. For .NET this means that if all operations on a transactions are called from a single thread it doesn't matter which thread is executing a transaction and LMDB will just work.

In some cases one my need background execution of write transactions or .NET async operations inside LMDB transactions. For this case Spreads.LMDB fully supports async/await. Write transactions are executed in a single thread via a blocking concurrent queue. Read transactions could be used from async code, which requires forcing MDB_NOTLS attribute for environments:

A thread may use parallel read-only transactions. A read-only transaction may span threads if the user synchronizes its use. Applications that multiplex many user threads over individual OS threads need this option. Such an application must also serialize the write transactions in an OS thread, since LMDB's write locking is unaware of the user threads.

Async support is disabled by default, but could be turned on via LMDBEnvironment.Create(..., disableAsync: false); if needed.

Read-only transaction and cursor renewal

Spreads.LMDB automatically takes care of read-only transaction and cursor renewals if they are properly disposed as .NET objects. It does not allocate those objects in steady state (uses internal pools).

Working with memory safely

Warning! This library exposes MDB_val directly as DirectBuffer struct, the struct MUST ONLY be read when inside a transaction (or when it points to an overflow page - but that is an undocumented hack working so far). For writes, the memory behind DirectBuffer MUST BE pinned.

DirectBuffer.Span property allows to access MDB_val as Span<byte>. DirectBuffer can be easily constructed from Span<byte>, but the span must be pinned as well if it is backed by byte[].

DirectBuffer has many methods to read/write primitive and generic blittable struct values from any offset, e.g. directBufferInstance.Read<ulong>(8) to read ulong from offset 8. By default it checks bounds, and LMDB call via P/Invoke takes much longer so there is no reason to switch the bounds checks off. But you can still do so e.g. if you read separate bytes of large values a lot (e.g. via indexer directBufferInstance[offset] that returns a single byte at offset).

Generic key/values support

Any fixed-sized unmanaged structs could be used directly as keys/values. Until unmanaged constraint and blittable helpers (at least IsBlittable) are widly available we use opt-in to treat a custom user-defined struct as blittable. It must have defined Spreads' BinarySerializationAttribute with BlittableSize parameter for non-generic types or PreferBlittable set to true for generic types that could be blittable depending on a concrete type. The logic to decide if a type is fixed-size is in TypeHelper and its TypeHelper<T>.Size static property must be positive.

IEnumerable support

A database or duplicate values of a key in a single dupsorted database could be enumerated via dataBaseInstance.AsEnumerable([several overloads]) methods that could return either DirectBuffers or generic blittable structs.

Examples

Tests show how to use the code.

Status & limitations

This library is being deployed and tested in production and is went through many performance and correctness stress tests as a part of a larger workload.

The project has required native binaries packed with NuGet. The library works with original native binaries as well if not using two TryFind helper methods.

The library does not support nested transactions yet - only because we do not use them currently. They will be added as soon as we find a real-world compelling case for them.

Contributing

Issues & PRs are welcome!

Copyright

MPL 2.0 (c) Victor Baybekov, 2018

About

Low-level zero-overhead and the fastest LMDB .NET wrapper with some additional native methods useful for Spreads

Topics

Resources

License

Packages

No packages published

Languages

You can’t perform that action at this time.