kudu-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From t...@apache.org
Subject [1/2] kudu git commit: [C++ client] doxygenized all C++ client API
Date Wed, 10 Aug 2016 17:50:20 GMT
Repository: kudu
Updated Branches:
  refs/heads/master 1dbfb7550 -> 88fe33c99


http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/util/slice.h
----------------------------------------------------------------------
diff --git a/src/kudu/util/slice.h b/src/kudu/util/slice.h
index 609fa6e..8738a5d 100644
--- a/src/kudu/util/slice.h
+++ b/src/kudu/util/slice.h
@@ -1,23 +1,8 @@
+//
 // Copyright (c) 2011 The LevelDB Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file. See the AUTHORS file for names of contributors.
 //
-// Slice is a simple structure containing a pointer into some external
-// storage and a size.  The user of a Slice must ensure that the slice
-// is not used after the corresponding external storage has been
-// deallocated.
-//
-// Multiple threads can invoke const methods on a Slice without
-// external synchronization, but if any of the threads may call a
-// non-const method, all threads accessing the same Slice must use
-// external synchronization.
-//
-// Slices can be built around faststrings and StringPieces using constructors
-// with implicit casts. Both StringPieces and faststrings depend on a great
-// deal of gutil code, so these constructors are conditionalized on
-// KUDU_HEADERS_USE_RICH_SLICE. Likewise, KUDU_HEADERS_USE_RICH_SLICE controls
-// whether to use gutil-based memeq/memcmp substitutes; if it is unset, Slice
-// will fall back to standard memcmp.
 
 #ifndef KUDU_UTIL_SLICE_H_
 #define KUDU_UTIL_SLICE_H_
