Merge pull request #14 from linksplatform/issue-13-0b67341a17ae

Reorganize the code to make it crystal clear how the same logic is implemented in Doublets and Neo4j

Author: konard

rust/benches/bench.rs

@@ -1,8 +1,12 @@
 #![feature(allocator_api)]
 
 use benchmarks::{
-    create_links, delete_links, each_all, each_concrete, each_identity, each_incoming,
-    each_outgoing, update_links,
+    // Neo4j benchmarks
+    neo4j_create_links, neo4j_delete_links, neo4j_each_all, neo4j_each_concrete,
+    neo4j_each_identity, neo4j_each_incoming, neo4j_each_outgoing, neo4j_update_links,
+    // Doublets benchmarks
+    doublets_create_links, doublets_delete_links, doublets_each_all, doublets_each_concrete,
+    doublets_each_identity, doublets_each_incoming, doublets_each_outgoing, doublets_update_links,
 };
 use criterion::{criterion_group, criterion_main};
 
@@ -18,15 +22,30 @@ macro_rules! tri {
 
 pub(crate) use tri;
 
+// Neo4j benchmarks group
 criterion_group!(
-    benches,
-    create_links,
-    delete_links,
-    each_identity,
-    each_concrete,
-    each_outgoing,
-    each_incoming,
-    each_all,
-    update_links
+    neo4j_benches,
+    neo4j_create_links,
+    neo4j_delete_links,
+    neo4j_each_identity,
+    neo4j_each_concrete,
+    neo4j_each_outgoing,
+    neo4j_each_incoming,
+    neo4j_each_all,
+    neo4j_update_links
 );
-criterion_main!(benches);
+
+// Doublets benchmarks group
+criterion_group!(
+    doublets_benches,
+    doublets_create_links,
+    doublets_delete_links,
+    doublets_each_identity,
+    doublets_each_concrete,
+    doublets_each_outgoing,
+    doublets_each_incoming,
+    doublets_each_all,
+    doublets_update_links
+);
+
+criterion_main!(neo4j_benches, doublets_benches);

rust/benches/benchmarks/create.rs …st/benches/benchmarks/doublets/create.rsrust/benches/benchmarks/create.rs renamed to rust/benches/benchmarks/doublets/create.rs rust/benches/benchmarks/create.rs renamed to rust/benches/benchmarks/doublets/create.rs

@@ -1,21 +1,33 @@
+//! # Doublets Create Links Benchmark
+//!
+//! This benchmark measures the performance of creating new links in Doublets.
+//!
+//! ## Implementation
+//!
+//! Doublets creates links by:
+//! - Allocating next available ID from internal counter
+//! - Writing (id, id, id) tuple directly to memory/file
+//! - Updating source and target indexes
+//! - Time complexity: O(log n) for index updates
+
 use std::{
     alloc::Global,
     time::{Duration, Instant},
 };
 
 use criterion::{measurement::WallTime, BenchmarkGroup, Criterion};
 use doublets::{
-    data::LinkType,
     mem::{Alloc, FileMapped},
     parts::LinkPart,
     split::{self, DataPart, IndexPart},
     unit, Doublets,
 };
-use linksneo4j::{bench, connect, Benched, Client, Exclusive, Fork, Transaction, LINK_COUNT};
+use linksneo4j::{bench, Benched, Fork, LINK_COUNT};
 
 use crate::tri;
 
-fn bench<T: LinkType, B: Benched + Doublets<T>>(
+/// Runs the create benchmark on a Doublets backend.
+fn bench<B: Benched + Doublets<usize>>(
     group: &mut BenchmarkGroup<WallTime>,
     id: &str,
     mut benched: B,
@@ -29,19 +41,10 @@ fn bench<T: LinkType, B: Benched + Doublets<T>>(
     });
 }
 
+/// Creates benchmark for Doublets backends on link creation.
 pub fn create_links(c: &mut Criterion) {
     let mut group = c.benchmark_group("Create");
-    tri! {
-        bench(&mut group, "Neo4j_NonTransaction", Exclusive::<Client<usize>>::setup(()).unwrap());
-    }
-    tri! {
-        let client = connect().unwrap();
-        bench(
-            &mut group,
-            "Neo4j_Transaction",
-            Exclusive::<Transaction<'_, usize>>::setup(&client).unwrap(),
-        );
-    }
+
     tri! {
         bench(
             &mut group,
@@ -70,5 +73,6 @@ pub fn create_links(c: &mut Criterion) {
             split::Store::<usize, FileMapped<_>, FileMapped<_>>::setup(("split_index.links", "split_data.links")).unwrap()
         )
     }
+
     group.finish();
 }

rust/benches/benchmarks/delete.rs …st/benches/benchmarks/doublets/delete.rsrust/benches/benchmarks/delete.rs renamed to rust/benches/benchmarks/doublets/delete.rs rust/benches/benchmarks/delete.rs renamed to rust/benches/benchmarks/doublets/delete.rs

@@ -1,3 +1,15 @@
+//! # Doublets Delete Links Benchmark
+//!
+//! This benchmark measures the performance of deleting links by ID in Doublets.
+//!
+//! ## Implementation
+//!
+//! Doublets deletes links by:
+//! - Looking up link by ID (O(1) array access)
+//! - Removing from source and target indexes
+//! - Marking slot as free for reuse
+//! - Time complexity: O(log n) for index updates
+
 use std::{
     alloc::Global,
     time::{Duration, Instant},
@@ -10,10 +22,11 @@ use doublets::{
     split::{self, DataPart, IndexPart},
     unit, Doublets,
 };
-use linksneo4j::{bench, connect, Benched, Client, Exclusive, Fork, Transaction, LINK_COUNT};
+use linksneo4j::{bench, Benched, Fork, LINK_COUNT};
 
 use crate::tri;
 
+/// Runs the delete benchmark on a Doublets backend.
 fn bench<B: Benched + Doublets<usize>>(
     group: &mut BenchmarkGroup<WallTime>,
     id: &str,
@@ -22,31 +35,20 @@ fn bench<B: Benched + Doublets<usize>>(
     group.bench_function(id, |bencher| {
         bench!(|fork| as B {
             use linksneo4j::BACKGROUND_LINKS;
-            // Create additional links beyond background links to delete
             for _prepare in BACKGROUND_LINKS..BACKGROUND_LINKS + *LINK_COUNT {
                 let _ = fork.create_point();
             }
-            // Delete the links we just created (in reverse order)
             for id in (BACKGROUND_LINKS + 1..=BACKGROUND_LINKS + *LINK_COUNT).rev() {
                 let _ = elapsed! {fork.delete(id)?};
             }
         })(bencher, &mut benched);
     });
 }
 
+/// Creates benchmark for Doublets backends on link deletion.
 pub fn delete_links(c: &mut Criterion) {
     let mut group = c.benchmark_group("Delete");
-    tri! {
-        bench(&mut group, "Neo4j_NonTransaction", Exclusive::<Client<usize>>::setup(()).unwrap());
-    }
-    tri! {
-        let client = connect().unwrap();
-        bench(
-            &mut group,
-            "Neo4j_Transaction",
-            Exclusive::<Transaction<'_, usize>>::setup(&client).unwrap(),
-        );
-    }
+
     tri! {
         bench(
             &mut group,
@@ -75,5 +77,6 @@ pub fn delete_links(c: &mut Criterion) {
             split::Store::<usize, FileMapped<_>, FileMapped<_>>::setup(("split_index.links", "split_data.links")).unwrap()
         )
     }
+
     group.finish();
 }

rust/benches/benchmarks/each/all.rs …/benches/benchmarks/doublets/each/all.rsrust/benches/benchmarks/each/all.rs renamed to rust/benches/benchmarks/doublets/each/all.rs rust/benches/benchmarks/each/all.rs renamed to rust/benches/benchmarks/doublets/each/all.rs

@@ -1,20 +1,32 @@
+//! # Doublets Each All Benchmark
+//!
+//! Measures the performance of iterating over ALL links in Doublets.
+//!
+//! ## Implementation
+//!
+//! Doublets iterates all links by:
+//! - Sequential iteration through internal link array
+//! - Skipping empty/deleted slots
+//! - Time complexity: O(n) where n = total links
+
 use std::{
     alloc::Global,
     time::{Duration, Instant},
 };
 
 use criterion::{measurement::WallTime, BenchmarkGroup, Criterion};
+use doublets::data::{Flow, LinkType};
 use doublets::{
-    data::{Flow, LinkType},
     mem::{Alloc, FileMapped},
     parts::LinkPart,
     split::{self, DataPart, IndexPart},
     unit, Doublets,
 };
-use linksneo4j::{bench, connect, Benched, Client, Exclusive, Fork, Transaction};
+use linksneo4j::{bench, Benched, Fork};
 
 use crate::tri;
 
+/// Runs the each_all benchmark on a Doublets backend.
 fn bench<T: LinkType, B: Benched + Doublets<T>>(
     group: &mut BenchmarkGroup<WallTime>,
     id: &str,
@@ -28,19 +40,10 @@ fn bench<T: LinkType, B: Benched + Doublets<T>>(
     });
 }
 
+/// Creates benchmark for Doublets backends on full table scan.
 pub fn each_all(c: &mut Criterion) {
     let mut group = c.benchmark_group("Each_All");
-    tri! {
-        bench(&mut group, "Neo4j_NonTransaction", Exclusive::<Client<usize>>::setup(()).unwrap());
-    }
-    tri! {
-        let client = connect().unwrap();
-        bench(
-            &mut group,
-            "Neo4j_Transaction",
-            Exclusive::<Transaction<'_, usize>>::setup(&client).unwrap(),
-        );
-    }
+
     tri! {
         bench(
             &mut group,
@@ -69,5 +72,6 @@ pub fn each_all(c: &mut Criterion) {
             split::Store::<usize, FileMapped<_>, FileMapped<_>>::setup(("split_index.links", "split_data.links")).unwrap()
         )
     }
+
     group.finish();
 }

rust/benches/benchmarks/each/concrete.rs …hes/benchmarks/doublets/each/concrete.rsrust/benches/benchmarks/each/concrete.rs renamed to rust/benches/benchmarks/doublets/each/concrete.rs rust/benches/benchmarks/each/concrete.rs renamed to rust/benches/benchmarks/doublets/each/concrete.rs

@@ -1,20 +1,32 @@
+//! # Doublets Each Concrete Benchmark
+//!
+//! Measures the performance of querying links by BOTH source AND target in Doublets.
+//!
+//! ## Implementation
+//!
+//! Doublets queries by source AND target using:
+//! - Uses source OR target index tree to find candidates
+//! - Filters by the other field
+//! - Time complexity: O(log n) for tree traversal
+
 use std::{
     alloc::Global,
     time::{Duration, Instant},
 };
 
 use criterion::{measurement::WallTime, BenchmarkGroup, Criterion};
+use doublets::data::{Flow, LinksConstants};
 use doublets::{
-    data::{Flow, LinksConstants},
     mem::{Alloc, FileMapped},
     parts::LinkPart,
     split::{self, DataPart, IndexPart},
     unit, Doublets,
 };
-use linksneo4j::{bench, connect, Benched, Client, Exclusive, Fork, Transaction};
+use linksneo4j::{bench, Benched, Fork};
 
 use crate::tri;
 
+/// Runs the each_concrete benchmark on a Doublets backend.
 fn bench<B: Benched + Doublets<usize>>(
     group: &mut BenchmarkGroup<WallTime>,
     id: &str,
@@ -25,27 +37,17 @@ fn bench<B: Benched + Doublets<usize>>(
     group.bench_function(id, |bencher| {
         bench!(|fork| as B {
             use linksneo4j::BACKGROUND_LINKS;
-            // Query all background links by concrete source/target
             for index in 1..=BACKGROUND_LINKS {
                 elapsed! {fork.each_by([any, index, index], handler)};
             }
         })(bencher, &mut benched);
     });
 }
 
+/// Creates benchmark for Doublets backends on composite index lookup.
 pub fn each_concrete(c: &mut Criterion) {
     let mut group = c.benchmark_group("Each_Concrete");
-    tri! {
-        bench(&mut group, "Neo4j_NonTransaction", Exclusive::<Client<usize>>::setup(()).unwrap());
-    }
-    tri! {
-        let client = connect().unwrap();
-        bench(
-            &mut group,
-            "Neo4j_Transaction",
-            Exclusive::<Transaction<'_, usize>>::setup(&client).unwrap(),
-        );
-    }
+
     tri! {
         bench(
             &mut group,
@@ -74,5 +76,6 @@ pub fn each_concrete(c: &mut Criterion) {
             split::Store::<usize, FileMapped<_>, FileMapped<_>>::setup(("split_index.links", "split_data.links")).unwrap()
         )
     }
+
     group.finish();
 }

rust/benches/benchmarks/each/identity.rs …hes/benchmarks/doublets/each/identity.rsrust/benches/benchmarks/each/identity.rs renamed to rust/benches/benchmarks/doublets/each/identity.rs rust/benches/benchmarks/each/identity.rs renamed to rust/benches/benchmarks/doublets/each/identity.rs

@@ -1,20 +1,31 @@
+//! # Doublets Each Identity Benchmark
+//!
+//! Measures the performance of looking up links by ID in Doublets.
+//!
+//! ## Implementation
+//!
+//! Doublets looks up by ID using:
+//! - Direct array index access: O(1)
+//! - Returns link at `links[id]` if it exists
+
 use std::{
     alloc::Global,
     time::{Duration, Instant},
 };
 
 use criterion::{measurement::WallTime, BenchmarkGroup, Criterion};
+use doublets::data::{Flow, LinksConstants};
 use doublets::{
-    data::{Flow, LinksConstants},
     mem::{Alloc, FileMapped},
     parts::LinkPart,
     split::{self, DataPart, IndexPart},
     unit, Doublets,
 };
-use linksneo4j::{bench, connect, Benched, Client, Exclusive, Fork, Transaction};
+use linksneo4j::{bench, Benched, Fork};
 
 use crate::tri;
 
+/// Runs the each_identity benchmark on a Doublets backend.
 fn bench<B: Benched + Doublets<usize>>(
     group: &mut BenchmarkGroup<WallTime>,
     id: &str,
@@ -25,27 +36,17 @@ fn bench<B: Benched + Doublets<usize>>(
     group.bench_function(id, |bencher| {
         bench!(|fork| as B {
             use linksneo4j::BACKGROUND_LINKS;
-            // Query all background links by identity
             for index in 1..=BACKGROUND_LINKS {
                 elapsed! {fork.each_by([index, any, any], handler)};
             }
         })(bencher, &mut benched);
     });
 }
 
+/// Creates benchmark for Doublets backends on ID lookup.
 pub fn each_identity(c: &mut Criterion) {
     let mut group = c.benchmark_group("Each_Identity");
-    tri! {
-        bench(&mut group, "Neo4j_NonTransaction", Exclusive::<Client<usize>>::setup(()).unwrap());
-    }
-    tri! {
-        let client = connect().unwrap();
-        bench(
-            &mut group,
-            "Neo4j_Transaction",
-            Exclusive::<Transaction<'_, usize>>::setup(&client).unwrap(),
-        );
-    }
+
     tri! {
         bench(
             &mut group,
@@ -74,5 +75,6 @@ pub fn each_identity(c: &mut Criterion) {
             split::Store::<usize, FileMapped<_>, FileMapped<_>>::setup(("split_index.links", "split_data.links")).unwrap()
         )
     }
+
     group.finish();
 }