You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kudu.apache.org by to...@apache.org on 2016/08/10 17:50:21 UTC
[2/2] kudu git commit: [C++ client] doxygenized all C++ client API
[C++ client] doxygenized all C++ client API
Doxygenized the rest of header files distributed along with
Kudu C++ client bundle. The client.h file was already doxygenized.
Change-Id: Id0f82a6c8a500a892bc1daff8444e91191dab3af
Reviewed-on: http://gerrit.cloudera.org:8080/3840
Reviewed-by: Adar Dembo <ad...@cloudera.com>
Tested-by: Kudu Jenkins
Project: http://git-wip-us.apache.org/repos/asf/kudu/repo
Commit: http://git-wip-us.apache.org/repos/asf/kudu/commit/88fe33c9
Tree: http://git-wip-us.apache.org/repos/asf/kudu/tree/88fe33c9
Diff: http://git-wip-us.apache.org/repos/asf/kudu/diff/88fe33c9
Branch: refs/heads/master
Commit: 88fe33c99c8f69584334e83506bf710d885f6957
Parents: 1dbfb75
Author: Alexey Serbin <as...@cloudera.com>
Authored: Mon Aug 1 21:16:49 2016 -0700
Committer: Todd Lipcon <to...@apache.org>
Committed: Wed Aug 10 17:45:56 2016 +0000
----------------------------------------------------------------------
src/kudu/client/callbacks.h | 71 ++++++-
src/kudu/client/client.h | 17 +-
src/kudu/client/resource_metrics.h | 19 +-
src/kudu/client/row_result.h | 6 +-
src/kudu/client/scan_batch.h | 235 +++++++++++++++------
src/kudu/client/scan_predicate.h | 12 +-
src/kudu/client/schema.h | 359 +++++++++++++++++++++++---------
src/kudu/client/shared_ptr.h | 28 +--
src/kudu/client/stubs.h | 19 ++
src/kudu/client/value.h | 29 ++-
src/kudu/client/write_op.h | 107 +++++++---
src/kudu/common/partial_row.h | 317 +++++++++++++++++++++++-----
src/kudu/util/monotime.h | 167 ++++++++++++---
src/kudu/util/slice.h | 195 +++++++++++++----
src/kudu/util/status.h | 174 ++++++++++------
15 files changed, 1323 insertions(+), 432 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/callbacks.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/callbacks.h b/src/kudu/client/callbacks.h
index 5c65d3b..f2b1c09 100644
--- a/src/kudu/client/callbacks.h
+++ b/src/kudu/client/callbacks.h
@@ -31,7 +31,8 @@ class Status;
namespace client {
-// All possible log levels.
+
+/// @brief All possible log levels.
enum KuduLogSeverity {
SEVERITY_INFO,
SEVERITY_WARNING,
@@ -39,7 +40,7 @@ enum KuduLogSeverity {
SEVERITY_FATAL
};
-// Interface for all logging callbacks.
+/// @brief The interface for all logging callbacks.
class KUDU_EXPORT KuduLoggingCallback {
public:
KuduLoggingCallback() {
@@ -48,7 +49,22 @@ class KUDU_EXPORT KuduLoggingCallback {
virtual ~KuduLoggingCallback() {
}
- // 'message' is NOT terminated with an endline.
+ /// Log the message.
+ ///
+ /// @note The @c message is NOT terminated with an endline.
+ ///
+ /// @param [in] severity
+ /// Severity of the log message.
+ /// @param [in] filename
+ /// The name of the source file the message is originated from.
+ /// @param [in] line_number
+ /// The line of the source file the message is originated from.
+ /// @param [in] time
+ /// The absolute time when the log event was generated.
+ /// @param [in] message
+ /// The message to log. It's not terminated with an endline.
+ /// @param [in] message_len
+ /// Number of characters in the @c message.
virtual void Run(KuduLogSeverity severity,
const char* filename,
int line_number,
@@ -60,10 +76,11 @@ class KUDU_EXPORT KuduLoggingCallback {
DISALLOW_COPY_AND_ASSIGN(KuduLoggingCallback);
};
-// Logging callback that invokes a member function pointer.
+/// @brief The logging callback that invokes a member function of an object.
template <typename T>
class KUDU_EXPORT KuduLoggingMemberCallback : public KuduLoggingCallback {
public:
+ /// @brief A handy typedef for the member function with appropriate signature.
typedef void (T::*MemberType)(
KuduLogSeverity severity,
const char* filename,
@@ -72,11 +89,18 @@ class KUDU_EXPORT KuduLoggingMemberCallback : public KuduLoggingCallback {
const char* message,
size_t message_len);
+ /// Build an instance of KuduLoggingMemberCallback.
+ ///
+ /// @param [in] object
+ /// A pointer to the object.
+ /// @param [in] member
+ /// A pointer to the member function of the @c object to invoke.
KuduLoggingMemberCallback(T* object, MemberType member)
: object_(object),
member_(member) {
}
+ /// @copydoc KuduLoggingCallback::Run()
virtual void Run(KuduLogSeverity severity,
const char* filename,
int line_number,
@@ -92,10 +116,12 @@ class KUDU_EXPORT KuduLoggingMemberCallback : public KuduLoggingCallback {
MemberType member_;
};
-// Logging callback that invokes a function pointer with a single argument.
+/// @brief The logging callback that invokes a function by pointer
+/// with a single argument.
template <typename T>
class KUDU_EXPORT KuduLoggingFunctionCallback : public KuduLoggingCallback {
public:
+ /// @brief A handy typedef for the function with appropriate signature.
typedef void (*FunctionType)(T arg,
KuduLogSeverity severity,
const char* filename,
@@ -104,11 +130,18 @@ class KUDU_EXPORT KuduLoggingFunctionCallback : public KuduLoggingCallback {
const char* message,
size_t message_len);
+ /// Build an instance of KuduLoggingFunctionCallback.
+ ///
+ /// @param [in] function
+ /// A pointer to the logging function to invoke with the @c arg argument.
+ /// @param [in] arg
+ /// An argument for the function invocation.
KuduLoggingFunctionCallback(FunctionType function, T arg)
: function_(function),
arg_(arg) {
}
+ /// @copydoc KuduLoggingCallback::Run()
virtual void Run(KuduLogSeverity severity,
const char* filename,
int line_number,
@@ -124,7 +157,7 @@ class KUDU_EXPORT KuduLoggingFunctionCallback : public KuduLoggingCallback {
T arg_;
};
-// Interface for all status callbacks.
+/// @brief The interface for all status callbacks.
class KUDU_EXPORT KuduStatusCallback {
public:
KuduStatusCallback() {
@@ -133,23 +166,35 @@ class KUDU_EXPORT KuduStatusCallback {
virtual ~KuduStatusCallback() {
}
+ /// Notify/report on the status.
+ ///
+ /// @param [in] s
+ /// The status to report.
virtual void Run(const Status& s) = 0;
private:
DISALLOW_COPY_AND_ASSIGN(KuduStatusCallback);
};
-// Status callback that invokes a member function pointer.
+/// @brief The status callback that invokes a member function of an object.
template <typename T>
class KUDU_EXPORT KuduStatusMemberCallback : public KuduStatusCallback {
public:
+ /// @brief A handy typedef for the member with appropriate signature.
typedef void (T::*MemberType)(const Status& s);
+ /// Build an instance of the KuduStatusMemberCallback class.
+ ///
+ /// @param [in] object
+ /// A pointer to the object.
+ /// @param [in] member
+ /// A pointer to the member function of the @c object to invoke.
KuduStatusMemberCallback(T* object, MemberType member)
: object_(object),
member_(member) {
}
+ /// @copydoc KuduStatusCallback::Run()
virtual void Run(const Status& s) OVERRIDE {
(object_->*member_)(s);
}
@@ -159,17 +204,27 @@ class KUDU_EXPORT KuduStatusMemberCallback : public KuduStatusCallback {
MemberType member_;
};
-// Status callback that invokes a function pointer with a single argument.
+/// @brief The status callback that invokes a function by pointer
+/// with a single argument.
template <typename T>
class KUDU_EXPORT KuduStatusFunctionCallback : public KuduStatusCallback {
public:
+ /// @brief A handy typedef for the function with appropriate signature.
typedef void (*FunctionType)(T arg, const Status& s);
+ /// Build an instance of KuduStatusFunctionCallback.
+ ///
+ /// @param [in] function
+ /// A pointer to the status report function to invoke
+ /// with the @c arg argument.
+ /// @param [in] arg
+ /// An argument for the function invocation.
KuduStatusFunctionCallback(FunctionType function, T arg)
: function_(function),
arg_(arg) {
}
+ /// @copydoc KuduStatusCallback::Run()
virtual void Run(const Status& s) OVERRIDE {
function_(arg_, s);
}
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/client.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/client.h b/src/kudu/client/client.h
index 625ff3e..44843a3 100644
--- a/src/kudu/client/client.h
+++ b/src/kudu/client/client.h
@@ -303,10 +303,10 @@ class KUDU_EXPORT KuduClient : public sp::enable_shared_from_this<KuduClient> {
/// @return Operation status.
Status ListTabletServers(std::vector<KuduTabletServer*>* tablet_servers);
- /// List only those tables whose names pass a substring match on 'filter'.
+ /// List only those tables whose names pass a substring match on @c filter.
///
/// @param [out] tables
- /// Result tables 'tables' is appended to only on success.
+ /// The placeholder for the result. Appended only on success.
/// @param [in] filter
/// Substring filter to use; empty sub-string filter matches all tables.
/// @return Status object for the operation.
@@ -584,7 +584,7 @@ class KUDU_EXPORT KuduTableCreator {
KuduTableCreator& wait(bool wait);
/// Create a table in accordance with parameters currently set for the
- /// KuduTableCreator instance. Once created, the table handle
+ /// KuduTableCreator instance. Once created, the table handle
/// can be obtained using KuduClient::OpenTable() method.
///
/// @pre The following methods of the KuduTableCreator must be called
@@ -592,9 +592,10 @@ class KUDU_EXPORT KuduTableCreator {
/// @li table_name()
/// @li schema()
///
- /// @return Result status of the @c{CREATE TABLE} operation. The return value
- /// may indicate an error in the create table operation, or a misuse
- /// of the builder. In the latter case, only the last error is returned.
+ /// @return Result status of the <tt>CREATE TABLE</tt> operation.
+ /// The return value may indicate an error in the create table operation,
+ /// or a misuse of the builder. In the latter case, only the last error
+ /// is returned.
Status Create();
private:
@@ -677,7 +678,7 @@ class KUDU_EXPORT KuduTable : public sp::enable_shared_from_this<KuduTable> {
/// @param [in] col_name
/// Name of column to use for comparison.
/// @param [in] op
- /// Comparision operation to use.
+ /// Comparison operator to use.
/// @param [in] value
/// The type of the value must correspond to the type of the column
/// to which the predicate is to be applied. For example,
@@ -696,7 +697,7 @@ class KUDU_EXPORT KuduTable : public sp::enable_shared_from_this<KuduTable> {
KuduPredicate::ComparisonOp op,
KuduValue* value);
- /// @return The KuduClient object associated with the table. The caller
+ /// @return The KuduClient object associated with the table. The caller
/// should not free the returned pointer.
KuduClient* client() const;
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/resource_metrics.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/resource_metrics.h b/src/kudu/client/resource_metrics.h
index d31edaf..feab053 100644
--- a/src/kudu/client/resource_metrics.h
+++ b/src/kudu/client/resource_metrics.h
@@ -26,20 +26,31 @@
namespace kudu {
namespace client {
+/// @brief A generic catalog of simple metrics.
class KUDU_EXPORT ResourceMetrics {
public:
ResourceMetrics();
~ResourceMetrics();
- // Return a map that contains all metrics, its key is the metric name
- // and its value is corresponding metric count.
+ /// @return A map that contains all metrics, its key is the metric name
+ /// and its value is corresponding metric count.
std::map<std::string, int64_t> Get() const;
- // Increment the given metric.
+ /// Increment/decrement the given metric.
+ ///
+ /// @param [in] name
+ /// The name of the metric.
+ /// @param [in] amount
+ /// The amount to increment the metric
+ /// (negative @c amount corresponds to decrementing the metric).
void Increment(const std::string& name, int64_t amount);
- // Return the metric's current count.
+ /// Get current count for the specified metric.
+ ///
+ /// @param [in] name
+ /// Name of the metric in question.
+ /// @return The metric's current count.
int64_t GetMetric(const std::string& name) const;
private:
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/row_result.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/row_result.h b/src/kudu/client/row_result.h
index f1f29ee..f28b28a 100644
--- a/src/kudu/client/row_result.h
+++ b/src/kudu/client/row_result.h
@@ -22,9 +22,9 @@
namespace kudu {
namespace client {
-// DEPRECATED: Kudu 0.7.0 renamed KuduRowResult to KuduScanBatch::RowPtr.
-// The newer name is clearer that the row result's lifetime is tied to the
-// lifetime of a batch.
+/// @deprecated Kudu 0.7.0 renamed KuduRowResult to KuduScanBatch::RowPtr.
+/// The newer name is clearer that the row result's lifetime is tied to the
+/// lifetime of a batch.
typedef KuduScanBatch::RowPtr KuduRowResult;
} // namespace client
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/scan_batch.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/scan_batch.h b/src/kudu/client/scan_batch.h
index 7808905..f3b0ea0 100644
--- a/src/kudu/client/scan_batch.h
+++ b/src/kudu/client/scan_batch.h
@@ -39,56 +39,81 @@ class TsAdminClient;
namespace client {
class KuduSchema;
-// A batch of zero or more rows returned from a KuduScanner.
-//
-// With C++11, you can iterate over the rows in the batch using a
-// range-foreach loop:
-//
-// for (KuduScanBatch::RowPtr row : batch) {
-// ... row.GetInt(1, ...)
-// ...
-// }
-//
-// In C++03, you'll need to use a regular for loop:
-//
-// for (KuduScanBatch::const_iterator it = batch.begin(), it != batch.end();
-// ++i) {
-// KuduScanBatch::RowPtr row(*it);
-// ...
-// }
-//
-// or
-//
-// for (int i = 0, num_rows = batch.NumRows();
-// i < num_rows;
-// i++) {
-// KuduScanBatch::RowPtr row = batch.Row(i);
-// ...
-// }
-//
-// Note that, in the above example, NumRows() is only called once at the
-// beginning of the loop to avoid extra calls to the non-inlined method.
+/// @brief A batch of zero or more rows returned by a scan operation.
+///
+/// Every call to KuduScanner::NextBatch() returns a batch of zero or more rows.
+/// You can iterate over the rows in the batch using:
+///
+/// range-foreach loop (C++11):
+/// @code
+/// for (KuduScanBatch::RowPtr row : batch) {
+/// ... row.GetInt(1, ...)
+/// ...
+/// }
+/// @endcode
+///
+/// regular for loop (C++03):
+/// @code
+/// for (KuduScanBatch::const_iterator it = batch.begin(), it != batch.end();
+/// ++i) {
+/// KuduScanBatch::RowPtr row(*it);
+/// ...
+/// }
+/// @endcode
+/// or
+/// @code
+/// for (int i = 0, num_rows = batch.NumRows();
+/// i < num_rows;
+/// i++) {
+/// KuduScanBatch::RowPtr row = batch.Row(i);
+/// ...
+/// }
+/// @endcode
+///
+/// @note In the above example, NumRows() is only called once at the
+/// beginning of the loop to avoid extra calls to the non-inlined method.
class KUDU_EXPORT KuduScanBatch {
public:
+ /// @brief A single row result from a scan.
+ ///
+ /// @note This object acts as a pointer into a KuduScanBatch, and therefore
+ /// is valid only as long as the batch it was constructed from.
class RowPtr;
+
+ /// @brief C++ forward iterator over the rows in a KuduScanBatch.
+ ///
+ /// This iterator yields KuduScanBatch::RowPtr objects which point inside
+ /// the row batch itself. Thus, the iterator and any objects obtained from it
+ /// are invalidated if the KuduScanBatch is destroyed or used
+ /// for a new NextBatch() call.
class const_iterator;
+
+ /// A handy typedef for the RowPtr.
typedef RowPtr value_type;
KuduScanBatch();
~KuduScanBatch();
- // Return the number of rows in this batch.
+ /// @return The number of rows in this batch.
int NumRows() const;
- // Return a reference to one of the rows in this batch.
- // The returned object is only valid for as long as this KuduScanBatch.
+ /// Get a row at the specified index.
+ ///
+ /// @param [in] idx
+ /// The index of the row to return.
+ /// @return A reference to one of the rows in this batch.
+ /// The returned object is only valid for as long as this KuduScanBatch
+ /// object is valid.
KuduScanBatch::RowPtr Row(int idx) const;
+ /// @return Forward iterator to the start of the rows in the batch.
const_iterator begin() const;
+ /// @return Forward iterator to the end of the rows in the batch.
const_iterator end() const;
- // Returns the projection schema for this batch.
- // All KuduScanBatch::RowPtr returned by this batch are guaranteed to have this schema.
+ /// @return The projection schema for this batch.
+ /// All KuduScanBatch::RowPtr returned by this batch are guaranteed
+ /// to have this schema.
const KuduSchema* projection_schema() const;
private:
@@ -100,21 +125,35 @@ class KUDU_EXPORT KuduScanBatch {
DISALLOW_COPY_AND_ASSIGN(KuduScanBatch);
};
-// A single row result from a scan. Note that this object acts as a pointer into
-// a KuduScanBatch, and therefore is valid only as long as the batch it was constructed
-// from.
class KUDU_EXPORT KuduScanBatch::RowPtr {
public:
- // Construct an invalid RowPtr. Before use, you must assign
- // a properly-initialized value.
+ /// Construct an invalid RowPtr. Before use, you must assign
+ /// a properly-initialized value.
RowPtr() : schema_(NULL), row_data_(NULL) {}
+ /// @param [in] col_name
+ /// Name of the column.
+ /// @return @c true iff the specified column of the row has @c NULL value.
bool IsNull(const Slice& col_name) const;
+
+ /// @param [in] col_idx
+ /// Index of the column.
+ /// @return @c true iff the specified column of the row has @c NULL value.
bool IsNull(int col_idx) const;
- // These getters return a bad Status if the type does not match,
- // the value is unset, or the value is NULL. Otherwise they return
- // the current set value in *val.
+ /// @name Getters for integral type columns by column name.
+ ///
+ /// @param [in] col_name
+ /// The name of the target column.
+ /// @param [out] val
+ /// Placeholder for the result value.
+ /// @return Operation result status. Return a bad Status if at least one
+ /// of the following is @c true:
+ /// @li The type does not match.
+ /// @li The value is unset.
+ /// @li The value is @c NULL.
+ ///
+ ///@{
Status GetBool(const Slice& col_name, bool* val) const WARN_UNUSED_RESULT;
Status GetInt8(const Slice& col_name, int8_t* val) const WARN_UNUSED_RESULT;
@@ -126,10 +165,26 @@ class KUDU_EXPORT KuduScanBatch::RowPtr {
Status GetFloat(const Slice& col_name, float* val) const WARN_UNUSED_RESULT;
Status GetDouble(const Slice& col_name, double* val) const WARN_UNUSED_RESULT;
-
- // Same as above getters, but with numeric column indexes.
- // These are faster since they avoid a hashmap lookup, so should
- // be preferred in performance-sensitive code.
+ ///@}
+
+ /// @name Getters for integral type columns by column index.
+ ///
+ /// These methods are faster than their name-based counterparts
+ /// since using indices avoids a hashmap lookup, so index-based getters
+ /// should be preferred in performance-sensitive code.
+ ///
+ /// @param [in] col_index
+ /// The index of the column.
+ /// @param [out] val
+ /// Pointer to the placeholder to put the resulting value.
+ ///
+ /// @return Operation result status. Return a bad Status if at least one
+ /// of the following is @c true:
+ /// @li The type does not match.
+ /// @li The value is unset.
+ /// @li The value is @c NULL.
+ ///
+ ///@{
Status GetBool(int col_idx, bool* val) const WARN_UNUSED_RESULT;
Status GetInt8(int col_idx, int8_t* val) const WARN_UNUSED_RESULT;
@@ -140,17 +195,63 @@ class KUDU_EXPORT KuduScanBatch::RowPtr {
Status GetFloat(int col_idx, float* val) const WARN_UNUSED_RESULT;
Status GetDouble(int col_idx, double* val) const WARN_UNUSED_RESULT;
-
- // Gets the string/binary value but does not copy the value. Callers should
- // copy the resulting Slice if necessary.
+ ///@}
+
+ /// @name Getters for string/binary column by column name.
+ ///
+ /// Get the string/binary value for a column by its name.
+ ///
+ /// @param [in] col_name
+ /// Name of the column.
+ /// @param [out] val
+ /// Pointer to the placeholder to put the resulting value.
+ /// Note that the method does not copy the value. Callers should copy
+ /// the resulting Slice if necessary.
+ /// @return Operation result status. Return a bad Status if at least one
+ /// of the following is @c true:
+ /// @li The type does not match.
+ /// @li The value is unset.
+ /// @li The value is @c NULL.
+ ///
+ ///@{
Status GetString(const Slice& col_name, Slice* val) const WARN_UNUSED_RESULT;
- Status GetString(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
Status GetBinary(const Slice& col_name, Slice* val) const WARN_UNUSED_RESULT;
+ ///@}
+
+ /// @name Getters for string/binary column by column index.
+ ///
+ /// Get the string/binary value for a column by its index.
+ ///
+ /// These methods are faster than their name-based counterparts
+ /// since using indices avoids a hashmap lookup, so index-based getters
+ /// should be preferred in performance-sensitive code.
+ ///
+ /// @param [in] col_index
+ /// The index of the column.
+ /// @param [out] val
+ /// Pointer to the placeholder to put the resulting value.
+ /// Note that the method does not copy the value. Callers should copy
+ /// the resulting Slice if necessary.
+ /// @return Operation result status. Return a bad Status if at least one
+ /// of the following is @c true:
+ /// @li The type does not match.
+ /// @li The value is unset.
+ /// @li The value is @c NULL.
+ ///
+ ///@{
+ Status GetString(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
Status GetBinary(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
-
- // Raw cell access. Should be avoided unless absolutely necessary.
+ ///@}
+
+ /// Get the column's row data.
+ ///
+ /// @note Should be avoided unless absolutely necessary.
+ /// @param [in] col_idx
+ /// The index of the column.
+ /// @return Raw cell data for the specified index.
const void* cell(int col_idx) const;
+ /// @return String representation for this row.
std::string ToString() const;
private:
@@ -175,38 +276,50 @@ class KUDU_EXPORT KuduScanBatch::RowPtr {
const uint8_t* row_data_;
};
-// C++ forward iterator over the rows in a KuduScanBatch.
-//
-// This iterator yields KuduScanBatch::RowPtr objects which point inside the row batch
-// itself. Thus, the iterator and any objects obtained from it are invalidated if the
-// KuduScanBatch is destroyed or used for a new NextBatch() call.
class KUDU_EXPORT KuduScanBatch::const_iterator
: public std::iterator<std::forward_iterator_tag, KuduScanBatch::RowPtr> {
public:
~const_iterator() {}
+ /// @return The row in the batch the iterator is pointing at.
KuduScanBatch::RowPtr operator*() const {
return batch_->Row(idx_);
}
- // Prefix increment operator: advances the iterator to the next position.
- // Returns the reference to the incremented/advanced iterator.
+ /// Prefix increment operator: advances the iterator to the next position.
+ ///
+ /// @return The reference to the iterator, pointing to the next position.
const_iterator& operator++() {
++idx_;
return *this;
}
- // Postfix increment operator: advances the iterator to the next position.
- // Returns a copy of the iterator pointing to the pre-incremented position.
+ /// Postfix increment operator: advances the iterator to the next position.
+ ///
+ /// @return A copy of the iterator pointing to the pre-increment position.
const_iterator operator++(int) {
const_iterator tmp(batch_, idx_);
++idx_;
return tmp;
}
+ /// An operator to check whether two iterators are 'equal'.
+ ///
+ /// @param [in] other
+ /// The iterator to compare with.
+ /// @return @c true iff the other iterator points to the same row
+ /// of the same batch.
bool operator==(const const_iterator& other) const {
return (idx_ == other.idx_) && (batch_ == other.batch_);
}
+
+ /// An operator to check whether two iterators are 'not equal'.
+ ///
+ /// @param [in] other
+ /// The iterator to compare with.
+ /// @return @c true iff the other iterator points to a different row
+ /// in the same batch, or to a row belonging to a different batch
+ /// altogether.
bool operator!=(const const_iterator& other) const {
return !(*this == other);
}
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/scan_predicate.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/scan_predicate.h b/src/kudu/client/scan_predicate.h
index c1586fe..99736c5 100644
--- a/src/kudu/client/scan_predicate.h
+++ b/src/kudu/client/scan_predicate.h
@@ -30,8 +30,12 @@
namespace kudu {
namespace client {
+/// @brief A representation of comparison predicate for Kudu queries.
+///
+/// Call KuduTable::NewComparisonPredicate() to create a predicate object.
class KUDU_EXPORT KuduPredicate {
public:
+ /// @brief Supported comparison operators.
enum ComparisonOp {
LESS_EQUAL,
GREATER_EQUAL,
@@ -42,11 +46,13 @@ class KUDU_EXPORT KuduPredicate {
~KuduPredicate();
- // Returns a new, identical, KuduPredicate.
+ /// @return A new, identical, KuduPredicate object.
KuduPredicate* Clone() const;
- // The PIMPL class has to be public since it's actually just an interface,
- // and gcc gives an error trying to derive from a private nested class.
+ /// @brief Forward declaration for the embedded PIMPL class.
+ ///
+ /// The PIMPL class has to be public since it's actually just an interface,
+ /// and gcc gives an error trying to derive from a private nested class.
class KUDU_NO_EXPORT Data;
private:
friend class ComparisonPredicateData;
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/schema.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/schema.h b/src/kudu/client/schema.h
index 65fb5c3..099185a 100644
--- a/src/kudu/client/schema.h
+++ b/src/kudu/client/schema.h
@@ -1,4 +1,3 @@
-
//
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
@@ -50,8 +49,10 @@ class KuduSchema;
class KuduSchemaBuilder;
class KuduWriteOperation;
+/// @brief Representation of column storage attributes.
class KUDU_EXPORT KuduColumnStorageAttributes {
public:
+ /// @brief Column encoding types.
enum EncodingType {
AUTO_ENCODING = 0,
PLAIN_ENCODING = 1,
@@ -62,6 +63,7 @@ class KUDU_EXPORT KuduColumnStorageAttributes {
BIT_SHUFFLE = 6
};
+ /// @brief Column compression types.
enum CompressionType {
DEFAULT_COMPRESSION = 0,
NO_COMPRESSION = 1,
@@ -71,8 +73,17 @@ class KUDU_EXPORT KuduColumnStorageAttributes {
};
- // NOTE: this constructor is deprecated for external use, and will
- // be made private in a future release.
+ /// @deprecated This constructor is deprecated for external use, and will
+ /// be made private in a future release.
+ ///
+ /// @todo Make this constructor private.
+ ///
+ /// @param [in] encoding
+ /// Encoding type for the column storage.
+ /// @param [in] compression
+ /// Compression type for the column storage.
+ /// @param [in] block_size
+ /// Block size (in bytes, uncompressed data) for the column storage.
KuduColumnStorageAttributes(EncodingType encoding = AUTO_ENCODING,
CompressionType compression = DEFAULT_COMPRESSION,
int32_t block_size = 0)
@@ -81,14 +92,17 @@ class KUDU_EXPORT KuduColumnStorageAttributes {
block_size_(block_size) {
}
+ /// @return Encoding type for the column storage.
const EncodingType encoding() const {
return encoding_;
}
+ /// @return Comporession type for the column storage.
const CompressionType compression() const {
return compression_;
}
+ /// @return String representation of the storage attributes.
std::string ToString() const;
private:
@@ -97,8 +111,10 @@ class KUDU_EXPORT KuduColumnStorageAttributes {
int32_t block_size_;
};
+/// @brief Representation of the column schema.
class KUDU_EXPORT KuduColumnSchema {
public:
+ /// @brief Supported data types for columns.
enum DataType {
INT8 = 0,
INT16 = 1,
@@ -112,31 +128,74 @@ class KUDU_EXPORT KuduColumnSchema {
TIMESTAMP = 9
};
+ /// @param [in] type
+ /// Column data type.
+ /// @return String representation of the column data type.
static std::string DataTypeToString(DataType type);
- // DEPRECATED: use KuduSchemaBuilder instead.
- // TODO(KUDU-809): make this hard-to-use constructor private. Clients should use
- // the Builder API. Currently only the Python API uses this old API.
+ /// @deprecated Use KuduSchemaBuilder instead.
+ ///
+ /// @todo KUDU-809: make this hard-to-use constructor private.
+ /// Clients should use the Builder API. Currently only the Python API
+ /// uses this old API.
+ ///
+ /// @param [in] name
+ /// The name of the column.
+ /// @param [in] type
+ /// The type of the column.
+ /// @param [in] is_nullable
+ /// Whether the column is nullable.
+ /// @param [in] default_value
+ /// Default value for the column.
+ /// @param [in] attributes
+ /// Column storage attributes.
KuduColumnSchema(const std::string &name,
DataType type,
bool is_nullable = false,
const void* default_value = NULL,
KuduColumnStorageAttributes attributes = KuduColumnStorageAttributes());
+
+ /// Construct KuduColumnSchema object as a copy of another object.
+ ///
+ /// @param [in] other
+ /// The reference object to copy from.
KuduColumnSchema(const KuduColumnSchema& other);
~KuduColumnSchema();
+ /// The assignment operator.
+ ///
+ /// @param [in] other
+ /// The reference object to assign from.
+ /// @return The updated object.
KuduColumnSchema& operator=(const KuduColumnSchema& other);
+ /// Make this object an identical copy of the other one.
+ ///
+ /// @param [in] other
+ /// The reference object to copy from.
void CopyFrom(const KuduColumnSchema& other);
+ /// Check whether the object is identical to the other one.
+ ///
+ /// @param [in] other
+ /// The reference object to compare with.
+ /// @return @c true iff the object is identical to the specified one.
bool Equals(const KuduColumnSchema& other) const;
- // Getters to expose column schema information.
+ /// @name Getters to expose column schema information.
+ ///
+ /// @todo Expose default column value and attributes?
+ ///
+ ///@{
+ /// @return Name of the column schema.
const std::string& name() const;
+
+ /// @return Type of the column schema.
DataType type() const;
- bool is_nullable() const;
- // TODO: Expose default column value and attributes?
+ /// @return @c true iff the column schema has the nullable attribute set.
+ bool is_nullable() const;
+ ///@}
private:
friend class KuduColumnSpec;
@@ -152,82 +211,122 @@ class KUDU_EXPORT KuduColumnSchema {
ColumnSchema* col_;
};
-// Builder API for specifying or altering a column within a table schema.
-// This cannot be constructed directly, but rather is returned from
-// KuduSchemaBuilder::AddColumn() to specify a column within a Schema.
-//
-// TODO(KUDU-861): this API will also be used for an improved AlterTable API.
+/// @brief Builder API for specifying or altering a column
+/// within a table schema.
+///
+/// An object of this type cannot be constructed directly, but rather
+/// is returned from KuduSchemaBuilder::AddColumn() to specify a column
+/// within a Schema.
+///
+/// @todo KUDU-861: this API will also be used for an improved AlterTable API.
class KUDU_EXPORT KuduColumnSpec {
public:
- // Set the default value for this column.
- //
- // When adding a new column to a table, this default value will be used to
- // fill the new column in all existing rows.
- //
- // When a user inserts data, if the user does not specify any value for
- // this column, the default will also be used.
- //
- // The KuduColumnSpec takes ownership over 'value'.
+ /// Set the default value for the column.
+ ///
+ /// When adding a new column to a table, this default value will be used to
+ /// fill the new column in all existing rows. The default value
+ /// will also be used when inserting a new row with no value for the column.
+ ///
+ /// @param [in] value
+ /// The value to use as the default. The KuduColumnSpec takes ownership
+ /// over the passed parameter.
+ ///
+ /// @return Pointer to the modified object.
KuduColumnSpec* Default(KuduValue* value);
- // Set the preferred compression for this column.
+ /// Set the preferred compression type for the column.
+ ///
+ /// @param [in] compression
+ /// The compression type to use.
+ /// @return Pointer to the modified object.
KuduColumnSpec* Compression(KuduColumnStorageAttributes::CompressionType compression);
- // Set the preferred encoding for this column.
- // Note that not all encodings are supported for all column types.
+ /// Set the preferred encoding for the column.
+ ///
+ /// @note Not all encodings are supported for all column types.
+ ///
+ /// @param [in] encoding
+ /// The encoding to use.
+ /// @return Pointer to the modified object.
KuduColumnSpec* Encoding(KuduColumnStorageAttributes::EncodingType encoding);
- // Set the target block size for this column.
- //
- // This is the number of bytes of user data packed per block on disk, and
- // represents the unit of IO when reading this column. Larger values
- // may improve scan performance, particularly on spinning media. Smaller
- // values may improve random access performance, particularly for workloads
- // that have high cache hit rates or operate on fast storage such as SSD.
- //
- // Note that the block size specified here corresponds to uncompressed data.
- // The actual size of the unit read from disk may be smaller if
- // compression is enabled.
- //
- // It's recommended that this not be set any lower than 4096 (4KB) or higher
- // than 1048576 (1MB).
- // TODO(KUDU-1107): move above info to docs
+ /// Set the target block size for the column.
+ ///
+ /// This is the number of bytes of user data packed per block on disk, and
+ /// represents the unit of IO when reading the column. Larger values
+ /// may improve scan performance, particularly on spinning media. Smaller
+ /// values may improve random access performance, particularly for workloads
+ /// that have high cache hit rates or operate on fast storage such as SSD.
+ ///
+ /// @note The block size specified here corresponds to uncompressed data.
+ /// The actual size of the unit read from disk may be smaller if
+ /// compression is enabled.
+ ///
+ /// @note It's recommended that this not be set any lower than 4096 (4KB)
+ /// or higher than 1048576 (1MB).
+ /// @todo KUDU-1107: move above info to docs
+ ///
+ /// @param [in] block_size
+ /// Block size (in bytes) to use.
+ /// @return Pointer to the modified object.
KuduColumnSpec* BlockSize(int32_t block_size);
- // Operations only relevant for Create Table
- // ------------------------------------------------------------
-
- // Set this column to be the primary key of the table.
- //
- // This may only be used to set non-composite primary keys. If a composite
- // key is desired, use KuduSchemaBuilder::SetPrimaryKey(). This may not be
- // used in conjunction with KuduSchemaBuilder::SetPrimaryKey().
- //
- // Only relevant for a CreateTable operation. Primary keys may not be changed
- // after a table is created.
+ /// @name Operations only relevant for Create Table
+ ///
+ ///@{
+ /// Set the column to be the primary key of the table.
+ ///
+ /// This may only be used to set non-composite primary keys. If a composite
+ /// key is desired, use KuduSchemaBuilder::SetPrimaryKey(). This may not be
+ /// used in conjunction with KuduSchemaBuilder::SetPrimaryKey().
+ ///
+ /// @note Primary keys may not be changed after a table is created.
+ ///
+ /// @return Pointer to the modified object.
KuduColumnSpec* PrimaryKey();
- // Set this column to be not nullable.
- // Column nullability may not be changed once a table is created.
+ /// Set the column to be not nullable.
+ ///
+ /// @note Column nullability may not be changed once a table is created.
+ ///
+ /// @return Pointer to the modified object.
KuduColumnSpec* NotNull();
- // Set this column to be nullable (the default).
- // Column nullability may not be changed once a table is created.
+ /// Set the column to be nullable (the default).
+ ///
+ /// @note Column nullability may not be changed once a table is created.
+ ///
+ /// @return Pointer to the modified object.
KuduColumnSpec* Nullable();
- // Set the type of this column.
- // Column types may not be changed once a table is created.
+ /// Set the data type of the column.
+ ///
+ /// @note Column data types may not be changed once a table is created.
+ ///
+ /// @param [in] type
+ /// The data type to set.
+ /// @return Pointer to the modified object.
KuduColumnSpec* Type(KuduColumnSchema::DataType type);
-
- // Operations only relevant for Alter Table
- // ------------------------------------------------------------
-
- // Remove the default value for this column. Without a default, clients must
- // always specify a value for this column when inserting data.
+ ///@}
+
+ /// @name Operations only relevant for Alter Table
+ ///
+ ///@{
+ /// Remove the default value for the column.
+ ///
+ /// Without a default, clients must always specify a value for the column
+ /// when inserting data.
+ ///
+ /// @return Pointer to the modified object.
KuduColumnSpec* RemoveDefault();
- // Rename this column.
+ /// Rename the column.
+ ///
+ /// @param [in] new_name
+ /// The new name for the column.
+ /// @return Pointer to the modified object.
KuduColumnSpec* RenameTo(const std::string& new_name);
+ ///@}
private:
class KUDU_NO_EXPORT Data;
@@ -246,41 +345,58 @@ class KUDU_EXPORT KuduColumnSpec {
Data* data_;
};
-// Builder API for constructing a KuduSchema object.
-// The API here is a "fluent" style of programming, such that the resulting code
-// looks somewhat like a SQL "CREATE TABLE" statement. For example:
-//
-// SQL:
-// CREATE TABLE t (
-// my_key int not null primary key,
-// a float default 1.5
-// );
-//
-// is represented as:
-//
-// KuduSchemaBuilder t;
-// t.AddColumn("my_key")->Type(KuduColumnSchema::INT32)->NotNull()->PrimaryKey();
-// t.AddColumn("a")->Type(KuduColumnSchema::FLOAT)->Default(KuduValue::FromFloat(1.5));
-// KuduSchema schema;
-// t.Build(&schema);
-//
+/// @brief Builder API for constructing a KuduSchema object.
+///
+/// The API here is a "fluent" style of programming, such that the resulting
+/// code looks somewhat like a SQL "CREATE TABLE" statement. For example:
+///
+/// SQL:
+/// @code
+/// CREATE TABLE t (
+/// my_key int not null primary key,
+/// a float default 1.5
+/// );
+/// @endcode
+///
+/// is represented as:
+/// @code
+/// KuduSchemaBuilder t;
+/// t.AddColumn("my_key")->Type(KuduColumnSchema::INT32)->NotNull()->PrimaryKey();
+/// t.AddColumn("a")->Type(KuduColumnSchema::FLOAT)->Default(KuduValue::FromFloat(1.5));
+/// KuduSchema schema;
+/// t.Build(&schema);
+/// @endcode
class KUDU_EXPORT KuduSchemaBuilder {
public:
KuduSchemaBuilder();
~KuduSchemaBuilder();
- // Return a KuduColumnSpec for a new column within the Schema.
- // The returned object is owned by the KuduSchemaBuilder.
+ /// Add a column with the specified name to the schema.
+ ///
+ /// @param [in] name
+ /// Name of the column to add.
+ /// @return A KuduColumnSpec object for a new column within the Schema.
+ /// The returned object is owned by the KuduSchemaBuilder.
KuduColumnSpec* AddColumn(const std::string& name);
- // Set the primary key of the new Schema based on the given column names.
- // This may be used to specify a compound primary key.
+ /// Set the primary key of the new Schema based on the given column names.
+ ///
+ /// This may be used to specify a compound primary key.
+ ///
+ /// @param [in] key_col_names
+ /// Names of the columns to include into the compound primary key.
+ /// @return Pointer to the modified object.
KuduSchemaBuilder* SetPrimaryKey(const std::vector<std::string>& key_col_names);
- // Resets 'schema' to the result of this builder.
- //
- // If the Schema is invalid for any reason (eg missing types, duplicate column names, etc)
- // a bad Status will be returned.
+ /// Build the schema based on current configuration of the builder object.
+ ///
+ /// @param [out] schema
+ /// The placeholder for the result schema. Upon successful completion,
+ /// the parameter is reset to the result of this builder: literally,
+ /// calling KuduSchema::Reset() on the parameter.
+ /// @return Operation result status. If the resulting would-be-schema
+ /// is invalid for any reason (e.g. missing types, duplicate column names,
+ /// etc.) a bad Status is returned.
Status Build(KuduSchema* schema);
private:
@@ -289,36 +405,73 @@ class KUDU_EXPORT KuduSchemaBuilder {
Data* data_;
};
+/// @brief A representation of a table's schema.
class KUDU_EXPORT KuduSchema {
public:
KuduSchema();
+ /// Create a KuduSchema object as a copy of the other one.
+ ///
+ /// @param [in] other
+ /// The other KuduSchema object to use as a reference.
KuduSchema(const KuduSchema& other);
~KuduSchema();
+ /// @name Assign/copy the schema
+ ///
+ /// @param [in] other
+ /// The source KuduSchema object to use as a reference.
+ ///
+ ///@{
KuduSchema& operator=(const KuduSchema& other);
void CopyFrom(const KuduSchema& other);
-
- // DEPRECATED: will be removed soon.
+ ///@}
+
+ /// @deprecated This method will be removed soon.
+ ///
+ /// @todo Remove KuduSchema::Reset().
+ ///
+ /// @param [in] columns
+ /// Per-column schema information.
+ /// @param [in] key_columns
+ /// Number of key columns in the schema.
+ /// @return Operation result status.
Status Reset(const std::vector<KuduColumnSchema>& columns, int key_columns)
WARN_UNUSED_RESULT;
+ /// Check whether the schema is identical to the other one.
+ ///
+ /// @param [in] other
+ /// The other KuduSchema object to compare with.
+ /// @return @c true iff this KuduSchema object is identical
+ /// to the specified one.
bool Equals(const KuduSchema& other) const;
+
+ /// @param [in] idx
+ /// Column index.
+ /// @return Schema for the specified column.
KuduColumnSchema Column(size_t idx) const;
+
+ /// @return The number of columns in the schema.
size_t num_columns() const;
- // Get the indexes of the primary key columns within this Schema.
- // In current versions of Kudu, these will always be contiguous column
- // indexes starting with 0. However, in future versions this assumption
- // may not hold, so callers should not assume it is the case.
+ /// Get the indexes of the primary key columns within this Schema.
+ ///
+ /// @attention In current versions of Kudu, these will always be contiguous
+ /// column indexes starting with 0. However, in future versions this
+ /// assumption may not hold, so callers should not assume it is the case.
+ ///
+ /// @param [out] indexes
+ /// The placeholder for the result.
void GetPrimaryKeyColumnIndexes(std::vector<int>* indexes) const;
- // Create a new row corresponding to this schema.
- //
- // The new row refers to this KuduSchema object, so must be destroyed before
- // the KuduSchema object.
- //
- // The caller takes ownership of the created row.
+ /// Create a new row corresponding to this schema.
+ ///
+ /// @note The new row refers to this KuduSchema object, so it must be
+ /// destroyed before the KuduSchema object to avoid dangling pointers.
+ ///
+ /// @return A pointer to the newly created row. The caller takes ownership
+ /// of the created row.
KuduPartialRow* NewRow() const;
private:
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/shared_ptr.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/shared_ptr.h b/src/kudu/client/shared_ptr.h
index 2cc8c16..731b8cb 100644
--- a/src/kudu/client/shared_ptr.h
+++ b/src/kudu/client/shared_ptr.h
@@ -18,20 +18,20 @@
#ifndef KUDU_CLIENT_SHARED_PTR_H
#define KUDU_CLIENT_SHARED_PTR_H
-// Kudu uses c++11 features internally, but provides a client interface which
-// does not require c++11. We use std::tr1::shared_ptr in our public interface
-// to hold shared instances of KuduClient, KuduSession, and KuduTable.
-//
-// Unfortunately, on OS X, libc++ is the default c++ standard library
-// implementation and is required when compiling with c++11, but it does not
-// include the tr1 APIs. As a workaround, we use std::shared_ptr on OS X, since
-// OS X is for development only, and it is acceptable to require clients to
-// compile with c++11.
-//
-// In order to allow applications to compile against Kudu on both Linux and OS
-// X, we provide this typedef which resolves to std::tr1::shared_ptr on Linux
-// and std::shared_ptr on OS X. Clients are encouraged to use these typedefs in
-// order to ensure that applications will compile on both Linux and OS X.
+/// Kudu uses c++11 features internally, but provides a client interface which
+/// does not require c++11. We use std::tr1::shared_ptr in our public interface
+/// to hold shared instances of KuduClient, KuduSession, and KuduTable.
+///
+/// Unfortunately, on OS X, libc++ is the default c++ standard library
+/// implementation and is required when compiling with c++11, but it does not
+/// include the tr1 APIs. As a workaround, we use std::shared_ptr on OS X, since
+/// OS X is for development only, and it is acceptable to require clients to
+/// compile with c++11.
+///
+/// In order to allow applications to compile against Kudu on both Linux and OS
+/// X, we provide this typedef which resolves to std::tr1::shared_ptr on Linux
+/// and std::shared_ptr on OS X. Clients are encouraged to use these typedefs in
+/// order to ensure that applications will compile on both Linux and OS X.
#if defined(__APPLE__)
#include <memory>
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/stubs.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/stubs.h b/src/kudu/client/stubs.h
index a52bf77..f2158fc 100644
--- a/src/kudu/client/stubs.h
+++ b/src/kudu/client/stubs.h
@@ -170,16 +170,30 @@ namespace kudu {
namespace internal_logging {
+/// @brief A helper for the nil log sink.
+///
+/// Using this helper is analogous to sending log messages to /dev/null:
+/// nothing gets logged.
class NullLog {
public:
+ /// The no-op output operator.
+ ///
+ /// @param [in] t
+ /// The object to send into the nil sink.
+ /// @return Reference to the updated object.
template<class T>
NullLog& operator<<(const T& t) {
return *this;
}
};
+/// @brief A helper for stderr log sink.
class CerrLog {
public:
+ /// Create a CerrLog sink helper object.
+ ///
+ /// @param [in] severity
+ /// The severity for log messages output to the sink (stderr).
CerrLog(int severity) // NOLINT(runtime/explicit)
: severity_(severity),
has_logged_(false) {
@@ -194,6 +208,11 @@ class CerrLog {
}
}
+ /// The output operator.
+ ///
+ /// @param [in] t
+ /// The object to print into stderr.
+ /// @return Reference to the updated object.
template<class T>
CerrLog& operator<<(const T& t) {
has_logged_ = true;
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/value.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/value.h b/src/kudu/client/value.h
index 5ec4031..03a38f5 100644
--- a/src/kudu/client/value.h
+++ b/src/kudu/client/value.h
@@ -29,25 +29,32 @@
namespace kudu {
namespace client {
-// A constant cell value with a specific type.
+/// @brief A constant cell value with a specific type.
class KUDU_EXPORT KuduValue {
public:
- // Return a new identical KuduValue object.
+ /// @return A new identical KuduValue object.
KuduValue* Clone() const;
- // Construct a KuduValue from the given integer.
- static KuduValue* FromInt(int64_t v);
-
- // Construct a KuduValue from the given float.
+ /// @name Builders from integral types.
+ ///
+ /// Construct a KuduValue object from the given value of integral type.
+ ///
+ /// @param [in] val
+ /// The value to build the KuduValue from.
+ /// @return A new KuduValue object.
+ ///
+ ///@{
+ static KuduValue* FromInt(int64_t val);
static KuduValue* FromFloat(float f);
-
- // Construct a KuduValue from the given double.
static KuduValue* FromDouble(double d);
-
- // Construct a KuduValue from the given bool.
static KuduValue* FromBool(bool b);
+ ///@}
- // Construct a KuduValue by copying the value of the given Slice.
+ /// Construct a KuduValue by copying the value of the given Slice.
+ ///
+ /// @param [in] s
+ /// The slice to copy value from.
+ /// @return A new KuduValue object.
static KuduValue* CopyString(Slice s);
~KuduValue();
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/write_op.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/write_op.h b/src/kudu/client/write_op.h
index 51e16a0..b534f1d 100644
--- a/src/kudu/client/write_op.h
+++ b/src/kudu/client/write_op.h
@@ -36,23 +36,25 @@ class WriteRpc;
class KuduTable;
-// A single-row write operation to be sent to a Kudu table.
-//
-// This is the abstract base class from which the particular row operations
-// (KuduInsert, KuduUpdate, etc) are derived. These subclasses are instantiated
-// by KuduTable::NewInsert(), etc.
-//
-// The row key, as well as the columns to be inserted or updated are set using
-// the embedded KuduPartialRow object accessible via mutable_row().
-//
-// Typical usage example:
-//
-// KuduInsert* t = table->NewInsert();
-// KUDU_CHECK_OK(t->mutable_row()->SetInt32("key", 1234));
-// KUDU_CHECK_OK(t->mutable_row()->SetStringCopy("foo", "bar"));
-// session->Apply(t);
+/// @brief A single-row write operation to be sent to a Kudu table.
+///
+/// This is the abstract base class from which the particular row operations
+/// (KuduInsert, KuduUpdate, etc) are derived. These subclasses are instantiated
+/// by KuduTable::NewInsert(), etc.
+///
+/// The row key, as well as the columns to be inserted or updated are set using
+/// the embedded KuduPartialRow object accessible via mutable_row().
+///
+/// Typical usage example:
+/// @code
+/// KuduInsert* t = table->NewInsert();
+/// KUDU_CHECK_OK(t->mutable_row()->SetInt32("key", 1234));
+/// KUDU_CHECK_OK(t->mutable_row()->SetStringCopy("foo", "bar"));
+/// session->Apply(t);
+/// @endcode
class KUDU_EXPORT KuduWriteOperation {
public:
+ /// @brief Write operation types.
enum Type {
INSERT = 1,
UPDATE = 2,
@@ -61,20 +63,40 @@ class KUDU_EXPORT KuduWriteOperation {
};
virtual ~KuduWriteOperation();
- // See KuduPartialRow API for field setters, etc.
+ /// @note To work with a row, use the KuduPartialRow API for field getters,
+ /// etc.
+ /// @return Immutable reference to the corresponding row-like object.
const KuduPartialRow& row() const { return row_; }
+
+ /// @note To work with a row, use the KuduPartialRow API for field setters,
+ /// etc.
+ /// @return Pointer to the corresponding row-like object.
KuduPartialRow* mutable_row() { return &row_; }
+ /// @return String representation of the operation.
virtual std::string ToString() const = 0;
protected:
+ /// @cond PROTECTED_MEMBERS_DOCUMENTED
+
+ /// Create a write operation on the specified table.
+ ///
+ /// @param [in] table
+ /// Smart pointer to the target table.
explicit KuduWriteOperation(const sp::shared_ptr<KuduTable>& table);
+
+ /// @return Type of the operation.
virtual Type type() const = 0;
- // KuduWriteOperation holds shared ownership of its KuduTable to allow the client's
- // scope to end while the KuduWriteOperation is still alive.
+ /// KuduWriteOperation holds shared ownership of its KuduTable
+ /// to allow the client's scope to end while the KuduWriteOperation
+ /// is still alive.
sp::shared_ptr<KuduTable> const table_;
+
+ /// The partial row to access schema-related properties.
KuduPartialRow row_;
+ /// @endcond
+
private:
friend class internal::Batcher;
friend class internal::WriteRpc;
@@ -94,77 +116,106 @@ class KUDU_EXPORT KuduWriteOperation {
};
-// A single row insert to be sent to the cluster.
-// An insert requires all key columns to be set, as well as all
-// columns which do not have default values.
+/// @brief A single row insert to be sent to the cluster.
+///
+/// @pre An insert requires all key columns to be set, as well as all
+/// columns which do not have default values.
class KUDU_EXPORT KuduInsert : public KuduWriteOperation {
public:
virtual ~KuduInsert();
+ /// @copydoc KuduWriteOperation::ToString()
virtual std::string ToString() const OVERRIDE { return "INSERT " + row_.ToString(); }
protected:
+ /// @cond PROTECTED_MEMBERS_DOCUMENTED
+
+ /// @copydoc KuduWriteOperation::type()
virtual Type type() const OVERRIDE {
return INSERT;
}
+ /// @endcond
+
private:
friend class KuduTable;
explicit KuduInsert(const sp::shared_ptr<KuduTable>& table);
};
-// A single row upsert to be sent to the cluster.
-// See KuduInsert for more details.
+/// @brief A single row upsert to be sent to the cluster.
+///
+/// See KuduInsert for more details.
class KUDU_EXPORT KuduUpsert : public KuduWriteOperation {
public:
virtual ~KuduUpsert();
+ /// @copydoc KuduWriteOperation::ToString()
virtual std::string ToString() const OVERRIDE { return "UPSERT " + row_.ToString(); }
protected:
+ /// @cond PROTECTED_MEMBERS_DOCUMENTED
+
+ /// @copydoc KuduWriteOperation::type()
virtual Type type() const OVERRIDE {
return UPSERT;
}
+ /// @endcond
+
private:
friend class KuduTable;
explicit KuduUpsert(const sp::shared_ptr<KuduTable>& table);
};
-// A single row update to be sent to the cluster.
-// An update requires the key columns and at least one other column
-// in the schema to be set in the embedded PartialRow object.
+/// @brief A single row update to be sent to the cluster.
+///
+/// @pre An update requires the key columns and at least one other column
+/// in the schema to be set in the embedded KuduPartialRow object.
class KUDU_EXPORT KuduUpdate : public KuduWriteOperation {
public:
virtual ~KuduUpdate();
+ /// @copydoc KuduWriteOperation::ToString()
virtual std::string ToString() const OVERRIDE { return "UPDATE " + row_.ToString(); }
protected:
+ /// @cond PROTECTED_MEMBERS_DOCUMENTED
+
+ /// @copydoc KuduWriteOperation::type()
virtual Type type() const OVERRIDE {
return UPDATE;
}
+ /// @endcond
+
private:
friend class KuduTable;
explicit KuduUpdate(const sp::shared_ptr<KuduTable>& table);
};
-// A single row delete to be sent to the cluster.
-// A delete requires the key columns to be set in the embedded PartialRow object.
+/// @brief A single row delete to be sent to the cluster.
+///
+/// @pre A delete requires the key columns to be set in the embedded
+/// KuduPartialRow object.
class KUDU_EXPORT KuduDelete : public KuduWriteOperation {
public:
virtual ~KuduDelete();
+ /// @copydoc KuduWriteOperation::ToString()
virtual std::string ToString() const OVERRIDE { return "DELETE " + row_.ToString(); }
protected:
+ /// @cond PROTECTED_MEMBERS_DOCUMENTED
+
+ /// @copydoc KuduWriteOperation::type()
virtual Type type() const OVERRIDE {
return DELETE;
}
+ /// @endcond
+
private:
friend class KuduTable;
explicit KuduDelete(const sp::shared_ptr<KuduTable>& table);
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/common/partial_row.h
----------------------------------------------------------------------
diff --git a/src/kudu/common/partial_row.h b/src/kudu/common/partial_row.h
index 66b430f..e9519ab 100644
--- a/src/kudu/common/partial_row.h
+++ b/src/kudu/common/partial_row.h
@@ -45,25 +45,44 @@ template<typename KeyTypeWrapper> struct IntKeysTestSetup;
class Schema;
class PartialRowPB;
-// A row which may only contain values for a subset of the columns.
-// This type contains a normal contiguous row, plus a bitfield indicating
-// which columns have been set. Additionally, this type may optionally own
-// copies of indirect data for variable length columns.
+/// @brief A row which may only contain values for a subset of the columns.
+///
+/// This object contains a normal contiguous row, plus a bitfield indicating
+/// which columns have been set. Additionally, this type may optionally own
+/// copies of indirect data for variable length columns.
class KUDU_EXPORT KuduPartialRow {
public:
- // The given Schema object must remain valid for the lifetime of this
- // row.
+ /// @param [in] schema
+ /// Schema to use for the row. The given Schema object must remain valid
+ /// for the lifetime of this row.
explicit KuduPartialRow(const Schema* schema);
+
virtual ~KuduPartialRow();
+ /// Create a copy of KuduPartialRow instance.
+ ///
+ /// @param [in] other
+ /// KuduPartialRow instance to copy from.
KuduPartialRow(const KuduPartialRow& other);
+ /// Overwrite this KuduPartialRow instance with data from other instance.
+ ///
+ /// @param [in] other
+ /// KuduPartialRow instance to assign from.
+ /// @return Reference to the updated object.
KuduPartialRow& operator=(KuduPartialRow other);
- //------------------------------------------------------------
- // Setters
- //------------------------------------------------------------
-
+ /// @name Setters for integral type columns by name.
+ ///
+ /// Set value for a column by name.
+ ///
+ /// @param [in] col_name
+ /// Name of the target column.
+ /// @param [in] val
+ /// The value to set.
+ /// @return Operation result status.
+ ///
+ ///@{
Status SetBool(const Slice& col_name, bool val) WARN_UNUSED_RESULT;
Status SetInt8(const Slice& col_name, int8_t val) WARN_UNUSED_RESULT;
@@ -74,10 +93,24 @@ class KUDU_EXPORT KuduPartialRow {
Status SetFloat(const Slice& col_name, float val) WARN_UNUSED_RESULT;
Status SetDouble(const Slice& col_name, double val) WARN_UNUSED_RESULT;
-
- // Same as above setters, but with numeric column indexes.
- // These are faster since they avoid a hashmap lookup, so should
- // be preferred in performance-sensitive code (eg bulk loaders).
+ ///@}
+
+ /// @name Setters for integral type columns by index.
+ ///
+ /// Set value for a column by index.
+ ///
+ /// These setters are the same as corresponding column-name-based setters,
+ /// but with numeric column indexes. These are faster since they avoid
+ /// hashmap lookups, so should be preferred in performance-sensitive code
+ /// (e.g. bulk loaders).
+ ///
+ /// @param [in] col_idx
+ /// The index of the target column.
+ /// @param [in] val
+ /// The value to set.
+ /// @return Operation result status.
+ ///
+ ///@{
Status SetBool(int col_idx, bool val) WARN_UNUSED_RESULT;
Status SetInt8(int col_idx, int8_t val) WARN_UNUSED_RESULT;
@@ -88,44 +121,156 @@ class KUDU_EXPORT KuduPartialRow {
Status SetFloat(int col_idx, float val) WARN_UNUSED_RESULT;
Status SetDouble(int col_idx, double val) WARN_UNUSED_RESULT;
-
- // Sets the string/binary value but does not copy the value. The slice
- // must remain valid until the call to AppendToPB().
+ ///@}
+
+ /// @name Setters for string/binary columns by name.
+ ///
+ /// Set the string/binary value for a column by name.
+ ///
+ /// @note These methods do not copy the value, so the slice must remain valid
+ /// until corresponding data is sent to the server.
+ ///
+ /// @param [in] col_name
+ /// Name of the target column.
+ /// @param [in] val
+ /// The value to set.
+ /// @return Operation result status.
+ ///
+ ///@{
Status SetString(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
- Status SetString(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
Status SetBinary(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
+ ///@}
+
+ /// @name Setters for string/binary columns by index.
+ ///
+ /// Set the string/binary value for a column by index.
+ ///
+ /// These setters are same as the corresponding column-name-based setters,
+ /// but with numeric column indexes. These are faster since they avoid
+ /// hashmap lookups, so should be preferred in performance-sensitive code
+ /// (e.g. bulk loaders).
+ ///
+ /// @note These methods do not copy the value, so the slice must remain valid
+ /// until corresponding data is sent to the server.
+ ///
+ /// @param [in] col_idx
+ /// The index of the target column.
+ /// @param [in] val
+ /// The value to set.
+ /// @return Operation result status.
+ ///
+ ///@{
Status SetBinary(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
-
- // Copies 'val' immediately.
+ Status SetString(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
+ ///@}
+
+ /// @name Setters for string/binary columns by name (copying).
+ ///
+ /// Set the string/binary value for a column by name.
+ ///
+ /// @param [in] col_name
+ /// Name of the target column.
+ /// @param [in] val
+ /// The value to set.
+ /// @return Operation result status.
+ ///
+ ///@{
Status SetStringCopy(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
- Status SetStringCopy(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
Status SetBinaryCopy(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
+ ///@}
+
+ /// @name Setters for string/binary columns by index (copying).
+ ///
+ /// Set the string/binary value for a column by index.
+ ///
+ /// @param [in] col_idx
+ /// The index of the target column.
+ /// @param [in] val
+ /// The value to set.
+ /// @return Operation result status.
+ ///
+ ///@{
+ Status SetStringCopy(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
Status SetBinaryCopy(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
-
- // Set the given column to NULL. This will only succeed on nullable
- // columns. Use Unset(...) to restore a column to its default.
+ ///@}
+
+ /// Set column value to @c NULL; the column is identified by its name.
+ ///
+ /// This will only succeed on nullable columns. Use Unset() to restore
+ /// column value to its default.
+ ///
+ /// @param [in] col_name
+ /// Name of the target column.
+ /// @return Operation result status.
Status SetNull(const Slice& col_name) WARN_UNUSED_RESULT;
+
+ /// Set column value to @c NULL; the column is identified by its index.
+ ///
+ /// This will only succeed on nullable columns. Use Unset() to restore
+ /// column value to its default.
+ ///
+ /// @param [in] col_idx
+ /// The index of the target column.
+ /// @return Operation result status.
Status SetNull(int col_idx) WARN_UNUSED_RESULT;
- // Unsets the given column. Note that this is different from setting
- // it to NULL.
+ /// Unset the given column by name, restoring its default value.
+ ///
+ /// @note This is different from setting it to @c NULL.
+ ///
+ /// @param [in] col_name
+ /// Name of the target column.
+ /// @return Operation result status.
Status Unset(const Slice& col_name) WARN_UNUSED_RESULT;
- Status Unset(int col_idx) WARN_UNUSED_RESULT;
- //------------------------------------------------------------
- // Getters
- //------------------------------------------------------------
- // These getters return a bad Status if the type does not match,
- // the value is unset, or the value is NULL. Otherwise they return
- // the current set value in *val.
+ /// Unset the given column by index, restoring its default value.
+ ///
+ /// @note This is different from setting it to @c NULL.
+ ///
+ /// @param [in] col_idx
+ /// The index of the target column.
+ /// @return Operation result status.
+ Status Unset(int col_idx) WARN_UNUSED_RESULT;
- // Return true if the given column has been specified.
+ /// Check whether the specified column is set for the row.
+ ///
+ /// @param [in] col_name
+ /// Name of the column.
+ /// @return @c true iff the given column has been specified.
bool IsColumnSet(const Slice& col_name) const;
+
+ /// Check whether the specified column is set for the row.
+ ///
+ /// @param [in] col_idx
+ /// The index of the column.
+ /// @return @c true iff the given column has been specified.
bool IsColumnSet(int col_idx) const;
+ /// Check whether the specified column is @c NULL for the row.
+ ///
+ /// @param [in] col_name
+ /// Name of the target column.
+ /// @return @c true iff the given column's value is @c NULL.
bool IsNull(const Slice& col_name) const;
+
+ /// Check whether the specified column is @c NULL for the row.
+ ///
+ /// @param [in] col_idx
+ /// The index of the column.
+ /// @return @c true iff the given column's value is @c NULL.
bool IsNull(int col_idx) const;
+ /// @name Getters for integral type columns by column name.
+ ///
+ /// Get value of the column specified by name.
+ ///
+ /// @return Operation result status. Return a bad Status if at least one
+ /// of the following is @c true:
+ /// @li The type does not match.
+ /// @li The value is unset.
+ /// @li The value is @c NULL.
+ ///
+ ///@{
Status GetBool(const Slice& col_name, bool* val) const WARN_UNUSED_RESULT;
Status GetInt8(const Slice& col_name, int8_t* val) const WARN_UNUSED_RESULT;
@@ -137,10 +282,26 @@ class KUDU_EXPORT KuduPartialRow {
Status GetFloat(const Slice& col_name, float* val) const WARN_UNUSED_RESULT;
Status GetDouble(const Slice& col_name, double* val) const WARN_UNUSED_RESULT;
-
- // Same as above getters, but with numeric column indexes.
- // These are faster since they avoid a hashmap lookup, so should
- // be preferred in performance-sensitive code.
+ ///@}
+
+ /// @name Getters for column of integral type by column index.
+ ///
+ /// Get value of a column of integral type by column index.
+ ///
+ /// These getters are the same as the corresponding column-name-based getters,
+ /// but with numeric column indexes. These are faster since they avoid
+ /// hashmap lookups, so should be preferred in performance-sensitive code
+ /// (e.g. bulk loaders).
+ ///
+ /// @param [in] col_idx
+ /// The index of the target column.
+ /// @return Operation result status. Return a bad Status if at least one
+ /// of the following is @c true:
+ /// @li The type does not match.
+ /// @li The value is unset.
+ /// @li The value is @c NULL.
+ ///
+ ///@{
Status GetBool(int col_idx, bool* val) const WARN_UNUSED_RESULT;
Status GetInt8(int col_idx, int8_t* val) const WARN_UNUSED_RESULT;
@@ -151,42 +312,94 @@ class KUDU_EXPORT KuduPartialRow {
Status GetFloat(int col_idx, float* val) const WARN_UNUSED_RESULT;
Status GetDouble(int col_idx, double* val) const WARN_UNUSED_RESULT;
-
- // Gets the string/binary value but does not copy the value. Callers should
- // copy the resulting Slice if necessary.
+ ///@}
+
+ /// @name Getters for string/binary column by column name.
+ ///
+ /// Get the string/binary value for a column by its name.
+ ///
+ /// @param [in] col_name
+ /// Name of the column.
+ /// @param [out] val
+ /// Pointer to the placeholder to put the resulting value.
+ /// Note that the method does not copy the value. Callers should copy
+ /// the resulting Slice if necessary.
+ /// @return Operation result status. Return a bad Status if at least one
+ /// of the following is @c true:
+ /// @li The type does not match.
+ /// @li The value is unset.
+ /// @li The value is @c NULL.
+ ///
+ ///@{
Status GetString(const Slice& col_name, Slice* val) const WARN_UNUSED_RESULT;
- Status GetString(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
Status GetBinary(const Slice& col_name, Slice* val) const WARN_UNUSED_RESULT;
+ ///@}
+
+ /// @name Getters for string/binary column by column index.
+ ///
+ /// Get the string/binary value for a column by its index.
+ ///
+ /// These methods are faster than their name-based counterparts
+ /// since they use indices to avoid hashmap lookups, so index-based getters
+ /// should be preferred in performance-sensitive code.
+ ///
+ /// @param [in] col_index
+ /// The index of the column.
+ /// @param [out] val
+ /// Pointer to the placeholder to put the resulting value.
+ /// Note that the method does not copy the value. Callers should copy
+ /// the resulting Slice if necessary.
+ /// @return Operation result status. Return a bad Status if at least one
+ /// of the following is @c true:
+ /// @li The type does not match.
+ /// @li The value is unset.
+ /// @li The value is @c NULL.
+ ///
+ ///@{
+ Status GetString(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
Status GetBinary(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
+ ///@}
//------------------------------------------------------------
// Key-encoding related functions
//------------------------------------------------------------
- // Encode a row key suitable for use as a tablet split key, an encoded
- // key range, etc.
- //
- // Requires that all of the key columns must be set; otherwise, returns
- // InvalidArgument.
+ /// Encode a row key.
+ ///
+ /// The result is suitable for use as a tablet split key, an encoded
+ /// key range, etc.
+ ///
+ /// @pre All of the key columns must be set.
+ ///
+ /// @param [out] encoded_key
+ /// The encoded key (i.e. the result of the encoding).
+ /// @return Operation result status. In particular, this method returns
+ /// InvalidArgument if not all the key columns are set.
Status EncodeRowKey(std::string* encoded_key) const;
- // Convenience method which is equivalent to the above, but triggers a
- // FATAL error on failure.
+ /// Convenience method which is similar to EncodeRowKey.
+ ///
+ /// This is equivalent to the EncodeRowKey, but triggers a FATAL error
+ /// on failure.
+ ///
+ /// @return The encoded key.
std::string ToEncodedRowKeyOrDie() const;
//------------------------------------------------------------
// Utility code
//------------------------------------------------------------
- // Return true if all of the key columns have been specified
- // for this mutation.
+ /// @return @c true if all key column values have been set
+ /// for this mutation.
bool IsKeySet() const;
- // Return true if all columns have been specified.
+ /// @return @c true if all column values have been set.
bool AllColumnsSet() const;
+ /// @return String representation for the partial row.
std::string ToString() const;
+ /// @return The schema object for the partial row.
const Schema* schema() const { return schema_; }
private:
http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/util/monotime.h
----------------------------------------------------------------------
diff --git a/src/kudu/util/monotime.h b/src/kudu/util/monotime.h
index 25f3056..de1c1e9 100644
--- a/src/kudu/util/monotime.h
+++ b/src/kudu/util/monotime.h
@@ -36,37 +36,94 @@ struct timespec;
namespace kudu {
class MonoTime;
-// Represent an elapsed duration of time -- i.e the delta between
-// two MonoTime instances.
-//
-// A MonoDelta built with the default constructor is "uninitialized" and
-// may not be used for any operation.
+/// @brief A representation of a time interval.
+///
+/// The MonoDelta class represents an elapsed duration of time -- i.e.
+/// the delta between two MonoTime instances.
class KUDU_EXPORT MonoDelta {
public:
+ /// @name Converters from seconds representation (and ubiquitous SI prefixes).
+ ///
+ /// @param [in] seconds/ms/us/ns
+ /// Time interval representation in seconds (with ubiquitous SI prefixes).
+ /// @return The resulting MonoDelta object initialized in accordance with
+ /// the specified parameter.
+ ///
+ ///@{
static MonoDelta FromSeconds(double seconds);
static MonoDelta FromMilliseconds(int64_t ms);
static MonoDelta FromMicroseconds(int64_t us);
static MonoDelta FromNanoseconds(int64_t ns);
+ ///@}
+
+ /// Build a MonoDelta object.
+ ///
+ /// @note A MonoDelta instance built with the this default constructor is
+ /// "uninitialized" and may not be used for any operation.
MonoDelta();
+
+ /// @return @c true iff this object is initialized.
bool Initialized() const;
+
+ /// Check whether this time interval is shorter than the specified one.
+ ///
+ /// @param [in] rhs
+ /// A time interval for comparison.
+ /// @return @c true iff this time interval is strictly shorter
+ /// than the specified one.
bool LessThan(const MonoDelta &rhs) const;
+
+ /// Check whether this time interval is longer than the specified one.
+ ///
+ /// @param [in] rhs
+ /// A time interval for comparison.
+ /// @return @c true iff this time interval is strictly longer
+ /// than the specified one.
bool MoreThan(const MonoDelta &rhs) const;
+
+ /// Check whether this time interval has the same duration
+ /// as the specified one.
+ ///
+ /// @param [in] rhs
+ /// A time interval for comparison.
+ /// @return @c true iff this time interval has the same duration as the
+ /// the specified one.
bool Equals(const MonoDelta &rhs) const;
+
+ /// @return String representation of this interval's duration (in seconds).
std::string ToString() const;
+
+ /// @name Converters into seconds representation (and ubiquitous SI prefixes).
+ ///
+ /// @return Representation of the time interval in appropriate SI units.
+ ///
+ ///@{
double ToSeconds() const;
int64_t ToMilliseconds() const;
int64_t ToMicroseconds() const;
int64_t ToNanoseconds() const;
+ ///@}
- // Update struct timeval to current value of delta, with microsecond accuracy.
- // Note that if MonoDelta::IsPositive() returns true, the struct timeval
- // is guaranteed to hold a positive number as well (at least 1 microsecond).
+ /// Represent this time interval as a timeval structure, with microsecond
+ /// accuracy.
+ ///
+ /// @param [out] tv
+ /// Placeholder for the result value.
void ToTimeVal(struct timeval *tv) const;
- // Update struct timespec to current value of delta, with nanosecond accuracy.
+ /// Represent this time interval as a timespec structure, with nanosecond
+ /// accuracy.
+ ///
+ /// @param [out] ts
+ /// Placeholder for the result value.
void ToTimeSpec(struct timespec *ts) const;
- // Convert a nanosecond value to a timespec.
+ /// Convert a nanosecond value to a timespec.
+ ///
+ /// @param [in] nanos
+ /// Representation of a relative point in time in nanoseconds.
+ /// @param [out] ts
+ /// Placeholder for the resulting timespec representation.
static void NanosToTimeSpec(int64_t nanos, struct timespec* ts);
private:
@@ -78,44 +135,97 @@ class KUDU_EXPORT MonoDelta {
int64_t nano_delta_;
};
-// Represent a particular point in time, relative to some fixed but unspecified
-// reference point.
-//
-// This time is monotonic, meaning that if the user changes his or her system
-// clock, the monotime does not change.
+/// @brief Representation of a particular point in time.
+///
+/// The MonoTime class represents a particular point in time,
+/// relative to some fixed but unspecified reference point.
+///
+/// This time is monotonic, meaning that if the user changes his or her system
+/// clock, the monotime does not change.
class KUDU_EXPORT MonoTime {
public:
+ /// @brief The granularity of the time specification
+ ///
+ /// The coarse monotonic time is faster to retrieve, but "only"
+ /// accurate to within a millisecond or two. The speed difference will
+ /// depend on your timer hardware.
enum Granularity {
COARSE,
FINE
};
+ /// @name Conversion constants for ubiquitous time units.
+ ///
+ ///@{
static const int64_t kNanosecondsPerSecond = 1000000000L;
static const int64_t kNanosecondsPerMillisecond = 1000000L;
static const int64_t kNanosecondsPerMicrosecond = 1000L;
static const int64_t kMicrosecondsPerSecond = 1000000L;
+ ///@}
- // The coarse monotonic time is faster to retrieve, but "only"
- // accurate to within a millisecond or two. The speed difference will
- // depend on your timer hardware.
+ /// Get current time in MonoTime representation.
+ ///
+ /// @param [in] granularity
+ /// Granularity for the resulting time specification.
+ /// @return Time specification for the moment of the method's invocation.
static MonoTime Now(enum Granularity granularity);
- // Return MonoTime equal to farthest possible time into the future.
+ /// @return MonoTime equal to farthest possible time into the future.
static MonoTime Max();
- // Return MonoTime equal to farthest possible time into the past.
+ /// @return MonoTime equal to farthest possible time into the past.
static MonoTime Min();
- // Return the earliest (minimum) of the two monotimes.
+ /// Select the earliest between the specified time points.
+ ///
+ /// @param [in] a
+ /// The first MonoTime object to select from.
+ /// @param [in] b
+ /// The second MonoTime object to select from.
+ /// @return The earliest (minimum) of the two monotimes.
static const MonoTime& Earliest(const MonoTime& a, const MonoTime& b);
+ /// Build a MonoTime object. The resulting object is not initialized
+ /// and not ready to use.
MonoTime();
+
+ /// @return @c true iff the object is initialized.
bool Initialized() const;
+
+ /// Compute time interval between the point in time specified by this
+ /// and the specified object.
+ ///
+ /// @param [in] rhs
+ /// The object that corresponds to the left boundary of the time interval,
+ /// where this object corresponds to the right boundary of the interval.
+ /// @return The resulting time interval represented as a MonoDelta object.
MonoDelta GetDeltaSince(const MonoTime &rhs) const;
+
+ /// Advance this object's time specification by the specified interval.
+ ///
+ /// @param [in] delta
+ /// The time interval to add.
void AddDelta(const MonoDelta &delta);
+
+ /// Check whether the point in time specified by this object is earlier
+ /// than the specified one.
+ ///
+ /// @param [in] rhs
+ /// The other MonoTime object to compare with.
+ /// @return @c true iff the point in time represented by this MonoTime object
+ /// is earlier then the point in time represented by the parameter.
bool ComesBefore(const MonoTime &rhs) const;
+
+ /// @return String representation of the object (in seconds).
std::string ToString() const;
+
+ /// Check whether this object represents the same point in time as the other.
+ ///
+ /// @param [in] other
+ /// The other MonoTime object to compare.
+ /// @return @c true iff the point in time represented by this MonoTime object
+ /// is the same as the one represented by the other.
bool Equals(const MonoTime& other) const;
private:
@@ -129,11 +239,16 @@ class KUDU_EXPORT MonoTime {
uint64_t nanos_;
};
-// Sleep for a MonoDelta duration.
-//
-// This is preferred over sleep(3), usleep(3), and nanosleep(3). It's less prone to mixups with
-// units since it uses a MonoDelta. It also ignores EINTR, so will reliably sleep at least the
-// MonoDelta duration.
+/// Sleep for an interval specified by a MonoDelta instance.
+///
+/// This is preferred over sleep(3), usleep(3), and nanosleep(3).
+/// It's less prone to mixups with units since it uses the MonoDelta for
+/// interval specification.
+/// Besides, it ignores signals/EINTR, so will reliably sleep at least for the
+/// MonoDelta duration.
+///
+/// @param [in] delta
+/// The time interval to sleep for.
void KUDU_EXPORT SleepFor(const MonoDelta& delta);
} // namespace kudu