1
1
# tntcxx — Tarantool C++ Connector
2
2
3
- This repository contains the tntcxx Tarantool C++ connector code. tntcxx is an
4
- open-source Tarantool C++ connector (compliant to C++17) designed with high
3
+ This repository contains the tntcxx Tarantool C++ connector code. tntcxx is an
4
+ open-source Tarantool C++ connector (compliant to C++17) designed with high
5
5
efficiency in mind.
6
6
7
7
## Building tntcxx
@@ -25,21 +25,21 @@ subdirectory of your project or as an embedded dependency.
25
25
26
26
1 . Make tntcxx's source code available to the main build. This can be done a few
27
27
different ways:
28
- * Download the tntcxx source code manually and place it at a known location.
28
+ * Download the tntcxx source code manually and place it at a known location.
29
29
This is the least flexible approach and can make it more difficult to use
30
30
with continuous integration systems, etc.
31
31
* Embed the tntcxx source code as a direct copy in the main project's source
32
- tree. This is often the simplest approach, but is also the hardest to keep
32
+ tree. This is often the simplest approach, but is also the hardest to keep
33
33
up to date. Some organizations may not permit this method.
34
34
* Add tntcxx as a [ git submodule] ( https://git-scm.com/docs/git-submodule ) or
35
35
equivalent. This may not always be possible or appropriate. Git submodules,
36
36
for example, have their own set of advantages and drawbacks.
37
37
* Use the CMake [ ` FetchContent ` ] ( https://cmake.org/cmake/help/latest/module/FetchContent.html )
38
- commands to download tntcxx as part of the build's configure step. This
38
+ commands to download tntcxx as part of the build's configure step. This
39
39
approach doesn't have the limitations of the other methods.
40
40
41
- The last of the above methods is implemented with a small piece of CMake code
42
- that downloads and pulls the tntcxx code into the main build. Just add the
41
+ The last of the above methods is implemented with a small piece of CMake code
42
+ that downloads and pulls the tntcxx code into the main build. Just add the
43
43
following snippet to your CMakeLists.txt:
44
44
``` cmake
45
45
include(FetchContent)
@@ -50,7 +50,7 @@ FetchContent_Declare(
50
50
FetchContent_MakeAvailable(tntcxx)
51
51
```
52
52
53
- After obtaining tntcxx sources using the rest of the methods, you can use the
53
+ After obtaining tntcxx sources using the rest of the methods, you can use the
54
54
following CMake command to incorporate tntcxx into your CMake project:
55
55
``` cmake
56
56
add_subdirectory(${TNTCXX_SOURCE_DIR})
@@ -64,8 +64,8 @@ target_link_libraries(example tntcxx::tntcxx)
64
64
65
65
##### Running tntcxx Tests with CMake
66
66
67
- Use the ` -DTNTCXX_BUILD_TESTING=ON ` option to run the tntcxx tests. This option
68
- is enabled by default if the tntcxx project is determined to be the top level
67
+ Use the ` -DTNTCXX_BUILD_TESTING=ON ` option to run the tntcxx tests. This option
68
+ is enabled by default if the tntcxx project is determined to be the top level
69
69
project. Note that ` BUILD_TESTING ` must also be on (the default).
70
70
71
71
For example, to run the tntcxx tests, you could use this script:
80
80
81
81
### CMake Option Synopsis
82
82
83
- - ` -DTNTCXX_BUILD_TESTING=ON ` must be set to enable testing. This option is
84
- enabled by default if the tntcxx project is determined to be the top level
83
+ - ` -DTNTCXX_BUILD_TESTING=ON ` must be set to enable testing. This option is
84
+ enabled by default if the tntcxx project is determined to be the top level
85
85
project.
86
86
87
87
## Internals
@@ -107,7 +107,7 @@ as template parameter of buffer.
107
107
Connector can be embedded in any C++ application with including main header:
108
108
` #include "<path-to-cloned-repo>/src/Client/Connector.hpp" `
109
109
110
- ### Objects instantiation
110
+ ### Objects Instantiation
111
111
112
112
To create client one should specify buffer's and network provider's implementations
113
113
as template parameters. Connector's main class has the following signature:
@@ -139,12 +139,12 @@ Connection<Buf_t, Net_t> conn(client);
139
139
140
140
Now assume Tarantool instance is listening `3301` port on localhost. To connect
141
141
to the server we should invoke `Connector::connect()` method of client object and
142
- pass three arguments: connection instance, address and port.
142
+ pass three arguments: connection instance, address and port.
143
143
```c++
144
144
int rc = client.connect(conn, address, port);
145
145
```
146
146
147
- ### Error handling
147
+ ### Error Handling
148
148
149
149
Implementation of connector is exception
150
150
free, so we rely on return codes: in case of fail, ` connect() ` will return ` rc < 0 ` .
@@ -159,18 +159,18 @@ if (rc != 0) {
159
159
To reset connection after errors (clean up error message and connection status),
160
160
one can use ` Connection::reset() ` .
161
161
162
- ### Preparing requests
162
+ ### Preparing Requests
163
163
164
164
To execute simplest request (i.e. ping), one can invoke corresponding method of
165
165
connection object:
166
166
``` c++
167
167
rid_t ping = conn.ping();
168
- ```
168
+ ```
169
169
Each request method returns request id, which is sort of future. It can be used
170
170
to get the result of request execution once it is ready (i.e. response). Requests
171
171
are queued in the input buffer of connection until ` Connector::wait() ` is called.
172
172
173
- ### Sending requests
173
+ ### Sending Requests
174
174
175
175
That said, to send requests to the server side, we should invoke ` client.wait() ` :
176
176
``` c++
@@ -182,7 +182,7 @@ request is ready, `wait()` terminates. It also provides negative return code in
182
182
case of system related fails (e.g. broken or time outed connection). If ` wait() `
183
183
returns 0, then response is received and expected to be parsed.
184
184
185
- ### Receiving responses
185
+ ### Receiving Responses
186
186
187
187
To get the response when it is ready, we can use ` Connection::getResponse() ` .
188
188
It takes request id and returns optional object containing response (` nullptr `
@@ -200,11 +200,11 @@ either runtime error(s) (accessible by `response.body.error_stack`) or data
200
200
tuples are not decoded and come in form of pointers to the start and end of
201
201
msgpacks. See section below to understand how to decode tuples.
202
202
203
- ### Data manipulation
203
+ ### Data Manipulation
204
204
205
205
Now let's consider a bit more sophisticated requests.
206
206
Assume we have space with ` id = 512 ` and following format on the server:
207
- ` CREATE TABLE t(id INT PRIMARY KEY, a TEXT, b DOUBLE); `
207
+ ` CREATE TABLE t(id INT PRIMARY KEY, a TEXT, b DOUBLE); `
208
208
Preparing analogue of ` t:replace(1, "111", 1.01); ` request can be done this way:
209
209
210
210
``` c++
@@ -218,7 +218,7 @@ auto i = conn.space[512].index[1];
218
218
rid_t select = i.select(std::make_tuple(1 ), 1 , 0 /* offset*/ , IteratorType::EQ);
219
219
```
220
220
221
- ### Data readers
221
+ ### Data Readers
222
222
223
223
Responses from server contain raw data (i.e. encoded into MsgPack tuples).
224
224
Let's define structure describing data stored in space ` t ` :
0 commit comments