absl::Status

class [[nodiscard]] Status final

Description

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;