The services have similar but different data models, so we outlined the common features.

In our implementation, keys form a ZK-like hierarchy. Each key has a version that is uint64 number greater than 0. Current version is returned with other data by the most of operations. All the operations supported are listed below.

Our library has only an asynchronous interface, but if you want a synchronous one, just call get() on the returned futures.

Transactions consist of 4 operations: create, set, erase, check. Their descriptions can be found below. At the moment set has different behavior in comparison to ordinary set: when used in transaction, set does not create key if it does not exist. Besides using any of the operations you cannot assign watch. Transaction body is separated into two blocks: firstly you should write all required checks and then the sequence of other operations (see an example below). As a result you get a list of new versions for all the keys involved in set operations.

    #include <future>
    #include <iostream>

    #include "client.hpp"
    #include "error.hpp"
    #include "result.hpp"
    
    
    using namespace liboffkv;
    
    
    
    int main() 
    {
        // firstly specify protocol (zk | consul | etcd) and address to connect to the service
        // you can also specify a prefix all the keys will start with
        auto client = connect("consul://127.0.0.1:8500", "/prefix");
        
        // each method returns a future
        std::future<CreateResult> result = client->create("/key", "value");
        
        // sometimes it is returned with an exception (for more details see "liboffkv/client_interface.hpp"
        try {
            std::cout << "Key \"/prefix/key\" created successfully! "
                      << "Its initial version is " << result.get().version << std::endl;
        } catch (EntryExists&) {
            std::cout << "Error: key \"/prefix/key\" already exists!" << std::endl;
        }
	
	
	// WATCH EXAMPLE
	
	std::mutex lock;
    	lock.lock();
	
	// let's create a thread erasing key
    	std::thread([this, &lock]() mutable {
	    std::lock_guard<std::mutex> lock_guard(lock);
	    client->erase("/key").get();
        }).detach();
	
	// we call exists on newly create key "/prefix/key"
        auto result = client->exists("/key", true).get();
	
	// here we allow to launch erase job
        lock.unlock();

	// result is true
        assert(result);
	
	// here we wait untill "/prefix/key" is deleted
        result.watch.get();
	
	// and then result is false
        assert(!client->exists("/key").get());
        
	
	// TRANSACTION EXAMPLE
        
        // n.b. checks and other ops are separated from each other
        client->commit(
            {
                {
                    op::Check("/key", 42u),
                    op::Check("/foo"),
                },
                {
                    op::erase("/key"),
                    op::set("/foo", "new_value"),
                }
            }
        ).get();
    }

The library is currently tested on

• Ubuntu 18.04

  Full support.

• MacOS

  Full support.

• Windows 10

  Only Consul is supported.

• C++ compiler

  Currently tested compilers are

  • VS 2019
  • g++ 7.4.0
  • clang

  VS 2017 is known to fail.

• CMake

  We suggest using cmake bundled with vcpkg.

• vcpkg

• Copy all ports from liboffkv/vcpkg/ports/ to [vcpkg root]/ports or create corresponding symbolic links.

  Note that the original vcpkg curl port is broken. Use fixed version from this repo.

• Install dependencies

  # from vcpkg root
  vcpkg install ppconsul etcdcpp zkpp

  Installing all three packages is not required. See control flags at the next step.

• Build tests

  # from liboffkv directory
  mkdir cmake-build-debug && cd $_
  cmake -DCMAKE_BUILD_TYPE=Debug \
        -DCMAKE_TOOLCHAIN_FILE="<replace with path to vcpkg.cmake>" \
        -DBUILD_TESTS=ON ..
  cmake --build .

  You can control the set of supported services with the following flags

  • -DENABLE_ZK=[ON|OFF]
  • -DENABLE_ETCD=[ON|OFF]
  • -DENABLE_CONSUL=[ON|OFF]

  Sometimes you may also need to specify VCPKG_TARGET_TRIPLET.

• Run tests

  # from liboffkv/cmake-build-debug directory
  make test

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.