Bidirectional Iterators (#588)

* tweak iterator api to make it easier to add bidirectionality

* debugging btree reverse iteration

* reduce time we hold locks during btree_split_child_leaf

* further refine the locking in btree node splits and fix reverse iterator bug

* btree iterator init at key other than min and add btree_iterator_seek

* splinterdb_iterator_prev implmentated and working

* clang formatting

* improve the trunk iterator logic

* corrections for pull request

* more pull request fixes

* assert fix

* more pull request feedback

* iterator stress test, bug fixes, formatting

* final bit of pr feedback

* formatting

---------

Co-authored-by: Evan West <[email protected]>

include/splinterdb/splinterdb.h

@@ -330,12 +330,36 @@ splinterdb_iterator_deinit(splinterdb_iterator *iter);
 
 // Checks that the iterator status is OK (no errors) and that get_current()
 // will succeed. If false, there are two possibilities:
-// 1. Iterator has passed the final item.  In this case, status() == 0
+// 1. Iterator is out of bounds.  In this case, status() == 0
 // 2. Iterator has encountered an error.  In this case, status() != 0
 _Bool
 splinterdb_iterator_valid(splinterdb_iterator *iter);
 
-// Attempts to advance the iterator to the next item.
+/*
+ * splinterdb_iterator_can_next --
+ * splinterdb_iterator_can_prev --
+ *
+ * Knowing the iterator is invalid does not provide enough information to
+ * determine if next and prev are safe operations.
+ *
+ * These functions provide granular information on which operations are safe.
+ * splinterdb_iterator_can_next == TRUE <-> splinterdb_iterator_next is safe
+ * splinterdb_iterator_can_prev == TRUE <-> splinterdb_iterator_prev is safe
+ */
+_Bool
+splinterdb_iterator_can_prev(splinterdb_iterator *iter);
+
+_Bool
+splinterdb_iterator_can_next(splinterdb_iterator *iter);
+
+// Moves the iterator to the previous item.
+// Precondition for calling: splinterdb_iterator_can_prev() returns TRUE
+// Any error will cause valid() == false and be visible with status()
+void
+splinterdb_iterator_prev(splinterdb_iterator *iter);
+
+// Moves the iterator to the next item.
+// Precondition for calling: splinterdb_iterator_can_next() returns TRUE
 // Any error will cause valid() == false and be visible with status()
 void
 splinterdb_iterator_next(splinterdb_iterator *iter);