C++ Client

Overview

This section provides information about the C++ client for Hazelcast, and explains how to install and use the client.

To learn how to get started quickly with the Hazelcast C++ client, follow our simple Get started with C++ tutorial.

The Hazelcast native C++ client is an official library that allows C++ applications to connect to and interact with Hazelcast clusters. With the Hazelcast C++ client, developers can build high-performance, distributed applications in C++ that leverage Hazelcast’s powerful in-memory computing platform. The key features and benefits include:

Distributed Data Structures: the client offers access to various distributed data structures such as Map, Queue, Reliable Topic, Set, List, MultiMap, RingBuffer, etc.
Near Cache Support: the Near Cache feature allows frequently read data to be stored for faster read speeds compared to traditional caches.
Enterprise-Level security: the client provides SSL support for enhanced security requirements.
Distributed synchronization: the client offers distributed synchronization mechanisms through the CP Subsystem, including fenced_lock, counting_semaphore and latch.
Smart Client functionality: by default, it operates as a smart client, meaning it knows the data location within the cluster and can directly request the correct member (note that you can disable this feature using the client_config::get_networking_config::set_smart_routing method if you do not want the clients to connect to every member).
Listeners: ability to add cluster listeners to a cluster and entry/item listeners to distributed data structures.
Cloud integration: it offers the ability to discover existing Hazelcast clusters in an AWS environment.
Asynchronous operations: the client supports asynchronous execution of tasks in the cluster and non-blocking asynchronous methods for improved performance.
Flexible installation: it can be installed using package managers like Vcpkg or Conan, or built from source using CMake.

The C++ client API is fully asynchronous. The API returns boost::future API which has the capability of continuations. To make sure the requested operation is completed in the cluster and committed in the distributed database, you must wait for the result of the future.

For the latest C++ API documentation, see Hazelcast C++ Client docs.

The C++ client uses Hazelcast’s Open Client Protocol. This is the client-server protocol that Hazelcast uses to communicate with the clients.

Install the C++ client

This section explains how to install the Hazelcast C++ client.

Vcpkg users

Hazelcast C++ client package is available for Vcpkg users. The package name is hazelcast-cpp-client.

See Get started with vcpkg to learn how to use the Vcpkg package manager with your application. In summary:

If you use Linux or Mac:

git clone https://github.com/microsoft/vcpkg --branch 2025.02.14
./vcpkg/bootstrap-vcpkg.sh
./vcpkg/vcpkg install "hazelcast-cpp-client[openssl]" --recurse

If you use Windows:

git clone https://github.com/microsoft/vcpkg --branch 2025.02.14
.\vcpkg\bootstrap-vcpkg.bat
.\vcpkg\vcpkg install "hazelcast-cpp-client[openssl]:x64-windows" --recurse

The above code snippet installs hazelcast-cpp-client with its boost and openssl dependencies.

After installation, the library is available to use. 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=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake
cmake --build [build directory]

Conan users

The Hazelcast C++ client package is indexed at Conan Center Index. You can use the Conan package manager to install Hazelcast C++ client. The package name is hazelcast-cpp-client.

See example instructions on how to use the Conan package manager with your application. In summary:

Put the following lines into your conanfile.txt:

[requires]
hazelcast-cpp-client/5.2.0

[generators]
cmake

Then, execute the following:

$ mkdir build && cd build
$ conan install ..

This generates the conanbuildinfo.cmake file to be included in your CMakeLists.txt. Follow the instructions at the example page and build your application.

Install from source code using CMake

Requirements

Linux, macOS or Windows
A compiler that supports C++11
CMake 3.10 or above
Boost 1.71 or above. Minimum boost version is upgraded to 1.73 for Windows due to this bug
OpenSSL (optional)

Download source code

Go to the releases page to download the source code for the latest Hazelcast C++ client.

The releases page has both tar.gz and zip archives available. Choose the one that best suits your system.

Follow the instructions for your platform:

Linux and macOS users

