Clients

Hazelcast C++ Client

Extend the benefits of real-time data platform to your C++ applications running in Linux, Windows, and macOS.

  • Use the Hazelcast Near Cache feature to store frequently read data in your C++ process. This provides faster read speeds than traditional caches such as Redis or Memcached.
  • Access all of the Hazelcast data structures plus distributed queues, topics, and more with the Hazelcast IMDG C++ Client.
  • Provides SSL support for your enterprise-level security requirements.
  • Ability to discover the existing Hazelcast clusters in an AWS environment.
  • Asynchronously execute your tasks in the cluster, such as database queries, complex calculations, and image rendering.
  • Non-blocking asynchronous methods for more powerful operations like batched writing or reading.
  • Ability to send multiple requests in parallel using a single thread via Pipelining API, which increases the throughput

Quick Start + Download

Quick Start

You can use Conan or Vcpkg to install Hazelcast C++ Client. Also, you can install it from the source code using CMake.
Please see the documentation for all options.

Conan
You need to put the following lines to your conanfile.txt:

[requires]
hazelcast-cpp-client/5.0.0
[generators]
cmake

Then, you execute the following:

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

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

Vcpkg
The port name is hazelcast-cpp-client.

> git clone https://github.com/microsoft/vcpkg
> .\vcpkg\bootstrap-vcpkg.bat
> .\vcpkg\vcpkg install hazelcast-cpp-client

The above code snippet will install hazelcast-cpp-client with its boost dependencies.

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=https://hazelcast.com/wp-content/themes/hazelcast/scripts/buildsystems/vcpkg.cmake
> cmake --build [build directory]
Downloads
Version Downloads Documentation
Hazelcast IMDG C++ Client 5.0.0 (latest)
10/18/2021
Hazelcast IMDG C++ Client 4.2.1
08/11/2022
Hazelcast IMDG C++ Client 4.2.0
08/31/2021
Hazelcast IMDG C++ Client 4.1.1
05/26/2021

For all downloads please see the Download Archives

Previous Releases

Code Samples

#include <hazelcast/client/hazelcast.h>

    using namespace hazelcast::client;
    int main() {
    // Start the Hazelcast Client and connect to an already running Hazelcast Cluster on 127.0.0.1
      hazelcast_client hz;
    // Get the Distributed Map from Cluster.
    auto map = hz.get_map("my-distributed-map").get();
    //Standard Put and Get.
      map->put("key", "value").get();
      map->get("key").get();
    //Concurrent Map methods, optimistic updating
      map->put_if_absent("somekey", "somevalue").get();
    // use deferred future continuation
    auto future = map->replace("key", "value", "newvalue").then(
      boost::launch::deferred, [] (boost::future f) {
    if (f.get()) {
      std::cout << "Replaced successfully\n";
    return;
    }
      std::cerr << "Failed to replace\n";
    });

    // Wait until replace is completed
      future.get();

    // Shutdown this Hazelcast Client
      hz.shutdown();

    return 0;
    }
  
Get this code sample on Github
#include <hazelcast/client/hazelcast.h>

  using namespace hazelcast::client;
  int main() {
      // Start the Hazelcast Client and connect to an already running Hazelcast Cluster on 127.0.0.1
      hazelcast_client hz;
      // Get a Blocking Queue called "my-distributed-queue"
      auto queue = hz.get_queue("my-distributed-queue").get();
      // Offer a String into the Distributed Queue
      queue->offer("item").get();
      // Poll the Distributed Queue and return the String
      auto item = queue->poll().get();
      //Timed blocking Operations
      queue->offer("anotheritem", std::chrono::milliseconds(500)).get();
      auto anotherItem = queue->poll(std::chrono::seconds(5)).get();
      //Indefinitely blocking Operations
      queue->put("yetanotheritem");
      std::cout <take().get() << std::endl;
      // Shutdown this Hazelcast Client
      hz.shutdown();
  
      return 0;
  }
Get this code sample on Github
#include <hazelcast/client/hazelcast.h>

using namespace hazelcast::client;

