add README.md

database/README.md

@@ -8,6 +8,7 @@ Cuprate's database implementation.
     - [`src/ops`](#src-ops)
     - [`src/service/`](#src-service)
     - [`src/backend/`](#src-backend)
+1. [Benchmarking](#benchmarking)
 1. [Backends](#backends)
     - [`heed`](#heed)
     - [`redb`](#redb)
@@ -131,6 +132,11 @@ All backends follow the same file structure:
 | `transaction.rs` | Implementation of `trait TxR{o,w}`
 | `types.rs`       | Type aliases for long backend-specific types
 
+# Benchmarking
+There is a standalone binary within `benchmark` that allows various testing and benchmarking on all the features of `cuprate-database`.
+
+See [`benchmark/README.md`](benchmark/) for more info.
+
 # Backends
 `cuprate-database`'s `trait`s abstract over various actual databases.
 

database/benchmark/README.md

@@ -0,0 +1,56 @@
+# `cuprate-database-benchmark`
+This is a standalone binary that allows testing/benchmarking `cuprate-database`.
+
+<!-- Did you know markdown automatically increments number lists, even if they are all 1...? -->
+1. [Documentation](#documentation)
+1. [File Structure](#file-structure)
+    - [`src/`](#src)
+    - [`src/ops`](#src-ops)
+    - [`src/service/`](#src-service)
+    - [`src/backend/`](#src-backend)
+1. [Benchmarking](#benchmarking)
+1. [Testing](#testing)
+
+# Documentation
+In general, documentation for `database/` is split into 3:
+
+| Documentation location    | Purpose |
+|---------------------------|---------|
+| `database/README.md`      | High level design of `cuprate-database`
+| `cuprate-database`        | Practical usage documentation/warnings/notes/etc
+| Source file `// comments` | Implementation-specific details (e.g, how many reader threads to spawn?)
+
+This README serves as the overview/design document.
+
+For actual practical usage, `cuprate-database`'s types and general usage are documented via standard Rust tooling.
+
+Run:
+```bash
+cargo doc --package cuprate-database --open
+```
+at the root of the repo to open/read the documentation.
+
+If this documentation is too abstract, refer to any of the source files, they are heavily commented. There are many `// Regular comments` that explain more implementation specific details that aren't present here or in the docs. Use the file reference below to find what you're looking for.
+
+The code within `src/` is also littered with some `grep`-able comments containing some keywords:
+
+| Word        | Meaning |
+|-------------|---------|
+| `INVARIANT` | This code makes an _assumption_ that must be upheld for correctness
+| `SAFETY`    | This `unsafe` code is okay, for `x,y,z` reasons
+| `FIXME`     | This code works but isn't ideal
+| `HACK`      | This code is a brittle workaround
+| `PERF`      | This code is weird for performance reasons
+| `TODO`      | This must be implemented; There should be 0 of these in production code
+| `SOMEDAY`   | This should be implemented... someday
+
+# File Structure
+A quick reference of the structure of the folders & files in `cuprate-database`.
+
+Note that `lib.rs/mod.rs` files are purely for re-exporting/visibility/lints, and contain no code. Each sub-directory has a corresponding `mod.rs`.
+
+## `src/`
+The top-level `src/` files.
+
+| File                | Purpose |
+|---------------------|---------|

database/benchmark/src/main.rs

@@ -1,3 +1,91 @@
+//! `cuprate-database` testing & benchmarking binary.
+
+//---------------------------------------------------------------------------------------------------- Lints
+// Forbid lints.
+// Our code, and code generated (e.g macros) cannot overrule these.
+#![forbid(
+	// `unsafe` is allowed but it _must_ be
+	// commented with `SAFETY: reason`.
+	clippy::undocumented_unsafe_blocks,
+
+	// Never.
+	unused_unsafe,
+	redundant_semicolons,
+	unused_allocation,
+	coherence_leak_check,
+	while_true,
+	clippy::missing_docs_in_private_items,
+
+	// Maybe can be put into `#[deny]`.
+	unconditional_recursion,
+	for_loops_over_fallibles,
+	unused_braces,
+	unused_doc_comments,
+	unused_labels,
+	keyword_idents,
+	non_ascii_idents,
+	variant_size_differences,
+    single_use_lifetimes,
+
+	// Probably can be put into `#[deny]`.
+	future_incompatible,
+	let_underscore,
+	break_with_label_and_loop,
+	duplicate_macro_attributes,
+	exported_private_dependencies,
+	large_assignments,
+	overlapping_range_endpoints,
+	semicolon_in_expressions_from_macros,
+	noop_method_call,
+	unreachable_pub,
+)]
+// Deny lints.
+// Some of these are `#[allow]`'ed on a per-case basis.
+#![deny(
+    clippy::all,
+    clippy::correctness,
+    clippy::suspicious,
+    clippy::style,
+    clippy::complexity,
+    clippy::perf,
+    clippy::pedantic,
+    clippy::nursery,
+    clippy::cargo,
+    unused_mut,
+    missing_docs,
+    deprecated,
+    unused_comparisons,
+    nonstandard_style
+)]
+#![allow(unreachable_code, unused_variables, dead_code, unused_imports)] // TODO: remove
+#![allow(
+	// FIXME: this lint affects crates outside of
+	// `database/` for some reason, allow for now.
+	clippy::cargo_common_metadata,
+
+	// FIXME: adding `#[must_use]` onto everything
+	// might just be more annoying than useful...
+	// although it is sometimes nice.
+	clippy::must_use_candidate,
+
+	// TODO: should be removed after all `todo!()`'s are gone.
+	clippy::diverging_sub_expression,
+
+	clippy::module_name_repetitions,
+	clippy::module_inception,
+	clippy::redundant_pub_crate,
+	clippy::option_if_let_else,
+)]
+// Allow some lints when running in debug mode.
+#![cfg_attr(debug_assertions, allow(clippy::todo, clippy::multiple_crate_versions))]
+
+//---------------------------------------------------------------------------------------------------- Public API
+// Import private modules, export public types.
+//
+// Documentation for each module is located in the respective file.
+
+//---------------------------------------------------------------------------------------------------- Private
+
 fn main() {
     println!("Hello, world!");
 }