To download and extract version 5.2.0 using the curl command:

curl -Lo hazelcast-cpp-client-5.2.0.tar.gz https://github.com/hazelcast/hazelcast-cpp-client/archive/v5.2.0.tar.gz
tar xzf hazelcast-cpp-client-5.2.0.tar.gz

Alternatively, clone the repository and checkout a specific version:

git clone https://github.com/hazelcast/hazelcast-cpp-client.git
cd hazelcast-cpp-client
git checkout v5.2.0

Once you are in the source directory of the Hazelcast C++ client library, create and change into a new directory:

cd hazelcast-cpp-client-5.2.0
mkdir build
cd build

Run cmake (or cmake3 if you are on CentOS or RHEL) to configure:

cmake ..

See the Advanced installation section below for configuration options.

Run cmake again to build and install the library:

cmake --build .
sudo cmake --build . --target install

You can speed up the build process with parallel threads like 'cmake --build . -j 4'

For information on how to use a different installation location, see Custom install location.

Windows users

Download and extract the release archive from the releases page.

Open a cmd window and switch to the folder where you extracted the contents of the release archive. Then create and change to a new directory:

cd hazelcast-cpp-client-5.2.0
mkdir build
cd build

Run cmake to configure:

cmake ..

See the advanced installation section for configuration options.

Build and install:

cmake --build . --config Release
cmake --build . --target install --config Release

The above commands will build and install the library with the Release configuration. Make sure you pass the same --config option to both commands.

The install command may require administrator privileges depending on your install prefix. See Custom install location for information on how to use a different installation location.

Advanced installation

Custom install location

The first time you run cmake, pass the argument -DCMAKE_INSTALL_PREFIX=/path/to/install to configure the installation directory:

cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install

CMake configuration

You can provide additional configuration options using the -DVARIABLE=VALUE syntax on the command line. Below are all the supported options:

WITH_OPENSSL : Set to ON to build the library with SSL support. This will require OpenSSL to be installed on your system. The default is OFF.
BUILD_SHARED_LIBS : Set to ON or OFF depending on whether you want the shared(ON) or static(OFF) library. The default is ON.
DISABLE_LOGGING : Setting this option to ON disables logging. The default is OFF.

For example, if you want to build the static library with SSL support, use the following command:

cmake .. -DWITH_OPENSSL=ON -DBUILD_SHARED_LIBS=OFF

If you want to use the hazelcast-cpp-client library with the -DWITH_OPENSSL=ON option without find_package() you must define the HZ_BUILD_WITH_SSL symbolic constant before including any hazelcast-cpp-client header. This symbolic constant can be defined via compiler options or can be passed directly through the cmake command as -DVARIABLE=VALUE pairs.

For example:

g++ -DHZ_BUILD_WITH_SSL -DBOOST_CHRONO_DYN_LINK -DBOOST_CHRONO_NO_LIB -DBOOST_THREAD_DYN_LINK -DBOOST_THREAD_NO_LIB -DBOOST_THREAD_VERSION=5 -I/var/git/hazelcast-cpp-client/build/include -std=gnu++11 -c main.cpp

Start a Hazelcast cluster

The Hazelcast C++ client requires a working Hazelcast cluster to run. This cluster handles storage and manipulation of the user data. Clients are a way to connect to the Hazelcast cluster and access such data.

A Hazelcast cluster consists of one or more cluster members. These members generally run on multiple virtual or physical machines and are connected to each other via the network. Any data put on the cluster is partitioned to multiple members in a way that is transparent to the user. It is therefore easy to scale the system by adding new members as the data grows. Hazelcast clusters also offer resilience. Should any hardware or software problem causes a crash to any member, the data on that member is recovered from backups and the cluster continues to operate without any downtime. Using a Hazelcast client is an easy way to connect to a Hazelcast cluster and perform tasks on distributed data structures that reside on the cluster.

To use the Hazelcast C++ client, we first need to setup a Hazelcast server.

Start a Hazelcast server