@@ -40,112 +25,196 @@ namespace kudu {
 
 class Status;
 
+/// @brief A wrapper around externally allocated data.
+///
+/// Slice is a simple structure containing a pointer into some external
+/// storage and a size. The user of a Slice must ensure that the slice
+/// is not used after the corresponding external storage has been
+/// deallocated.
+///
+/// Multiple threads can invoke const methods on a Slice without
+/// external synchronization, but if any of the threads may call a
+/// non-const method, all threads accessing the same Slice must use
+/// external synchronization.
+///
+/// Slices can be built around faststrings and StringPieces using constructors
+/// with implicit casts. Both StringPieces and faststrings depend on a great
+/// deal of gutil code.
 class KUDU_EXPORT Slice {
  public:
-  // Create an empty slice.
+  /// Create an empty slice.
   Slice() : data_(reinterpret_cast<const uint8_t *>("")),
             size_(0) { }
 
-  // Create a slice that refers to d[0,n-1].
+  /// Create a slice that refers to a @c uint8_t byte array.
+  ///
+  /// @param [in] d
+  ///   The input array.
+  /// @param [in] n
+  ///   Number of bytes in the array.
   Slice(const uint8_t* d, size_t n) : data_(d), size_(n) { }
 
-  // Create a slice that refers to d[0,n-1].
+  /// Create a slice that refers to a @c char byte array.
+  ///
+  /// @param [in] d
+  ///   The input array.
+  /// @param [in] n
+  ///   Number of bytes in the array.
   Slice(const char* d, size_t n) :
     data_(reinterpret_cast<const uint8_t *>(d)),
     size_(n) { }
 
-  // Create a slice that refers to the contents of "s"
+  /// Create a slice that refers to the contents of the given string.
+  ///
+  /// @param [in] s
+  ///   The input string.
   Slice(const std::string& s) : // NOLINT(runtime/explicit)
     data_(reinterpret_cast<const uint8_t *>(s.data())),
     size_(s.size()) { }
 
-  // Create a slice that refers to s[0,strlen(s)-1]
+  /// Create a slice that refers to a C-string s[0,strlen(s)-1].
+  ///
+  /// @param [in] s
+  ///   The input C-string.
   Slice(const char* s) : // NOLINT(runtime/explicit)
     data_(reinterpret_cast<const uint8_t *>(s)),
     size_(strlen(s)) { }
 
 #ifdef KUDU_HEADERS_USE_RICH_SLICE
-  // Create a slice that refers to the contents of the faststring.
-  // Note that further appends to the faststring may invalidate this slice.
+  /// Create a slice that refers to the contents of a faststring.
+  ///
+  /// @note Further appends to the faststring may invalidate this slice.
+  ///
+  /// @param [in] s
+  ///   The input faststring.
   Slice(const faststring &s) // NOLINT(runtime/explicit)
     : data_(s.data()),
       size_(s.size()) {
   }
 
+  /// Create a slice that refers to the contents of a string piece.
+  ///
+  /// @param [in] s
+  ///   The input StringPiece.
   Slice(const StringPiece& s) // NOLINT(runtime/explicit)
     : data_(reinterpret_cast<const uint8_t*>(s.data())),
       size_(s.size()) {
   }
 #endif
 
-  // Return a pointer to the beginning of the referenced data
+  /// @return A pointer to the beginning of the referenced data.
   const uint8_t* data() const { return data_; }
 
-  // Return a mutable pointer to the beginning of the referenced data.
+  /// @return A mutable pointer to the beginning of the referenced data.
   uint8_t *mutable_data() { return const_cast<uint8_t *>(data_); }
 
-  // Return the length (in bytes) of the referenced data
+  /// @return The length (in bytes) of the referenced data.
   size_t size() const { return size_; }
 
-  // Return true iff the length of the referenced data is zero
+  /// @return @c true iff the length of the referenced data is zero.
   bool empty() const { return size_ == 0; }
 
-  // Return the ith byte in the referenced data.
-  // REQUIRES: n < size()
+  /// @pre n < size()
+  ///
+  /// @param [in] n
+  ///   The index of the byte.
+  /// @return the n-th byte in the referenced data.
   const uint8_t &operator[](size_t n) const {
     assert(n < size());
     return data_[n];
   }
 
-  // Change this slice to refer to an empty array
+  /// Change this slice to refer to an empty array.
   void clear() {
     data_ = reinterpret_cast<const uint8_t *>("");
     size_ = 0;
   }
 
-  // Drop the first "n" bytes from this slice.
+  /// Drop the first "n" bytes from this slice.
+  ///
+  /// @pre n <= size()
+  ///
+  /// @note Only the base and bounds of the slice are changed;
+  ///   the data is not modified.
+  ///
+  /// @param [in] n
+  ///   Number of bytes that should be dropped from the beginning.
   void remove_prefix(size_t n) {
     assert(n <= size());
     data_ += n;
     size_ -= n;
   }
 
-  // Truncate the slice to "n" bytes
+  /// Truncate the slice to the given number of bytes.
+  ///
+  /// @pre n <= size()
+  ///
+  /// @note Only the base and bounds of the slice are changed;
+  ///   the data is not modified.
+  ///
+  /// @param [in] n
+  ///   The new size of the slice.
   void truncate(size_t n) {
     assert(n <= size());
     size_ = n;
   }
 
-  // Checks that this slice has size() = 'expected_size' and returns
-  // Status::Corruption() otherwise.
+  /// Check that the slice has the expected size.
+  ///
+  /// @param [in] expected_size
+  /// @return Status::Corruption() iff size() != @c expected_size
   Status check_size(size_t expected_size) const;
 
-  // Return a string that contains the copy of the referenced data.
+  /// @return A string that contains a copy of the referenced data.
   std::string ToString() const;
 
+  /// Get printable representation of the data in the slice.
+  ///
+  /// @param [in] max_len
+  ///   The maximum number of bytes to output in the printable format;
+  ///   @c 0 means no limit.
+  /// @return A string with printable representation of the data.
   std::string ToDebugString(size_t max_len = 0) const;
 
-  // Three-way comparison.  Returns value:
-  //   <  0 iff "*this" <  "b",
-  //   == 0 iff "*this" == "b",
-  //   >  0 iff "*this" >  "b"
+  /// Do a three-way comparison of the slice's data.
+  ///
+  /// @param [in] b
+  ///   The other slice to compare with.
+  /// @return Values are
+  ///   @li <  0 iff "*this" <  "b"
+  ///   @li == 0 iff "*this" == "b"
+  ///   @li >  0 iff "*this" >  "b"
   int compare(const Slice& b) const;
 
-  // Return true iff "x" is a prefix of "*this"
+  /// Check whether the slice starts with the given prefix.
+  /// @param [in] x
+  ///   The slice in question.
+  /// @return @c true iff "x" is a prefix of "*this"
   bool starts_with(const Slice& x) const {
     return ((size_ >= x.size_) &&
             (MemEqual(data_, x.data_, x.size_)));
   }
 
-  // Comparator struct, useful for ordered collections (like STL maps).
+  /// @brief Comparator struct, useful for ordered collections (like STL maps).
   struct Comparator {
+    /// Compare two slices using Slice::compare()
+    ///
+    /// @param [in] a
+    ///   The slice to call Slice::compare() at.
+    /// @param [in] b
+    ///   The slice to use as a parameter for Slice::compare().
+    /// @return @c true iff @c a is less than @c b by Slice::compare().
     bool operator()(const Slice& a, const Slice& b) const {
       return a.compare(b) < 0;
     }
   };
 
-  // Relocates this slice's data into 'd' provided this isn't already the
-  // case. It is assumed that 'd' is large enough to fit the data.
+  /// Relocate/copy the slice's data into a new location.
+  ///
+  /// @param [in] d
+  ///   The new location for the data. If it's the same location, then no
+  ///   relocation is done. It is assumed that the new location is
+  ///   large enough to fit the data.
   void relocate(uint8_t* d) {
     if (data_ != d) {
       memcpy(d, data_, size_);
@@ -178,15 +247,36 @@ class KUDU_EXPORT Slice {
   // Intentionally copyable
 };
 
+/// Check whether two slices are identical.
+///
+/// @param [in] x
+///   One slice.
+/// @param [in] y
+///   Another slice.
+/// @return @c true iff two slices contain byte-for-byte identical data.
 inline bool operator==(const Slice& x, const Slice& y) {
   return ((x.size() == y.size()) &&
           (Slice::MemEqual(x.data(), y.data(), x.size())));
 }
 
+/// Check whether two slices are not identical.
+///
+/// @param [in] x
+///   One slice.
+/// @param [in] y
+///   Another slice.
+/// @return @c true iff slices contain different data.
 inline bool operator!=(const Slice& x, const Slice& y) {
   return !(x == y);
 }
 
+/// Output printable representation of the slice into the given output stream.
+///
+/// @param [out] o
+///   The output stream to print the info.
+/// @param [in] s
+///   The slice to print.
+/// @return Reference to the updated output stream.
 inline std::ostream& operator<<(std::ostream& o, const Slice& s) {
   return o << s.ToDebugString(16); // should be enough for anyone...
 }
@@ -201,11 +291,24 @@ inline int Slice::compare(const Slice& b) const {
   return r;
 }
 
-// STL map whose keys are Slices.
-//
-// See sample usage in slice-test.cc.
+/// @brief STL map whose keys are Slices.
+///
+/// An example of usage:
+/// @code
+///   typedef SliceMap<int>::type MySliceMap;
+///
+///   MySliceMap my_map;
+///   my_map.insert(MySliceMap::value_type(a, 1));
+///   my_map.insert(MySliceMap::value_type(b, 2));
+///   my_map.insert(MySliceMap::value_type(c, 3));
+///
+///   for (const MySliceMap::value_type& pair : my_map) {
+///     ...
+///   }
+/// @endcode
 template <typename T>
 struct SliceMap {
+  /// A handy typedef for the slice map with appropriate comparison operator.
   typedef std::map<Slice, T, Slice::Comparator> type;
 };
 

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/util/status.h
----------------------------------------------------------------------
diff --git a/src/kudu/util/status.h b/src/kudu/util/status.h
index 5124b7e..21f47e7 100644
--- a/src/kudu/util/status.h
+++ b/src/kudu/util/status.h
@@ -26,28 +26,28 @@
 #include "kudu/util/kudu_export.h"
 #include "kudu/util/slice.h"
 
-// Return the given status if it is not OK.
+/// @brief Return the given status if it is not @c OK.
 #define KUDU_RETURN_NOT_OK(s) do { \
     ::kudu::Status _s = (s); \
     if (PREDICT_FALSE(!_s.ok())) return _s;     \
   } while (0);
 
-// Return the given status if it is not OK, but first clone it and
-// prepend the given message.
+/// @brief Return the given status if it is not OK, but first clone it and
+///   prepend the given message.
 #define KUDU_RETURN_NOT_OK_PREPEND(s, msg) do { \
     ::kudu::Status _s = (s); \
     if (PREDICT_FALSE(!_s.ok())) return _s.CloneAndPrepend(msg); \
   } while (0);
 
-// Return 'to_return' if 'to_call' returns a bad status.
-// The substitution for 'to_return' may reference the variable
-// 's' for the bad status.
+/// @brief Return @c to_return if @c to_call returns a bad status.
+///   The substitution for 'to_return' may reference the variable
+///   @c s for the bad status.
 #define KUDU_RETURN_NOT_OK_RET(to_call, to_return) do { \
     ::kudu::Status s = (to_call); \
     if (PREDICT_FALSE(!s.ok())) return (to_return);  \
   } while (0);
 
-// Emit a warning if 'to_call' returns a bad status.
+/// @brief Emit a warning if @c to_call returns a bad status.
 #define KUDU_WARN_NOT_OK(to_call, warning_prefix) do { \
     ::kudu::Status _s = (to_call); \
     if (PREDICT_FALSE(!_s.ok())) { \
@@ -55,35 +55,37 @@
     } \
   } while (0);
 
