Readme for btree

features/readme.md

@@ -8,6 +8,5 @@ search engine code.
 * [query-parser](query-parser/) contains code for parsing the user-facing query grammar.
 * [renderer](renderer/) contains utility code for rendering website templates.
 
-
 * [screenshots](screenshots/) and [random-websites](random-websites/) contains SQL queries random
 exploration mode.

libraries/array/readme.md

@@ -8,9 +8,8 @@ It's a very C++-style library that does unidiomatic things with interface defaul
 functions to get diamond inheritance.
 
 # Quick demo:
-```
-var array =
-        LongArray.mmapForWriting(Path.of("/tmp/test"), 1<<16);
+```java
+var array = LongArray.mmapForWriting(Path.of("/tmp/test"), 1<<16);
 
 array.transformEach(50, 1000, (pos, val) -> Long.hashCode(pos));
 array.quickSort(50, 1000);

libraries/btree/readme.md

@@ -0,0 +1,37 @@
+# BTree
+
+This package contains a small library for creating and reading a static b-tree.
+
+The b-trees are specified through a [BTreeContext](src/main/java/nu/marginalia/btree/model/BTreeContext.java)
+which contains information about the data and index layout.
+
+## Demo
+
+```java
+BTreeContext ctx = new BTreeContext(
+        4,  // num layers max
+        1,  // entry size
+        512); // block size bits
+
+        // Allocate a memory area to work in, see the array library for how to do this with files
+        LongArray array = LongArray.allocate(8192);
+
+        // Write a btree at offset 123 in the area
+        long[] items = new long[400];
+        BTreeWriter writer = new BTreeWriter(array, ctx);
+        final int offsetInFile = 123;
+
+        long btreeSize = writer.write(offsetInFile, items.length, slice -> {
+            // we're *must* write items.length * entry.size words in slice
+            // these items must be sorted!!
+
+            for (int i = 0; i < items.length; i++) {
+                slice.set(i, items[i]);
+            }
+        });
+
+        // Read the BTree
+
+        BTreeReader reader = new BTreeReader(array, ctx, offsetInFile);
+        reader.findEntry(items[0]);
+```

libraries/btree/src/main/java/nu/marginalia/btree/model/BTreeContext.java

@@ -2,10 +2,16 @@ package nu.marginalia.btree.model;
 
 import nu.marginalia.btree.BTreeWriter;
 
-public record BTreeContext(int maxLayers,
-                           int entrySize,
-                           int blockSizeBits,
-                           int blockSizeWords) {
+/**
+ *
+ * @param maxLayers         The maximum number of index layers
+ * @param entrySize         The entry size, for size 1 the key is the data. For sizes larger than 1,
+ *                          the data will be expected to sit in the successive position to the key
+ *                          in the data layer
+ * @param blockSizeBits     Bits per data block
+ * @param blockSizeWords    Words per data block
+ */
+public record BTreeContext(int maxLayers, int entrySize, int blockSizeBits, int blockSizeWords) {
 
     // 8 pages is the breaking point where using a B-tree is actually advantageous
     // over just binary searching in a sorted list. Above 8 pages, binary search will
@@ -14,8 +20,8 @@ public record BTreeContext(int maxLayers,
 
     private static final int MIN_PAGES_FOR_BTREE = 8;
 
-    public BTreeContext(int MAX_LAYERS, int entrySize, int BLOCK_SIZE_BITS) {
-        this(MAX_LAYERS, entrySize, BLOCK_SIZE_BITS, 1 << BLOCK_SIZE_BITS);
+    public BTreeContext(int maxLayers, int entrySize, int blockSizeBits) {
+        this(maxLayers, entrySize, blockSizeBits, 1 << blockSizeBits);
     }
 
     public long calculateSize(int numEntries) {