int main() {
    // Start the Hazelcast Client and connect to an already running Hazelcast Cluster on 127.0.0.1
    hazelcast_client hz;
    // Get a Topic called "my-distributed-topic"
    auto topic = hz.get_topic("my-distributed-topic").get();
    // Add a Listener to the Topic
    topic->add_message_listener(
        topic::listener().
            on_received([](topic::message &&message) {
                std::cout << "Got message " << message.get_message_object().get().value_or("null") <publish("Hello to distributed world").get();
    // Shutdown this Hazelcast Client
    hz.shutdown();

    return 0;
}
Get this code sample on Github
#include <hazelcast/client/hazelcast.h>

using namespace hazelcast::client;
int main() {
    // Start the Hazelcast Client and connect to an already running Hazelcast Cluster on 127.0.0.1
    hazelcast_client hz;
    // Get the Distributed List from Cluster.
    auto list = hz.get_list("my-distributed-list").get();
    // Add elements to the list
    list->add("item1").get();
    // Using future continuation here so that the calls are not blocking
    auto f = list->add("item2").then(boost::launch::deferred, [=] (boost::future f) {
       if (!f.get()) {
           std::cerr << "Element 2 could not be added !!!\n";
           return;
       }

        std::cout << std::boolalpha;
        // Remove the first element
        std::cout << "Removed: " <remove(0).get();
        // There is only one element left
        std::cout << "Current size is " <size().get() <clear().get();
    });

    // make the deferred future execute
    f.get();

    // Shutdown this Hazelcast Client
    hz.shutdown();

    return 0;
}
Get this code sample on Github
#include <hazelcast/client/hazelcast.h>

using namespace hazelcast::client;
int main() {
    // Start the Hazelcast Client and connect to an already running Hazelcast Cluster on 127.0.0.1
    hazelcast_client hz;
    // Get a Replicated Map called "my-replicated-map"
    auto map = hz.get_replicated_map("my-replicated-map").get();
    // Add items to the set with duplicates
    // Put and Get a value from the Replicated Map
    auto replacedValue = map->put("key", "value").get();
    // key/value replicated to all members
    std::cout << "replacedValue = " <get("key").get();
    // the value is retrieved from a random member in the cluster
    std::cout << "value for key = " << value.value_or("null");
    // Shutdown this Hazelcast Client
    hz.shutdown();

    return 0;
}
Get this code sample on Github
#include <hazelcast/client/hazelcast.h>

using namespace hazelcast::client;
int main() {
    // Start the Hazelcast Client and connect to an already running Hazelcast Cluster on 127.0.0.1
    hazelcast_client hz;
    // Get the Distributed Set from Cluster.
    auto set = hz.get_set("my-distributed-set").get();
    // Add items to the set with duplicates
    set->add("item1").get();
    set->add("item1").get();
    set->add("item2").get();
    set->add("item2").get();
    set->add("item2").get();
    set->add("item3").get();
    // Get the items. Note that there are no duplicates.
    auto future = set->to_array().then(boost::launch::deferred, [] (boost::future<std::vector> f) {
        for(auto &v : f.get()) {
            std::cout << v << '\n';
        }
    });

    // do something else
    //...
    // print the output
    future.get();

    // Shutdown this Hazelcast Client
    hz.shutdown();

    return 0;
}
Get this code sample on Github
#include <hazelcast/client/hazelcast.h>

using namespace hazelcast::client;
int main() {
    // Start the Hazelcast Client and connect to an already running Hazelcast Cluster on 127.0.0.1
    hazelcast_client hz;
    // Get the Distributed MultiMap from Cluster.
    auto multiMap = hz.get_multi_map("my-distributed-multimap").get();
    // Put values in the map against the same key
    multiMap->put("my-key", "value1").get();
    multiMap->put("my-key", "value2").get();
    multiMap->put("my-key", "value3").get();
    // Print out all the values for associated with key called "my-key"
    multiMap->get("my-key").then(boost::launch::deferred,[] (boost::future<std::vector> f) {
        for (auto &value : f.get()) {
            std::cout << value <remove("my-key", "value2").get();    // Shutdown this Hazelcast Client
    hz.shutdown();

    return 0;
}
Get this code sample on Github
#include <hazelcast/client/hazelcast.h>

using namespace hazelcast::client;
int main() {
    // Start the Hazelcast Client and connect to an already running Hazelcast Cluster on 127.0.0.1
    hazelcast_client hz;
    auto rb = hz.get_ringbuffer("rb").get();
    // add two items into ring buffer
    rb->add(100).get();
    rb->add(200).get();
    // we start from the oldest item.
    // if you want to start from the next item, call rb.tailSequence()+1
    int64_t sequence = rb->head_sequence().get();
    std::cout <read_one(sequence).get() << std::endl;
    sequence++;
    std::cout <read_one(sequence).get() << std::endl;
    // Shutdown this Hazelcast Client
    hz.shutdown();
}
Get this code sample on Github

Roadmap

Upcoming C++ Client Features
  • SQL Support: Ability to query data stored in Hazelcast Map using SQL language declaratively.
  • Hazelcast Serialization 2.0 Support (Beta): Querying friendly and space efficient serialization that has high usability.
Recently Released C++ Client Features
  • Mutual Authentication: The process where the client verifies the identity of the server via server’s certificate and the server verifies the client identity via the client provided certificate.
  • Hazelcast Cloud Discovery: Ability to use Hazelcast Cloud via Hazelcast C++ client.
  • Availability in Conan and vcpkg package managers.
  • Hazelcast IMDG 4.0 Changes: Client protocol enhancements, architectural improvements, Serialization improvements.
  • C++11 Support: The client code has been upgraded to use the C++11 features. The API has been changed to reflect the C++11 usages.
  • Idiomatic API: Redesign of the API in a way that C++ developers used to.
  • Fully Async API: Almost all API methods now return boost::future which allows async programming for all the API calls.
  • CP Subsystem Support: New Concurrency APIs including FencedLock, AtomicLong, Semaphore, CountDownLatch, and AtomicReference.
  • Backup Acknowledgment: Significantly improved client performance by eliminating the sync backup wait from the client and send the backup ACK to the client.
  • Ownerless Client: Simpler design to track member leaves and joins to the cluster.

Features Implemented for this Client

Data Structures
C++ Client

Map

Queue

Set

List

MultiMap

Replicated Map

Ring Buffer

Topic

Reliable Topic

JCache

N/A

Cardinality Estimator

Concurrency Primitives
C++ Client

Lock

Condition

Semaphore

AtomicLong

AtomicReference

ID Generator

CountDownLatch

CRDT PN Counter

Flake ID Generator

Distributed Processing
C++ Client

Distributed Executor Service

Event Listeners

Sub-Listener Interfaces for Map Listener

Entry Processor

Transactions
C++ Client

TxnMap

TxnMultiMap

TxnQueue

TxnList

TxnSet

Query
C++ Client

Query (Predicates)

Paging Predicates

Partition Predicates

Built-in Predicates

Continuous Query Caching

N/A

Listener with Predicate

Projections

Fast Aggregations

Near Cache
C++ Client

Near Cache Support

HD Memory

N/A

Preload Cache from Last Used

Eventual Consistency Control

Configuration
C++ Client

Declarative Configuration (XML/JSON/YAML)

Programmatic Configuration

Client Configuration Import

Fail Fast on Invalid Configuration

Security
C++ Client

SSL Support

XA Transactions

Mutual Authentication

Authorization

Custom Authentication Modules

Management Center
C++ Client

Management Center Integration / Awareness

Client Near Cache Stats

Client Runtime Stats

Client Operating System Stats

Cloud
C++ Client

Hazelcast Cloud

Management Center Integration / Awareness

Kubernetes

AWS

Azure

Google Cloud Platform

Pivotal Cloud Foundry

Docker

Apache jclouds

Consul

etcd

Eureka

Heroku

Zookeeper

Infrastructure
C++ Client

Open Client Protocol

Smart Client

Unisocket Client

Lifecycle Service

HeartBeat

Backup Acknowledgement to Client

Diagnostics

Serialization
C++ Client

DataSerializable

N/A

IdentifiedDataSerializable

Portable Serialization

Custom Serialization

Global Serialization

Client Connectivity
C++ Client

Connection Strategy

Connection Retry

Blue/Green Deployments and Disaster Recovery