Use a Hazelcast Docker images

The quickest way to start a single member cluster for development purposes is to use our Docker images.

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

Use Hazelcast distribution

Alternatively, follow the instructions below to create a Hazelcast cluster:

Go to Hazelcast’s download page and download either the .zip or .tar distribution of Hazelcast.
Decompress the contents into any directory that you want to run members from.
Change into the directory that you decompressed the Hazelcast content and then into the bin directory.
Use either hz start or hz-start.bat depending on your operating system. Once you run the start script, you should see the Hazelcast logs in the terminal.

You should see a log similar to the following, which means that your single member cluster is ready to be used:

Nov 19, 2022 2:52:59 PM com.hazelcast.internal.cluster.ClusterService
INFO: [192.168.1.112]:5701 [dev] [<i>5.x.x</i>]

Members {size:1, ver:1} [
        Member [192.168.1.112]:5701 - 360ba49b-ef33-4590-9abd-ceff3e31dc06 this
]

Nov 19, 2022 2:52:59 PM com.hazelcast.core.LifecycleService
INFO: [192.168.1.112]:5701 [dev] [<i>5.x.x</i>] [192.168.1.112]:5701 is STARTED

Add user Java library to Java CLASSPATH

When you want to use features such as querying and language interoperability, you may need to add your own Java classes to the Hazelcast member in order to use them from your C++ client. This can be done by adding your own compiled code to the CLASSPATH. To do this, compile your code with the CLASSPATH and add the compiled files to the user-lib directory in the extracted hazelcast-<version>.zip (or tar). Then, you can start your Hazelcast member by using the start scripts in the bin directory. The start scripts will automatically add your compiled classes to the CLASSPATH.

If you are adding an IdentifiedDataSerializable or a Portable class, you need to add its factory too. Then, you configure the factory in the hazelcast.xml configuration file. This file resides in the bin directory where you extracted the hazelcast-<version>.zip (or tar).

The following is an example configuration when adding an IdentifiedDataSerializable class:

<hazelcast>
     ...
     <serialization>
        <data-serializable-factories>
            <data-serializable-factory factory-id="66">
                com.hazelcast.client.test.IdentifiedFactory
            </data-serializable-factory>
        </data-serializable-factories>
    </serialization>
    ...
</hazelcast>

To add a Portable class, use <portable-factories> instead of <data-serializable-factories> in the above configuration.

See the Hazelcast documentation for more information on setting up the clusters.

Compile your project

If you are using CMake, see the section below for CMake users, otherwise follow the instructions specific to your platform:

CMake users

The Hazelcast C++ client installation comes with package configuration files for CMake. If your project is using CMake, 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.

Linux and MacOS users

You can pass the -lhazelcast-cpp-client option to the compiler to link against the client library.

The client library depends on Boost.Thread and Boost.Chrono. You should also link your program against these libraries using -lboost_thread and -lboost_chrono. The Boost.Thread library should be provided with the preprocessor definition BOOST_THREAD_VERSION=5 for necessary features such as futures and future continuations to be enabled.

The following shows how to compile an example from the examples directory:

g++ -std=c++11 \
    examples/path/to/example.cpp \
    -DBOOST_THREAD_VERSION=5 \
    -lhazelcast-cpp-client -lboost_thread -lboost_chrono -lssl -lcrypto

If your environment could not find openssl library, define it as below (As an example: -L/opt/homebrew/Cellar/[email protected]/1.1.1t/lib)

g++ -std=c++11 \
    examples/path/to/example.cpp \
    -DBOOST_THREAD_VERSION=5 \
    -lhazelcast-cpp-client -lboost_thread -lboost_chrono -lssl -lcrypto
    -L/opt/homebrew/Cellar/[email protected]/1.1.1t/lib

If a custom installation directory was used during installation, you may also need to use the -L and -I options to add the library and include paths to the compiler’s search path.

