A type used to gracefully handle errors across API boundaries.
Synopsis
Declared in <absl/status/status.h>
class [[nodiscard]] Status finalDescription
The absl::Status class is generally used to gracefully handle errors across API boundaries (and in particular across RPC boundaries). Some of these errors may be recoverable, but others may not. Most functions which can produce a recoverable error should be designed to return either an absl::Status (or the similar absl::StatusOr<T>, which holds either an object of type T or an error).
API developers should construct their functions to return absl::OkStatus() upon success, or an absl::StatusCode upon another type of error (e.g an absl::StatusCode::kInvalidArgument error). The API provides convenience functions to construct each status code.
Example:
absl::Status myFunction(absl::string_view fname, ...) { ... // encounter error if (error condition) { // Construct an absl::StatusCode::kInvalidArgument error return absl::InvalidArgumentError("bad mode"); } // else, return OK return absl::OkStatus(); }
Users handling status error codes should prefer checking for an OK status using the ok() member function. Handling multiple error codes may justify use of switch statement, but only check for error codes you know how to handle; do not try to exhaustively match against all canonical error codes. Errors that cannot be handled should be logged and/or propagated for higher levels to deal with. If you do use a switch statement, make sure that you also provide a default: switch case, so that code does not break as other canonical codes are added to the API.
Example:
absl::Status result = DoSomething(); if (!result.ok()) { LOG(ERROR) << result; }
// Provide a default if switching on multiple error codes switch (result.code()) { // The user hasn't authenticated. Ask them to reauth case absl::StatusCode::kUnauthenticated: DoReAuth(); break; // The user does not have permission. Log an error. case absl::StatusCode::kPermissionDenied: LOG(ERROR) << result; break; // Propagate the error otherwise. default: return true; }
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 contextual information that is more appropriate to display to an end user.
Example:
absl::Status result = DoSomething(); // Inform user to retry after 30 seconds // See more error details in googleapis/google/rpc/error_details.proto if (absl::IsResourceExhausted(result)) { google::rpc::RetryInfo info; info.retry_delay().seconds() = 30; // Payloads require a unique key (a URL to ensure no collisions with // other payloads), and an absl::Cord to hold the encoded data. absl::string_view url = "type.googleapis.com/google.rpc.RetryInfo"; result.SetPayload(url, info.SerializeAsCord()); return result; }
For documentation see https://abseil.io/docs/cpp/guides/status.
Returned Status objects may not be ignored. status_internal.h has a forward declaration of the form class ABSL_MUST_USE_RESULT Status;
Member Functions
Name |
Description |
|
Constructors |
|
Destroys the status and releases any owned resources. |
Assignment operators |
|
Appends the |
|
Erases the payload corresponding to the |
|
Iterates over the stored payloads and calls the |
|
Gets the payload of a status given its unique |
|
Returns the source locations attached to this status. |
|
Ignores any errors. |
|
Sets the payload for a non‐ok status using a |
|
Returns a string based on the |
|
|
|
|
|
Returns the canonical error code of type |
|
Returns the error message associated with this error code, if available. |
|
Returns |
|
Returns a raw (canonical) error code corresponding to the enum value of |
Friends
Name |
Description |
|
|
Builds a status representation from an inlined rep and a message. |
|
A union of an object of type |
|
|
|
|
|
Creates a |
|
Swaps the contents of one status with another. |
|
Support |
|
Compares two statuses for inequality. |
|
Compares two statuses for equality. |
Non-Member Functions
Name |
Description |
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Convenience function that creates a |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Creates a status with the |
|
Creates a status with the |
|
Returns an OK status, equivalent to a default constructed instance. |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Retrieves a message's status as a null terminated C string. |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
|
Creates a status with the |
Return Value
|
Note
|
The return value should not be discarded. |
Created with MrDocs