[3/4] kudu git commit: [c++ client] notes for timestamp-related methods

[to...@apache.org]

[c++ client] notes for timestamp-related methods

Added notes on anticipated changes on methods related to getting
and setting hybrid timestamps while performing READ_AT_SNAPSHOT
scan operations:
  * KuduClient::GetLatestObservedTimestamp()
  * KuduClient::SetLatestObservedTimestamp()
  * KuduScanner::SetSnapshotRaw()

Some changes are anticipated there in the context of KUDU-611.
In short, the timestamp might be replaced with some opaque type
(e.g., a sequence of bytes).

Also, added code sample to provide an idea how to use value returned
by KuduClient::GetLatestObservedTimestamp() to set appropriate snapshot
timestamp via KuduScanner::SetSnapshotRaw().

This addresses the following JIRA issues:
  KUDU-1661 Mark KuduClient::GetLatestObservedTimestamp()
      as experimental
  KUDU-1663 Clean-up in-code documentation for KuduScanner::ReadMode
      and KuduClient::GetLatestObservedTimestamp

Change-Id: I6c45b797fa459ac9d214bb2612fd797f7a1eea45
Reviewed-on: http://gerrit.cloudera.org:8080/4569
Tested-by: Kudu Jenkins
Reviewed-by: David Ribeiro Alves <dr...@apache.org>


Project: http://git-wip-us.apache.org/repos/asf/kudu/repo
Commit: http://git-wip-us.apache.org/repos/asf/kudu/commit/b70d3625
Tree: http://git-wip-us.apache.org/repos/asf/kudu/tree/b70d3625
Diff: http://git-wip-us.apache.org/repos/asf/kudu/diff/b70d3625

Branch: refs/heads/master
Commit: b70d3625b88ef4ad5d15ef68865e933a73c9069c
Parents: 2528edf
Author: Alexey Serbin <as...@cloudera.com>
Authored: Thu Sep 29 17:37:39 2016 -0700
Committer: David Ribeiro Alves <dr...@apache.org>
Committed: Wed Oct 5 07:06:11 2016 +0000

----------------------------------------------------------------------
 src/kudu/client/client.h | 44 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/kudu/blob/b70d3625/src/kudu/client/client.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/client.h b/src/kudu/client/client.h
index 74b84a5..1a113e8 100644
--- a/src/kudu/client/client.h
+++ b/src/kudu/client/client.h
@@ -387,6 +387,38 @@ class KUDU_EXPORT KuduClient : public sp::enable_shared_from_this<KuduClient> {
   /// table which is guaranteed to contain all data written or previously read
   /// by this client. See KuduScanner for more details on timestamps.
   ///
+  /// How to get Read-Your-Writes consistency:
+  /// the code snippet below uses KuduClient::GetLatestObservedTimestamp() along
+  /// with KuduScanner::SetSnapshotRaw() to perform READ_AT_SNAPSHOT scan
+  /// containing the data which has just been written.  Notice extra 1
+  /// added to the timestamp passed to KuduScanner::SetSnapshotRaw():
+  /// @code
+  ///   shared_ptr<KuduClient> client;
+  ///   ... // open/initialize the client
+  ///   shared_ptr<KuduSession> session(client->NewSession());
+  ///   ... // set Kudu session properties
+  ///   shared_ptr<KuduTable> table;
+  ///   ... // open the table
+  ///   unique_ptr<KuduInsert> insert_op(table->NewInsert());
+  ///   ... // populate new insert operation with data
+  ///   RETURN_NOT_OK(session->Apply(insert_op.release()));
+  ///   RETURN_NOT_OK(session->Flush());
+  ///   uint64_t snapshot_timestamp = client->GetLatestObservedTimestamp() + 1;
+  ///   KuduScanner scanner(table.get());
+  ///   RETURN_NOT_OK(scanner.SetSnapshotRaw(snapshot_timestamp));
+  ///   RETURN_NOT_OK(scanner.SetSelection(KuduClient::LEADER_ONLY));
+  ///   RETURN_NOT_OK(scanner.SetReadMode(KuduScanner::READ_AT_SNAPSHOT));
+  ///   RETURN_NOT_OK(scanner.Open());
+  ///   ... // retrieve scanned rows
+  /// @endcode
+  /// There are currently races in which, in rare occasions, Read-Your-Writes
+  /// consistency might not hold even in this case. These are being
+  /// taken care of as part of
+  /// <a href="https://issues.apache.org/jira/browse/KUDU-430">KUDU-430</a>
+  ///
+  /// @note This method is experimental and will either disappear or
+  ///   change in a future release.
+  ///
   /// @return Highest HybridTime timestamp observed by the client.
   uint64_t GetLatestObservedTimestamp() const;
 
@@ -399,6 +431,9 @@ class KUDU_EXPORT KuduClient : public sp::enable_shared_from_this<KuduClient> {
   /// The HybridTime encoded timestamp should be obtained from another client's
   /// KuduClient::GetLatestObservedTimestamp() method.
   ///
+  /// @note This method is experimental and will either disappear or
+  ///   change in a future release.
+  ///
   /// @param [in] ht_timestamp
   ///   Timestamp encoded in HybridTime format.
   void SetLatestObservedTimestamp(uint64_t ht_timestamp);
@@ -1517,7 +1552,8 @@ class KUDU_EXPORT KuduScanner {
     /// timestamp will yield the same data. This is performed at the expense
     /// of waiting for in-flight transactions whose timestamp is lower than
     /// the snapshot's timestamp to complete, so it might incur
-    /// a latency penalty.
+    /// a latency penalty. See KuduScanner::SetSnapshotMicros() and
+    /// KuduScanner::SetSnapshotRaw() for details.
     ///
     /// In ACID terms this, by itself, corresponds to Isolation mode "Repeatable
     /// Read". If all writes to the scanned tablet are made externally
@@ -1806,6 +1842,12 @@ class KUDU_EXPORT KuduScanner {
 
   /// Set snapshot timestamp for scans in @c READ_AT_SNAPSHOT mode (raw).
   ///
+  /// See KuduClient::GetLatestObservedTimestamp() for details on how to
+  /// use this method to achieve Read-Your-Writes behavior.
+  ///
+  /// @note This method is experimental and will either disappear or
+  ///   change in a future release.
+  ///
   /// @param [in] snapshot_timestamp
   ///   Timestamp to set in raw encoded form
   ///   (i.e. as returned by a previous call to a server).