Language bindings for pmemkv

Posted March 04, 2020         « Previous post     Next post »

pmemkv is a local/embedded key-value datastore optimized for persistent memory. It is written in C and C++, but to satisfy a wider audience it comes with several bindings for high-level languages. Currently: Java (with JNI), Node.js, Python and Ruby.

The picture below illustrates architecture and software stack of pmemkv and its bindings. pmemkv_bindings_image

The most up-to-date information about pmemkv and its bindings is located in pmemkv’s README file.

Common for bindings

There are few common characteristics of all bindings:

Compatibility with libpmemkv 1.0

All of our currently released bindings work properly with libpmemkv 1.0. Unfortunately their API may not be functionally equivalent to the native C/C++ API. Bindings in version 1.0 deliver API compatible with pmemkv 1.0. Pmemkv’s binding released in version X.Y will be always compatible with pmemkv in the same X.Y version. Additionally, bindings with major version 0 should be considered experimental.

The pmemkv project is currently undergoing intensive development, and it is likely that the core library feature set will outpace features of the various bindings. Moreover, individual bindings are developed independently. To see if a feature is present, it is recommended to check documentation or a changelog for specific bindings.

Idiomatic language support

Each binding is developed to be as natural to the language as possible and hence some parts of the API may slightly differ from the one known from pmemkv.

For example, statuses returned by pmemkv are translated into numeric value or wrapped into exceptions. What’s more, bindings using exceptions do not use status “OK”, they just return nothing or a numeric value (of PMEMKV_STATUS_OK) if no error occurred.

Some functions’ return values may also differ - see details of each API in binding’s documentation and compare to pmemkv’s man pages.

Each language has also different system of packaging and installation. Native (or one of the most common) system was picked for each language.

Direct object access

Pmemkv library supports direct pointers to the data stored on the persistent memory out of the box. Bindings need to support it and at the moment only some of them implement that. See notes in individual descriptions below or in readme files on their repositories to check the support. Bindings without direct access need to use buffer to copy the data to.

Examples, tests and CI

Each repository includes:

Contributions are welcome

All pmemkv related repositories are open source and BSD-licensed, so contributions are welcome.

pmemkv-nodejs

Node.js binding is the first one that reached the 1.0 version. This guarantees backward compatibility and stable API, compatible with libpmemkv 1.0. This binding supports direct access to the data stored in the persistent memory.

It also delivers API description in form of JSDoc documentation (accessible e.g. as html in here) and NodeJS-native support for configuring engines by JSON object. This binding uses exceptions for error handling. It uses npm for distribution and can be installed with command npm install executed within the source directory. It then installs the dependencies listed in package.json in the local node_modules folder.

For more information, such as required dependencies, usage and full installation guide, see pmemkv-nodejs github repository.

pmemkv-python

This is the second binding that reached the 1.0 version. This guarantees backward compatibility and stable API, compatible with libpmemkv 1.0. It supports direct access to the data on the persistent memory.

It also delivers API description in form of PyDoc documentation (accessible e.g. as html in here) and Python-native data type (dict) to store engine’s configuration items. It uses exceptions for error handling. To install this project in your system type: python3 setup.py install. If you rather want it to be installed in your home directory (~/.local/lib/), add --user to the installation command.

For more information, such as required dependencies, usage and full installation guide, see pmemkv-python github repository.

pmemkv-java

Latest released version is 0.9 and and is compatible with libpmemkv 1.0, but comes with no guarantees of stable API. It uses exceptions for error handling. This binding uses JNI to interoperate with C and that pmemkv C JNI implementation is delivered in a separate repository. Installation process, when pmemkv and pmemkv-jni are installed in the system, comes down to executing, within source directory, command: mvn install.

For more information, such as required dependencies, usage and full installation guide, see pmemkv-java github repository. To see the repository of JNI content, see pmemkv-jni github repository.

pmemkv-ruby

It’s currently released as version 0.9 and is compatible with libpmemkv 1.0, but comes with no guarantees of stable API. It uses exceptions for error handling. Installation of this project and its dependencies is done using bundler (gem install bundler -v '< 2.0') and it then comes down to executing command: bundle install.

For more information, such as required dependencies, usage and full installation guide, see pmemkv-ruby github repository.

Summary

Language Version Direct access URL
Node.js 1.0 yes GitHub, docs
Python 1.0 yes GitHub, docs
Java 0.9 no GitHub
Ruby 0.9 no GitHub

Looking forward

We may deliver more bindings in the future, but we also encourage community to create their own bindings and share them with us.

We are currently aware of two community developed bindings:

If you feel like we’re missing some language, that may be useful to have bindings written in, or you just want to let us know we don’t have information about some (possibly yours) pmemkv’s binding, or you believe we’re missing some functionalities, please file an issue in pmemkv’s repository to let us know. We are always eager to help our community grow.



Posted by @lukaszstolarczuk         « Previous post     Next post »