implement range bounds in iterators

.gitignore

@@ -18,3 +18,151 @@ build
 compile_commands.json
 *~
 .cache/
+.cursor-ai/.gitignore
+.cursor-ai/config.json
+.cursor-ai/sync-vault.ps1
+.cursor-ai/sync-vault.sh
+.vscode/settings.json
+raw-data/matrixkv_ycsb.build
+raw-data/matrixkv.build
+raw-data/matrixkv.conf
+raw-data/non-txn_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_1.out
+raw-data/non-txn_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_2.out
+raw-data/non-txn_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_3.out
+raw-data/non-txn_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_4.out
+raw-data/non-txn_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_5.out
+raw-data/non-txn_ycsb.build
+raw-data/non-txn.build
+raw-data/persistron_threads_2_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_1.out
+raw-data/persistron_threads_2_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_2.out
+raw-data/persistron_threads_2_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_3.out
+raw-data/persistron_threads_2_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_4.out
+raw-data/persistron_threads_2_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_5.out
+raw-data/persistron_threads_4_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_1.out
+raw-data/persistron_threads_4_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_2.out
+raw-data/persistron_threads_4_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_3.out
+raw-data/persistron_threads_4_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_4.out
+raw-data/persistron_threads_4_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_5.out
+raw-data/persistron_threads_6_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_1.out
+raw-data/persistron_threads_6_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_2.out
+raw-data/persistron_threads_6_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_3.out
+raw-data/persistron_threads_6_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_4.out
+raw-data/persistron_threads_6_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_5.out
+raw-data/persistron_threads_8_dram_cache_size_2048_pmem_cache_size_24576_log_flush_interval_0_iter_1.out
+raw-data/persistron_threads_8_dram_cache_size_2048_pmem_cache_size_24576_log_flush_interval_0_iter_2.out
+raw-data/persistron_threads_8_dram_cache_size_2048_pmem_cache_size_24576_log_flush_interval_0_iter_3.out
+raw-data/persistron_threads_8_dram_cache_size_2048_pmem_cache_size_24576_log_flush_interval_0_iter_4.out
+raw-data/persistron_threads_8_dram_cache_size_2048_pmem_cache_size_24576_log_flush_interval_0_iter_5.out
+raw-data/persistron_threads_8_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_1.out
+raw-data/persistron_threads_8_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_2.out
+raw-data/persistron_threads_8_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_3.out
+raw-data/persistron_threads_8_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_4.out
+raw-data/persistron_threads_8_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_5.out
+raw-data/persistron_threads_8_dram_cache_size_6144_pmem_cache_size_8192_log_flush_interval_0_iter_1.out
+raw-data/persistron_threads_8_dram_cache_size_6144_pmem_cache_size_8192_log_flush_interval_0_iter_2.out
+raw-data/persistron_threads_8_dram_cache_size_6144_pmem_cache_size_8192_log_flush_interval_0_iter_3.out
+raw-data/persistron_threads_8_dram_cache_size_6144_pmem_cache_size_8192_log_flush_interval_0_iter_4.out
+raw-data/persistron_threads_8_dram_cache_size_6144_pmem_cache_size_8192_log_flush_interval_0_iter_5.out
+raw-data/persistron_threads_10_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_1.out
+raw-data/persistron_threads_10_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_2.out
+raw-data/persistron_threads_10_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_3.out
+raw-data/persistron_threads_10_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_4.out
+raw-data/persistron_threads_10_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_5.out
+raw-data/persistron_threads_12_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_1.out
+raw-data/persistron_threads_12_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_2.out
+raw-data/persistron_threads_12_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_3.out
+raw-data/persistron_threads_12_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_4.out
+raw-data/persistron_threads_12_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_5.out
+raw-data/persistron_threads_14_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_1.out
+raw-data/persistron_threads_14_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_2.out
+raw-data/persistron_threads_14_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_3.out
+raw-data/persistron_threads_14_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_4.out
+raw-data/persistron_threads_14_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_5.out
+raw-data/persistron_threads_16_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_1.out
+raw-data/persistron_threads_16_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_2.out
+raw-data/persistron_threads_16_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_3.out
+raw-data/persistron_threads_16_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_4.out
+raw-data/persistron_threads_16_dram_cache_size_4096_pmem_cache_size_16384_log_flush_interval_0_iter_5.out
+raw-data/persistron_ycsb.build
+raw-data/persistron.build
+raw-data/pmem-cow_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_1.out
+raw-data/pmem-cow_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_2.out
+raw-data/pmem-cow_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_3.out
+raw-data/pmem-cow_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_4.out
+raw-data/pmem-cow_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_5.out
+raw-data/pmem-cow_ycsb.build
+raw-data/pmem-cow.build
+raw-data/pmem-only_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_1.out
+raw-data/pmem-only_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_2.out
+raw-data/pmem-only_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_3.out
+raw-data/pmem-only_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_4.out
+raw-data/pmem-only_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_0_iter_5.out
+raw-data/splinterdb_threads_2_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_1.out
+raw-data/splinterdb_threads_2_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_2.out
+raw-data/splinterdb_threads_2_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_3.out
+raw-data/splinterdb_threads_2_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_4.out
+raw-data/splinterdb_threads_2_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_5.out
+raw-data/splinterdb_threads_4_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_1.out
+raw-data/splinterdb_threads_4_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_2.out
+raw-data/splinterdb_threads_4_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_3.out
+raw-data/splinterdb_threads_4_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_4.out
+raw-data/splinterdb_threads_4_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_5.out
+raw-data/splinterdb_threads_6_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_1.out
+raw-data/splinterdb_threads_6_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_2.out
+raw-data/splinterdb_threads_6_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_3.out
+raw-data/splinterdb_threads_6_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_4.out
+raw-data/splinterdb_threads_6_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_5.out
+raw-data/splinterdb_threads_8_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_1.out
+raw-data/splinterdb_threads_8_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_2.out
+raw-data/splinterdb_threads_8_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_3.out
+raw-data/splinterdb_threads_8_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_4.out
+raw-data/splinterdb_threads_8_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_5.out
+raw-data/splinterdb_threads_10_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_1.out
+raw-data/splinterdb_threads_10_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_2.out
+raw-data/splinterdb_threads_10_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_3.out
+raw-data/splinterdb_threads_10_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_4.out
+raw-data/splinterdb_threads_10_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_5.out
+raw-data/splinterdb_threads_12_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_1.out
+raw-data/splinterdb_threads_12_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_2.out
+raw-data/splinterdb_threads_12_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_3.out
+raw-data/splinterdb_threads_12_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_4.out
+raw-data/splinterdb_threads_12_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_5.out
+raw-data/splinterdb_threads_14_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_1.out
+raw-data/splinterdb_threads_14_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_2.out
+raw-data/splinterdb_threads_14_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_3.out
+raw-data/splinterdb_threads_14_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_4.out
+raw-data/splinterdb_threads_14_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_5.out
+raw-data/splinterdb_threads_16_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_1.out
+raw-data/splinterdb_threads_16_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_2.out
+raw-data/splinterdb_threads_16_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_3.out
+raw-data/splinterdb_threads_16_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_4.out
+raw-data/splinterdb_threads_16_dram_cache_size_8192_pmem_cache_size_0_log_flush_interval_0_iter_5.out
+raw-data/splinterdb_ycsb.build
+raw-data/splinterdb-withlog_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_10000_iter_1.out
+raw-data/splinterdb-withlog_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_10000_iter_2.out
+raw-data/splinterdb-withlog_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_10000_iter_3.out
+raw-data/splinterdb-withlog_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_10000_iter_4.out
+raw-data/splinterdb-withlog_threads_8_dram_cache_size_0_pmem_cache_size_16384_log_flush_interval_10000_iter_5.out
+raw-data/splinterdb-withlog_ycsb.build
+raw-data/splinterdb-withlog.build
+raw-data/splinterdb.build
+.codex
+.gitignore
+deadlock-notes.txt
+deadlock-notes2.txt
+deadlock-notes3.txt
+fio.db
+non-txn.build
+notes.txt
+perf.data
+perf.data.old
+persistron_ycsb.build
+persistron.build
+pmem-cow_ycsb.build
+pmem-cow.build
+splinterdb_ycsb.build
+splinterdb.build
+TAGS
+trunk.log
+src/trunk.c.orig
+src/trunk.h.orig