g++ -std=c++11 \
    examples/path/to/example.cpp \
    -I /path/to/install/include -L /path/to/install/lib \
    -lhazelcast-cpp-client -lboost_thread -lboost_chrono  -lssl -lcrypto

Windows users

Provide your compiler with the include directories and library files for the Hazelcast C++ client and its dependencies.

You also need to pass the preprocessor definition BOOST_THREAD_VERSION=5 for necessary features such as futures and future continuations to be enabled.

You can use the following command to compile an example from the examples directory:

cl.exe path\to\example.cpp ^
    C:\path\to\hazelcast\lib\hazelcast-cpp-client.lib ^
    C:\path\to\boost\lib\boost_thread.lib C:\path\to\boost\lib\boost_chrono.lib ^
    /EHsc /DBOOST_THREAD_VERSION=5 ^
    /I C:\path\to\hazelcast\include /I C:\path\to\boost\include

Basic configuration

If you are using Hazelcast and the Hazelcast C++ Client on the same computer, the default configuration is generally fine, and ideal for trying out the client. However, if you run the client on a different computer than any of the cluster members, you may need to do some simple configuration such as specifying the member addresses.

Hazelcast members and clients have their own configuration options. You may need to reflect some of the member-side configurations on the client side to connect properly to the cluster.

This section describes the most common configuration elements to get you started quickly. It outlines some member-side configuration options to help you understand Hazelcast’s ecosystem, together with client-side configuration options for cluster connection. The configurations for the Hazelcast data structures that can be used in the C++ client are also explained in the following sections.

For more detailed information, see the Configuration Overview.

Configuring Hazelcast server

Hazelcast aims to run 'out of the box' for most common scenarios. However, if you have limitations on your network such as multicast being disabled, you may have to configure your Hazelcast members so that they can find each other on the network. Also, since most of the distributed data structures are configurable, you may want to tailor them according to your needs. This section shows you the basics of network configuration.

Use one of the following options to configure Hazelcast:

The hazelcast.xml configuration file.
Programmatically configure the member before starting it from the Java code.

Since we use standalone servers, we will use the hazelcast.xml file to configure our cluster members.

When you download and unzip hazelcast-<version>.zip (or tar), the hazelcast.xml appears in the bin directory. When a Hazelcast member starts, it looks for the hazelcast.xml file to load the configuration from. A sample hazelcast.xml is shown below.

<hazelcast>
    <cluster-name>dev</cluster-name>

    <network>
        <port auto-increment="true" port-count="100">5701</port>
        <join>
            <multicast enabled="true">
                <multicast-group>224.2.2.3</multicast-group>
                <multicast-port>54327</multicast-port>
            </multicast>
            <tcp-ip enabled="false">
                <interface>127.0.0.1</interface>
                <member-list>
                    <member>127.0.0.1</member>
                </member-list>
            </tcp-ip>
        </join>
        <ssl enabled="false"/>
    </network>
    <partition-group enabled="false"/>
    <map name="default">
        <backup-count>1</backup-count>
    </map>
</hazelcast>

Other important configuration elements include:

<cluster-name>: Specifies which cluster this member belongs to.
<network>
- <port>: Specifies the port number to be used by the member when it starts. Its default value is 5701. You can specify another port number, and if you set auto-increment to true, then Hazelcast will try the subsequent ports until it finds an available port or the port-count is reached.
- <join>: Specifies the strategies to be used by the member to find other cluster members. Choose which strategy you want to use by setting its enabled attribute to true and the others to false.
  - <multicast>: Members find each other by sending multicast requests to the specified address and port. It is useful if IP addresses of the members are not static.
  - <tcp>: This strategy uses a pre-configured list of known members to find an already existing cluster. It is enough for a member to find only one cluster member to connect to the cluster. The rest of the member list is automatically retrieved from that member. We recommend putting multiple known member addresses there to avoid disconnectivity should one of the members in the list is unavailable at the time of connection.

These configuration elements are enough for most connection scenarios. Next, we will look at the configuration of the C++ client.

Configuring Hazelcast C++ client

