Skip to content

Commit 610be4b

Browse files
akeles85akeles85
authored
Readme update (#1189)
* initial commit * Update README.md * Update README.md * review fixes * Update README.md * license updated * Update README.md * Update README.md * review fixes * fixes
1 parent c7f2179 commit 610be4b

File tree

3 files changed

+180
-9
lines changed

3 files changed

+180
-9
lines changed

‎README.md

Lines changed: 153 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,166 @@
1-
[![codecov](https://codecov.io/gh/hazelcast/hazelcast-cpp-client/branch/master/graph/badge.svg)](https://codecov.io/gh/hazelcast/hazelcast-cpp-client)
1+
<p align="center">
2+
<a href="https://hazelcast.com">
3+
<img class="center" width=10% src="https://hazelcast.com/wp-content/themes/hazelcast/img/logo_login.svg" alt="logo">
4+
</a>
5+
<h2 align="center">Hazelcast C++ Client</h2>
6+
</p>
27

3-
# Async Hazelcast C++ Client
48

5-
Hazelcast is an open-source distributed in-memory data store and computation platform. It provides a wide variety of distributed data structures and concurrency primitives.
9+
<p align="center">
10+
<a href="https://hazelcastcommunity.slack.com/channels/cpp-client">
11+
<img src="https://img.shields.io/badge/slack-chat-green.svg" alt="Chat on Slack">
12+
</a>
13+
<a href="https://twitter.com/Hazelcast">
14+
<!-- markdownlint-disable-next-line MD013 -->
15+
<img src="https://img.shields.io/twitter/follow/Hazelcast.svg?style=flat-square&colorA=1da1f2&colorB=&label=Follow%20on%20Twitter" alt="Follow on Twitter">
16+
</a>
17+
<a href="LICENSE">
18+
<img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="Chat on Slack">
19+
</a>
20+
</p>
21+
22+
---
23+
24+
# What is Hazelcast?
25+
26+
[Hazelcast](https://hazelcast.com/) is a distributed computation and storage platform for consistently low-latency querying,
27+
aggregation and stateful computation against event streams and traditional data sources. It allows you to quickly build
28+
resource-efficient, real-time applications. You can deploy it at any scale from small edge devices to a large cluster of
29+
cloud instances.
30+
31+
A cluster of Hazelcast nodes share both the data storage and computational load which can dynamically scale up and down.
32+
When you add new nodes to the cluster, the data is automatically rebalanced across the cluster, and currently running
33+
computational tasks (known as jobs) snapshot their state and scale with processing guarantees.
34+
35+
For more info, check out Hazelcast [repository](https://github.com/hazelcast/hazelcast).
36+
37+
38+
# Hazelcast C++ Client
639

740
hazelcast-cpp-client is the official C++ library API for using the Hazelcast in-memory database platform. It requires C++11 support.
841

9-
The library can be installed using package managers [Conan](https://github.com/hazelcast/hazelcast-cpp-client/blob/master/Reference_Manual.md#111-conan-users) and [Vcpkg](https://github.com/hazelcast/hazelcast-cpp-client/blob/master/Reference_Manual.md#112-vcpkg-users) or directly [from source code](https://github.com/hazelcast/hazelcast-cpp-client/blob/master/Reference_Manual.md#113-install-from-source-code-using-cmake) using [CMake](https://cmake.org/).
1042

11-
* [Hazelcast Community Slack - C++ Client Channel](https://hazelcastcommunity.slack.com/channels/cpp-client)
12-
* Google Groups: https://groups.google.com/forum/#!forum/hazelcast
13-
* Stack Overflow: https://stackoverflow.com/questions/tagged/hazelcast
43+
## Installation
44+
### Hazelcast
45+
Hazelcast C++ client requires a working Hazelcast cluster to run. This cluster handles the storage and
46+
manipulation of the user data.
47+
48+
A Hazelcast cluster consists of one or more cluster members. These members generally run on multiple virtual or
49+
physical machines and are connected to each other via the network. Any data put on the cluster is partitioned to
50+
multiple members transparent to the user. It is therefore very easy to scale the system by adding new members as
51+
the data grows. Hazelcast cluster also offers resilience. Should any hardware or software problem causes a crash
52+
to any member, the data on that member is recovered from backups and the cluster continues to operate without any
53+
downtime.
54+
55+
The quickest way to start a single member cluster for development purposes is to use our
56+
[Docker images](https://hub.docker.com/r/hazelcast/hazelcast/).
57+
58+
```bash
59+
docker run -p 5701:5701 hazelcast/hazelcast
60+
```
61+
62+
This command fetches the latest Hazelcast version. You can find all available tags
63+
[here](https://hub.docker.com/r/hazelcast/hazelcast/tags).
64+
65+
You can also use our ZIP or TAR [distributions](https://hazelcast.com/open-source-projects/downloads/)
66+
as described [here](Reference_Manual.md#12-starting-hazelcast-cluster).
67+
68+
### Client
69+
70+
#### Vcpkg Users
71+
Hazelcast C++ client package is available for [Vcpkg](https://github.com/microsoft/vcpkg) users. The package name is `hazelcast-cpp-client`.
72+
73+
Please see [getting started](https://github.com/microsoft/vcpkg#getting-started) on how to use Vcpkg package manager with your application. In summary,
74+
75+
If you use Linux or Mac:
76+
77+
```sh
78+
git clone https://github.com/microsoft/vcpkg
79+
./vcpkg/bootstrap-vcpkg.sh
80+
./vcpkg/vcpkg install "hazelcast-cpp-client[openssl]" --recurse
81+
```
82+
83+
If you use Windows:
84+
85+
```bat
86+
git clone https://github.com/microsoft/vcpkg
87+
.\vcpkg\bootstrap-vcpkg.bat
88+
.\vcpkg\vcpkg install "hazelcast-cpp-client[openssl]:x64-windows" --recurse
89+
```
90+
The above code snippet will install `hazelcast-cpp-client` with its `boost` and `openssl` dependencies.
91+
92+
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`.
93+
```bat
94+
cmake -B [build directory] -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake
95+
cmake --build [build directory]
96+
```
97+
98+
##### Other Methods
99+
100+
You can also install the hazelcast-cpp-client with [conan](https://conan.io/) and from source code. You can more information from [Reference Manual](https://github.com/akeles85/hazelcast-cpp-client/blob/readme_update/Reference_Manual.md#11-installing).
101+
102+
## Overview
103+
104+
### Usage
105+
106+
There is an example project in [sample_project](https://github.com/akeles85/hazelcast-cpp-client/tree/readme_update/sample_project) directory. You can run the example as below:
107+
108+
If you use Linux or Mac:
109+
110+
```sh
111+
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake
112+
cmake --build build
113+
./build/client
114+
```
115+
116+
If you use Windows:
117+
118+
```bat
119+
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]\scripts\buildsystems\vcpkg.cmake && ^
120+
cmake --build build && ^
121+
.\build\Debug\client
122+
```
123+
124+
The sample code creates a client, the client automatically connects to the cluster.
125+
It creates a map named `personnel_map` and puts the records inside it.
126+
It then gets all the entries from the cluster and prints them.
127+
```c++
128+
#include <hazelcast/client/hazelcast_client.h>
129+
int main() {
130+
auto hz = hazelcast::new_client().get(); // Connects to the cluster
131+
132+
auto personnel = hz.get_map("personnel_map").get();
133+
personnel->put<std::string, std::string>("Alice", "IT").get();
134+
personnel->put<std::string, std::string>("Bob", "IT").get();
135+
personnel->put<std::string, std::string>("Clark", "IT").get();
136+
std::cout << "Added IT personnel. Logging all known personnel" << std::endl;
137+
for (const auto &entry : personnel->entry_set<std::string, std::string>().get()) {
138+
std::cout << entry.first << " is in " << entry.second << " department." << std::endl;
139+
}
140+
141+
return 0;
142+
}
143+
```
144+
145+
## Features
146+
147+
* Distributed, partitioned and queryable in-memory key-value store implementation, called [Map](examples/distributed-map/basic/FillMap.cpp)
148+
* Eventually consistent cache implementation to store a subset of the Map data locally in the memory of the client, called [Near Cache](examples/distributed-map/near-cache)
149+
* Additional data structures and simple messaging constructs such as [Set](examples/distributed-collections/set), [MultiMap](https://github.com/hazelcast/hazelcast-cpp-client/blob/master/examples/distributed-map/multimap/MultimapPut.cpp), [Queue](examples/distributed-collections/blockingqueue), [Topic](examples/distributed-topic)
150+
* Cluster-wide unique ID generator, called [FlakeIdGenerator](https://github.com/hazelcast/hazelcast-cpp-client/tree/master/examples/learning-basics/unique-names)
151+
* Distributed, CRDT based counter, called [PNCounter](examples/distributed-primitives/crdt-pncounter)
152+
* Distributed concurrency primitives from CP Subsystem such as [FencedLock](examples/cp/fenced_lock.cpp), [Semaphore](examples/cp/counting_semphore.cpp), [AtomicLong](examples/cp/atomic_long.cpp)
153+
* Integration with [Viridian](https://viridian.hazelcast.com/) (Hazelcast Cloud)
154+
* Support for serverless and traditional web service architectures with **Unisocket** and **Smart** operation modes
155+
* Ability to listen client lifecycle, cluster state and distributed data structure events
156+
* and [many more](https://hazelcast.com/clients/cplusplus/#client-features).
14157

15158
## Documentation
16159

17160
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).
18161

19-
## License
162+
## Copyright
20163

21-
hazelcast-cpp-client library is an open source project using the [Apache 2 License](https://github.com/hazelcast/hazelcast-cpp-client/blob/master/LICENSE).
164+
Copyright (c) 2008-2023, Hazelcast, Inc. All Rights Reserved.
22165

166+
Visit [www.hazelcast.com](http://www.hazelcast.com) for more information.

‎sample_project/CMakeLists.txt

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
cmake_minimum_required(VERSION 3.10)
2+
3+
project(HazelcastClientSample)
4+
5+
set(CMAKE_CXX_STANDARD 11)
6+
set(CMAKE_CXX_STANDARD_REQUIRED ON)
7+
8+
find_package(hazelcast-cpp-client CONFIG REQUIRED)
9+
10+
11+
add_executable(client client.cpp)
12+
target_link_libraries(client PRIVATE hazelcast-cpp-client::hazelcast-cpp-client)

‎sample_project/client.cpp

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#include <hazelcast/client/hazelcast_client.h>
2+
int main() {
3+
auto hz = hazelcast::new_client().get(); // Connects to the cluster
4+
5+
auto personel = hz.get_map("personel_map").get();
6+
personel->put<std::string, std::string>("Alice", "IT").get();
7+
personel->put<std::string, std::string>("Bob", "IT").get();
8+
personel->put<std::string, std::string>("Clark", "IT").get();
9+
std::cout << "Added IT personel. Logging all known personel" << std::endl;
10+
for (const auto &entry : personel->entry_set<std::string, std::string>().get()) {
11+
std::cout << entry.first << " is in " << entry.second << " department." << std::endl;
12+
}
13+
14+
return 0;
15+
}

0 commit comments

Comments
 (0)