examples/splinterdb_custom_ipv4_addr_sortcmp_example.c

@@ -346,7 +346,7 @@ do_iterate_from(splinterdb *spl_handle, const char *from_key)
    slice start_key =
       (from_key ? slice_create(strlen(from_key), from_key) : NULL_SLICE);
    int rc = splinterdb_iterator_init(
-      spl_handle, &it, start_key, greater_than_or_equal);
+      spl_handle, &it, greater_than_or_equal, start_key);
 
    int i = 0;
 

examples/splinterdb_intro_example.c

@@ -113,7 +113,7 @@ main()
 
    splinterdb_iterator *it = NULL;
    rc                      = splinterdb_iterator_init(
-      spl_handle, &it, NULL_SLICE, greater_than_or_equal);
+      spl_handle, &it, greater_than_or_equal, NULL_SLICE);
 
    int i = 0;
    for (; splinterdb_iterator_valid(it); splinterdb_iterator_next(it)) {

examples/splinterdb_iterators_example.c

@@ -146,7 +146,7 @@ do_iterate_from(splinterdb *spl_handle, const char *from_key)
    slice start_key =
       (from_key ? slice_create(strlen(from_key), from_key) : NULL_SLICE);
    int rc = splinterdb_iterator_init(
-      spl_handle, &it, start_key, greater_than_or_equal);
+      spl_handle, &it, greater_than_or_equal, start_key);
 
    int i = 0;
 