You must configure the Hazelcast C++ client programmatically as config files of any type are not yet supported.

You can start the client with no custom configuration like this:

    auto hz = hazelcast::new_client().get(); // Connects to the cluster

This section describes some network configuration settings to cover common use cases in connecting the client to a cluster. See the Configuration Overview and the following sections for information about detailed network configurations and/or additional features of Hazelcast C++ client configuration.

An easy way to configure your Hazelcast C++ client is to create a client_config object and set the appropriate options. Then you need to pass this object to the client when starting it, as shown below:

    hazelcast::client::client_config config;
    config.set_cluster_name("my-cluster"); // the server is configured to use the `my_cluster` as the cluster name hence we need to match it to be able to connect to the server.
    config.get_network_config().add_address(address("192.168.1.10", 5701));
    auto hz = hazelcast::new_client(std::move(config)).get(); // Connects to the cluster member at ip address `192.168.1.10` and port 5701

If you run Hazelcast members in a different server than the client, you most probably have configured the ports and the cluster names of the members as explained in the previous section. If you did, you need to make certain changes to the network settings of your client.

Cluster name

You only need to provide the name of the cluster if it is explicitly configured on the server side (otherwise the default value of dev is used).

hazelcast::client::client_config config;
config.set_cluster_name("my-cluster"); // the server is configured to use the `my_cluster` as the cluster name hence we need to match it to be able to connect to the server.

Network settings

You need to provide the IP address and port of at least one member in your cluster so the client can find it.

hazelcast::client::client_config config;
config.get_network_config().add_address(hazelcast::client::address("your server ip", 5701 /* your server port*/));

Client system properties

While configuring your C++ client, you can use various system properties provided by Hazelcast to tune its clients. These properties can be set programmatically through config.set_property or by using an environment variable. The value of this property will be:

the programmatically configured value, if programmatically set
the environment variable value, if the environment variable is set
the default value, if none of the above is set.

See the following for an example client system property configuration:

Programmatically:

config.set_property(hazelcast::client::client_properties::INVOCATION_TIMEOUT_SECONDS, "2") // Sets invocation timeout as 2 seconds

config.set_property("hazelcast.client.invocation.timeout.seconds", "2") // Sets invocation timeout as 2 seconds

By using an environment variable on Linux:

export hazelcast.client.invocation.timeout.seconds=2

If you set a property both programmatically and via an environment variable, the programmatically set value will be used.

See the complete list of system properties, along with their descriptions, which can be used to configure your Hazelcast C++ client.

Basic usage

Now that we have a working cluster and we know how to configure both our cluster and client, we can run a simple program to use a distributed map with the C++ client.

The following example first creates a programmatic configuration object. Then, it starts a client.

#include <hazelcast/client/hazelcast_client.h>
int main() {
    auto hz = hazelcast::new_client().get(); // Connects to the cluster
    std::cout << "Started the Hazelcast C++ client instance " << hz.get_name() << std::endl; // Prints client instance name
    hz.shutdown().get();
    return 0;
}

This prints logs about the cluster members and information about the client itself, such as client type and local address port.

18/11/2022 21:22:26.835 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:375] (Wed Nov 18 17:25:23 2022 +0300:3b11bea) LifecycleService::LifecycleEvent Client (75121987-12fe-4ede-860d-59222e6d3ef2) is STARTING
18/11/2022 21:22:26.835 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:379] (Wed Nov 18 17:25:23 2022 +0300:3b11bea) LifecycleService::LifecycleEvent STARTING
18/11/2022 21:22:26.835 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:387] LifecycleService::LifecycleEvent STARTED
18/11/2022 21:22:26.837 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/network.cpp:587] Trying to connect to Address[10.212.1.117:5701]
18/11/2022 21:22:26.840 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:411] LifecycleService::LifecycleEvent CLIENT_CONNECTED
18/11/2022 21:22:26.840 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/network.cpp:637] Authenticated with server  Address[:5701]:a27f900e-b1eb-48be-aa46-d7a4922ef704, server version: 4.2, local address: Address[10.212.1.116:37946]
18/11/2022 21:22:26.841 INFO: [139868341360384] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:881]

