232 #237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft

RAprogramm wants to merge 85 commits into objectionary:master from RAprogramm:232

Cargo.lock

Large diffs are not rendered by default.

Cargo.toml

-Original file line number
+Diff line change
@@ Expand Up / @@ -15,24 +15,28 @@ categories = ["data-structures", "memory-management"] @@
     [features]
     gc = []
+    callgrind = []
     [dependencies]
     anyhow = "1.0.100"
     bincode = { version = "2.0.1", features = ["serde"] }
     ctor = "0.5.0"
     emap = { version = "0.0.13", features = ["serde"] }
     hex = "0.4.3"
+    itoa = "1.0.11"
     itertools = "0.14.0"
     lazy_static = "1.5.0"
     libc = "0.2.176"
     log = "0.4.28"
     micromap = { version = "0.1.0", features = ["serde"] }
-    microstack = { version = "0.0.7", features = ["serde"] }
+    smallvec = { version = "1.15.1", features = ["serde"] }
+    arrayvec = "0.7.6"
     nohash-hasher = "0.2.0"
     openssl = { version = "0.10.73", features = ["vendored"] }
     regex = "1.11.2"
     rstest = "0.26.1"
     rustc-hash = "2.1.1"
+    serde_bytes = "0.11.15"
     serde = { version = "1.0.226", features = ["derive"] }
     simple_logger = "5.0.0"
     sxd-document = "0.3.2"
@@ Expand All / @@ -42,13 +46,20 @@ xml-builder = "0.5.4" @@
     [dev-dependencies]
     criterion = "0.7.0"
+    fsutils = "0.1.7"
+    iai-callgrind = "0.16.1"
     predicates = "3.1.3"
     tempfile = "3.23.0"
     [[bench]]
     name = "bench"
     harness = false
+    [[bench]]
+    name = "edge_index"
+    harness = false
+    required-features = ["callgrind"]
     [lints.clippy]
     all = "warn"
     pedantic = "warn"
@@ Expand Down @@

README.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -19,33 +19,45 @@ @@
     right after the data it contains is read _and_ no other vertices
     transitively point to it.
+    The current implementation keeps runtime overhead low by interning edge labels
+    and indexing them through a hybrid small-map/hash-map structure.
+    Edge payloads are stored in a `Hex` helper that keeps tiny blobs inline
+    and promotes larger values to reference-counted slices, so cloning a graph
+    snapshot stays cheap.
     Here is how you can create a di-graph:
     ```rust
-    use sodg::Sodg;
-    use sodg::Hex;
-    let mut g = Sodg::empty(256);
+    use std::str::FromStr as _;
+    use sodg::{Hex, Label, Sodg};
+    let mut g: Sodg<16> = Sodg::empty(256);
     g.add(0); // add a vertex no.0
     g.add(1); // add a vertex no.1
-    g.bind(0, 1, "foo"); // connect v0 to v1 with label "foo"
+    g.bind(0, 1, Label::from_str("foo").unwrap()).unwrap(); // connect v0 to v1 with label "foo"
+    g.bind(0, 1, Label::from_str("bar").unwrap()).unwrap(); // add another edge with label "bar"
     g.put(1, &Hex::from_str_bytes("Hello, world!")); // attach data to v1
     ```
     Then, you can find a vertex by the label of an edge departing
     from another vertex:
     ```rust
-    let id = g.kid(0, "foo");
+    let id = g.kid(0, Label::from_str("foo").unwrap()).unwrap();
     assert_eq!(1, id);
     ```
     Then, you can find all kids of a vertex:
     ```rust
-    let kids: Vec<(String, String, usize)> = g.kids(0);
-    assert_eq!("foo", kids[0].0);
-    assert_eq!("bar", kids[0].1);
-    assert_eq!(1, kids[0].2);
+    let mut kids = g.kids(0);
+    let first = kids.next().unwrap();
+    assert_eq!("foo", first.label().to_string());
+    assert_eq!(1, first.destination());
+    let second = kids.next().unwrap();
+    assert_eq!("bar", second.label().to_string());
+    let label_id = first.label_id();
+    assert!(label_id > 0);
     ```
     Then, you can read the data of a vertex:
