Rust wrapper for SplinterDB

rust/.gitignore

@@ -0,0 +1,2 @@
+Cargo.lock
+target

rust/Cargo.toml

@@ -0,0 +1,6 @@
+[workspace]
+members = [
+    "splinterdb-sys",
+    "splinterdb-rs",
+    "splinterdb-cli",
+]

rust/README.md

@@ -0,0 +1,38 @@
+# Rust Wrapper for SplinterDB
+
+These docs assume some basic familiarity with the Rust language and tools, particularly the [Rust build tool `cargo`](https://doc.rust-lang.org/book/ch01-03-hello-cargo.html)
+
+## Overview
+Rust may be suitable for developing applications that use SplinterDB, and for writing certain types of tests of SplinterDB.
+
+This directory contains Rust bindings for SplinterDB
+- `splinterdb-sys`: Lowest level, unsafe Rust declarations for a subset of the SplinterDB public API.
+- `splinterdb-rs`: A safe and ergonomic Rust wrapper, intended for use by other Rust libraries and Rust applications.
+- `splinterdb-cli`: A simple command line utility that provides a limited key/value interface.
+   It serves as an example of how to build a Rust application that uses SplinterDB as a library, and can be used for basic performance testing.
+
+## Usage
+Ensure you have Rust and Cargo available, e.g. use [rustup](https://rustup.rs/).
+
+Next, [build and install the SplinterDB C library](../../docs/build.md) **using `clang-13`**,
+e.g.:
+```sh
+CC=clang-13 LD=clang-13 make -C .. && make install -C ..
+```
+
+Then from this directory, run
+```sh
+cargo build
+cargo test
+```
+
+Cargo builds into the `target/debug` subdirectory.  For release builds, add `--release` to the above commands and look in `target/release`.
+
+
+## Why does this only build with `clang` and not `gcc`?
+Short answer: because of link time optimization (LTO).
+
+Longer answer:
+To use LTO across languages, e.g. C with Rust, all compilation units must be built using the same toolchain.
+The Rust compiler is based on LLVM, not GCC.  Therefore, SplinterDB must be built with `clang` (or
+without LTO), in order to be usable from Rust.

rust/splinterdb-cli/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "splinterdb-cli"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+clap = { version = "3.0.7", features = ["derive"] }
+crossbeam-utils = "0.8.5"
+rand = "0.8.4"
+rand_pcg = "0.3.1"
+serde = { version = "1.0", optional = true, features = ["derive"] }
+serde_json = "1.0"
+splinterdb-rs = { path = "../splinterdb-rs", features = ["serde"] }

rust/splinterdb-cli/README.md

@@ -0,0 +1,52 @@
+# SplinterDB Client
+A simple command line utility for SplinterDB.
+
+It also serves as an example of how to build an application using the Rust wrapper for SplinterDB.
+
+For build instructions, see the [README in the parent directory](../README.md).
+
+For usage, run `target/debug/splinterdb-cli --help`:
+
+## Walkthrough
+Initialize a new database file on disk
+```
+$ target/debug/splinterdb-cli --file /tmp/my-db init-db --disk-mb 2000 --key-size 20 --value-size 110
+```
+Note this creates both the named `/tmp/my-db` file and an extra metadata
+file `/tmp/my-db.meta`.  Both files must be present for the other
+commands to work.
+
+List contents (currently empty)
+```
+$ target/debug/splinterdb-cli --file /tmp/my-db list
+```
+
+Add some data
+```
+$ target/debug/splinterdb-cli --file /tmp/my-db insert -k "key1" -v "value1"
+$ target/debug/splinterdb-cli --file /tmp/my-db insert -k "key2" -v "value2"
+$ target/debug/splinterdb-cli --file /tmp/my-db insert -k "key3" -v "value3"
+```
+
+List contents again
+```
+$ target/debug/splinterdb-cli --file /tmp/my-db list
+```
+
+Delete a key/value pair
+```
+$ target/debug/splinterdb-cli --file /tmp/my-db delete --key "key2"
+```
+
+Lookup a single value
+```
+$ target/debug/splinterdb-cli --file /tmp/my-db get -k "key1"
+```
+
+## Performance testing
+The same tool may be used for testing the performance of SplinterDB.
+
+This will overwrite the chosen file or block device with random data, and print results at the end
+```
+$ target/debug/splinterdb-cli --file /tmp/test perf --threads 8 --writes-per-thread 50000
+```