# anna-rs **Repository Path**: carsmos/anna-rs ## Basic Information - **Project Name**: anna-rs - **Description**: Rust port of the anna key-value store, using zenoh for communication. - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2022-07-02 - **Last Updated**: 2024-08-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # anna-rs Rust port of the **[`anna`](https://github.com/hydro-project/anna)** key-value store, using **[`zenoh`](https://zenoh.io/)** for communication. **Note:** This project is still in a prototype state, so don't use it in production! ## Attribution This crate started out as a line-by-line port of the original **[`anna`](https://github.com/hydro-project/anna)** project developed in the [RISE Lab](https://rise.cs.berkeley.edu) at [UC Berkeley](https://berkeley.edu). We recommend to check out their [ICDE 2018 paper](http://db.cs.berkeley.edu/jmh/papers/anna_ieee18.pdf) for more information. ## Build You need the latest version of [Rust](https://www.rust-lang.org/) for building. The build commands are `cargo build` for a debug build and `cargo build --release` for an optimized release build. After building, you can find the resulting executables under `../target/debug` (for debug builds) or `../target/release` (for release builds). To run the **test suite**, execute `cargo test`. The **API documentation** can be generated through `cargo doc --open`. ## Run This project contains several executables: - **`kvs`**: The main key-value store node. - **`routing`**: Routing nodes are responsible for coordinating kvs nodes and keeping track of which key is mapped to which node. - **`client`**: A client proxy that provides an interactive prompt where you can send `GET`/`PUT` commands. - **`logger`**: Subscribes to all local `zenoh` messages and logs them to stdout. - **`benchmark`**: The benchmark node provides different ways to evaluate the performance of the key-value store. To trigger benchmark commands, the `send-benchmark-commands` executable can be used. - TODO: monitoring, management Each executable can be started by running the built executable from `target`. Alternatively, it's also possible to combine the build and run steps using `cargo run --bin `, where `` is the name of the executable. Since all nodes expect that an routing node is available, it is recommended to start the `routing` executable first. ### Config Files All executables (with the exception of the logger) expect the path to a config file as argument. An example for this config file can be found in [`example-config.yml`](example-config.yml). With `cargo run`, this argument can be passed in the following way: ``` cargo run --bin -- ``` Note the additional space between `--` and ``. The `cargo run` command uses a `--` argument as separator, so everything after it is passed to the executable. ### Example Open four terminal windows and run the following commands in them (one per terminal window): 1. `cargo run --bin logger` to start the zenoh logger, so that we can see the messages that are sent. This step is optional. 2. `cargo run --bin routing -- example-config.yml` to start the routing node. 3. `cargo run --bin kvs -- example-config.yml` to start the key-value store node. 4. `cargo run --bin client -- example-config.yml` to start the client proxy. The client proxy executable will show a `kvs>` prompt, in which you can use the following commands:
OperationEffect
**`PUT `** Writes the given `` with the given `` into the key value store. Uses the `LastWriterWinsLattice` type for values to achieve _"read commited"_ consistency.
**`GET `** Queries the value for the given `` from the key value store. Expects that the value is of type `LastWriterWinsLattice`, so it should be only used to read values that were written using `PUT`.
**`PUT_SET ...`** Writes the given `` with a the given set of values. Uses the `SetLattice` type for storing values, which resolves conflicts by taking the [union](https://en.wikipedia.org/wiki/Union_(set_theory)) of all conflicting sets.
**`GET_SET `** Used to read a set of values that was previously written using `PUT_SET`.
**`PUT_CAUSAL `** Writes the given `` with the given `` into the key value store. Uses the `MultiKeyCausalLattice` type to achieve [_"causal consistency"_](https://en.wikipedia.org/wiki/Causal_consistency) for the value.
**`GET_CAUSAL `** Used to read a value with _"causal consistency"_ that was previously written using `PUT_CAUSAL`.
All operations can also be written in lowercase, e.g. `put_set` instead of `PUT_SET`. For a description of the mentioned lattice types (e.g. `LastWriterWinsLattice`), see the `lattice` module in the API docs of this crate, which you can generate using **`cargo doc --open`**. ## Benchmarks For benchmarking, the `benchmark` executable can be used. It spawns a proxy node that listens for incoming benchmark commands and executes them. It supports a variety of different commands, for example for executing a specific number of random `PUT` requests. To send commands, the `send-benchmark-commands` executable can be used. ### Example Run the `routing` and `kvs` executables as described above under [_Example_](#example), but in `--release` mode. Then open two additional terminal windows. In the first, spawn the benchmark node by running `cargo run --bin benchmark --release -- example-config.yml`. From the second window, run `cargo run --bin send-benchmark-commands -- ` to send trigger the benchmark command ``. ### Commands The following commands are supported: - **`cache `:** Determines the responsible KVS nodes for keys `0..num_keys` and caches this information for subsequent commands. - **`warm `:** Generates `num_keys` `PUT` requests to the key-value store. The `total_threads` argument must be the configured number of benchmark threads (the requests are split between the threads). The stored values are of the form `aaaaaaa...`, with a length determined by the `value_len` argument. - **`load