Skip to content
This repository was archived by the owner on Apr 11, 2025. It is now read-only.

Commit 75b7538

Browse files
ihsandemirihsandemir
authored
Merge pull request #1 from hakanaktas0/master
Cpp getting started guide is added.
2 parents f76faa1 + bd7c101 commit 75b7538

File tree

3 files changed

+220
-58
lines changed

3 files changed

+220
-58
lines changed

‎README.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
// Replace <filename> with the name of your repository, and replace <tutorial name> with the title of the tutorial.
22
// For guidance on using this template, see .github/CONTRIBUTING.adoc
3-
This repository hosts the documentation and code samples for the link:https://docs.hazelcast.com/tutorials/<filename>[<tutorial name> tutorial].
3+
This repository hosts the documentation and code samples for the link:https://docs.hazelcast.com/tutorials/cpp-client-getting-started[C++ Client Getting Started tutorial].

‎docs/modules/ROOT/pages/cpp-client-getting-started.adoc

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
= Getting Started with the Hazelcast C++ Client
2+
:page-layout: tutorial
3+
:page-product: platform
4+
:page-categories: Caching, Getting Started
5+
:page-lang: cplus
6+
:page-est-time: 5-10 mins
7+
:description: This tutorial will get you started with the Hazelcast C++ client.
8+
9+
== What You'll Learn
10+
11+
{description}
12+
13+
== Before you Begin
14+
15+
* A text editor or IDE
16+
* Docker
17+
* C++ 11+ supporting compiler
18+
* Vcpkg
19+
20+
== Start a Hazelcast Member
21+
22+
We will use the 5.1 version of Hazelcast for this tutorial.
23+
24+
In this tutorial, we will use Docker for simplicity. You can also use https://docs.hazelcast.com/hazelcast/5.1/getting-started/get-started-cli[CLI], https://docs.hazelcast.com/hazelcast/5.1/getting-started/get-started-binary[Binary] and https://docs.hazelcast.com/hazelcast/5.1/getting-started/get-started-java[Maven].
25+
26+
[source,bash]
27+
----
28+
docker run -p 5701:5701 hazelcast/hazelcast:5.1
29+
----
30+
31+
This will start a new Hazelcast member at port 5701. Now, we have a Hazelcast cluster with just one member.
32+
33+
== Install Hazelcast C++ Client
34+
In this tutorial we will use Vcpkg for installing the C++ client. You can also use https://github.com/hazelcast/hazelcast-cpp-client/blob/master/Reference_Manual.md#111-conan-users[Conan] or install from source using CMake as explained https://github.com/hazelcast/hazelcast-cpp-client/blob/master/Reference_Manual.md#113-install-from-source-code-using-cmake[here].
35+
36+
37+
Before starting download and install Vcpkg itself if you haven't already: +
38+
for Windows;
39+
[source,bash]
40+
----
41+
git clone https://github.com/microsoft/vcpkg
42+
.\vcpkg\bootstrap-vcpkg.bat
43+
----
44+
45+
for non-Windows;
46+
[source,bash]
47+
----
48+
git clone https://github.com/microsoft/vcpkg
49+
./vcpkg/bootstrap-vcpkg.sh
50+
----
51+
First, execute the following to install `hazelcast-cpp-client` with its `boost` dependency: +
52+
for Windows;
53+
[source,bash]
54+
----
55+
.\vcpkg\vcpkg.exe install hazelcast-cpp-client
56+
----
57+
for non-Windows;
58+
[source,bash]
59+
----
60+
./vcpkg/vcpkg install hazelcast-cpp-client
61+
----
62+
63+
After the installation, the library is available for usage.
64+
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`.
65+
66+
[source,bash]
67+
----
68+
cmake -B [build directory] -S . -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake
69+
cmake --build [build directory]
70+
----
71+
For more information about Vcpkg installation check https://github.com/hazelcast/hazelcast-cpp-client/blob/master/Reference_Manual.md#112-vcpkg-users[here].
72+
73+
== Starting the C++ Client
74+
In this tutorial we use CMake for compilation, for other options you can check https://github.com/hazelcast/hazelcast-cpp-client/blob/master/Reference_Manual.md#13-compiling-your-project[here].
75+
If you are using CMake like we do, you can easily find and link against the client library:
76+
[source]
77+
----
78+
find_package(hazelcast-cpp-client CONFIG REQUIRED)
79+
80+
target_link_libraries(mytarget PRIVATE hazelcast-cpp-client::hazelcast-cpp-client)
81+
----
82+
Make sure you add the installation prefix of the client library to CMAKE_PREFIX_PATH if you are using a custom installation location.
83+
84+
Then, You can include the library and start a client using the following code:
85+
[source,cpp]
86+
----
87+
#include <hazelcast/client/hazelcast_client.h>
88+
89+
int main() {
90+
auto hz = hazelcast::new_client().get();
91+
std::cout << "Hazelcast client started and connected to Hazelcast cluster successfully" << std::endl;
92+
return 0;
93+
}
94+
----
95+
96+
The following line creates and starts a new Hazelcast C++ client with the default configuration.
97+
98+
[source,cpp]
99+
----
100+
auto hz = hazelcast::new_client().get();
101+
----
102+
103+
The client automatically connects to the Hazelcast member available on the local machine. Client also automatically disconnects upon its destruction.
104+
105+
== Use Map
106+
107+
A Hazelcast map is a distributed key-value store, similar to JavaScript Map class or plain objects. You can store key-value pairs in a map.
108+
In the following example, we will work with map entries where the keys are session ids and the values are emails.
109+
110+
[source,cpp]
111+
----
112+
#include <hazelcast/client/hazelcast_client.h>
113+
114+
int main() {
115+
auto hz = hazelcast::new_client().get();
116+
auto map = hz.get_map("some_map").get();
117+
map->put<std::string,std::string>("sid12345","example1@email.com");
118+
map->put<std::string,std::string>("sid12346","example2@email.com");
119+
std::cout << map->get<std::string,std::string>("sid12345").get() << std::endl;
120+
std::cout << map->get<std::string,std::string>("sid12346").get() << std::endl;
121+
}
122+
----
123+
124+
The output of this snippet is given below:
125+
126+
[source,bash]
127+
----
128+
example1@email.com
129+
example2@email.com
130+
----
131+
132+
The following line returns a map proxy object for the 'some_map' map:
133+
134+
[source,cpp]
135+
----
136+
auto map = hz.get_map("some_map").get();
137+
----
138+
139+
If the map called “some_map” does not exist in the Hazelcast cluster, it will be automatically created. All the clients that connect to the same cluster will have access to the same map.
140+
141+
With these two lines, the C++ client adds data to the map. The first parameter is the key of the entry, the second one is the value:
142+
143+
[source,cpp]
144+
----
145+
map->put<std::string,std::string>("sid12345","example1@email.com");
146+
map->put<std::string,std::string>("sid12346","example2@email.com");
147+
----
148+
149+
Finally, we get the values we added to the map with the get method:
150+
151+
[source,cpp]
152+
----
153+
std::cout << map->get<std::string,std::string>("sid12345").get() << std::endl;
154+
std::cout << map->get<std::string,std::string>("sid12346").get() << std::endl;
155+
----
156+
157+
== Add a Listener to the Map
158+
159+
You can add an entry listener using the `add_entry_listener` method available on map proxy object.
160+
This will allow you to listen to certain events that happen in the map across the cluster.
161+
162+
The first argument to the `add_entry_listener` method is an object that is used to define listeners.
163+
In this example, we registered listeners for the `on_added`, `on_removed` and `on_updated` events.
164+
165+
The second argument in the `add_entry_listener` method is `include_value`. It is a boolean parameter, and if it is true, the entry event contains the entry value.
166+
In this example, it will be true.
167+
168+
[source,cpp]
169+
----
170+
#include <hazelcast/client/hazelcast_client.h>
171+
172+
int main(){
173+
auto client = hazelcast::new_client().get();
174+
auto map = client.get_map("some_map").get();
175+
176+
map->add_entry_listener(
177+
hazelcast::client::entry_listener().on_added([](hazelcast::client::entry_event &&event) {
178+
std::cout << "Entry added. Key:" << event.get_key().get<std::string>() << " Value: " << event.get_value().get<std::string>() << std::endl;
179+
}).on_removed([](hazelcast::client::entry_event &&event) {
180+
std::cout << "Entry removed. Key: " << event.get_key().get<std::string>() << std::endl;
181+
}).on_updated([](hazelcast::client::entry_event &&event) {
182+
std::cout << "Entry updated. Key: " << event.get_key().get<std::string>() << " Value change: " << event.get_old_value().get<std::string>() << " -> " << event.get_value().get<std::string>() << std::endl;
183+
}), true).get();
184+
185+
map->clear().get();
186+
187+
map->put<std::string,std::string>("sid12345", "example1@email.com").get();
188+
map->put<std::string,std::string>("sid12346", "example2@email.com").get();
189+
map->delete_entry("sid12345").get();
190+
map->put<std::string,std::string>("sid12346", "example1@email.com").get();
191+
}
192+
----
193+
194+
First, the map is cleared to fire events even if there are some entries in the map. Then, two session entries are added, and they are logged.
195+
After that, we remove one of the entries and update the other one. Then, we log the session entries again.
196+
197+
The output is as follows:
198+
199+
[source,bash]
200+
----
201+
Entry added. Key: sid12345 Value: example1@email.com
202+
Entry added. Key: sid12346 Value: example2@email.com
203+
Entry removed. Key: sid12345
204+
Entry updated. Key: sid12346 Value change: example2@email.com -> example1@email.com
205+
----
206+
207+
208+
209+
== Summary
210+
211+
In this tutorial, you learned how to get started with Hazelcast C++ Client using a distributed map.
212+
213+
== See Also
214+
215+
There are a lot of things that you can do with the C++ client. For more, such as how you can query a map with predicates,
216+
check out our https://github.com/hazelcast/hazelcast-cpp-client[client repository.]
217+
218+
If you have any questions, suggestions, or feedback please do not hesitate to reach out to us via https://slack.hazelcast.com/[Hazelcast Community Slack.]
219+
Also, please take a look at https://github.com/hazelcast/hazelcast-cpp-client/issues[the issue list] if you would like to contribute to the client.

‎docs/modules/ROOT/pages/rename-me.adoc

Lines changed: 0 additions & 57 deletions
This file was deleted.

0 commit comments

Comments
 (0)