Skip to content

Commit e17d3f1

Browse files
HoverbearHoverbear
committed
Criterion and proptest
Signed-off-by: Ana Hobden <[email protected]>
1 parent ebe3261 commit e17d3f1

File tree

6 files changed

+323
-74
lines changed

6 files changed

+323
-74
lines changed

‎Cargo.toml

+6-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ integration-tests = ["property-testing"]
1616
# Enable propery testing features with `proptest`.
1717
property-testing = ["proptest", "proptest-derive"]
1818

19-
2019
[lib]
2120
name = "tikv_client"
2221

@@ -43,7 +42,13 @@ default-features = false
4342
features = ["push", "process"]
4443

4544
[dev-dependencies]
45+
criterion = "0.2"
46+
proptest = "0.9"
4647
clap = "2.32"
4748
tempdir = "0.3"
4849
runtime = "0.3.0-alpha.3"
4950
runtime-tokio = "0.3.0-alpha.3"
51+
52+
[[bench]]
53+
name = "bench"
54+
harness = false

‎README.md

+91-73
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,91 @@
1-
# TiKV Client (Rust)
2-
3-
[![Build Status](https://travis-ci.org/tikv/client-rust.svg?branch=master)](https://travis-ci.org/tikv/client-rust)
4-
[![Documentation](https://docs.rs/tikv-client/badge.svg)](https://docs.rs/tikv-client/)
5-
6-
> 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!
7-
8-
This crate provides a clean, ready to use client for [TiKV](https://github.com/tikv/tikv), a
9-
distributed transactional Key-Value database written in Rust.
10-
11-
With this crate you can easily connect to any TiKV deployment, interact with it, and mutate the data it contains.
12-
13-
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.*
14-
15-
## Using the client
16-
17-
The TiKV client is a Rust library (crate). It requires version 1.36 of the compiler and standard libraries (which will be stable from the 4th July 2019, see below for ensuring compatibility).
18-
19-
To use this crate in your project, add it as a dependency in your `Cargo.toml`:
20-
21-
```toml
22-
[dependencies]
23-
# ...Your other dependencies...
24-
tikv-client = { git = "https://github.com/tikv/client-rust.git" }
25-
```
26-
27-
The client requires a Git dependency until we can [publish it](https://github.com/tikv/client-rust/issues/32).
28-
29-
There are [examples](examples) which show how to use the client in a Rust program.
30-
31-
The examples and documentation use async/await syntax. This is a new feature in Rust and is currently unstable. To use async/await you'll need to add the feature flag `#![async_await]` to your crate and use a nightly compiler (see below).
32-
33-
## Access the documentation
34-
35-
We recommend using the cargo-generated documentation to browse and understand the API. We've done
36-
our best to include ample, tested, and understandable examples.
37-
38-
You can visit [docs.rs/tikv-client](https://docs.rs/tikv-client/), or build the documentation yourself.
39-
40-
You can access the documentation on your machine by running the following in any project that depends on `tikv-client`.
41-
42-
```bash
43-
cargo doc --package tikv-client --open
44-
# If it didn't work, browse file URL it tried to open with your browser.
45-
```
46-
47-
## Toolchain versions
48-
49-
To check what version of Rust you are using, run
50-
51-
```bash
52-
rustc --version
53-
```
54-
55-
You'll see something like `rustc 1.36.0-nightly (a784a8022 2019-05-09)` where the `1.36.0` is the toolchain version, and `nightly` is the channel (stable/beta/nightly). To install another toolchain use
56-
57-
```bash
58-
rustup toolchain install nightly
59-
```
60-
61-
Where `nightly` here is the channel to add. To update your toolchains, run
62-
63-
```bash
64-
rustup update
65-
```
66-
67-
To build your project using a specified toolchain, use something like
68-
69-
```bash
70-
cargo +nightly build
71-
```
72-
73-
Where `nightly` names the toolchain (by specifying the channel, in this case).
1+
# TiKV Client (Rust)
2+
3+
[![Build Status](https://travis-ci.org/tikv/client-rust.svg?branch=master)](https://travis-ci.org/pingcap/client-rust)
4+
[![Documentation](https://docs.rs/tikv-client/badge.svg)](https://docs.rs/tikv-client/)
5+
6+
> 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!
7+
8+
This crate provides a clean, ready to use client for [TiKV](https://github.com/tikv/tikv), a
9+
distributed transactional Key-Value database written in Rust.
10+
11+
With this crate you can easily connect to any TiKV deployment, interact with it, and mutate the data it contains.
12+
13+
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.*
14+
15+
## Using the client
16+
17+
The TiKV client is a Rust library (crate). It requires version 1.36 of the compiler and standard libraries (which will be stable from the 4th July 2019, see below for ensuring compatibility).
18+
19+
To use this crate in your project, add it as a dependency in your `Cargo.toml`:
20+
21+
```toml
22+
[dependencies]
23+
# ...Your other dependencies...
24+
tikv-client = { git = "https://github.com/tikv/client-rust.git" }
25+
```
26+
27+
The client requires a Git dependency until we can [publish it](https://github.com/tikv/client-rust/issues/32).
28+
29+
There are [examples](examples) which show how to use the client in a Rust program.
30+
31+
The examples and documentation use async/await syntax. This is a new feature in Rust and is currently unstable. To use async/await you'll need to add the feature flag `#![async_await]` to your crate and use a nightly compiler (see below).
32+
33+
## Access the documentation
34+
35+
We recommend using the cargo-generated documentation to browse and understand the API. We've done
36+
our best to include ample, tested, and understandable examples.
37+
38+
You can visit [docs.rs/tikv-client](https://docs.rs/tikv-client/), or build the documentation yourself.
39+
40+
You can access the documentation on your machine by running the following in any project that depends on `tikv-client`.
41+
42+
```bash
43+
cargo doc --package tikv-client --open
44+
# If it didn't work, browse file URL it tried to open with your browser.
45+
```
46+
47+
## Running benchmarks
48+
49+
This crate uses [`criterion`](https://github.com/bheisler/criterion.rs) for benchmarking. Most benchmarks use [`proptest`](https://github.com/altsysrq/proptest) to generate values for bench runs.
50+
51+
Currently, all of the benchmarks are gated by the `integration-tests` feature, and require a functioning TiKV (and PD) cluster.
52+
53+
```bash
54+
export PD_ADDRS=192.168.0.100:2379,192.168.0.101:2379,192.168.0.102:2379
55+
cargo +nightly bench --features integration-tests
56+
```
57+
58+
It is possible to limit the scope of benchmarks:
59+
60+
```bash
61+
export PD_ADDRS=192.168.0.100:2379,192.168.0.101:2379,192.168.0.102:2379
62+
cargo +nightly bench --features integration-tests raw
63+
```
64+
65+
## Toolchain versions
66+
67+
To check what version of Rust you are using, run
68+
69+
```bash
70+
rustc --version
71+
```
72+
73+
You'll see something like `rustc 1.36.0-nightly (a784a8022 2019-05-09)` where the `1.36.0` is the toolchain version, and `nightly` is the channel (stable/beta/nightly). To install another toolchain use
74+
75+
```bash
76+
rustup toolchain install nightly
77+
```
78+
79+
Where `nightly` here is the channel to add. To update your toolchains, run
80+
81+
```bash
82+
rustup update
83+
```
84+
85+
To build your project using a specified toolchain, use something like
86+
87+
```bash
88+
cargo +nightly build
89+
```
90+
91+
Where `nightly` names the toolchain (by specifying the channel, in this case).

‎benches/bench.rs

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
#![feature(async_await)]
2+
use core::fmt::Debug;
3+
use proptest::{
4+
self,
5+
strategy::{Strategy, ValueTree},
6+
};
7+
8+
#[cfg(feature = "integration-tests")]
9+
use criterion::criterion_main;
10+
#[cfg(feature = "integration-tests")]
11+
mod integration;
12+
13+
use std::env::var;
14+
15+
// Typical usage
16+
pub const DEFAULT_KEY_SIZE_BOUND: usize = 512;
17+
pub const DEFAULT_VALUE_SIZE_BOUND: usize = 2048;
18+
pub const DEFAULT_BATCH_BOUND: usize = 8;
19+
20+
pub const ENV_PD_ADDR: &str = "PD_ADDR";
21+
22+
pub fn pd_addrs() -> Vec<String> {
23+
var(ENV_PD_ADDR)
24+
.expect(&format!("Expected {}:", ENV_PD_ADDR))
25+
.split(",")
26+
.map(From::from)
27+
.collect()
28+
}
29+
30+
pub fn generate<T: Debug>(strat: impl Strategy<Value = T>) -> T {
31+
strat
32+
.new_tree(&mut proptest::test_runner::TestRunner::new(
33+
proptest::test_runner::Config::default(),
34+
))
35+
.unwrap()
36+
.current()
37+
}
38+
39+
#[cfg(feature = "proptest")]
40+
const PROPTEST_BATCH_SIZE_MAX: usize = 16;
41+
42+
#[cfg(feature = "proptest")]
43+
pub fn arb_batch<T: core::fmt::Debug>(
44+
single_strategy: impl Strategy<Value = T>,
45+
max_batch_size: impl Into<Option<usize>>,
46+
) -> impl Strategy<Value = Vec<T>> {
47+
let max_batch_size = max_batch_size.into().unwrap_or(PROPTEST_BATCH_SIZE_MAX);
48+
proptest::collection::vec(single_strategy, 0..max_batch_size)
49+
}
50+
51+
52+
#[cfg(feature = "integration-tests")]
53+
criterion_main!(integration::raw::suite);
54+
55+
#[cfg(not(feature = "integration-tests"))]
56+
fn main() {
57+
unimplemented!();
58+
}

‎benches/integration/mod.rs

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pub mod raw;

0 commit comments

Comments
 (0)