include/splinterdb/splinterdb.h

@@ -324,8 +324,9 @@ Known issue: a live iterator may block inserts and deletes from the same thread.
 Sample application code:
 
    splinterdb_iterator* it;
-   int rc = splinterdb_iterator_init(kvs, &it, NULL_SLICE,
-greater_than_or_equal); if (rc != 0) { ... handle error ... }
+   int rc = splinterdb_iterator_init(kvs, &it, greater_than_or_equal,
+                                     NULL_SLICE);
+   if (rc != 0) { ... handle error ... }
 
    slice key, value;
 
@@ -361,10 +362,32 @@ typedef enum comparison {
 // - greater_than_or_equal: the minimum key
 // - less_than_or_equal: the maximum key
 int
-splinterdb_iterator_init(splinterdb           *kvs,       // IN
-                         splinterdb_iterator **iter,      // OUT
-                         slice                 start_key, // IN
-                         comparison            start_type // IN
+splinterdb_iterator_init(splinterdb           *kvs,        // IN
+                         splinterdb_iterator **iter,       // OUT
+                         comparison            start_type, // IN
+                         slice                 start_key   // IN
+);
+
+// Initialize a new iterator with lower and upper bounds.
+//
+// If min_key is NULL_SLICE, the iterator has no lower bound.
+// min_key_comparison must be greater_than or greater_than_or_equal.
+//
+// If max_key is NULL_SLICE, the iterator has no upper bound.
+// max_key_comparison must be less_than or less_than_or_equal.
+//
+// If start_key is NULL_SLICE, the iterator will start at:
+// - greater_than_or_equal / greater_than: the first key in bounds
+// - less_than_or_equal / less_than: the last key in bounds
+int
+splinterdb_iterator_init_with_bounds(splinterdb           *kvs,     // IN
+                                     splinterdb_iterator **iter,    // OUT
+                                     comparison min_key_comparison, // IN
+                                     slice      min_key,            // IN
+                                     comparison max_key_comparison, // IN
+                                     slice      max_key,            // IN
+                                     comparison start_type,         // IN
+                                     slice      start_key           // IN
 );
 
 // Deinitialize an iterator