-// Log the given status and return immediately.
+/// @brief Log the given status and return immediately.
 #define KUDU_LOG_AND_RETURN(level, status) do { \
     ::kudu::Status _s = (status); \
     KUDU_LOG(level) << _s.ToString(); \
     return _s; \
   } while (0);
 
-// If 'to_call' returns a bad status, CHECK immediately with a logged message
-// of 'msg' followed by the status.
+/// @brief If @c to_call returns a bad status, CHECK immediately with
+///   a logged message of @c msg followed by the status.
 #define KUDU_CHECK_OK_PREPEND(to_call, msg) do { \
   ::kudu::Status _s = (to_call); \
   KUDU_CHECK(_s.ok()) << (msg) << ": " << _s.ToString(); \
   } while (0);
 
-// If the status is bad, CHECK immediately, appending the status to the
-// logged message.
+/// @brief If the status is bad, CHECK immediately, appending the status to the
+///   logged message.
 #define KUDU_CHECK_OK(s) KUDU_CHECK_OK_PREPEND(s, "Bad status")
 
-// This header is used in both the Kudu build as well as in builds of
-// applications that use the Kudu C++ client. In the latter we need to be
-// careful to "namespace" our macros, to avoid colliding or overriding with
-// similarly named macros belonging to the application.
-//
-// KUDU_HEADERS_USE_SHORT_STATUS_MACROS handles this behavioral change. When
-// defined, we're building Kudu and:
-// 1. Non-namespaced macros are allowed and mapped to the namespaced versions
-//    defined above.
-// 2. Namespaced versions of glog macros are mapped to the real glog macros
-//    (otherwise the macros are defined in the C++ client stubs).
+/// @file status.h
+///
+/// This header is used in both the Kudu build as well as in builds of
+/// applications that use the Kudu C++ client. In the latter we need to be
+/// careful to "namespace" our macros, to avoid colliding or overriding with
+/// similarly named macros belonging to the application.
+///
+/// KUDU_HEADERS_USE_SHORT_STATUS_MACROS handles this behavioral change. When
+/// defined, we're building Kudu and:
+/// @li Non-namespaced macros are allowed and mapped to the namespaced versions
+///   defined above.
+/// @li Namespaced versions of glog macros are mapped to the real glog macros
+///   (otherwise the macros are defined in the C++ client stubs).
 #ifdef KUDU_HEADERS_USE_SHORT_STATUS_MACROS
 #define RETURN_NOT_OK         KUDU_RETURN_NOT_OK
 #define RETURN_NOT_OK_PREPEND KUDU_RETURN_NOT_OK_PREPEND
