From 930fbec75b452af8bb8c796f5bb754e953e29cf5 Mon Sep 17 00:00:00 2001 From: Abseil Team Date: Wed, 2 Sep 2020 08:15:12 -0700 Subject: Export of internal Abseil changes -- ea5599482a5120800f060c6d41334dbdbabc3941 by Mark Barolak : Import of CCTZ from GitHub. PiperOrigin-RevId: 329715235 -- e897a582bed3aff509b98e5da0711b2afd15ed17 by Tom Manshreck : * Update Status with overview * Move public API helper functions out of "Implementation Details" * Add documentation to Status Codes PiperOrigin-RevId: 329595541 -- f93b28596f24fa005606565e0a8a4dabe260b01c by Abseil Team : Fix -Wextra-semi issues. ABSL_COMPARE_INLINE_xxx_DECL may expand to nothing. That produces structs that have only semicolon inside class declaration. such struct is not a valid c++ code and fails to compile when -Wextra-semi is turned on. PiperOrigin-RevId: 329564534 GitOrigin-RevId: ea5599482a5120800f060c6d41334dbdbabc3941 Change-Id: Icc9944c3ec8303abc26a167c2ba7c91e59a4877f --- absl/status/status.h | 413 +++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 303 insertions(+), 110 deletions(-) (limited to 'absl/status/status.h') diff --git a/absl/status/status.h b/absl/status/status.h index 8097b05a..8e1974c9 100644 --- a/absl/status/status.h +++ b/absl/status/status.h @@ -11,6 +11,52 @@ // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. +// +// ----------------------------------------------------------------------------- +// File: status.h +// ----------------------------------------------------------------------------- +// +// This header file defines the Abseil `status` library, consisting of: +// +// * An `absl::Status` class for holding error handling information +// * A set of canonical `absl::StatusCode` error codes, and associated +// utilities for generating and propogating status codes. +// * A set of helper functions for creating status codes and checking their +// values +// +// Within Google, `absl::Status` is the primary mechanism for indicating +// recoverable errors across API boundaries (and in particular across RPC +// boundaries). Most functions which can produce a recoverable error should +// be designed to return an `absl::Status` (or `absl::StatusOr`). +// +// Example: +// +// absl::Status myFunction(absl::string_view fname, ...) { +// ... +// // encounter error +// if (error condition) { +// return absl::InvalidArgumentError("bad mode"); +// } +// // else, return OK +// return absl::OkStatus(); +// } +// +// An `absl::Status` is designed to either return "OK" or one of a number of +// different error codes, corresponding to typical error conditions. +// In almost all cases, when using `absl::Status` you should use the canonical +// error codes (of type `absl::StatusCode`) enumerated in this header file. +// These canonical codes are understood across the codebase and will be +// accepted across all API and RPC boundaries. +// +// An `absl::Status` can optionally include a payload with more information +// about the error. Typically, this payload serves one of several purposes: +// +// * It may provide more fine-grained semantic information about the error to +// facilitate actionable remedies. +// * It may provide human-readable contexual information that is more +// appropriate +// to display to an end user. +// #ifndef ABSL_STATUS_STATUS_H_ #define ABSL_STATUS_STATUS_H_ @@ -25,72 +71,125 @@ namespace absl { ABSL_NAMESPACE_BEGIN -// Sometimes multiple error codes may apply. Services should return -// the most specific error code that applies. For example, prefer -// `kOutOfRange` over `kFailedPrecondition` if both codes apply. -// Similarly prefer `kNotFound` or `kAlreadyExists` over `kFailedPrecondition`. +// absl::StatusCode +// +// An `absl::StatusCode` is an enumerated type indicating either no error ("OK") +// or an error condition. In most cases, an `absl::Status` indicates a +// recoverable error, and the purpose of signalling an error is to indicate what +// action to take in response to that error. These error codes map to the proto +// RPC error codes indicated in https://cloud.google.com/apis/design/errors. +// +// The errors listed below are the canonical errors associated with +// `absl::Status` and are used throughout the codebase. As a result, these +// error codes are somewhat generic. +// +// In general, try to return the most specific error that applies if more than +// one error may pertain. For example, prefer `kOutOfRange` over +// `kFailedPrecondition` if both codes apply. Similarly prefer `kNotFound` or +// `kAlreadyExists` over `kFailedPrecondition`. +// +// Because these errors may travel RPC boundaries, these codes are tied to the +// `google.rpc.Code` definitions within +// https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto +// The string value of these RPC codes is denoted within each enum below. +// +// If your error handling code requires more context, you can attach payloads +// to your status. See `absl::Status::SetPayload()` and +// `absl::Status::GetPayload()` below. enum class StatusCode : int { - // Not an error; returned on success + // StatusCode::kOk + // + // kOK (gRPC code "OK") does not indicate an error; this value is returned on + // success. It is typical to check for this value before proceeding on any + // given call across an API or RPC boundary. To check this value, use the + // `absl::Status::ok()` member function rather than inspecting the raw code. kOk = 0, - // The operation was cancelled, typically by the caller. + // StatusCode::kCancelled + // + // kCanelled (gRPC code "CANCELLED") indicates the operation was cancelled, + // typically by the caller. kCancelled = 1, - // Unknown error. For example, errors raised by APIs that do not return - // enough error information may be converted to this error. + // StatusCode::kUnknown + // + // kUnknown (gRPC code "UNKNOWN") indicates an unknown error occurred. In + // general, more specific errors should be raised, if possible. Errors raised + // by APIs that do not return enough error information may be converted to + // this error. kUnknown = 2, - // The client specified an invalid argument. Note that this differs - // from `kFailedPrecondition`. `kInvalidArgument` indicates arguments - // that are problematic regardless of the state of the system - // (such as a malformed file name). + // StatusCode::kInvalidArgument + // + // kInvalidArgument (gRPC code "INVALID_ARGUMENT") indicates the caller + // specified an invalid argument, such a malformed filename. Note that such + // errors should be narrowly limited to indicate to the invalid nature of the + // arguments themselves. Errors with validly formed arguments that may cause + // errors with the state of the receiving system should be denoted with + // `kFailedPrecondition` instead. kInvalidArgument = 3, - // The deadline expired before the operation could complete. For operations - // that change the state of the system, this error may be returned - // even if the operation has completed successfully. For example, a - // successful response from a server could have been delayed long - // enough for the deadline to expire. + // StatusCode::kDeadlineExceeded + // + // kDeadlineExceeded (gRPC code "DEADLINE_EXCEEDED") indicates a deadline + // expired before the operation could complete. For operations that may change + // state within a system, this error may be returned even if the operation has + // completed successfully. For example, a successful response from a server + // could have been delayed long enough for the deadline to expire. kDeadlineExceeded = 4, - // Some requested entity (such as file or directory) was not found. + // StatusCode::kNotFound // - // Note to server developers: if a request is denied for an entire class - // of users, such as gradual feature rollout or undocumented whitelist, - // `kNotFound` may be used. If a request is denied for some users within - // a class of users, such as user-based access control, `kPermissionDenied` - // must be used. + // kNotFound (gRPC code "NOT_FOUND") indicates some requested entity (such as + // a file or directory) was not found. + // + // `kNotFound` is useful if a request should be denied for an entire class of + // users, such as during a gradual feature rollout or undocumented allow list. + // If, instead, a request should be denied for specific sets of users, such as + // through user-based access control, use `kPermissionDenied` instead. kNotFound = 5, - // The entity that a client attempted to create (such as file or directory) - // already exists. + // StatusCode::kAlreadyExists + // + // kAlreadyExists (gRPC code "ALREADY_EXISTS") indicates the entity that a + // caller attempted to create (such as file or directory) is already present. kAlreadyExists = 6, - // The caller does not have permission to execute the specified - // operation. `kPermissionDenied` must not be used for rejections - // caused by exhausting some resource (use `kResourceExhausted` - // instead for those errors). `kPermissionDenied` must not be - // used if the caller can not be identified (use `kUnauthenticated` - // instead for those errors). This error code does not imply the - // request is valid or the requested entity exists or satisfies - // other pre-conditions. + // StatusCode::kPermissionDenied + // + // kPermissionDenied (gRPC code "PERMISSION_DENIED") indicates that the caller + // does not have permission to execute the specified operation. Note that this + // error is different than an error due to an *un*authenticated user. This + // error code does not imply the request is valid or the requested entity + // exists or satisfies any other pre-conditions. + // + // `kPermissionDenied` must not be used for rejections caused by exhausting + // some resource. Instead, use `kResourceExhausted` for those errors. + // `kPermissionDenied` must not be used if the caller cannot be identified. + // Instead, use `kUnauthenticated` for those errors. kPermissionDenied = 7, - // Some resource has been exhausted, perhaps a per-user quota, or - // perhaps the entire file system is out of space. + // StatusCode::kResourceExhausted + // + // kResourceExhausted (gRPC code "RESOURCE_EXHAUSTED") indicates some resource + // has been exhausted, perhaps a per-user quota, or perhaps the entire file + // system is out of space. kResourceExhausted = 8, - // The operation was rejected because the system is not in a state - // required for the operation's execution. For example, the directory - // to be deleted is non-empty, an rmdir operation is applied to - // a non-directory, etc. + // StatusCode::kFailedPrecondition + // + // kFailedPrecondition (gRPC code "FAILED_PRECONDITION") indicates that the + // operation was rejected because the system is not in a state required for + // the operation's execution. For example, a directory to be deleted may be + // non-empty, an "rmdir" operation is applied to a non-directory, etc. + // + // Some guidelines that may help a service implementer in deciding between + // `kFailedPrecondition`, `kAborted`, and `kUnavailable`: // - // A litmus test that may help a service implementer in deciding - // between `kFailedPrecondition`, `kAborted`, and `kUnavailable`: // (a) Use `kUnavailable` if the client can retry just the failing call. - // (b) Use `kAborted` if the client should retry at a higher-level - // (such as when a client-specified test-and-set fails, indicating the - // client should restart a read-modify-write sequence). + // (b) Use `kAborted` if the client should retry at a higher transaction + // level (such as when a client-specified test-and-set fails, indicating + // the client should restart a read-modify-write sequence). // (c) Use `kFailedPrecondition` if the client should not retry until // the system state has been explicitly fixed. For example, if an "rmdir" // fails because the directory is non-empty, `kFailedPrecondition` @@ -98,15 +197,21 @@ enum class StatusCode : int { // the files are deleted from the directory. kFailedPrecondition = 9, - // The operation was aborted, typically due to a concurrency issue such as - // a sequencer check failure or transaction abort. + // StatusCode::kAborted + // + // kAborted (gRPC code "ABORTED") indicates the operation was aborted, + // typically due to a concurrency issue such as a sequencer check failure or a + // failed transaction. // - // See litmus test above for deciding between `kFailedPrecondition`, + // See the guidelines above for deciding between `kFailedPrecondition`, // `kAborted`, and `kUnavailable`. kAborted = 10, - // The operation was attempted past the valid range, such as seeking or - // reading past end-of-file. + // StatusCode::kOutofRange + // + // kOutofRange (gRPC code "OUT_OF_RANGE") indicates the operation was + // attempted past the valid range, such as seeking or reading past an + // end-of-file. // // Unlike `kInvalidArgument`, this error indicates a problem that may // be fixed if the system state changes. For example, a 32-bit file @@ -122,51 +227,73 @@ enum class StatusCode : int { // they are done. kOutOfRange = 11, - // The operation is not implemented or is not supported/enabled in this - // service. + // StatusCode::kUnimplemented + // + // kUnimplemented (gRPC code "UNIMPLEMENTED") indicates the operation is not + // implemented or supported in this service. In this case, the operation + // should not be re-attempted. kUnimplemented = 12, - // Internal errors. This means that some invariants expected by the - // underlying system have been broken. This error code is reserved - // for serious errors. + // StatusCode::kInternal + // + // kInternal (gRPC code "INTERNAL") indicates an internal error has occurred + // and some invariants expected by the underlying system have not been + // satisfied. This error code is reserved for serious errors. kInternal = 13, - // The service is currently unavailable. This is most likely a - // transient condition, which can be corrected by retrying with - // a backoff. Note that it is not always safe to retry - // non-idempotent operations. + // StatusCode::kUnavailable // - // See litmus test above for deciding between `kFailedPrecondition`, + // kUnavailable (gRPC code "UNAVAILABLE") indicates the service is currently + // unavailable and that this is most likely a transient condition. An error + // such as this can be corrected by retrying with a backoff scheme. Note that + // it is not always safe to retry non-idempotent operations. + // + // See the guidelines above for deciding between `kFailedPrecondition`, // `kAborted`, and `kUnavailable`. kUnavailable = 14, - // Unrecoverable data loss or corruption. + // StatusCode::kDataLoss + // + // kDataLoss (gRPC code "DATA_LOSS") indicates that unrecoverable data loss or + // corruption has occurred. As this error is serious, proper alerting should + // be attached to errors such as this. kDataLoss = 15, - // The request does not have valid authentication credentials for the - // operation. + // StatusCode::kUnauthenticated + // + // kUnauthenticated (gRPC code "UNAUTHENTICATED") indicates that the request + // does not have valid authentication credentials for the operation. Correct + // the authentication and try again. kUnauthenticated = 16, - // An extra enum entry to prevent people from writing code that - // fails to compile when a new code is added. + // StatusCode::DoNotUseReservedForFutureExpansionUseDefaultInSwitchInstead_ // - // Nobody should ever reference this enumeration entry. In particular, - // if you write C++ code that switches on this enumeration, add a default: - // case instead of a case that mentions this enumeration entry. + // NOTE: this error code entry should not be used and you should not rely on + // its value, which may change. // - // Nobody should rely on the value (currently 20) listed here. It - // may change in the future. + // The purpose of this enumerated value is to force people who handle status + // codes with `switch()` statements to *not* simply enumerate all possible + // values, but instead provide a "default:" case. Providing such a default + // case ensures that code will compile when new codes are added. kDoNotUseReservedForFutureExpansionUseDefaultInSwitchInstead_ = 20 }; +// StatusCodeToString() +// // Returns the name for the status code, or "" if it is an unknown value. std::string StatusCodeToString(StatusCode code); +// operator<< +// // Streams StatusCodeToString(code) to `os`. std::ostream& operator<<(std::ostream& os, StatusCode code); +// absl::Status +// class ABSL_MUST_USE_RESULT Status final { public: + // Constructors + // Creates an OK status with no message or payload. Status(); @@ -181,13 +308,16 @@ class ABSL_MUST_USE_RESULT Status final { Status(const Status&); Status& operator=(const Status& x); - // Move operations. + // Move operators + // The moved-from state is valid but unspecified. Status(Status&&) noexcept; Status& operator=(Status&&); ~Status(); + // Status::Update() + // // If `this->ok()`, stores `new_status` into *this. If `!this->ok()`, // preserves the current data. May, in the future, augment the current status // with additional information about `new_status`. @@ -202,17 +332,25 @@ class ABSL_MUST_USE_RESULT Status final { void Update(const Status& new_status); void Update(Status&& new_status); + // Status::ok() + // // Returns true if the Status is OK. ABSL_MUST_USE_RESULT bool ok() const; + // Status::code() + // // Returns the (canonical) error code. absl::StatusCode code() const; + // Status::raw_code() + // // Returns the raw (canonical) error code which could be out of the range of // the local `absl::StatusCode` enum. NOTE: This should only be called when // converting to wire format. Use `code` for error handling. int raw_code() const; + // Status::message() + // // Returns the error message. Note: prefer ToString() for debug logging. // This message rarely describes the error code. It is not unusual for the // error message to be the empty string. @@ -221,6 +359,8 @@ class ABSL_MUST_USE_RESULT Status final { friend bool operator==(const Status&, const Status&); friend bool operator!=(const Status&, const Status&); + // Status::ToString() + // // Returns a combination of the error code name, the message and the payloads. // You can expect the code name and the message to be substrings of the // result, and the payloads to be printed by the registered printer extensions @@ -229,15 +369,21 @@ class ABSL_MUST_USE_RESULT Status final { // which is subject to change. std::string ToString() const; + // Status::IgnoreError() + // // Ignores any errors. This method does nothing except potentially suppress // complaints from any tools that are checking that errors are not dropped on // the floor. void IgnoreError() const; + // swap() + // // Swap the contents of `a` with `b` friend void swap(Status& a, Status& b); + //---------------------------------------------------------------------------- // Payload management APIs + //---------------------------------------------------------------------------- // Type URL should be unique and follow the naming convention below: // The idea of type URL comes from `google.protobuf.Any` @@ -250,19 +396,27 @@ class ABSL_MUST_USE_RESULT Status final { // URLs. Users should make sure that the type URL can be mapped to a concrete // C++ type if they want to deserialize the payload and read it effectively. + // Status::GetPayload() + // // Gets the payload based for `type_url` key, if it is present. absl::optional GetPayload(absl::string_view type_url) const; + // Status::SetPayload() + // // Sets the payload for `type_url` key for a non-ok status, overwriting any // existing payload for `type_url`. // // NOTE: Does nothing if the Status is ok. void SetPayload(absl::string_view type_url, absl::Cord payload); + // Status::ErasePayload() + // // Erases the payload corresponding to the `type_url` key. Returns true if // the payload was present. bool ErasePayload(absl::string_view type_url); + // Status::ForEachPayload() + // // Iterates over the stored payloads and calls `visitor(type_key, payload)` // for each one. // @@ -338,14 +492,92 @@ class ABSL_MUST_USE_RESULT Status final { uintptr_t rep_; }; +// OkStatus() +// // Returns an OK status, equivalent to a default constructed instance. Status OkStatus(); +// operator<<() +// // Prints a human-readable representation of `x` to `os`. std::ostream& operator<<(std::ostream& os, const Status& x); -// ----------------------------------------------------------------- +// IsAborted() +// IsAlreadyExists() +// IsCancelled() +// IsDataLoss() +// IsDeadlineExceeded() +// IsFailedPrecondition() +// IsInternal() +// IsInvalidArgument() +// IsNotFound() +// IsOutOfRange() +// IsPermissionDenied() +// IsResourceExhausted() +// IsUnauthenticated() +// IsUnavailable() +// IsUnimplemented() +// IsUnknown() +// +// These convenience functions return `true` if a given status matches the +// `absl::StatusCode` error code of its associated function. +ABSL_MUST_USE_RESULT bool IsAborted(const Status& status); +ABSL_MUST_USE_RESULT bool IsAlreadyExists(const Status& status); +ABSL_MUST_USE_RESULT bool IsCancelled(const Status& status); +ABSL_MUST_USE_RESULT bool IsDataLoss(const Status& status); +ABSL_MUST_USE_RESULT bool IsDeadlineExceeded(const Status& status); +ABSL_MUST_USE_RESULT bool IsFailedPrecondition(const Status& status); +ABSL_MUST_USE_RESULT bool IsInternal(const Status& status); +ABSL_MUST_USE_RESULT bool IsInvalidArgument(const Status& status); +ABSL_MUST_USE_RESULT bool IsNotFound(const Status& status); +ABSL_MUST_USE_RESULT bool IsOutOfRange(const Status& status); +ABSL_MUST_USE_RESULT bool IsPermissionDenied(const Status& status); +ABSL_MUST_USE_RESULT bool IsResourceExhausted(const Status& status); +ABSL_MUST_USE_RESULT bool IsUnauthenticated(const Status& status); +ABSL_MUST_USE_RESULT bool IsUnavailable(const Status& status); +ABSL_MUST_USE_RESULT bool IsUnimplemented(const Status& status); +ABSL_MUST_USE_RESULT bool IsUnknown(const Status& status); + +// AbortedError() +// AlreadyExistsError() +// CancelledError() +// DataLossError() +// DeadlineExceededError() +// FailedPreconditionError() +// InternalError() +// InvalidArgumentError() +// NotFoundError() +// OutOfRangeError() +// PermissionDeniedError() +// ResourceExhaustedError() +// UnauthenticatedError() +// UnavailableError() +// UnimplementedError() +// UnknownError() +// +// These convenience functions create an `absl::Status` object with an error +// code as indicated by the associated function name, using the error message +// passed in `message`. +Status AbortedError(absl::string_view message); +Status AlreadyExistsError(absl::string_view message); +Status CancelledError(absl::string_view message); +Status DataLossError(absl::string_view message); +Status DeadlineExceededError(absl::string_view message); +Status FailedPreconditionError(absl::string_view message); +Status InternalError(absl::string_view message); +Status InvalidArgumentError(absl::string_view message); +Status NotFoundError(absl::string_view message); +Status OutOfRangeError(absl::string_view message); +Status PermissionDeniedError(absl::string_view message); +Status ResourceExhaustedError(absl::string_view message); +Status UnauthenticatedError(absl::string_view message); +Status UnavailableError(absl::string_view message); +Status UnimplementedError(absl::string_view message); +Status UnknownError(absl::string_view message); + +//------------------------------------------------------------------------------ // Implementation details follow +//------------------------------------------------------------------------------ inline Status::Status() : rep_(CodeToInlinedRep(absl::StatusCode::kOk)) {} @@ -471,50 +703,11 @@ inline void Status::Unref(uintptr_t rep) { inline Status OkStatus() { return Status(); } -// Each of the functions below creates a Status object with a particular error -// code and the given message. The error code of the returned status object -// matches the name of the function. -Status AbortedError(absl::string_view message); -Status AlreadyExistsError(absl::string_view message); -Status CancelledError(absl::string_view message); -Status DataLossError(absl::string_view message); -Status DeadlineExceededError(absl::string_view message); -Status FailedPreconditionError(absl::string_view message); -Status InternalError(absl::string_view message); -Status InvalidArgumentError(absl::string_view message); -Status NotFoundError(absl::string_view message); -Status OutOfRangeError(absl::string_view message); -Status PermissionDeniedError(absl::string_view message); -Status ResourceExhaustedError(absl::string_view message); -Status UnauthenticatedError(absl::string_view message); -Status UnavailableError(absl::string_view message); -Status UnimplementedError(absl::string_view message); -Status UnknownError(absl::string_view message); - // Creates a `Status` object with the `absl::StatusCode::kCancelled` error code // and an empty message. It is provided only for efficiency, given that // message-less kCancelled errors are common in the infrastructure. inline Status CancelledError() { return Status(absl::StatusCode::kCancelled); } -// Each of the functions below returns true if the given status matches the -// error code implied by the function's name. -ABSL_MUST_USE_RESULT bool IsAborted(const Status& status); -ABSL_MUST_USE_RESULT bool IsAlreadyExists(const Status& status); -ABSL_MUST_USE_RESULT bool IsCancelled(const Status& status); -ABSL_MUST_USE_RESULT bool IsDataLoss(const Status& status); -ABSL_MUST_USE_RESULT bool IsDeadlineExceeded(const Status& status); -ABSL_MUST_USE_RESULT bool IsFailedPrecondition(const Status& status); -ABSL_MUST_USE_RESULT bool IsInternal(const Status& status); -ABSL_MUST_USE_RESULT bool IsInvalidArgument(const Status& status); -ABSL_MUST_USE_RESULT bool IsNotFound(const Status& status); -ABSL_MUST_USE_RESULT bool IsOutOfRange(const Status& status); -ABSL_MUST_USE_RESULT bool IsPermissionDenied(const Status& status); -ABSL_MUST_USE_RESULT bool IsResourceExhausted(const Status& status); -ABSL_MUST_USE_RESULT bool IsUnauthenticated(const Status& status); -ABSL_MUST_USE_RESULT bool IsUnavailable(const Status& status); -ABSL_MUST_USE_RESULT bool IsUnimplemented(const Status& status); -ABSL_MUST_USE_RESULT bool IsUnknown(const Status& status); - ABSL_NAMESPACE_END } // namespace absl -- cgit v1.2.3