Getting Started with the Hazelcast C++ Client

What You’ll Learn

This tutorial will get you started with the Hazelcast C++ client.

Before you Begin

A text editor or IDE
Docker
C++ 11+ supporting compiler
Vcpkg

Start a Hazelcast Member

We will use the 5.1 version of Hazelcast for this tutorial.

In this tutorial, we will use Docker for simplicity. You can also use CLI, Binary and Maven.

docker run -p 5701:5701 hazelcast/hazelcast:5.1

This will start a new Hazelcast member at port 5701. Now, we have a Hazelcast cluster with just one member.

Install Hazelcast C++ Client

In this tutorial we will use Vcpkg for installing the C++ client. You can also use Conan or install from source using CMake as explained here.

Before starting download and install Vcpkg itself if you haven’t already:
for Windows;

git clone https://github.com/microsoft/vcpkg
.\vcpkg\bootstrap-vcpkg.bat

for non-Windows;

git clone https://github.com/microsoft/vcpkg
./vcpkg/bootstrap-vcpkg.sh

First, execute the following to install hazelcast-cpp-client with its boost dependency:
for Windows;

.\vcpkg\vcpkg.exe install hazelcast-cpp-client

for non-Windows;

./vcpkg/vcpkg install hazelcast-cpp-client

After the installation, the library is available for usage. For example, if you are using CMake for your builds, you can use the following cmake build command with the CMAKE_TOOLCHAIN_FILE cmake option to be the vcpkg.cmake.

cmake -B [build directory] -S . -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build [build directory]

For more information about Vcpkg installation check here.

Starting the C++ Client

In this tutorial we use CMake for compilation, for other options you can check here. If you are using CMake like we do, you can easily find and link against the client library:

find_package(hazelcast-cpp-client CONFIG REQUIRED)

target_link_libraries(mytarget PRIVATE hazelcast-cpp-client::hazelcast-cpp-client)

Make sure you add the installation prefix of the client library to CMAKE_PREFIX_PATH if you are using a custom installation location.

Then, You can include the library and start a client using the following code:

#include <hazelcast/client/hazelcast_client.h>

int main() {
    auto hz = hazelcast::new_client().get();
    std::cout << "Hazelcast client started and connected to Hazelcast cluster successfully" << std::endl;
    return 0;
}

The following line creates and starts a new Hazelcast C++ client with the default configuration.

auto hz = hazelcast::new_client().get();

The client automatically connects to the Hazelcast member available on the local machine. Client also automatically disconnects upon its destruction.

Use Map

A Hazelcast map is a distributed key-value store, similar to JavaScript Map class or plain objects. You can store key-value pairs in a map. In the following example, we will work with map entries where the keys are session ids and the values are emails.

#include <hazelcast/client/hazelcast_client.h>

int main() {
    auto hz = hazelcast::new_client().get();
    auto map = hz.get_map("some_map").get();
    map->put<std::string,std::string>("sid12345","example1@email.com");
    map->put<std::string,std::string>("sid12346","example2@email.com");
    std::cout << map->get<std::string,std::string>("sid12345").get() << std::endl;
    std::cout << map->get<std::string,std::string>("sid12346").get() << std::endl;
}

The output of this snippet is given below:

example1@email.com
example2@email.com

The following line returns a map proxy object for the 'some_map' map:

auto map = hz.get_map("some_map").get();

If the map called “some_map” does not exist in the Hazelcast cluster, it will be automatically created. All the clients that connect to the same cluster will have access to the same map.

With these two lines, the C++ client adds data to the map. The first parameter is the key of the entry, the second one is the value:

map->put<std::string,std::string>("sid12345","example1@email.com");
map->put<std::string,std::string>("sid12346","example2@email.com");

Finally, we get the values we added to the map with the get method:

std::cout << map->get<std::string,std::string>("sid12345").get() << std::endl;
std::cout << map->get<std::string,std::string>("sid12346").get() << std::endl;

Add a Listener to the Map

You can add an entry listener using the add_entry_listener method available on map proxy object. This will allow you to listen to certain events that happen in the map across the cluster.

The first argument to the add_entry_listener method is an object that is used to define listeners. In this example, we registered listeners for the on_added, on_removed and on_updated events.

The second argument in the add_entry_listener method is include_value. It is a boolean parameter, and if it is true, the entry event contains the entry value. In this example, it will be true.

#include <hazelcast/client/hazelcast_client.h>

int main(){
    auto client = hazelcast::new_client().get();
    auto map = client.get_map("some_map").get();

    map->add_entry_listener(
            hazelcast::client::entry_listener().on_added([](hazelcast::client::entry_event &&event) {
                std::cout << "Entry added. Key:" << event.get_key().get<std::string>() << " Value: " << event.get_value().get<std::string>() << std::endl;
            }).on_removed([](hazelcast::client::entry_event &&event) {
                std::cout << "Entry removed. Key: " << event.get_key().get<std::string>() << std::endl;
            }).on_updated([](hazelcast::client::entry_event &&event) {
                std::cout << "Entry updated. Key: " << event.get_key().get<std::string>() << " Value change: "  << event.get_old_value().get<std::string>() << " -> " << event.get_value().get<std::string>() <<  std::endl;
            }), true).get();

    map->clear().get();

    map->put<std::string,std::string>("sid12345", "example1@email.com").get();
    map->put<std::string,std::string>("sid12346", "example2@email.com").get();
    map->delete_entry("sid12345").get();
    map->put<std::string,std::string>("sid12346", "example1@email.com").get();
}

First, the map is cleared to fire events even if there are some entries in the map. Then, two session entries are added, and they are logged. After that, we remove one of the entries and update the other one. Then, we log the session entries again.

The output is as follows:

Entry added. Key: sid12345 Value: example1@email.com
Entry added. Key: sid12346 Value: example2@email.com
Entry removed. Key: sid12345
Entry updated. Key: sid12346 Value change: example2@email.com -> example1@email.com

Summary

In this tutorial, you learned how to get started with Hazelcast C++ Client using a distributed map.