@@ -100,26 +102,55 @@
 
 namespace kudu {
 
+/// @brief A representation of an operation's outcome.
 class KUDU_EXPORT Status {
  public:
-  // Create a success status.
+  /// Create an object representing success status.
   Status() : state_(NULL) { }
+
   ~Status() { delete[] state_; }
 
-  // Copy the specified status.
+  /// Copy the specified status.
+  ///
+  /// @param [in] s
+  ///   The status object to copy from.
   Status(const Status& s);
+
+  /// Assign the specified status.
+  ///
+  /// @param [in] s
+  ///   The status object to assign from.
   void operator=(const Status& s);
 
 #if __cplusplus >= 201103L
-  // Move the specified status.
+  /// Move the specified status (C++11).
+  ///
+  /// @param [in] s
+  ///   rvalue reference to a Status object.
   Status(Status&& s);
+
+  /// Assign the specified status using move semantics (C++11).
+  ///
+  /// @param [in] s
+  ///   rvalue reference to a Status object.
   void operator=(Status&& s);
 #endif
 
-  // Return a success status.
+  /// @return A success status.
   static Status OK() { return Status(); }
 
-  // Return error status of an appropriate type.
+
+  /// @name Methods to build status objects for various types of errors.
+  ///
+  /// @param [in] msg
+  ///   The informational message on the error.
+  /// @param [in] msg2
+  ///   Additional information on the error (optional).
+  /// @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);
@@ -192,96 +223,109 @@ class KUDU_EXPORT Status {
                           int64_t posix_code = -1) {
     return Status(kEndOfFile, msg, msg2, posix_code);
   }
+  ///@}
 
-  // Returns true iff the status indicates success.
+  /// @return @c true iff the status indicates success.
   bool ok() const { return (state_ == NULL); }
 
-  // Returns true iff the status indicates a NotFound error.
+  /// @return @c true iff the status indicates a NotFound error.
   bool IsNotFound() const { return code() == kNotFound; }
 
-  // Returns true iff the status indicates a Corruption error.
+  /// @return @c true iff the status indicates a Corruption error.
   bool IsCorruption() const { return code() == kCorruption; }
 
-  // Returns true iff the status indicates a NotSupported error.
+  /// @return @c true iff the status indicates a NotSupported error.
   bool IsNotSupported() const { return code() == kNotSupported; }
 
-  // Returns true iff the status indicates an IOError.
+  /// @return @c true iff the status indicates an IOError.
   bool IsIOError() const { return code() == kIOError; }
 
-  // Returns true iff the status indicates an InvalidArgument error
+  /// @return @c true iff the status indicates an InvalidArgument error.
   bool IsInvalidArgument() const { return code() == kInvalidArgument; }
 
-  // Returns true iff the status indicates an AlreadyPresent error
+  /// @return @c true iff the status indicates an AlreadyPresent error.
   bool IsAlreadyPresent() const { return code() == kAlreadyPresent; }
 
-  // Returns true iff the status indicates a RuntimeError.
+  /// @return @c true iff the status indicates a RuntimeError.
   bool IsRuntimeError() const { return code() == kRuntimeError; }
 
-  // Returns true iff the status indicates a NetworkError.
+  /// @return @c true iff the status indicates a NetworkError.
   bool IsNetworkError() const { return code() == kNetworkError; }
 
-  // Returns true iff the status indicates a IllegalState.
+  /// @return @c true iff the status indicates an IllegalState error.
   bool IsIllegalState() const { return code() == kIllegalState; }
 
-  // Returns true iff the status indicates a NotAuthorized.
+  /// @return @c true iff the status indicates a NotAuthorized error.
   bool IsNotAuthorized() const { return code() == kNotAuthorized; }
 
-  // Returns true iff the status indicates Aborted.
+  /// @return @c true iff the status indicates an Aborted error.
   bool IsAborted() const { return code() == kAborted; }
 
-  // Returns true iff the status indicates RemoteError.
+  /// @return @c true iff the status indicates a RemoteError.
   bool IsRemoteError() const { return code() == kRemoteError; }
 
-  // Returns true iff the status indicates ServiceUnavailable.
+  /// @return @c true iff the status indicates ServiceUnavailable.
   bool IsServiceUnavailable() const { return code() == kServiceUnavailable; }
 
-  // Returns true iff the status indicates TimedOut.
+  /// @return @c true iff the status indicates TimedOut.
   bool IsTimedOut() const { return code() == kTimedOut; }
 
-  // Returns true iff the status indicates Uninitialized.
+  /// @return @c true iff the status indicates Uninitialized.
   bool IsUninitialized() const { return code() == kUninitialized; }
 
-  // Returns true iff the status indicates Configuration error.
+  /// @return @c true iff the status indicates ConfigurationError.
   bool IsConfigurationError() const { return code() == kConfigurationError; }
 
-  // Returns true iff the status indicates Incomplete.
+  /// @return @c true iff the status indicates Incomplete.
   bool IsIncomplete() const { return code() == kIncomplete; }
 
-  // Returns true iff the status indicates end of file.
+  /// @return @c true iff the status indicates end of file.
   bool IsEndOfFile() const { return code() == kEndOfFile; }
 
-  // Return a string representation of this status suitable for printing.
-  // Returns the string "OK" for success.
+  /// @return A string representation of this status suitable for printing.
+  ///   Returns the string "OK" for success.
   std::string ToString() const;
 
-  // Return a string representation of the status code, without the message
-  // text or posix code information.
+  /// @return A string representation of the status code, without the message
+  ///   text or posix code information.
   std::string CodeAsString() const;
 
-  // Return the message portion of the Status. This is similar to ToString,
-  // except that it does not include the stringified error code or posix code.
-  //
-  // For OK statuses, this returns an empty string.
-  //
-  // The returned Slice is only valid as long as this Status object remains
-  // live and unchanged.
+  /// This is similar to ToString, except that it does not include
+  /// the stringified error code or posix code.
+  ///
+  /// @note The returned Slice is only valid as long as this Status object
+  ///   remains live and unchanged.
+  ///
+  /// @return The message portion of the Status. For @c OK statuses,
+  ///   this returns an empty string.
   Slice message() const;
 
-  // Get the POSIX code associated with this Status, or -1 if there is none.
+  /// @return The POSIX code associated with this Status object,
+  ///   or @c -1 if there is none.
   int16_t posix_code() const;
 
-  // Return a new Status object with the same state plus an additional leading message.
+  /// Clone the object and add the specified prefix to the clone's message.
+  ///
+  /// @param [in] msg
+  ///   The message to prepend.
+  /// @return A new Status object with the same state plus an additional
+  ///   leading message.
   Status CloneAndPrepend(const Slice& msg) const;
 
-  // Same as CloneAndPrepend, but appends to the message instead.
+  /// Clone the object and add the specified suffix to the clone's message.
+  ///
+  /// @param [in] msg
+  ///   The message to append.
+  /// @return A new Status object with the same state plus an additional
+  ///   trailing message.
   Status CloneAndAppend(const Slice& msg) const;
 
-  // Returns the memory usage of this object without the object itself. Should
-  // be used when embedded inside another object.
+  /// @return The memory usage of this object without the object itself.
+  ///   Should be used when embedded inside another object.
   size_t memory_footprint_excluding_this() const;
 
-  // Returns the memory usage of this object including the object itself.
-  // Should be used when allocated on the heap.
+  /// @return The memory usage of this object including the object itself.
+  ///   Should be used when allocated on the heap.
   size_t memory_footprint_including_this() const;
 
  private:


Mime
View raw message