Members [1]  {
        Member[10.212.1.117]:5701 - a27f900e-b1eb-48be-aa46-d7a4922ef704
}

Started the Hazelcast C++ client instance hz.client_1

Congratulations! You just started a Hazelcast C++ client.

Using a Map

Next, manipulate a distributed map on a cluster using the client.

Save the following file as IT.cpp and compile it using a command similar to the following (Linux g++ compilation is used for demonstration):

g++ IT.cpp -o IT -lhazelcast-cpp-client -lboost_thread -lboost_chrono -DBOOST_THREAD_VERSION=5 -lssl -lcrypto --std=c++11

Then, you can run the application using the following command:

./IT

IT.cpp

#include <hazelcast/client/hazelcast_client.h>
int main() {
    auto hz = hazelcast::new_client().get(); // Connects to the cluster

    auto personnel = hz.get_map("personnel_map").get();
    personnel->put<std::string, std::string>("Amanda", "IT").get();
    personnel->put<std::string, std::string>("Rob", "IT").get();
    personnel->put<std::string, std::string>("Olly", "IT").get();
    std::cout << "Added IT personnel. Logging all known personnel" << std::endl;
    for (const auto &entry : personnel->entry_set<std::string, std::string>().get()) {
        std::cout << entry.first << " is in " << entry.second << " department." << std::endl;
    }
    hz.shutdown().get();
    return 0;
}

Output

18/11/2022 21:22:26.835 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:375] (Wed Nov 18 17:25:23 2022 +0300:3b11bea) LifecycleService::LifecycleEvent Client (75121987-12fe-4ede-860d-59222e6d3ef2) is STARTING
18/11/2022 21:22:26.835 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:379] (Wed Nov 18 17:25:23 2022 +0300:3b11bea) LifecycleService::LifecycleEvent STARTING
18/11/2022 21:22:26.835 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:387] LifecycleService::LifecycleEvent STARTED
18/11/2022 21:22:26.837 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/network.cpp:587] Trying to connect to Address[10.212.1.117:5701]
18/11/2022 21:22:26.840 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:411] LifecycleService::LifecycleEvent CLIENT_CONNECTED
18/11/2022 21:22:26.840 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/network.cpp:637] Authenticated with server  Address[:5701]:a27f900e-b1eb-48be-aa46-d7a4922ef704, server version: 4.2, local address: Address[10.212.1.116:37946]
18/11/2022 21:22:26.841 INFO: [139868341360384] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:881]

Members [1]  {
        Member[10.212.1.117]:5701 - a27f900e-b1eb-48be-aa46-d7a4922ef704
}
Added IT personnel. Logging all known personnel
Amanda is in IT department
Olly is in IT department
Rob is in IT department

This example puts all the IT personnel into a cluster-wide personnel_map and then prints all the known personnel.

Now create a Sales.cpp file, compile and run it as shown below:

Compile:

g++ Sales.cpp -o Sales -lhazelcast-cpp-client -lboost_thread -lboost_chrono -DBOOST_THREAD_VERSION=5 -lssl -lcrypto --std=c++11

Run

Then, run the application using the following command:

./Sales

Sales.cpp

#include <hazelcast/client/hazelcast_client.h>
int main() {
auto hz = hazelcast::new_client().get(); // Connects to the cluster

auto personnel = hz.get_map("personnel_map").get();
    personnel->put<std::string, std::string>("Denise", "Sales").get();
    personnel->put<std::string, std::string>("Erwing", "Sales").get();
    personnel->put<std::string, std::string>("Fatih", "Sales").get();
    personnel->put<std::string, std::string>("Rob", "IT").get();
    personnel->put<std::string, std::string>("Olly", "IT").get();
    std::cout << "Added all sales personnel. Logging all known personnel" << std::endl;
    for (const auto &entry : personnel.entry_set().get()) {
        std::cout << entry.first << " is in " << entry.second << " department." << std::endl;
    }
hz.shutdown().get();
return 0;
}

