Refine the README for openssl, API references, and how to unlock.

Signed-off-by: Tao He <sighingnow@gmail.com>
This commit is contained in:
Tao He 2022-09-24 11:38:17 +08:00
parent 39be27e021
commit 92efa7c9de
1 changed files with 28 additions and 6 deletions

View File

@ -38,8 +38,7 @@ i.e., `ETCDCTL_API=3`.
brew install boost openssl brew install boost openssl
2. protobuf 2. protobuf & gRPC
3. gRPC
+ On Ubuntu, above requirements related to protobuf and gRPC can be installed as: + On Ubuntu, above requirements related to protobuf and gRPC can be installed as:
@ -50,11 +49,14 @@ i.e., `ETCDCTL_API=3`.
+ On MacOS, above requirements related to protobuf and gRPC can be installed as: + On MacOS, above requirements related to protobuf and gRPC can be installed as:
brew install grpc protobuf brew install grpc protobuf
+ When building grpc from source code (e.g., on [Ubuntu 18.04][https://github.com/etcd-cpp-apiv3/etcd-cpp-apiv3/blob/master/.github/workflows/build-test.yml#L73]
and on [CentOS](https://github.com/etcd-cpp-apiv3/etcd-cpp-apiv3/blob/master/.github/workflows/centos-latest.yml#L44-L67)),
if the system-installed openssl is preferred, you need to add `-DgRPC_SSL_PROVIDER=package`
when building gRPC with CMake.
4. [cpprestsdk](https://github.com/microsoft/cpprestsdk), the latest version of master branch 3. [cpprestsdk](https://github.com/microsoft/cpprestsdk), the latest version of master branch
on github should work, you can build and install this dependency using cmake with: on github should work, you can build and install this dependency using cmake with:
git clone https://github.com/microsoft/cpprestsdk.git git clone https://github.com/microsoft/cpprestsdk.git
@ -63,6 +65,13 @@ i.e., `ETCDCTL_API=3`.
cmake .. -DCPPREST_EXCLUDE_WEBSOCKETS=ON cmake .. -DCPPREST_EXCLUDE_WEBSOCKETS=ON
make -j$(nproc) && make install make -j$(nproc) && make install
## API documentation
The _etcd-cpp-apiv3_ doesn't maintain a website for documentation, for detail usage of the
etcd APIs, please refer to [the "etcd operations" section](https://github.com/etcd-cpp-apiv3/etcd-cpp-apiv3#etcd-operations)
in README, and see the detail C++ interfaces in [Client.hpp](https://github.com/etcd-cpp-apiv3/etcd-cpp-apiv3/blob/master/etcd/Client.hpp)
and [SyncClient.hpp](https://github.com/etcd-cpp-apiv3/etcd-cpp-apiv3/blob/master/etcd/SyncClient.hpp).
## Build and install ## Build and install
The _etcd-cpp-apiv3_ library could be easily built and installed using cmake, after all above The _etcd-cpp-apiv3_ library could be easily built and installed using cmake, after all above
@ -89,11 +98,11 @@ the implementation of underlying thread model).
The _etcd-cpp-apiv3_ library supports both synchronous and asynchronous runtime, in two separate The _etcd-cpp-apiv3_ library supports both synchronous and asynchronous runtime, in two separate
library as follows: library as follows:
- etcd-cpp-api-core: the synchronous runtime, provides a blocking-style API and the users are responsible - **etcd-cpp-api-core**: the synchronous runtime, provides a blocking-style API and the users are responsible
for handling dispatch the request into separate thread to avoid been blocked by waiting for response. for handling dispatch the request into separate thread to avoid been blocked by waiting for response.
- target found by cmake: `ETCD_CPP_CORE_LIBRARIES` - target found by cmake: `ETCD_CPP_CORE_LIBRARIES`
- etcd-cpp-api: the asynchronous runtime backed by the `pplx` library from - **etcd-cpp-api**: the asynchronous runtime backed by the `pplx` library from
[cpprestsdk](https://github.com/microsoft/cpprestsdk), where a `boost::asio::io_context` and a pool [cpprestsdk](https://github.com/microsoft/cpprestsdk), where a `boost::asio::io_context` and a pool
of threads is used to run the asynchronous operations in the background. By default the number of of threads is used to run the asynchronous operations in the background. By default the number of
threads in the thread pool equals to `std::thread::hardware_concurrency()`. threads in the thread pool equals to `std::thread::hardware_concurrency()`.
@ -542,6 +551,19 @@ Users can also feed their own lease directory for lock:
etcd.lock_with_lease("/test/lock", lease_id); etcd.lock_with_lease("/test/lock", lease_id);
``` ```
Note that the arguments for `unlock()` is the the same key that used for `lock()`, but the
`response.lock_key()` that return by `lock()`:
```c++
etcd::Client etcd("http://127.0.0.1:2379");
// lock
auto response = etcd.lock("/test/lock").get();
// unlock
auto _ = etcd.unlock(response.lock_key()).get();
```
### Watching for changes ### Watching for changes
Watching for a change is possible with the `watch()` operation of the client. The watch method Watching for a change is possible with the `watch()` operation of the client. The watch method