From f8d6e2dddce34304dec1adbceb037fc10975788b Mon Sep 17 00:00:00 2001 From: Jason Volk Date: Wed, 27 Sep 2017 18:24:55 -0700 Subject: [PATCH] ircd::db: Update docs. --- include/ircd/db/cell.h | 3 +-- include/ircd/db/index.h | 20 ++++++++++++++++++++ ircd/db.cc | 3 +++ 3 files changed, 24 insertions(+), 2 deletions(-) diff --git a/include/ircd/db/cell.h b/include/ircd/db/cell.h index 713d63bb1..85b6d5084 100644 --- a/include/ircd/db/cell.h +++ b/include/ircd/db/cell.h @@ -116,8 +116,7 @@ namespace ircd::db { // [SET] Perform operations in a sequence as a single transaction. No template // iterators supported yet, just a ptr range good for contiguous sequences like - // vectors and initializer_lists. To support any iterator I think we'll need to - // forward-expose a wrapping of rocksdb::WriteBatch. + // vectors and initializer_lists. Alternatively, see: iov.h. void write(const cell::delta *const &begin, const cell::delta *const &end, const sopts & = {}); void write(const std::initializer_list &, const sopts & = {}); void write(const sopts &, const std::initializer_list &); diff --git a/include/ircd/db/index.h b/include/ircd/db/index.h index 13ee6821e..e66783036 100644 --- a/include/ircd/db/index.h +++ b/include/ircd/db/index.h @@ -28,6 +28,26 @@ namespace ircd::db struct index; } +/// An index is a glorified column; the database descriptor for this column +/// must specify a prefix-extractor otherwise this index just behaves like +/// a regular key/value column. Index is used to create iterable domains of +/// a column which all share the same key-prefix. +/// +/// The index allows a concatenation of two strings to form a key. This con- +/// catenated key is still unique for the column as a whole and is stored as +/// the full concatenation -- however, as stated above the prefix function must +/// be aware of how such a concatenation can be separated back into two +/// strings. +/// +/// db::index allows the user to query for either just the first string, or +/// the whole concatenation. In either case, the resulting iterator can move +/// only around the keys and values within the domain of that first string. +/// The iterator presents the user with it.first = second string only, thereby +/// hiding the prefix allowing for easier iteration of the domain. +/// +/// Index is not good at reverse iteration due to limitations in RocksDB. Thus +/// it's better to just flip the comparator function for the column. +/// struct ircd::db::index :column { diff --git a/ircd/db.cc b/ircd/db.cc index c71033091..c5a36d813 100644 --- a/ircd/db.cc +++ b/ircd/db.cc @@ -1310,6 +1310,9 @@ ircd::db::for_each(const iov &t, wb.Iterate(&h); } +/// Iterate the iov using the "until protocol" +/// reminder: the closure remains-true-until-the-end; false to break; +/// returns true if the end reached; false if broken early bool ircd::db::until(const iov &t, const std::function &closure)