Output

18/11/2022 21:22:26.835 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:375] (Wed Nov 18 17:25:23 2022 +0300:3b11bea) LifecycleService::LifecycleEvent Client (75121987-12fe-4ede-860d-59222e6d3ef2) is STARTING
18/11/2022 21:22:26.835 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:379] (Wed Nov 18 17:25:23 2022 +0300:3b11bea) LifecycleService::LifecycleEvent STARTING
18/11/2022 21:22:26.835 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:387] LifecycleService::LifecycleEvent STARTED
18/11/2022 21:22:26.837 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/network.cpp:587] Trying to connect to Address[10.212.1.117:5701]
18/11/2022 21:22:26.840 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:411] LifecycleService::LifecycleEvent CLIENT_CONNECTED
18/11/2022 21:22:26.840 INFO: [139868602337152] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/network.cpp:637] Authenticated with server  Address[:5701]:a27f900e-b1eb-48be-aa46-d7a4922ef704, server version: 4.2, local address: Address[10.212.1.116:37946]
18/11/2022 21:22:26.841 INFO: [139868341360384] client_1[dev] [<i>5.x.x</i>] [/home/ihsan/hazelcast-cpp-client/hazelcast/src/hazelcast/client/spi.cpp:881]

Members [1]  {
        Member[10.212.1.117]:5701 - a27f900e-b1eb-48be-aa46-d7a4922ef704
}
Added Sales personnel. Logging all known personnel
Denise is in Sales department
Erwing is in Sales department
Fatih is in Sales department
Rob is in IT department
Olly is in IT department

This time, we added only the sales employees but we get the list of all known employees including the ones in IT. That is because our map lives in the cluster and no matter which client we use, we can access the whole map.

Use a sample project

There is an example project in the sample project directory. Run this as follows:

If you use Linux or Mac:

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake
cmake --build build
./build/client

If you use Windows:

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]\scripts\buildsystems\vcpkg.cmake && ^
cmake --build build && ^
.\build\Debug\client

The sample code creates a client, and the client automatically connects to the cluster. It creates a map named personnel_map and puts the records inside it. It then gets all the entries from the cluster and prints them.

#include <hazelcast/client/hazelcast_client.h>
int main() {
    auto hz = hazelcast::new_client().get(); // Connects to the cluster

    auto personnel = hz.get_map("personnel_map").get();
    personnel->put<std::string, std::string>("Alice", "IT").get();
    personnel->put<std::string, std::string>("Bob", "IT").get();
    personnel->put<std::string, std::string>("Clark", "IT").get();
    std::cout << "Added IT personnel. Logging all known personnel" << std::endl;
    for (const auto &entry : personnel->entry_set<std::string, std::string>().get()) {
        std::cout << entry.first << " is in " << entry.second << " department." << std::endl;
    }

    return 0;
}

Next steps

For information about supported data structures and features, and about configuring the C++ client, serialization, query support and available APIs, see the Hazelcast C++ Client GitHub repo.

For more examples, see the code samples for this client.

To learn how to get started quickly with the C++ client for Hazelcast, follow our simple tutorial Get started with C++

C++ Client

Overview

Install the C++ client

Vcpkg users

Conan users

Install from source code using CMake

Requirements

Download source code

Linux and macOS users

Windows users

Advanced installation

Custom install location

CMake configuration

Start a Hazelcast cluster

Start a Hazelcast server

Use a Hazelcast Docker images

Use Hazelcast distribution

Add user Java library to Java CLASSPATH

Compile your project

CMake users

Linux and MacOS users

Windows users

Basic configuration

Configuring Hazelcast server

Configuring Hazelcast C++ client

Cluster name

Network settings

Client system properties

Basic usage

Use a sample project

Next steps

Send us your feedback

Help and support