From 79d0d56193727cfd8220574ba2ab7470d02431b6 Mon Sep 17 00:00:00 2001 From: Nick Cameron Date: Wed, 21 Apr 2021 09:29:20 +1200 Subject: [PATCH] Documentation in lib.rs Signed-off-by: Nick Cameron --- src/lib.rs | 71 +++++++++++++++++++++++++++++++++++++++++++++-------- src/mock.rs | 3 ++- 2 files changed, 63 insertions(+), 11 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index c8ad1d5..a75eded 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -6,10 +6,28 @@ //! This crate lets you connect to a TiKV cluster and use either a transactional or raw (simple //! get/put style without transactional consistency guarantees) API to access and update your data. //! +//! The TiKV Rust client supports several levels of abstraction. The most convenient way to use the +//! client is via [`RawClient`] and [`TransactionClient`]. This gives a very high-level API which +//! mostly abstracts over the distributed nature of the store and has sensible defaults for all +//! protocols. This interface can be configured, primarily when creating the client or transaction +//! objects via the [`Config`] and [`TransactionOptions`] structs. Using some options, you can take +//! over parts of the protocols (such as retrying failed messages) yourself. +//! +//! The lowest level of abstraction is to create and send gRPC messages directly to TiKV (and PD) +//! nodes. The `tikv-client-store` and `tikv-client-pd` crates make this easier than using the +//! protobuf definitions and a gRPC library directly, but give you the same level of control. +//! +//! In between these levels of abstraction, you can send and receive individual messages to the TiKV +//! cluster, but take advantage of library code for common operations such as resolving data to +//! regions and thus nodes in the cluster, or retrying failed messages. This can be useful for +//! testing a TiKV cluster or for some advanced use cases. See the [`request`] module for +//! this API, and [`raw::lowering`] and [`transaction::lowering`] for +//! convenience methods for creating request objects. +//! //! ## Choosing an API //! -//! This crate offers both [**raw**](raw/index.html) and -//! [**transactional**](transaction/index.html) APIs. You should choose just one for your system. +//! This crate offers both [raw](RawClient) and +//! [transactional](Transaction) APIs. You should choose just one for your system. //! //! The consequence of supporting transactions is increased overhead of coordination with the //! placement driver and TiKV, and additional code complexity. @@ -18,7 +36,7 @@ //! //! ### Transactional //! -//! The [transactional](transaction/index.html) API supports **transactions** via multi-version +//! The [transactional](Transaction) API supports **transactions** via multi-version //! concurrency control (MVCC). //! //! Best when you mostly do complex sets of actions, actions which may require a rollback, @@ -27,24 +45,56 @@ //! //! ### Raw //! -//! The [raw](raw/index.html) API has reduced coordination overhead, but lacks any +//! The [raw](RawClient) API has reduced coordination overhead, but lacks any //! transactional abilities. //! //! Best when you mostly do single value changes, and have very limited cross-value //! requirements. You will not be able to use transactions with this API. +//! +//! ## Usage +//! +//! The general flow of using the client crate is to create either a raw or transaction client +//! object (which can be configured) then send commands using the client object, or use it to create +//! transactions objects. In the latter case, the transaction is built up using various commands and +//! then committed (or rolled back). +//! +//! ### Examples +//! +//! Raw mode: +//! +//! ```rust +//! use tikv_client::RawClient; +//! +//! let client = RawClient::new(vec!["127.0.0.1:2379"]).await?; +//! client.put("key".to_owned(), "value".to_owned()).await?; +//! let value = client.get("key".to_owned()).await?; +//! ``` +//! +//! Transactional mode: +//! +//! ```rust +//! use tikv_client::TransactionClient; +//! +//! let txn_client = TransactionClient::new(vec!["127.0.0.1:2379"]).await?; +//! let mut txn = txn_client.begin_optimistic().await?; +//! txn.put("key".to_owned(), "value".to_owned()).await?; +//! let value = txn.get("key".to_owned()).await?; +//! txn.commit().await?; +//! ``` #[macro_use] -mod request; - +pub mod request; #[macro_use] -mod transaction; +#[doc(hidden)] +pub mod transaction; mod backoff; mod compat; mod config; mod kv; mod pd; -mod raw; +#[doc(hidden)] +pub mod raw; mod region; mod stats; mod store; @@ -64,14 +114,15 @@ pub use crate::backoff::Backoff; #[doc(inline)] pub use crate::kv::{BoundRange, IntoOwnedRange, Key, KvPair, Value}; #[doc(inline)] -pub use crate::raw::{lowering::*, Client as RawClient, ColumnFamily}; +pub use crate::raw::{lowering as raw_lowering, Client as RawClient, ColumnFamily}; #[doc(inline)] pub use crate::request::RetryOptions; #[doc(inline)] pub use crate::timestamp::{Timestamp, TimestampExt}; #[doc(inline)] pub use crate::transaction::{ - lowering::*, CheckLevel, Client as TransactionClient, Snapshot, Transaction, TransactionOptions, + lowering as transaction_lowering, CheckLevel, Client as TransactionClient, Snapshot, + Transaction, TransactionOptions, }; #[doc(inline)] pub use config::Config; diff --git a/src/mock.rs b/src/mock.rs index aeb9131..1270737 100644 --- a/src/mock.rs +++ b/src/mock.rs @@ -7,8 +7,9 @@ use crate::{ pd::{PdClient, PdRpcClient, RetryClient}, + region::{Region, RegionId}, store::Store, - Config, Error, Key, Region, RegionId, Result, Timestamp, + Config, Error, Key, Result, Timestamp, }; use async_trait::async_trait; use derive_new::new;