@@ Expand All / @@ -62,6 +74,14 @@ @@
     println!("{:?}", g);
     ```
+    Multi-hop traversals remain ergonomic thanks to [`Sodg::find`], which walks a
+    dot-separated path and returns the final vertex if each edge exists:
+    ```rust
+    assert_eq!(Some(1), g.find(0, "foo"));
+    assert_eq!(None, g.find(0, "foo.baz"));
+    ```
     Using `merge()`, you can merge two graphs together, provided they are trees.
     Using `save()` and `load()`, you can serialize and deserialize the graph.
@@ Expand All / @@ -75,6 +95,80 @@ @@
     Read [the documentation](https://docs.rs/sodg/latest/sodg/).
+    ## Benchmarks
+    The project ships two complementary benchmarking harnesses:
+    * A [Criterion](https://github.com/bheisler/criterion.rs) suite in
+      `benches/bench.rs` that measures wall-clock performance of vertex management,
+      edge insertion/removal/lookups, and multi-segment `find()` traversals across
+      different out-degrees.
+    * An [`iai-callgrind`](https://github.com/gungraun/gungraun) harness in
+      `benches/edge_index.rs` (guarded by the `callgrind` feature) that collects
+      Valgrind statistics for the same scenarios.
+    Criterion only requires a stable Rust toolchain. Gnuplot is optional; when it is
+    not installed, Criterion falls back to the bundled Plotters backend for report
+    generation.
+    ### Running Criterion locally
+. Build and run all Criterion benchmarks:
+       ```bash
+       cargo bench --bench bench
+       ```
+. Inspect the generated reports under
+       `target/criterion/<benchmark>/<measurement>/report/index.html`. They include
+       plots, summary statistics, and raw sample data.
+    ### Comparing against a saved baseline
+    Criterion can persist previous results to highlight regressions and
+    improvements:
+. Check out the branch or commit that should become the reference point (for
+       example `master`) and save a baseline:
+       ```bash
+       cargo bench --bench bench -- --save-baseline master
+       ```
+       The snapshot is stored inside `target/criterion` and can be reused across
+       branches as long as the directory is kept intact.
+. Switch back to your working branch and compare the current code against the
+       saved numbers:
+       ```bash
+       cargo bench --bench bench -- --baseline master
+       ```
+. Examine the console output or open the HTML reports to see per-benchmark
+       percentage changes. Positive percentages indicate improvements, negative ones
+       signal regressions.
+    To focus on a single benchmark group, pass its name after a double dash, e.g.
+    `cargo bench --bench bench -- find_multi_segment`.
+    ### Running the Callgrind harness
+    The Callgrind harness provides instruction- and cache-level metrics:
+. Install Valgrind (`apt install valgrind` on Debian/Ubuntu). Gungraun supports
+       Linux and other platforms with working Valgrind ports; Windows is not
+       supported.
+. Enable the `callgrind` feature and execute the harness:
+       ```bash
+       cargo bench --features callgrind --bench edge_index
+       ```
+. Review the generated profiles under `target/iai` with tools like
+       `kcachegrind`, `callgrind_annotate`, or Gungraun’s HTML report. This makes it
+       easy to inspect hot paths and validate that optimizations change instruction
+       counts in the intended way.
+    When the feature is not enabled, the `edge_index` binary prints a short message
+    and exits immediately so the harness can stay in the repository without adding a
+    hard dependency on Valgrind.
     ## How to Contribute
     First, install [Rust](https://www.rust-lang.org/tools/install) and then:
@@ Expand Down @@

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

232 #237

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

GitHub Actions / markdown-lint

GitHub Actions / markdown-lint

GitHub Actions / markdown-lint

GitHub Actions / markdown-lint

GitHub Actions / markdown-lint

GitHub Actions / markdown-lint

GitHub Actions / markdown-lint

Uh oh!

Uh oh!

232 #237

Are you sure you want to change the base?

Uh oh!

232 #237

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

GitHub Actions / markdown-lint

GitHub Actions / markdown-lint

GitHub Actions / markdown-lint

GitHub Actions / markdown-lint

GitHub Actions / markdown-lint

GitHub Actions / markdown-lint

GitHub Actions / markdown-lint

Uh oh!

Uh oh!