From 249dd973cd74e69202971fa897815602dea9adc4 Mon Sep 17 00:00:00 2001 From: Ana Hobden Date: Mon, 11 Feb 2019 16:44:59 -0800 Subject: [PATCH 1/3] Add README and some lib.rs docs Signed-off-by: Ana Hobden --- README.md | 37 ++++++++++++++++++ src/lib.rs | 96 ++++++++++++++++++++++++++++++++++++++++++++++ src/raw.rs | 20 +++++----- src/transaction.rs | 15 ++++---- 4 files changed, 151 insertions(+), 17 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..8d2ee7da --- /dev/null +++ b/README.md @@ -0,0 +1,37 @@ +# TiKV Client (Rust) + +[![Build Status](https://travis-ci.org/tikv/client-rust.svg?branch=master)](https://travis-ci.org/pingcap/client-rust) +[![Documentation](https://docs.rs/tikv-client/badge.svg)](https://docs.rs/tikv-client/) + +> Currently this crate is experimental and some portions (eg the Transactional API) are still in active development. You're encouraged to use this library for testing and help us find problems! + +This crate provides Rust bindings to [TiKV](https://github.com/tikv/tikv), a distributed transactional Key-Value database written in Rust. + +With this crate you can easily connect to any TiKV deployment, interact with it, and mutate the data it contains. + +This is an open source (Apache 2) project hosted by the Cloud Native Computing Foundation (CNCF) and maintained by the TiKV Authors. *We'd love it if you joined us in improving this project.* + +## Install + +There are no special requirements to use this. It is a Rust 2018 edition crate supporting stable and nightly. + +To use this crate in your project, depend on it in the `Cargo.toml` of your Rust project: + +```toml +[dependencies] +# ...Your other dependencies... +tikv-client = "~0.1" +``` + +## Access the documentation + +We reccomend using the autogenerated to browse and understand the API. We've done our best to include ample, tested, and understandable examples. + +You can access the documentation on your machine by running the following in any project that depends on `tikv-client`. + +```bash +cargo doc --package tikv-client --open +# If it didn't work, browse file URL it tried to open with your browser. +``` + +Otherwise, you can visit [docs.rs/tikv-client](https://docs.rs/tikv-client/). diff --git a/src/lib.rs b/src/lib.rs index a652bad2..94193f98 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -13,6 +13,102 @@ #![recursion_limit = "128"] #![type_length_limit = "1572864"] +//! TiKV Client for Rust. +//! +//! > Currently this crate is experimental and some portions (eg the Transactional API) are still +//! > in active development. You're encouraged to use this library for testing and help us find +//! > problems! +//! +//! This crate provides Rust bindings to [TiKV](https://github.com/tikv/tikv), a distributed +//! transactional Key-Value database written in Rust. +//! +//! With this crate you can easily connect to any TiKV deployment, interact with it, and mutate the +//! data it contains. +//! +//! This is an open source (Apache 2) project hosted by the Cloud Native Computing Foundation +//! (CNCF) and maintained by the TiKV Authors. *We'd love it if you joined us in improving this +//! project.* +//! +//! ## Install +//! +//! There are no special requirements to use this. It is a Rust 2018 edition crate supporting +//! stable and nightly. +//! +//! To use this crate in your project, depend on it in the `Cargo.toml` of your Rust project: +//! +//! ```toml +//! [dependencies] +//! # ...Your other dependencies... +//! tikv-client = "~0.1" +//! futures = "0.1" # You'll need this later. +//! ``` +//! +//! Then give a `cargo build --package tikv-client` to test building the crate. +//! +//! Next, you need to choose the API appropriate for your needs. +//! +//! ## 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. +//! +//! The *consequence* of supporting transactions is increased overhead of coordination with `pd` +//! for timestamp acquisition. This is approximately 1 RTT. +//! +//! *While it is possible to use both APIs at the same time, doing so is unsafe and unsupported.* +//! +//! Choose the one that suites your needs as described below, then add the import statement to your +//! file where you need to use the library. +//! +//! ### Transactional +//! +//! The [transactional](transaction/index.html) API supports **transactions** via Multi-View +//! Concurrency Control (MVCC). +//! +//! **Best when you mostly do** complex sets of actions, actions which may require a rollback, +//! operations affecting multiple keys or values, or operations that depend on strong ordering. +//! +//! ```rust +//! use tikv_client::{*, transaction::*}; +//! ``` +//! +//! ### Raw +//! +//! The [raw](raw/index.html) API has **reduced coordination overhead**, but lacks any +//! transactional abilities. +//! +//! **Best when you mostly do** single row changes, and have very limited cross-row (eg. foreign +//! key) requirements. +//! +//! ```rust +//! use tikv_client::{*, raw::*}; +//! ``` +//! +//! ## Connect +//! +//! Regardless of which API you choose, you'll need to connect your client +//! ([raw](raw/struct.Client.html), [transactional](transaction/struct.Client.html)). +//! +//! ```rust +//! # use tikv_client::{*, raw::*}; +//! use futures::Future; +//! +//! // Configure endpoints and optional TLS. +//! let config = Config::new(vec![ // A list of PD endpoints. +//! "192.168.0.100:2379", +//! "192.168.0.101:2379", +//! ]).with_security("root.ca", "internal.cert", "internal.key"); +//! +//! // Get an unresolved connection. +//! let connect = Client::new(&config); +//! +//! // Resolve the connection into a client. +//! let client = connect.wait(); +//! ``` +//! +//! At this point, you should seek the documentation in the related API modules. +//! + use futures::Future; use serde_derive::*; use std::{ diff --git a/src/raw.rs b/src/raw.rs index ce552041..f729966d 100644 --- a/src/raw.rs +++ b/src/raw.rs @@ -11,15 +11,15 @@ // See the License for the specific language governing permissions and // limitations under the License. -/// Raw related functionality. -/// -/// Using the [`raw::Client`](struct.Client.html) you can utilize TiKV's raw interface. -/// -/// This interface offers optimal performance as it does not require coordination with a timestamp -/// oracle, while the transactional interface does. -/// -/// **Warning:** It is not advisible to use the both raw and transactional functionality in the same keyspace. -/// +//! Raw related functionality. +//! +//! Using the [`raw::Client`](struct.Client.html) you can utilize TiKV's raw interface. +//! +//! This interface offers optimal performance as it does not require coordination with a timestamp +//! oracle, while the transactional interface does. +//! +//! **Warning:** It is not advisible to use the both raw and transactional functionality in the same keyspace. +//! use crate::{rpc::RpcClient, Config, Error, Key, KeyRange, KvFuture, KvPair, Result, Value}; use futures::{future, Async, Future, Poll}; use std::{ @@ -318,7 +318,7 @@ impl Deref for ColumnFamily { } } -pub trait RequestInner: Sized { +trait RequestInner: Sized { type Resp; fn execute(self, client: Arc, cf: Option) -> KvFuture; diff --git a/src/transaction.rs b/src/transaction.rs index 28cb88d6..ed2b60b6 100644 --- a/src/transaction.rs +++ b/src/transaction.rs @@ -11,14 +11,15 @@ // See the License for the specific language governing permissions and // limitations under the License. -/*! Transactional related functionality. +//! Transactional related functionality. +//! +//! Using the [`transaction::Client`](struct.Client.html) you can utilize TiKV's transactional interface. +//! +//! This interface offers SQL-like transactions on top of the raw interface. +//! +//! **Warning:** It is not advisible to use the both raw and transactional functionality in the same keyspace. +//! -Using the [`transaction::Client`](struct.Client.html) you can utilize TiKV's transactional interface. - -This interface offers SQL-like transactions on top of the raw interface. - -**Warning:** It is not advisible to use the both raw and transactional functionality in the same keyspace. - */ use crate::{Config, Error, Key, KvPair, Value}; use futures::{Future, Poll, Stream}; use std::ops::RangeBounds; From 9d9b2cc61493ee56981b00df607228128424bde1 Mon Sep 17 00:00:00 2001 From: Ana Hobden Date: Tue, 12 Feb 2019 11:13:10 -0800 Subject: [PATCH 2/3] Apply suggestions from code review Nit fixes. Signed-off-by: Ana Hobden --- README.md | 6 +++--- src/lib.rs | 4 ++-- src/raw.rs | 2 +- src/transaction.rs | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 8d2ee7da..de18cdde 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![Build Status](https://travis-ci.org/tikv/client-rust.svg?branch=master)](https://travis-ci.org/pingcap/client-rust) [![Documentation](https://docs.rs/tikv-client/badge.svg)](https://docs.rs/tikv-client/) -> Currently this crate is experimental and some portions (eg the Transactional API) are still in active development. You're encouraged to use this library for testing and help us find problems! +> Currently this crate is experimental and some portions (e.g. the Transactional API) are still in active development. You're encouraged to use this library for testing and help us find problems! This crate provides Rust bindings to [TiKV](https://github.com/tikv/tikv), a distributed transactional Key-Value database written in Rust. @@ -15,7 +15,7 @@ This is an open source (Apache 2) project hosted by the Cloud Native Computing F There are no special requirements to use this. It is a Rust 2018 edition crate supporting stable and nightly. -To use this crate in your project, depend on it in the `Cargo.toml` of your Rust project: +To use this crate in your project, add it as a dependency in the `Cargo.toml` of your Rust project: ```toml [dependencies] @@ -25,7 +25,7 @@ tikv-client = "~0.1" ## Access the documentation -We reccomend using the autogenerated to browse and understand the API. We've done our best to include ample, tested, and understandable examples. +We recommend using the autogenerated to browse and understand the API. We've done our best to include ample, tested, and understandable examples. You can access the documentation on your machine by running the following in any project that depends on `tikv-client`. diff --git a/src/lib.rs b/src/lib.rs index 94193f98..fb930b77 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -34,7 +34,7 @@ //! There are no special requirements to use this. It is a Rust 2018 edition crate supporting //! stable and nightly. //! -//! To use this crate in your project, depend on it in the `Cargo.toml` of your Rust project: +//! To use this crate in your project, add it as a dependency in the `Cargo.toml` of your Rust project: //! //! ```toml //! [dependencies] @@ -43,7 +43,7 @@ //! futures = "0.1" # You'll need this later. //! ``` //! -//! Then give a `cargo build --package tikv-client` to test building the crate. +//! Then run a `cargo build --package tikv-client` command to test building the crate. //! //! Next, you need to choose the API appropriate for your needs. //! diff --git a/src/raw.rs b/src/raw.rs index f729966d..b5de288e 100644 --- a/src/raw.rs +++ b/src/raw.rs @@ -18,7 +18,7 @@ //! This interface offers optimal performance as it does not require coordination with a timestamp //! oracle, while the transactional interface does. //! -//! **Warning:** It is not advisible to use the both raw and transactional functionality in the same keyspace. +//! **Warning:** It is not advisable to use both raw and transactional functionality in the same keyspace. //! use crate::{rpc::RpcClient, Config, Error, Key, KeyRange, KvFuture, KvPair, Result, Value}; use futures::{future, Async, Future, Poll}; diff --git a/src/transaction.rs b/src/transaction.rs index ed2b60b6..381f2b82 100644 --- a/src/transaction.rs +++ b/src/transaction.rs @@ -17,7 +17,7 @@ //! //! This interface offers SQL-like transactions on top of the raw interface. //! -//! **Warning:** It is not advisible to use the both raw and transactional functionality in the same keyspace. +//! **Warning:** It is not advisable to use both raw and transactional functionality in the same keyspace. //! use crate::{Config, Error, Key, KvPair, Value}; From 104509ff21f415629f5c00b00bc9089f8b0f076f Mon Sep 17 00:00:00 2001 From: Ana Hobden Date: Wed, 13 Feb 2019 13:18:18 -0800 Subject: [PATCH 3/3] Nit fixes Signed-off-by: Ana Hobden --- README.md | 12 +++++++----- src/lib.rs | 12 ++++++------ 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index de18cdde..c1743982 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,10 @@ [![Build Status](https://travis-ci.org/tikv/client-rust.svg?branch=master)](https://travis-ci.org/pingcap/client-rust) [![Documentation](https://docs.rs/tikv-client/badge.svg)](https://docs.rs/tikv-client/) -> Currently this crate is experimental and some portions (e.g. the Transactional API) are still in active development. You're encouraged to use this library for testing and help us find problems! +> Currently this crate is experimental and some portions (e.g. the Transactional API) are still in active development. You're encouraged to use this library for testing and to help us find problems! -This crate provides Rust bindings to [TiKV](https://github.com/tikv/tikv), a distributed transactional Key-Value database written in Rust. +This crate provides a clean, ready to use client for [TiKV](https://github.com/tikv/tikv), a +distributed transactional Key-Value database written in Rust. With this crate you can easily connect to any TiKV deployment, interact with it, and mutate the data it contains. @@ -25,7 +26,10 @@ tikv-client = "~0.1" ## Access the documentation -We recommend using the autogenerated to browse and understand the API. We've done our best to include ample, tested, and understandable examples. +We recommend using the cargo-generated documentation to browse and understand the API. We've done +our best to include ample, tested, and understandable examples. + +You can visit [docs.rs/tikv-client](https://docs.rs/tikv-client/), or build the documentation yourself. You can access the documentation on your machine by running the following in any project that depends on `tikv-client`. @@ -33,5 +37,3 @@ You can access the documentation on your machine by running the following in any cargo doc --package tikv-client --open # If it didn't work, browse file URL it tried to open with your browser. ``` - -Otherwise, you can visit [docs.rs/tikv-client](https://docs.rs/tikv-client/). diff --git a/src/lib.rs b/src/lib.rs index fb930b77..1745d129 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -19,8 +19,8 @@ //! > in active development. You're encouraged to use this library for testing and help us find //! > problems! //! -//! This crate provides Rust bindings to [TiKV](https://github.com/tikv/tikv), a distributed -//! transactional Key-Value database written in Rust. +//! This crate provides a clean, ready to use client for [TiKV](https://github.com/tikv/tikv), a +//! distributed transactional Key-Value database written in Rust. //! //! With this crate you can easily connect to any TiKV deployment, interact with it, and mutate the //! data it contains. @@ -52,8 +52,8 @@ //! This crate offers both [**raw**](raw/index.html) and //! [**transactional**](transaction/index.html) APIs. You should choose just one for your system. //! -//! The *consequence* of supporting transactions is increased overhead of coordination with `pd` -//! for timestamp acquisition. This is approximately 1 RTT. +//! The *consequence* of supporting transactions is increased overhead of coordination with the +//! placement driver for timestamp acquisition. This is approximately 1 RTT. //! //! *While it is possible to use both APIs at the same time, doing so is unsafe and unsupported.* //! @@ -62,7 +62,7 @@ //! //! ### Transactional //! -//! The [transactional](transaction/index.html) API supports **transactions** via Multi-View +//! The [transactional](transaction/index.html) API supports **transactions** via Multi-Version //! Concurrency Control (MVCC). //! //! **Best when you mostly do** complex sets of actions, actions which may require a rollback, @@ -78,7 +78,7 @@ //! transactional abilities. //! //! **Best when you mostly do** single row changes, and have very limited cross-row (eg. foreign -//! key) requirements. +//! key) requirements. You will not be able to use transactions with this API. //! //! ```rust //! use tikv_client::{*, raw::*};