You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kudu.apache.org by ab...@apache.org on 2020/08/27 13:52:11 UTC
[kudu] branch master updated: Fix C++ client API docs
This is an automated email from the ASF dual-hosted git repository.
abukor pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/kudu.git
The following commit(s) were added to refs/heads/master by this push:
new c590a05 Fix C++ client API docs
c590a05 is described below
commit c590a05778443bb6112e831d0b0ad0dce4b74724
Author: Attila Bukor <ab...@apache.org>
AuthorDate: Wed Aug 26 14:02:06 2020 +0200
Fix C++ client API docs
This patch fixes C++ API doxygen comments so the build succeeds. It's
unclear when this broke exactly.
Running docs/support/scripts/make_site.sh with Doxygen 1.8.11 failed
with the below warning:
util/monotime.h:371: error: argument 'lhs' of command @param is not found in the argument list of kudu::MonoDelta::operator+(const MonoDelta &, const MonoDelta &) (warning treated as error, aborting now)
When Kudu 1.12.0 was released, the docs were generated with Doxygen
1.8.11, although it's possible that treating warnings as errors was
disabled for the release to work around this issue.
After upgrading to Doxygen 1.8.15 this warning disappeared, but a
different one surfaced:
common/partial_row.h:105: error: Member SetBool(const Slice &col_name, bool val) WARN_UNUSED_RESULT (function) of class KuduPartialRow is not documented. (warning treated as error, aborting now)
I disabled WARN_AS_ERROR temporarily only to discover several other
warnings. Some of them were due to Doxygen bugs solved by another update
to 1.8.19 in commit de31237, the rest manually by this commit.
Change-Id: I387be394d656a7614189148a39ff7dec76eb994d
Reviewed-on: http://gerrit.cloudera.org:8080/16372
Tested-by: Kudu Jenkins
Reviewed-by: Grant Henke <gr...@apache.org>
---
src/kudu/client/client.h | 22 +++--
src/kudu/client/scan_batch.cc | 10 ++-
src/kudu/client/scan_batch.h | 78 +++++++++++-----
src/kudu/client/schema.h | 26 +++---
src/kudu/client/value.h | 11 ++-
src/kudu/common/partial_row.h | 204 ++++++++++++++++++++++++++----------------
src/kudu/util/monotime.h | 45 +++++++---
src/kudu/util/status.h | 6 +-
8 files changed, 255 insertions(+), 147 deletions(-)
diff --git a/src/kudu/client/client.h b/src/kudu/client/client.h
index e845c8f..4062c59 100644
--- a/src/kudu/client/client.h
+++ b/src/kudu/client/client.h
@@ -1111,10 +1111,16 @@ class KUDU_EXPORT KuduTable : public sp::enable_shared_from_this<KuduTable> {
KuduPredicate::ComparisonOp op,
KuduValue* value);
+ /// @name Advanced/Unstable API
+ ///
+ /// There are no guarantees on the stability of this client API.
+ ///
+ ///@{
+
/// Create a new IN Bloom filter predicate which can be used for scanners on
/// this table.
///
- /// @note This method is experimental and may change or disappear in future.
+ /// @warning This method is experimental and may change or disappear in future.
///
/// A Bloom filter is a space-efficient probabilistic data structure used to
/// test set membership with a possibility of false positive matches.
@@ -1147,11 +1153,6 @@ class KUDU_EXPORT KuduTable : public sp::enable_shared_from_this<KuduTable> {
KuduPredicate* NewInBloomFilterPredicate(const Slice& col_name,
std::vector<KuduBloomFilter*>* bloom_filters);
- /// @name Advanced/Unstable API
- ///
- /// There are no guarantees on the stability of this client API.
- ///
- ///@{
/// Create a new IN Bloom filter predicate using direct BlockBloomFilter
/// pointers which can be used for scanners on this table.
///
@@ -1169,6 +1170,8 @@ class KUDU_EXPORT KuduTable : public sp::enable_shared_from_this<KuduTable> {
/// positives and automatic disablement of an ineffective Bloom filter
/// predicate to get precise set membership information.
///
+ /// @warning This method is experimental and may change or disappear in future.
+ ///
/// @param [in] col_name
/// Name of the column to which the predicate applies.
/// @param bloom_filters
@@ -2433,14 +2436,15 @@ class KUDU_EXPORT KuduScanner {
sp::shared_ptr<KuduTable> GetKuduTable();
/// @name Advanced/Unstable API
- //
- ///@{
+ ///
/// Modifier flags for the row format returned from the server.
///
/// @note Each flag corresponds to a bit that gets set on a bitset that is sent
/// to the server. See SetRowFormatFlags() for example usage.
+ ///@{
+
+ /// No flags set.
static const uint64_t NO_FLAGS = 0;
- /// Makes the server pad UNIXTIME_MICROS slots to 16 bytes.
/// @note This flag actually wastes throughput by making messages larger than they need to
/// be. It exists merely for compatibility reasons and requires the user to know the row
/// format in order to decode the data. That is, if this flag is enabled, the user _must_
diff --git a/src/kudu/client/scan_batch.cc b/src/kudu/client/scan_batch.cc
index 6f3c278..f9271fc 100644
--- a/src/kudu/client/scan_batch.cc
+++ b/src/kudu/client/scan_batch.cc
@@ -146,8 +146,9 @@ Status KuduScanBatch::RowPtr::GetInt64(const Slice& col_name, int64_t* val) cons
return Get<TypeTraits<INT64> >(col_name, val);
}
-Status KuduScanBatch::RowPtr::GetUnixTimeMicros(const Slice& col_name, int64_t* val) const {
- return Get<TypeTraits<UNIXTIME_MICROS> >(col_name, val);
+Status KuduScanBatch::RowPtr::GetUnixTimeMicros(const Slice& col_name,
+ int64_t* micros_since_utc_epoch) const {
+ return Get<TypeTraits<UNIXTIME_MICROS> >(col_name, micros_since_utc_epoch);
}
Status KuduScanBatch::RowPtr::GetDate(const Slice& col_name, int32_t* days_since_unix_epoch) const {
@@ -200,8 +201,9 @@ Status KuduScanBatch::RowPtr::GetInt64(int col_idx, int64_t* val) const {
return Get<TypeTraits<INT64> >(col_idx, val);
}
-Status KuduScanBatch::RowPtr::GetUnixTimeMicros(int col_idx, int64_t* val) const {
- return Get<TypeTraits<UNIXTIME_MICROS> >(col_idx, val);
+Status KuduScanBatch::RowPtr::GetUnixTimeMicros(int col_idx,
+ int64_t* micros_since_utc_epoch) const {
+ return Get<TypeTraits<UNIXTIME_MICROS> >(col_idx, micros_since_utc_epoch);
}
Status KuduScanBatch::RowPtr::GetDate(int col_idx, int32_t* days_since_unix_epoch) const {
diff --git a/src/kudu/client/scan_batch.h b/src/kudu/client/scan_batch.h
index 2889138..5002536 100644
--- a/src/kudu/client/scan_batch.h
+++ b/src/kudu/client/scan_batch.h
@@ -132,17 +132,21 @@ class KUDU_EXPORT KuduScanBatch {
///
/// @note The Slices returned by both direct_data() and indirect_data()
/// are only valid for the lifetime of the KuduScanBatch.
- //
///@{
+
/// Return a slice that points to the direct row data received from the
/// server. Users of this API must have knowledge of the data format in
/// order to decode the data.
///
+ /// @warning Unstable API
+ ///
/// @return a Slice that points to the raw direct row data.
Slice direct_data() const;
/// Like the method above, but for indirect data.
///
+ /// @warning Unstable API
+ ///
/// @return a Slice that points to the raw indirect row data.
Slice indirect_data() const;
///@}
@@ -188,7 +192,8 @@ class KUDU_EXPORT KuduScanBatch::RowPtr {
Status IsDeleted(bool* val) const WARN_UNUSED_RESULT KUDU_NO_EXPORT;
/// @name Getters for integral type columns by column name.
- ///
+ ///@{
+
/// @param [in] col_name
/// The name of the target column.
/// @param [out] val
@@ -198,21 +203,34 @@ class KUDU_EXPORT KuduScanBatch::RowPtr {
/// @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;
Status GetInt16(const Slice& col_name, int16_t* val) const WARN_UNUSED_RESULT;
Status GetInt32(const Slice& col_name, int32_t* val) const WARN_UNUSED_RESULT;
Status GetInt64(const Slice& col_name, int64_t* val) const WARN_UNUSED_RESULT;
- Status GetUnixTimeMicros(const Slice& col_name, int64_t* micros_since_utc_epoch)
- const WARN_UNUSED_RESULT;
+ /// @param [in] col_name
+ /// The name of the target column.
+ /// @param [out] micros_since_utc_epoch
+ /// 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 GetUnixTimeMicros(const Slice& col_name,
+ int64_t* micros_since_utc_epoch) const WARN_UNUSED_RESULT;
+ /// @param [in] col_name
+ /// The name of the target column.
+ /// @param [out] days_since_unix_epoch
+ /// 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 GetDate(const Slice& col_name, int32_t* days_since_unix_epoch) const WARN_UNUSED_RESULT;
-
Status GetFloat(const Slice& col_name, float* val) const WARN_UNUSED_RESULT;
Status GetDouble(const Slice& col_name, double* val) const WARN_UNUSED_RESULT;
-
#if KUDU_INT128_SUPPORTED
Status GetUnscaledDecimal(const Slice& col_name, int128_t* val) const WARN_UNUSED_RESULT;
#endif
@@ -223,8 +241,9 @@ class KUDU_EXPORT KuduScanBatch::RowPtr {
/// 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
+ ///@{
+
+ /// @param [in] col_idx
/// The index of the column.
/// @param [out] val
/// Pointer to the placeholder to put the resulting value.
@@ -234,27 +253,43 @@ class KUDU_EXPORT KuduScanBatch::RowPtr {
/// @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;
Status GetInt16(int col_idx, int16_t* val) const WARN_UNUSED_RESULT;
Status GetInt32(int col_idx, int32_t* val) const WARN_UNUSED_RESULT;
Status GetInt64(int col_idx, int64_t* val) const WARN_UNUSED_RESULT;
+ /// @param [in] col_idx
+ /// The index of the column.
+ /// @param [out] micros_since_utc_epoch
+ /// 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 GetUnixTimeMicros(int col_idx, int64_t* micros_since_utc_epoch) const WARN_UNUSED_RESULT;
+ /// @param [in] col_idx
+ /// The index of the column.
+ /// @param [out] days_since_unix_epoch
+ /// 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 GetDate(int col_idx, int32_t* days_since_unix_epoch) const WARN_UNUSED_RESULT;
-
Status GetFloat(int col_idx, float* val) const WARN_UNUSED_RESULT;
Status GetDouble(int col_idx, double* val) const WARN_UNUSED_RESULT;
-
#if KUDU_INT128_SUPPORTED
Status GetUnscaledDecimal(int col_idx, int128_t* val) const WARN_UNUSED_RESULT;
#endif
///@}
/// @name Getters for string/binary/varchar column by column name.
- ///
+ ///@{
+
/// Get the string/binary/varchar value for a column by its name.
///
/// @param [in] col_name
@@ -268,22 +303,21 @@ class KUDU_EXPORT KuduScanBatch::RowPtr {
/// @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 GetBinary(const Slice& col_name, Slice* val) const WARN_UNUSED_RESULT;
Status GetVarchar(const Slice& col_name, Slice* val) const WARN_UNUSED_RESULT;
///@}
/// @name Getters for string/binary/varchar column by column index.
- ///
+ ///@{
+
/// Get the string/binary/varchar 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
+ /// @param [in] col_idx
/// The index of the column.
/// @param [out] val
/// Pointer to the placeholder to put the resulting value.
@@ -294,8 +328,6 @@ class KUDU_EXPORT KuduScanBatch::RowPtr {
/// @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;
Status GetVarchar(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
diff --git a/src/kudu/client/schema.h b/src/kudu/client/schema.h
index 08e9846..7e3f2a9 100644
--- a/src/kudu/client/schema.h
+++ b/src/kudu/client/schema.h
@@ -91,12 +91,15 @@ class KUDU_EXPORT KuduColumnTypeAttributes {
~KuduColumnTypeAttributes();
/// @name Assign/copy KuduColumnTypeAttributes.
- ///
+ ///@{
+
/// @param [in] other
/// The source KuduColumnTypeAttributes object to use as a reference.
- ///
- ///@{
+ /// @return Copy of 'other'
KuduColumnTypeAttributes& operator=(const KuduColumnTypeAttributes& other);
+
+ /// @param [in] other
+ /// The source KuduColumnTypeAttributes object to use as a reference.
void CopyFrom(const KuduColumnTypeAttributes& other);
///@}
@@ -388,7 +391,7 @@ class KUDU_EXPORT KuduColumnSpec {
KuduColumnSpec* BlockSize(int32_t block_size);
/// @name Operations only relevant for decimal columns.
- ///
+
///@{
/// Set the precision for the column.
///
@@ -426,7 +429,7 @@ class KUDU_EXPORT KuduColumnSpec {
///@}
/// @name Operation only relevant for VARCHAR columns.
- ///
+
///@{
/// Set the length for a column.
///
@@ -444,7 +447,7 @@ class KUDU_EXPORT KuduColumnSpec {
///@}
/// @name Operations only relevant for Create Table
- ///
+
///@{
/// Set the column to be the primary key of the table.
///
@@ -482,7 +485,7 @@ class KUDU_EXPORT KuduColumnSpec {
///@}
/// @name Operations only relevant for Alter Table
- ///
+
///@{
/// Remove the default value for the column.
///
@@ -603,12 +606,15 @@ class KUDU_EXPORT KuduSchema {
~KuduSchema();
/// @name Assign/copy the schema
- ///
+ ///@{
+
/// @param [in] other
/// The source KuduSchema object to use as a reference.
- ///
- ///@{
+ /// @return Copy of 'other'
KuduSchema& operator=(const KuduSchema& other);
+
+ /// @param [in] other
+ /// The source KuduSchema object to use as a reference.
void CopyFrom(const KuduSchema& other);
///@}
diff --git a/src/kudu/client/value.h b/src/kudu/client/value.h
index 62277ff..7791555 100644
--- a/src/kudu/client/value.h
+++ b/src/kudu/client/value.h
@@ -38,18 +38,17 @@ class KUDU_EXPORT KuduValue {
KuduValue* Clone() const;
/// @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);
- static KuduValue* FromDouble(double d);
- static KuduValue* FromBool(bool b);
+ static KuduValue* FromFloat(float val);
+ static KuduValue* FromDouble(double val);
+ static KuduValue* FromBool(bool val);
///@}
#if KUDU_INT128_SUPPORTED
diff --git a/src/kudu/common/partial_row.h b/src/kudu/common/partial_row.h
index e0b4b64..fb29ef0 100644
--- a/src/kudu/common/partial_row.h
+++ b/src/kudu/common/partial_row.h
@@ -92,7 +92,8 @@ class KUDU_EXPORT KuduPartialRow {
KuduPartialRow& operator=(KuduPartialRow other);
/// @name Setters for integral type columns by name.
- ///
+ ///@{
+
/// Set value for a column by name.
///
/// @param [in] col_name
@@ -100,19 +101,28 @@ class KUDU_EXPORT KuduPartialRow {
/// @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;
Status SetInt16(const Slice& col_name, int16_t val) WARN_UNUSED_RESULT;
Status SetInt32(const Slice& col_name, int32_t val) WARN_UNUSED_RESULT;
Status SetInt64(const Slice& col_name, int64_t val) WARN_UNUSED_RESULT;
+ /// Set value for a column by name.
+ ///
+ /// @param [in] col_name
+ /// Name of the target column.
+ /// @param [in] micros_since_utc_epoch
+ /// The value to set.
+ /// @return Operation result status.
Status SetUnixTimeMicros(const Slice& col_name,
int64_t micros_since_utc_epoch) WARN_UNUSED_RESULT;
- Status SetDate(const Slice& col_name,
- int32_t days_since_unix_epoch) WARN_UNUSED_RESULT;
-
+ /// Set value for a column by name.
+ ///
+ /// @param [in] col_name
+ /// Name of the target column.
+ /// @param [in] days_since_unix_epoch
+ /// The value to set.
+ /// @return Operation result status.
+ Status SetDate(const Slice& col_name, int32_t days_since_unix_epoch) WARN_UNUSED_RESULT;
Status SetFloat(const Slice& col_name, float val) WARN_UNUSED_RESULT;
Status SetDouble(const Slice& col_name, double val) WARN_UNUSED_RESULT;
#if KUDU_INT128_SUPPORTED
@@ -122,27 +132,36 @@ class KUDU_EXPORT KuduPartialRow {
/// @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;
Status SetInt16(int col_idx, int16_t val) WARN_UNUSED_RESULT;
Status SetInt32(int col_idx, int32_t val) WARN_UNUSED_RESULT;
Status SetInt64(int col_idx, int64_t val) WARN_UNUSED_RESULT;
+
+ /// @param [in] col_idx
+ /// The index of the target column.
+ /// @param [in] micros_since_utc_epoch
+ /// The value to set.
+ /// @return Operation result status.
Status SetUnixTimeMicros(int col_idx, int64_t micros_since_utc_epoch) WARN_UNUSED_RESULT;
+
+ /// @param [in] col_idx
+ /// The index of the target column.
+ /// @param [in] days_since_unix_epoch
+ /// The value to set.
+ /// @return Operation result status.
Status SetDate(int col_idx, int32_t days_since_unix_epoch) WARN_UNUSED_RESULT;
Status SetFloat(int col_idx, float val) WARN_UNUSED_RESULT;
@@ -153,7 +172,8 @@ class KUDU_EXPORT KuduPartialRow {
///@}
/// @name Setters for binary/string columns by name (copying).
- ///
+ ///@{
+
/// Set the binary/string value for a column by name, copying the specified
/// data immediately.
///
@@ -167,14 +187,10 @@ class KUDU_EXPORT KuduPartialRow {
/// @param [in] val
/// The value to set.
/// @return Operation result status.
- ///
- ///@{
Status SetBinary(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
Status SetString(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
///@}
- /// @name Setters for varchar columns by name (copying).
- ///
/// Set the varchar value for a column by name, copying the
/// specified data immediately.
///
@@ -187,7 +203,8 @@ class KUDU_EXPORT KuduPartialRow {
Status SetVarchar(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
/// @name Setters for binary/string columns by index (copying).
- ///
+ ///@{
+
/// Set the binary/string value for a column by index, copying
/// the specified data immediately.
///
@@ -206,14 +223,10 @@ class KUDU_EXPORT KuduPartialRow {
/// @param [in] val
/// The value to set.
/// @return Operation result status.
- ///
- ///@{
Status SetBinary(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
Status SetString(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
///@}
- /// @name Setter for varchar columns by index (copying).
- ///
/// Set the varchar value for a column by index, copying
/// the specified data immediately.
///
@@ -227,11 +240,11 @@ class KUDU_EXPORT KuduPartialRow {
/// @param [in] val
/// The value to set.
/// @return Operation result status.
- ///
Status SetVarchar(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
/// @name Setters for binary/string columns by name (copying).
- ///
+ ///@{
+
/// Set the binary/string value for a column by name, copying the specified
/// data immediately.
///
@@ -240,14 +253,13 @@ class KUDU_EXPORT KuduPartialRow {
/// @param [in] val
/// The value to set.
/// @return Operation result status.
- ///
- ///@{
Status SetBinaryCopy(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
Status SetStringCopy(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
///@}
/// @name Setters for binary/string columns by index (copying).
- ///
+ ///@{
+
/// Set the binary/string value for a column by index, copying the specified
/// data immediately.
///
@@ -261,14 +273,13 @@ class KUDU_EXPORT KuduPartialRow {
/// @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;
///@}
/// @name Setters for binary/string columns by name (non-copying).
- ///
+ ///@{
+
/// Set the binary/string value for a column by name, not copying the
/// specified data.
///
@@ -282,17 +293,16 @@ class KUDU_EXPORT KuduPartialRow {
/// @param [in] val
/// The value to set.
/// @return Operation result status.
- ///
- ///@{
Status SetBinaryNoCopy(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
Status SetStringNoCopy(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
///@}
- /// @name [Advanced][Unstable] Setter for varchar columns by name (non-copying).
- ///
- /// Set the varchar value for a column by name, not copying the
- /// specified data.
+ /// @name Advanced/Unstable API
///
+ /// There are no guarantees that the validation performed by these methods for
+ /// 'val' will not change.
+ ///@{
+
/// This method expects the values to be truncated already and they only do a
/// basic validation that the data is not larger than the maximum column
/// length (as indicated by the schema) multiplied by 4, as that's the upper
@@ -304,21 +314,23 @@ class KUDU_EXPORT KuduPartialRow {
/// if any errors happened (the errors can be fetched using the
/// KuduSession::GetPendingErrors() method).
///
+ /// @warning Unstable API
+ ///
/// @param [in] col_name
/// Name of the target column.
/// @param [in] val
/// The value to set.
/// @return Operation result status.
- ///
Status SetVarcharNoCopyUnsafe(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
- /// @name Setters for binary/string columns by index (non-copying).
- ///
- /// Set the binary/string value for a column by index, not copying the
- /// specified data.
+ /// This method expects the values to be truncated already and they only do a
+ /// basic validation that the data is not larger than the maximum column
+ /// length (as indicated by the schema) multiplied by 4, as that's the upper
+ /// limit if only 4-byte UTF8 characters are used. This is subject to change in
+ /// the future.
///
- /// These setters are the same as the corresponding column-name-based setters,
- /// but with numeric column indexes. These are faster since they avoid
+ /// This setter is the same as the corresponding column-name-based setter,
+ /// but with numeric column indexes. This is faster since it avoids
/// hashmap lookups, so should be preferred in performance-sensitive code
/// (e.g. bulk loaders).
///
@@ -327,29 +339,24 @@ class KUDU_EXPORT KuduPartialRow {
/// if any errors happened (the errors can be fetched using the
/// KuduSession::GetPendingErrors() method).
///
+ /// @warning Unstable API
+ ///
/// @param [in] col_idx
/// The index of the target column.
/// @param [in] val
/// The value to set.
/// @return Operation result status.
- ///
- ///@{
- Status SetBinaryNoCopy(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
- Status SetStringNoCopy(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
+ Status SetVarcharNoCopyUnsafe(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
///@}
- /// @name [Advanced][Unstable] Setter for varchar columns by index (non-copying).
- ///
- /// Set the varchar value for a column by index, not copying the specified data.
- ///
- /// This method expects the values to be truncated already and they only do a
- /// basic validation that the data is not larger than the maximum column
- /// length (as indicated by the schema) multiplied by 4, as that's the upper
- /// limit if only 4-byte UTF8 characters are used. This is subject to change in
- /// the future.
+ /// @name Setters for binary/string columns by index (non-copying).
+ ///@{
+
+ /// Set the binary/string value for a column by index, not copying the
+ /// specified data.
///
- /// This setter is the same as the corresponding column-name-based setter,
- /// but with numeric column indexes. This is faster since it avoids
+ /// These setters are the 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).
///
@@ -363,8 +370,9 @@ class KUDU_EXPORT KuduPartialRow {
/// @param [in] val
/// The value to set.
/// @return Operation result status.
- ///
- Status SetVarcharNoCopyUnsafe(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
+ Status SetBinaryNoCopy(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
+ Status SetStringNoCopy(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
+ ///@}
/// Set column value to @c NULL; the column is identified by its name.
///
@@ -433,24 +441,47 @@ class KUDU_EXPORT KuduPartialRow {
bool IsNull(int col_idx) const;
/// @name Getters for integral type columns by column name.
- ///
+ ///@{
+
/// Get value of the column specified by name.
///
+ /// @param [in] col_name
+ /// The name of the column.
+ /// @param [out] val
+ /// The value of the 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(const Slice& col_name, bool* val) const WARN_UNUSED_RESULT;
Status GetInt8(const Slice& col_name, int8_t* val) const WARN_UNUSED_RESULT;
Status GetInt16(const Slice& col_name, int16_t* val) const WARN_UNUSED_RESULT;
Status GetInt32(const Slice& col_name, int32_t* val) const WARN_UNUSED_RESULT;
Status GetInt64(const Slice& col_name, int64_t* val) const WARN_UNUSED_RESULT;
- Status GetUnixTimeMicros(const Slice& col_name, int64_t* micros_since_utc_epoch)
- const WARN_UNUSED_RESULT;
+
+ /// @param [in] col_name
+ /// The name of the column.
+ /// @param [out] micros_since_utc_epoch
+ /// The value of the 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 GetUnixTimeMicros(const Slice& col_name,
+ int64_t* micros_since_utc_epoch) const WARN_UNUSED_RESULT;
+
+ /// @param [in] col_name
+ /// The name of the column.
+ /// @param [out] days_since_unix_epoch
+ /// The value of the 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 GetDate(const Slice& col_name, int32_t* days_since_unix_epoch) const WARN_UNUSED_RESULT;
Status GetFloat(const Slice& col_name, float* val) const WARN_UNUSED_RESULT;
Status GetDouble(const Slice& col_name, double* val) const WARN_UNUSED_RESULT;
@@ -463,31 +494,50 @@ class KUDU_EXPORT KuduPartialRow {
/// @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).
+ ///@{
+
+ /// Get value of a column of integral type by column index.
///
/// @param [in] col_idx
/// The index of the target column.
+ /// @param [out] val
+ /// The value 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;
Status GetInt16(int col_idx, int16_t* val) const WARN_UNUSED_RESULT;
Status GetInt32(int col_idx, int32_t* val) const WARN_UNUSED_RESULT;
Status GetInt64(int col_idx, int64_t* val) const WARN_UNUSED_RESULT;
+
+ /// @param [in] col_idx
+ /// The index of the target column.
+ /// @param [out] micros_since_utc_epoch
+ /// The value 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 GetUnixTimeMicros(int col_idx, int64_t* micros_since_utc_epoch) const WARN_UNUSED_RESULT;
- Status GetDate(int col_idx, int32_t* days_since_unix_epoch) const WARN_UNUSED_RESULT;
+ /// @param [in] col_idx
+ /// The index of the target column.
+ /// @param [out] days_since_unix_epoch
+ /// The value 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 GetDate(int col_idx, int32_t* days_since_unix_epoch) const WARN_UNUSED_RESULT;
Status GetFloat(int col_idx, float* val) const WARN_UNUSED_RESULT;
Status GetDouble(int col_idx, double* val) const WARN_UNUSED_RESULT;
#if KUDU_INT128_SUPPORTED
@@ -498,7 +548,8 @@ class KUDU_EXPORT KuduPartialRow {
///@}
/// @name Getters for string/binary/varchar column by column name.
- ///
+ ///@{
+
/// Get the string/binary/varchar value for a column by its name.
///
/// @param [in] col_name
@@ -512,22 +563,21 @@ class KUDU_EXPORT KuduPartialRow {
/// @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 GetBinary(const Slice& col_name, Slice* val) const WARN_UNUSED_RESULT;
Status GetVarchar(const Slice& col_name, Slice* val) const WARN_UNUSED_RESULT;
///@}
/// @name Getters for string/binary/varchar column by column index.
- ///
+ ///@{
+
/// Get the string/binary/varchar 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
+ /// @param [in] col_idx
/// The index of the column.
/// @param [out] val
/// Pointer to the placeholder to put the resulting value.
@@ -538,8 +588,6 @@ class KUDU_EXPORT KuduPartialRow {
/// @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;
Status GetVarchar(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
diff --git a/src/kudu/util/monotime.h b/src/kudu/util/monotime.h
index 35e3fda..d29a005 100644
--- a/src/kudu/util/monotime.h
+++ b/src/kudu/util/monotime.h
@@ -57,16 +57,30 @@ namespace kudu {
class KUDU_EXPORT MonoDelta {
public:
/// @name Converters from seconds representation (and ubiquitous SI prefixes).
- ///
- /// @param [in] seconds/ms/us/ns
+ ///@{
+
+ /// @param [in] seconds
/// 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);
+
+ /// @param [in] ms
+ /// Time interval representation in seconds (with ubiquitous SI prefixes).
+ /// @return The resulting MonoDelta object initialized in accordance with
+ /// the specified parameter.
static MonoDelta FromMilliseconds(int64_t ms);
+
+ /// @param [in] us
+ /// Time interval representation in seconds (with ubiquitous SI prefixes).
+ /// @return The resulting MonoDelta object initialized in accordance with
+ /// the specified parameter.
static MonoDelta FromMicroseconds(int64_t us);
+
+ /// @param [in] ns
+ /// Time interval representation in seconds (with ubiquitous SI prefixes).
+ /// @return The resulting MonoDelta object initialized in accordance with
+ /// the specified parameter.
static MonoDelta FromNanoseconds(int64_t ns);
///@}
@@ -108,10 +122,9 @@ class KUDU_EXPORT MonoDelta {
std::string ToString() const;
/// @name Converters into seconds representation (and ubiquitous SI prefixes).
- ///
- /// @return Representation of the time interval in appropriate SI units.
- ///
///@{
+
+ /// @return Representation of the time interval in appropriate SI units.
double ToSeconds() const;
int64_t ToMilliseconds() const;
int64_t ToMicroseconds() const;
@@ -142,7 +155,7 @@ class KUDU_EXPORT MonoDelta {
/// @name Syntactic sugar: increment/decrement operators for MonoDelta.
///@{
- ///
+
/// Add a delta to current time interval.
///
/// @param [in] delta
@@ -183,12 +196,18 @@ class KUDU_EXPORT MonoDelta {
class KUDU_EXPORT MonoTime {
public:
/// @name Conversion constants for ubiquitous time units.
- ///
///@{
+
+ /// Nanoseconds per second
static const int64_t kNanosecondsPerSecond = 1000000000L;
+
+ /// Nanoseconds per millisecond
static const int64_t kNanosecondsPerMillisecond = 1000000L;
+
+ /// Nanoseconds per microseconds
static const int64_t kNanosecondsPerMicrosecond = 1000L;
+ /// Microseconds per second
static const int64_t kMicrosecondsPerSecond = 1000000L;
///@}
@@ -270,7 +289,7 @@ class KUDU_EXPORT MonoTime {
/// @name Syntactic sugar: increment/decrement operators for MonoTime.
///@{
- ///
+
/// Add a delta to the point in time represented by the object.
///
/// @param [in] delta
@@ -312,7 +331,7 @@ void KUDU_EXPORT SleepFor(const MonoDelta& delta);
/// @name Syntactic sugar: binary operators for MonoDelta.
///@{
-///
+
/// @param [in] lhs
/// A time interval for comparison: the left-hand operand.
/// @param [in] rhs
@@ -378,7 +397,7 @@ MonoDelta KUDU_EXPORT operator+(const MonoDelta& lhs, const MonoDelta& rhs);
/// @name Syntactic sugar: binary operators for MonoTime.
///@{
-///
+
/// Check if the specified objects represent the same point in time.
///
/// This is a handy operator which is semantically equivalent to
@@ -439,7 +458,7 @@ bool KUDU_EXPORT operator>=(const MonoTime& lhs, const MonoTime& rhs);
/// @name Syntactic sugar: mixed binary operators for MonoTime/MonoDelta.
///@{
-///
+
/// Add the specified time interval to the given point in time.
///
/// @param [in] t
diff --git a/src/kudu/util/status.h b/src/kudu/util/status.h
index 6a2b756..fe9edd9 100644
--- a/src/kudu/util/status.h
+++ b/src/kudu/util/status.h
@@ -229,9 +229,9 @@ class KUDU_EXPORT Status {
/// @return A success status.
static Status OK() { return Status(); }
-
/// @name Methods to build status objects for various types of errors.
- ///
+ ///@{
+
/// @param [in] msg
/// The informational message on the error.
/// @param [in] msg2
@@ -239,8 +239,6 @@ class KUDU_EXPORT Status {
/// @param [in] posix_code
/// POSIX error code, if applicable (optional).
/// @return The error status of an appropriate type.
- ///
- ///@{
static Status NotFound(const Slice& msg, const Slice& msg2 = Slice(),
int16_t posix_code = -1) {
return Status(kNotFound, msg, msg2, posix_code);