diff --git a/README.md b/README.md index 286931788..6afe9a1df 100644 --- a/README.md +++ b/README.md @@ -32,115 +32,15 @@ A cluster of Hazelcast nodes share both the data storage and computational load When you add new nodes to the cluster, the data is automatically rebalanced across the cluster, and currently running computational tasks (known as jobs) snapshot their state and scale with processing guarantees. -For more info, check out Hazelcast [repository](https://github.com/hazelcast/hazelcast). +For more information, see the Hazelcast [repository](https://github.com/hazelcast/hazelcast). # Hazelcast C++ Client -hazelcast-cpp-client is the official C++ library API for using the Hazelcast in-memory database platform. It requires C++11 support. - - -## Installation -### Hazelcast -Hazelcast C++ client requires a working Hazelcast cluster to run. This cluster handles the storage and -manipulation of the user 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 transparent to the user. It is therefore very easy to scale the system by adding new members as -the data grows. Hazelcast cluster also offers 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. - -The quickest way to start a single member cluster for development purposes is to use our -[Docker images](https://hub.docker.com/r/hazelcast/hazelcast/). - -```bash -docker run -p 5701:5701 hazelcast/hazelcast -``` - -This command fetches the latest Hazelcast version. You can find all available tags -[here](https://hub.docker.com/r/hazelcast/hazelcast/tags). - -You can also use our ZIP or TAR [distributions](https://hazelcast.com/open-source-projects/downloads/) -as described [here](Reference_Manual.md#12-starting-a-hazelcast-cluster). - -### Client - -#### Vcpkg Users -Hazelcast C++ client package is available for [Vcpkg](https://github.com/microsoft/vcpkg) users. The package name is `hazelcast-cpp-client`. - -Please see [getting started](https://github.com/microsoft/vcpkg#getting-started) on how to use Vcpkg package manager with your application. In summary, - -If you use Linux or Mac: - -```sh -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: +For an introduction to the C++ client for Hazelcast, and information on how to install and get started with the client, see the [Hazelcast documentation](https://docs.hazelcast.com/hazelcast/latest/clients/cplusplus). -```bat -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 will install `hazelcast-cpp-client` with its `boost` and `openssl` 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`. -```bat -cmake -B [build directory] -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake -cmake --build [build directory] -``` - -##### Other Methods - -You can also install the hazelcast-cpp-client with [conan](https://conan.io/) and from source code. You can more information from [Reference Manual](Reference_Manual.md#11-installing). - -## Overview - -### Usage - -There is an example project in the [sample_project](sample_project) directory. You can run the example as below: - -If you use Linux or Mac: - -```sh -cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake -cmake --build build -./build/client -``` - -If you use Windows: - -```bat -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, 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. -```c++ -#include -int main() { - auto hz = hazelcast::new_client().get(); // Connects to the cluster +hazelcast-cpp-client is the official C++ library API for using the Hazelcast in-memory database platform. It requires C++11 support. - auto personnel = hz.get_map("personnel_map").get(); - personnel->put("Alice", "IT").get(); - personnel->put("Bob", "IT").get(); - personnel->put("Clark", "IT").get(); - std::cout << "Added IT 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; - } - - return 0; -} -``` ## Features @@ -157,7 +57,12 @@ int main() { ## Documentation -You can find the detailed documentation at the [documentation site](https://hazelcast.github.io/hazelcast-cpp-client/doc-index.html) and the [API reference](https://hazelcast.github.io/hazelcast-cpp-client/api-index.html). +For information about: + +* how to install and get started with the client, see the [Hazelcast documentation](https://docs.hazelcast.com/hazelcast/latest/clients/cplusplus) +* how to configure and use the C++ client, see the Reference Manual in this repo +* the API, see the [API reference](https://hazelcast.github.io/hazelcast-cpp-client/api-index.html) + ## Copyright diff --git a/Reference_Manual.md.in b/Reference_Manual.md.in index 10f8e114d..14f8c693a 100644 --- a/Reference_Manual.md.in +++ b/Reference_Manual.md.in @@ -12,34 +12,6 @@ * [Resources](#resources) * [Release Notes](#release-notes) * [1. Getting Started](#1-getting-started) - * [1.1. Installing](#11-installing) - * [1.1.1. Vcpkg Users](#111-vcpkg-users) - * [1.1.2. Conan Users](#112-conan-users) - * [1.1.3. Install From Source Code Using CMake](#113-install-from-source-code-using-cmake) - * [1.1.3.1. Requirements](#1131-requirements) - * [1.1.3.2. Downloading Source Code](#1132-downloading-source-code) - * [1.1.3.3. Linux and MacOS Users](#1133-linux-and-macos-users) - * [1.1.3.4. Windows Users](#1134-windows-users) - * [1.1.3.5. Advanced Installation](#1135-advanced-installation) - * [1.1.3.5.1. Custom Install Location](#11351-custom-install-location) - * [1.1.3.5.2. CMake Configuration](#11352-cmake-configuration) - * [1.2. Starting a Hazelcast Cluster](#12-starting-a-hazelcast-cluster) - * [1.2.1. Starting Hazelcast Server](#121-starting-hazelcast-server) - * [1.2.1.1. Starting Server Using Hazelcast Docker Images](#1211-starting-server-using-hazelcast-docker-images) - * [1.2.1.2. Starting Server Using Hazelcast Distribution](#1212-starting-server-using-hazelcast-distribution) - * [1.2.1.3. Adding User Java Library to Java CLASSPATH](#1213-adding-user-java-library-to-java-classpath) - * [1.3. Compiling Your Project](#13-compiling-your-project) - * [1.3.1. CMake Users](#131-cmake-users) - * [1.3.2. Linux and MacOS Users](#132-linux-and-macos-users) - * [1.3.3. Windows Users](#133-windows-users) - * [1.4. Basic Configuration](#14-basic-configuration) - * [1.4.1. Configuring Hazelcast Server](#141-configuring-hazelcast-server) - * [1.4.2. Configuring Hazelcast C++ Client](#142-configuring-hazelcast-c-client) - * [1.4.2.1 Cluster Name](#1421-cluster-name) - * [1.4.2.2. Network Settings](#1422-network-settings) - * [1.4.3. Client System Properties](#143-client-system-properties) - * [1.5. Basic Usage](#15-basic-usage) - * [1.6. Code Samples](#16-code-samples) * [2. Features](#2-features) * [3. Configuration Overview](#3-configuration-overview) * [3.1. Configuration Options](#31-configuration-options) @@ -170,16 +142,17 @@ # Introduction -This document provides information about the C++ client for [Hazelcast](https://hazelcast.com/). This client uses Hazelcast's [Open Client Protocol](https://github.com/hazelcast/hazelcast-client-protocol) and works with Hazelcast 4.0 and higher versions. +This document provides information about how to configure and use the C++ client for [Hazelcast](https://hazelcast.com/). +Serialization, network-related configuration, and securing the client connection are also described. -The client API is fully asynchronous. The API returns `boost::future` API which has the capability of [continuations](https://www.boost.org/doc/libs/1_74_0/doc/html/thread/synchronization.html#thread.synchronization.futures.then). If the user wants to make sure that the requested operation is completed in the cluster and committed in the distributed database, he/she needs to wait for the result of the future. +For an introduction to the C++ client for Hazelcast, and information on how to install and get started with the client, see the [Hazelcast documentation](https://docs.hazelcast.com/hazelcast/latest/clients/cplusplus). # Resources -See the following for more information on Hazelcast: +For more information about Hazelcast, see the: * Hazelcast [website](https://hazelcast.com) -* Hazelcast [Reference Manual](https://docs.hazelcast.com/hazelcast/latest) +* Hazelcast [documentation](https://docs.hazelcast.com/hazelcast/latest) # Release Notes @@ -187,584 +160,9 @@ See the [Releases](https://github.com/hazelcast/hazelcast-cpp-client/releases) p # 1. Getting Started -This chapter provides information on how to get started with your Hazelcast C++ client. It outlines the requirements, installation and configuration of the client, setting up a cluster, and provides a simple application that uses a distributed map with the C++ client. +For information about how to install and get started with the C++ client for Hazelcast, see the [Hazelcast documentation](https://docs.hazelcast.com/hazelcast/latest/clients/cplusplus). -## 1.1. Installing - -### 1.1.1. Vcpkg Users -Hazelcast C++ client package is available for [Vcpkg](https://github.com/microsoft/vcpkg) users. The package name is `hazelcast-cpp-client`. - -Please see [getting started](https://github.com/microsoft/vcpkg#getting-started) on how to use Vcpkg package manager with your application. In summary, - -If you use Linux or Mac: - -```sh -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: - -```bat -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 will install `hazelcast-cpp-client` with its `boost` and `openssl` 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`. -```bat -cmake -B [build directory] -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake -cmake --build [build directory] -``` - -### 1.1.2. Conan Users -Hazelcast C++ client package is indexed at [Conan Center Index](https://conan.io/center/hazelcast-cpp-client). You can use [Conan package manager](https://conan.io/) to install Hazelcast C++ client. The package name is `hazelcast-cpp-client`. - -Please see [example instructions](https://docs.conan.io/en/latest/getting_started.html#an-md5-hash-calculator-using-the-poco-libraries) on how to use conan package manager with your application. In summary, - -- You need to put the following lines to your `conanfile.txt`: -``` -[requires] -hazelcast-cpp-client/@PROJECT_VERSION@ - -[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](https://docs.conan.io/en/latest/getting_started.html#an-md5-hash-calculator-using-the-poco-libraries) and build your application. - -### 1.1.3. Install From Source Code Using CMake -#### 1.1.3.1. Requirements -1. Linux, macOS or Windows -2. A compiler that supports C++11 -3. [CMake](https://cmake.org) 3.10 or above -4. [Boost](https://www.boost.org) 1.71 or above. Minimum boost version is upgraded to 1.73 for Windows due to [this](https://github.com/chriskohlhoff/asio/issues/431) bug. -5. [OpenSSL](https://www.openssl.org) (optional) - -#### 1.1.3.2. Downloading Source Code -Go to the [releases](https://github.com/hazelcast/hazelcast-cpp-client/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 which suits your system the best. - -Follow the instructions for your platform: -* [Linux and MacOS](#1133-linux-and-macos-users) -* [Windows](#1134-windows-users) - -#### 1.1.3.3. Linux and MacOS Users -Here is how you download and extract version @PROJECT_VERSION@ using the **curl** command: -```sh -curl -Lo hazelcast-cpp-client-@PROJECT_VERSION@.tar.gz https://github.com/hazelcast/hazelcast-cpp-client/archive/v@PROJECT_VERSION@.tar.gz -tar xzf hazelcast-cpp-client-@PROJECT_VERSION@.tar.gz -``` - -Alternatively, you may clone the repository and checkout a specific version: -```sh -git clone https://github.com/hazelcast/hazelcast-cpp-client.git -cd hazelcast-cpp-client -git checkout v@PROJECT_VERSION@ -``` - -Once you are in the source directory of the Hazelcast C++ client library, create and change into a new directory: -```sh -cd hazelcast-cpp-client-@PROJECT_VERSION@ -mkdir build -cd build -``` - -Run `cmake` (or `cmake3` if you are on CentOS or RHEL) to configure: -```sh -cmake .. -``` -See the [advanced installation](#1135-advanced-installation) section for configuration options. - -Run `cmake` again to build and install the library: -```sh -cmake --build . -sudo cmake --build . --target install -``` - -You could speed up the build process with parallel threads like 'cmake --build . -j 4' - -See [this section](#11351-custom-install-location) for information on how to use a different installation location. - -#### 1.1.3.4. Windows Users -Download and extract the release archive from the -[releases](https://github.com/hazelcast/hazelcast-cpp-client/releases) page. - -Open a `cmd` window and change into the folder where you extracted the contents of the release archive. Then create and change into a new directory: -```bat -cd hazelcast-cpp-client-@PROJECT_VERSION@ -mkdir build -cd build -``` - -Run `cmake` to configure: -```bat -cmake .. -``` -See the [advanced installation](#1135-advanced-installation) section for configuration options. - -Build and install: -```bat -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 [this section](#11351-custom-install-location) for information on how to use a different installation location. - -#### 1.1.3.5. Advanced Installation - -##### 1.1.3.5.1. Custom Install Location -Pass the argument `-DCMAKE_INSTALL_PREFIX=/path/to/install` the first time you run `cmake` to configure the installation directory: -```sh -cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install -``` - -##### 1.1.3.5.2. CMake Configuration -You can provide additional configuration options using the `-DVARIABLE=VALUE` syntax on the command line. Here are all the options that are supported: -* `WITH_OPENSSL` : Set to `ON` to build the library with SSL support. -This will require [OpenSSL](https://www.openssl.org) 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, you can use the following command: - -```sh -cmake .. -DWITH_OPENSSL=ON -DBUILD_SHARED_LIBS=OFF -``` - -Note that, if you want to use the `hazelcast-cpp-client` library with `-DWITH_OPENSSL=ON` option without `find_package()` then you need to define `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 cmake command as `-DVARIABLE=VALUE` pairs. - -For example: -```sh -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 -``` - -## 1.2. Starting 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 network. Any data put on the cluster is partitioned to multiple members transparent to the user. It is therefore very 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. Hazelcast clients are an easy way to connect to a Hazelcast cluster and perform tasks on distributed data structures that live on the cluster. - -In order to use the Hazelcast C++ client, we first need to setup a Hazelcast server. - -### 1.2.1. Starting Hazelcast Server - -#### 1.2.1.1. Starting Server Using Hazelcast Docker Images - -The quickest way to start a single member cluster for development purposes is to use our [Docker images](https://hub.docker.com/r/hazelcast/hazelcast/). - -```bash -docker run -p 5701:5701 hazelcast/hazelcast:latest -``` - -#### 1.2.1.2. Starting Server Using Hazelcast Distribution - -Follow the instructions below to create a Hazelcast cluster: - -1. Go to Hazelcast's download [page](https://hazelcast.com/open-source-projects/downloads/) and download either the `.zip` or `.tar` distribution of Hazelcast. -2. Decompress the contents into any directory that you want to run members from. -3. Change into the directory that you decompressed the Hazelcast content and then into the `bin` directory. -4. 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] [5.x.x]
-
-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] [5.x.x] [192.168.1.112]:5701 is STARTED
-
- -#### 1.2.1.3. Adding User Java Library to Java CLASSPATH - -When you want to use features such as querying and language interoperability, you might 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-.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`. - -Note that if you are adding an `IdentifiedDataSerializable` or a `Portable` class, you need to add its factory too. Then, you should configure the factory in the `hazelcast.xml` configuration file. This file resides in the `bin` directory where you extracted the `hazelcast-.zip` (or `tar`). - -The following is an example configuration when you are adding an `IdentifiedDataSerializable` class: - -```xml - - ... - - - - com.hazelcast.client.test.IdentifiedFactory - - - - ... - -``` -If you want to add a `Portable` class, you should use `` instead of `` in the above configuration. - -See the [Hazelcast Reference Manual](https://docs.hazelcast.com/hazelcast/latest) for more information on setting up the clusters. - -### 1.3. Compiling Your Project - -If you are using CMake, see the section for [CMake users](#131-cmake-users). - -If you are not, then read the instructions specific to your platform: -* [Linux and MacOS](#132-linux-and-macos-users) -* [Windows](#133-windows-users) - -#### 1.3.1. 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: -```cmake -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. - -#### 1.3.2. 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. - -Here is how you can compile an example from the examples directory: -```sh -g++ -std=c++11 \ - examples/path/to/example.cpp \ - -DBOOST_THREAD_VERSION=5 \ - -lhazelcast-cpp-client -lboost_thread -lboost_chrono -lssl -lcrypto -``` - -If your enviroment could not find openssl library, you could define it like below (As an example: `-L/opt/homebrew/Cellar/openssl@1.1/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/openssl@1.1/1.1.1t/lib -``` - -If a custom installation directory was used during installation, then 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 -``` - -#### 1.3.3. 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. - -The following is a command that can be used to compile an example from the examples directory. -```bat -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 -``` - -## 1.4. Basic Configuration - -If you are using Hazelcast and the Hazelcast C++ Client on the same computer, generally the default configuration should be fine. This is great 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 configurations 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 properly connect to the cluster. - -This section describes the most common configuration elements to get you started in no time. It discusses some member side configuration options to ease the understanding of Hazelcast's ecosystem. Then, the client side configuration options regarding the cluster connection are discussed. The configurations for the Hazelcast data structures that can be used in the C++ client are discussed in the following sections. - -See the [Hazelcast Reference Manual](https://docs.hazelcast.com/hazelcast/latest) and [Configuration Overview section](#3-configuration-overview) for more information. - -### 1.4.1. 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 configure them according to your needs. We will show you the basics of network configuration here. - -You can use the following options to configure Hazelcast: - -* Using the `hazelcast.xml` configuration file. -* Programmatically configuring 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-.zip` (or `tar`), you see the `hazelcast.xml` 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. - -```xml - - dev - - - 5701 - - - 224.2.2.3 - 54327 - - - 127.0.0.1 - - 127.0.0.1 - - - - - - - - 1 - - -``` - -We will go over some important configuration elements in the rest of this section. - -- ``: Specifies which cluster this member belongs to. - -- `` - - ``: 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. - - ``: 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`. - - ``: Members find each other by sending multicast requests to the specified address and port. It is very useful if IP addresses of the members are not static. - - ``: 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. Now we will move onto the configuration of the C++ client. - -### 1.4.2. Configuring Hazelcast C++ Client - -You must configure a Hazelcast C++ Client programmatically. Config files of any type are not yet supported for the C++ client. - -You can start the client with no custom configuration like this: - -```c++ - 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 section](#3-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. - -```c++ - 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, then you need to make certain changes to the network settings of your client. - -### 1.4.2.1 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). - -```c++ -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. -``` - -### 1.4.2.2. 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. - -```c++ -hazelcast::client::client_config config; -config.get_network_config().add_address(hazelcast::client::address("your server ip", 5701 /* your server port*/)); -``` -### 1.4.3. 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:** - -```c++ -config.set_property(hazelcast::client::client_properties::INVOCATION_TIMEOUT_SECONDS, "2") // Sets invocation timeout as 2 seconds -``` - -or - -```c++ -config.set_property("hazelcast.client.invocation.timeout.seconds", "2") // Sets invocation timeout as 2 seconds -``` - -**By using an environment variable on Linux:** - -```sh -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](hazelcast/include/hazelcast/client/client_properties.h), along with their descriptions, which can be used to configure your Hazelcast C++ client. - -## 1.5. 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. - -```c++ -#include -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 should print 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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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** - -Let's 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): - -```c++ -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** - -```c++ -#include -int main() { - auto hz = hazelcast::new_client().get(); // Connects to the cluster - - auto personnel = hz.get_map("personnel_map").get(); - personnel->put("Alice", "IT").get(); - personnel->put("Bob", "IT").get(); - personnel->put("Clark", "IT").get(); - std::cout << "Added IT 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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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
-Alice is in IT department
-Clark is in IT department
-Bob is in IT department
-
- -You see 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:** - -```c++ -g++ Sales.cpp -o Sales -lhazelcast-cpp-client -lboost_thread -lboost_chrono -DBOOST_THREAD_VERSION=5 -lssl -lcrypto --std=c++11 -``` -**Run** - -Then, you can run the application using the following command: - -``` -./Sales -``` - -**Sales.cpp** - -```c++ -#include -int main() { -auto hz = hazelcast::new_client().get(); // Connects to the cluster - -auto personnel = hz.get_map("personnel_map").get(); - personnel->put("Denise", "Sales").get(); - personnel->put("Erwing", "Sales").get(); - personnel->put("Fatih", "Sales").get(); - personnel->put("Bob", "IT").get(); - personnel->put("Clark", "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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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] [5.x.x] [/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
-Bob is in IT department
-Clark is in IT department
-
- -You will see this time we add only the sales employees but we get the list 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. - -## 1.6. Code Samples - -See the Hazelcast C++ [code samples](examples) for more examples. +For examples, see the Hazelcast C++ [code samples](examples). # 2. Features