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

Commit 16c1c37

Browse files
hakanaktas0hakanaktas0
committed
Cpp guide added
1 parent f76faa1 commit 16c1c37

File tree

3 files changed

+204
-58
lines changed

3 files changed

+204
-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: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
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+
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+
Before starting download and install Vcpkg itself if you haven't already:
37+
[source,bash]
38+
----
39+
git clone https://github.com/microsoft/vcpkg
40+
.\vcpkg\bootstrap-vcpkg.bat
41+
----
42+
43+
First, execute the following to install `hazelcast-cpp-client` ith its `boost` dependencies:
44+
45+
[source,bash]
46+
----
47+
.\vcpkg\vcpkg install hazelcast-cpp-client
48+
----
49+
After the installation, the library is available for usage.
50+
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`.
51+
52+
[source,bash]
53+
----
54+
cmake -B [build directory] -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake
55+
cmake --build [build directory]
56+
----
57+
For more information about Vcpkg installation check https://github.com/hazelcast/hazelcast-cpp-client/blob/master/Reference_Manual.md#112-vcpkg-users[here].
58+
59+
== Starting the C++ Client
60+
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].
61+
If you are using CMake like we do, you can easily find and link against the client library:
62+
[source]
63+
----
64+
find_package(hazelcast-cpp-client CONFIG REQUIRED)
65+
66+
target_link_libraries(mytarget PRIVATE hazelcast-cpp-client::hazelcast-cpp-client)
67+
----
68+
Make sure you add the installation prefix of the client library to CMAKE_PREFIX_PATH if you are using a custom installation location.
69+
70+
Then, You can include the library and start a client using the following code:
71+
[source,cpp]
72+
----
73+
#include <hazelcast/client/hazelcast_client.h>
74+
75+
int main() {
76+
auto hz = hazelcast::new_client().get();
77+
}
78+
----
79+
80+
The following line creates and starts a new Hazelcast C++ client with the default configuration.
81+
82+
[source,cpp]
83+
----
84+
auto hz = hazelcast::new_client().get();
85+
----
86+
87+
The client automatically connects to the Hazelcast member available on the local machine.
88+
89+
== Use Map
90+
91+
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.
92+
In the following example, we will work with map entries where the keys are session ids and the values are emails.
93+
94+
[source,cpp]
95+
----
96+
#include <hazelcast/client/hazelcast_client.h>
97+
98+
int main() {
99+
auto hz = hazelcast::new_client().get();
100+
auto map = hz.get_map("some_map").get();
101+
map->put<std::string,std::string>("sid12345","[email protected]");
102+
map->put<std::string,std::string>("sid12346","[email protected]");
103+
std::cout << map->get<std::string,std::string>("sid12345").get() << std::endl;
104+
std::cout << map->get<std::string,std::string>("sid12346").get() << std::endl;
105+
}
106+
----
107+
108+
The output of this snippet is given below:
109+
110+
[source,bash]
111+
----
112+
[email protected]
113+
[email protected]
114+
----
115+
116+
The following line returns a map proxy object for the 'some_map' map:
117+
118+
[source,cpp]
119+
----
120+
auto map = hz.get_map("some_map").get();
121+
----
122+
123+
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.
124+
125+
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:
126+
127+
[source,cpp]
128+
----
129+
map->put<std::string,std::string>("sid12345","[email protected]");
130+
map->put<std::string,std::string>("sid12346","[email protected]");
131+
----
132+
133+
Finally, we get the values we added to the map with the get method:
134+
135+
[source,cpp]
136+
----
137+
std::cout << map->get<std::string,std::string>("sid12345").get() << std::endl;
138+
std::cout << map->get<std::string,std::string>("sid12346").get() << std::endl;
139+
----
140+
141+
== Add a Listener to the Map
142+
143+
You can add an entry listener using the “add_entry_listener” method available on map proxy object.
144+
This will allow you to listen to certain events that happen in the map across the cluster.
145+
146+
The first argument to the “add_entry_listener” method is an object that is used to define listeners.
147+
In this example, we registered listeners for the “on_added”, “on_removed" and “on_updated” events.
148+
149+
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.
150+
In this example, it will be true.
151+
152+
[source,cpp]
153+
----
154+
#include <hazelcast/client/hazelcast_client.h>
155+
156+
int main(){
157+
auto client = hazelcast::new_client().get();
158+
auto map = client.get_map("some_map").get();
159+
160+
map->add_entry_listener(
161+
hazelcast::client::entry_listener().on_added([](hazelcast::client::entry_event &&event) {
162+
std::cout << "Entry added. Key:" << event.get_key().get<std::string>() << " Value: " << event.get_value().get<std::string>() << std::endl;
163+
}).on_removed([](hazelcast::client::entry_event &&event) {
164+
std::cout << "Entry removed. Key: " << event.get_key().get<std::string>() << std::endl;
165+
}).on_updated([](hazelcast::client::entry_event &&event) {
166+
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;
167+
}), true).get();
168+
169+
map->clear().get();
170+
171+
map->put<std::string,std::string>("sid12345", "[email protected]").get();
172+
map->put<std::string,std::string>("sid12346", "[email protected]").get();
173+
map->delete_entry("sid12345").get();
174+
map->put<std::string,std::string>("sid12346", "[email protected]").get();
175+
}
176+
----
177+
178+
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.
179+
After that, we remove one of the entries and update the other one. Then, we log the session entries again.
180+
181+
The output is as follows:
182+
183+
[source,bash]
184+
----
185+
Entry added. Key: sid12345 Value: [email protected]
186+
Entry added. Key: sid12346 Value: [email protected]
187+
Entry removed. Key: sid12345
188+
Entry updated. Key: sid12346 Value change: [email protected] -> [email protected]
189+
----
190+
191+
192+
193+
== Summary
194+
195+
In this tutorial, you learned how to get started with Hazelcast C++ Client using a distributed map.
196+
197+
== See Also
198+
199+
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,
200+
check out our https://github.com/hazelcast/hazelcast-cpp-client[client repository.]
201+
202+
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.]
203+
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)