From 6c564e2e174675a782de3fbaa3653e088b9b90d0 Mon Sep 17 00:00:00 2001
From: Yu Zhang <yuzhangyu@fb.com>
Date: Mon, 25 Sep 2023 19:00:39 -0700
Subject: [PATCH] Add some convenience util APIs to facilitate using U64Ts
 (#11888)

Summary:
Added some util function APIs to facilitate using the U64Ts.

The U64Ts format for encoding a timestamp is not entirely RocksDB internal. When users are using the user-defined timestamp feature from the transaction layer, its public APIs including `SetCommitTimestamp`, `GetCommitTimestamp`, `SetReadTimestampForValidation` are taking and returning timestamps as uint64_t.  But if users want to use the APIs from the DB layer, including populating `ReadOptions.timestamp`, interpreting `Iterator::timestamp()`, these APIs are using and returning U64Ts timestamps as an encoded Slice.  So these util functions are added to facilitate the usage.

Pull Request resolved: https://github.com/facebook/rocksdb/pull/11888

Reviewed By: ltamasi

Differential Revision: D49620709

Pulled By: jowlyzhang

fbshipit-source-id: ace8d782ee7c3372cf410abf761320d373e495e1
---
 include/rocksdb/comparator.h | 26 ++++++++++++++++++++++++++
 util/comparator.cc           | 26 ++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/include/rocksdb/comparator.h b/include/rocksdb/comparator.h
index d0ac9f1f448..4b39a25851a 100644
--- a/include/rocksdb/comparator.h
+++ b/include/rocksdb/comparator.h
@@ -175,4 +175,30 @@ const Comparator* BytewiseComparatorWithU64Ts();
 // comes first.
 const Comparator* ReverseBytewiseComparatorWithU64Ts();
 
+// Decode a `U64Ts` timestamp returned by RocksDB to uint64_t.
+// When a column family enables user-defined timestamp feature
+// with `BytewiseComparatorWithU64Ts` or `ReverseBytewiseComparatorWithU64Ts`
+// comparator, the `Iterator::timestamp()` API returns timestamp in `Slice`
+// format. This util function helps to translate that `Slice` into an uint64_t
+// type.
+Status DecodeU64Ts(const Slice& ts, uint64_t* int_ts);
+
+// Encode an uint64_t timestamp into a U64Ts `Slice`, to be used as
+// `ReadOptions.timestamp` for a column family that enables user-defined
+// timestamp feature with `BytewiseComparatorWithU64Ts` or
+// `ReverseBytewiseComparatorWithU64Ts` comparator.
+// Be mindful that the returned `Slice` is backed by `ts_buf`. When `ts_buf`
+// is deconstructed, the returned `Slice` can no longer be used.
+Slice EncodeU64Ts(uint64_t ts, std::string* ts_buf);
+
+// Returns a `Slice` representing the maximum U64Ts timestamp.
+// The returned `Slice` is backed by some static storage, so it's valid until
+// program destruction.
+Slice MaxU64Ts();
+
+// Returns a `Slice` representing the minimum U64Ts timestamp.
+// The returned `Slice` is backed by some static storage, so it's valid until
+// program destruction.
+Slice MinU64Ts();
+
 }  // namespace ROCKSDB_NAMESPACE
diff --git a/util/comparator.cc b/util/comparator.cc
index e573f5e8559..f1f249fd347 100644
--- a/util/comparator.cc
+++ b/util/comparator.cc
@@ -23,6 +23,7 @@
 #include "rocksdb/slice.h"
 #include "rocksdb/utilities/customizable_util.h"
 #include "rocksdb/utilities/object_registry.h"
+#include "util/coding.h"
 
 namespace ROCKSDB_NAMESPACE {
 
@@ -328,6 +329,31 @@ const Comparator* ReverseBytewiseComparatorWithU64Ts() {
   return &comp_with_u64_ts;
 }
 
+Status DecodeU64Ts(const Slice& ts, uint64_t* int_ts) {
+  if (ts.size() != sizeof(uint64_t)) {
+    return Status::InvalidArgument("U64Ts timestamp size mismatch.");
+  }
+  *int_ts = DecodeFixed64(ts.data());
+  return Status::OK();
+}
+
+Slice EncodeU64Ts(uint64_t ts, std::string* ts_buf) {
+  char buf[sizeof(ts)];
+  EncodeFixed64(buf, ts);
+  ts_buf->assign(buf, sizeof(buf));
+  return Slice(*ts_buf);
+}
+
+Slice MaxU64Ts() {
+  static constexpr char kTsMax[] = "\xff\xff\xff\xff\xff\xff\xff\xff";
+  return Slice(kTsMax, sizeof(uint64_t));
+}
+
+Slice MinU64Ts() {
+  static constexpr char kTsMin[] = "\x00\x00\x00\x00\x00\x00\x00\x00";
+  return Slice(kTsMin, sizeof(uint64_t));
+}
+
 static int RegisterBuiltinComparators(ObjectLibrary& library,
                                       const std::string& /*arg*/) {
   library.AddFactory<const Comparator>(