diff options
Diffstat (limited to 'pw_status/public/pw_status/status.h')
| -rw-r--r-- | pw_status/public/pw_status/status.h | 197 |
1 files changed, 49 insertions, 148 deletions
diff --git a/pw_status/public/pw_status/status.h b/pw_status/public/pw_status/status.h index 8ed5330ad..9f6c3e68c 100644 --- a/pw_status/public/pw_status/status.h +++ b/pw_status/public/pw_status/status.h @@ -29,141 +29,27 @@ extern "C" { // pw_Status uses the canonical Google error codes. The following enum was based // on Abseil's status/status.h. The values are all-caps and prefixed with // PW_STATUS_ instead of using C++ constant style. +// +// The status codes are described at https://pigweed.dev/pw_status#status-codes. +// Consult that guide when deciding which status code to use. typedef enum { - // Ok (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 - // `Status::ok()` member function rather than inspecting the raw code. - PW_STATUS_OK = 0, // Use OkStatus() in C++ - - // Cancelled (gRPC code "CANCELLED") indicates the operation was cancelled, - // typically by the caller. - PW_STATUS_CANCELLED = 1, // Use Status::Cancelled() in C++ - - // Unknown (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. - PW_STATUS_UNKNOWN = 2, // Use Status::Unknown() in C++ - - // InvalidArgument (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 - // `FailedPrecondition` instead. - PW_STATUS_INVALID_ARGUMENT = 3, // Use Status::InvalidArgument() in C++ - - // DeadlineExceeded (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. - PW_STATUS_DEADLINE_EXCEEDED = 4, // Use Status::DeadlineExceeded() in C++ - - // NotFound (gRPC code "NOT_FOUND") indicates some requested entity (such as - // a file or directory) was not found. - // - // `NotFound` 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 `PermissionDenied` instead. - PW_STATUS_NOT_FOUND = 5, // Use Status::NotFound() in C++ - - // AlreadyExists (gRPC code "ALREADY_EXISTS") indicates the entity that a - // caller attempted to create (such as file or directory) is already present. - PW_STATUS_ALREADY_EXISTS = 6, // Use Status::AlreadyExists() in C++ - - // PermissionDenied (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. - // - // `PermissionDenied` must not be used for rejections caused by exhausting - // some resource. Instead, use `ResourceExhausted` for those errors. - // `PermissionDenied` must not be used if the caller cannot be identified. - // Instead, use `Unauthenticated` for those errors. - PW_STATUS_PERMISSION_DENIED = 7, // Use Status::PermissionDenied() in C++ - - // ResourceExhausted (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. - PW_STATUS_RESOURCE_EXHAUSTED = 8, // Use Status::ResourceExhausted() in C++ - - // FailedPrecondition (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 - // `FailedPrecondition`, `Aborted`, and `Unavailable`: - // - // (a) Use `Unavailable` if the client can retry just the failing call. - // (b) Use `Aborted` 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 `FailedPrecondition` 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, `FailedPrecondition` - // should be returned since the client should not retry unless - // the files are deleted from the directory. + PW_STATUS_OK = 0, // Use OkStatus() in C++ + PW_STATUS_CANCELLED = 1, // Use Status::Cancelled() in C++ + PW_STATUS_UNKNOWN = 2, // Use Status::Unknown() in C++ + PW_STATUS_INVALID_ARGUMENT = 3, // Use Status::InvalidArgument() in C++ + PW_STATUS_DEADLINE_EXCEEDED = 4, // Use Status::DeadlineExceeded() in C++ + PW_STATUS_NOT_FOUND = 5, // Use Status::NotFound() in C++ + PW_STATUS_ALREADY_EXISTS = 6, // Use Status::AlreadyExists() in C++ + PW_STATUS_PERMISSION_DENIED = 7, // Use Status::PermissionDenied() in C++ + PW_STATUS_RESOURCE_EXHAUSTED = 8, // Use Status::ResourceExhausted() in C++ PW_STATUS_FAILED_PRECONDITION = 9, // Use Status::FailedPrecondition() in C++ - - // Aborted (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 the guidelines above for deciding between `FailedPrecondition`, - // `Aborted`, and `Unavailable`. - PW_STATUS_ABORTED = 10, // Use Status::Aborted() in C++ - - // OutOfRange (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 `InvalidArgument`, this error indicates a problem that may - // be fixed if the system state changes. For example, a 32-bit file - // system will generate `InvalidArgument` if asked to read at an - // offset that is not in the range [0,2^32-1], but it will generate - // `OutOfRange` if asked to read from an offset past the current - // file size. - // - // There is a fair bit of overlap between `FailedPrecondition` and - // `OutOfRange`. We recommend using `OutOfRange` (the more specific - // error) when it applies so that callers who are iterating through - // a space can easily look for an `OutOfRange` error to detect when - // they are done. - PW_STATUS_OUT_OF_RANGE = 11, // Use Status::OutOfRange() in C++ - - // Unimplemented (gRPC code "UNIMPLEMENTED") indicates the operation is not - // implemented or supported in this service. In this case, the operation - // should not be re-attempted. - PW_STATUS_UNIMPLEMENTED = 12, // Use Status::Unimplemented() in C++ - - // Internal (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. - PW_STATUS_INTERNAL = 13, // Use Status::Internal() in C++ - - // Unavailable (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 `FailedPrecondition`, - // `Aborted`, and `Unavailable`. - PW_STATUS_UNAVAILABLE = 14, // Use Status::Unavailable() in C++ - - // DataLoss (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. - PW_STATUS_DATA_LOSS = 15, // Use Status::DataLoss() in C++ - - // Unauthenticated (gRPC code "UNAUTHENTICATED") indicates that the request - // does not have valid authentication credentials for the operation. Correct - // the authentication and try again. - PW_STATUS_UNAUTHENTICATED = 16, // Use Status::Unauthenticated() in C++ + PW_STATUS_ABORTED = 10, // Use Status::Aborted() in C++ + PW_STATUS_OUT_OF_RANGE = 11, // Use Status::OutOfRange() in C++ + PW_STATUS_UNIMPLEMENTED = 12, // Use Status::Unimplemented() in C++ + PW_STATUS_INTERNAL = 13, // Use Status::Internal() in C++ + PW_STATUS_UNAVAILABLE = 14, // Use Status::Unavailable() in C++ + PW_STATUS_DATA_LOSS = 15, // Use Status::DataLoss() in C++ + PW_STATUS_UNAUTHENTICATED = 16, // Use Status::Unauthenticated() in C++ // NOTE: this error code entry should not be used and you should not rely on // its value, which may change. @@ -178,20 +64,32 @@ typedef enum { // Returns a null-terminated string representation of the pw_Status. const char* pw_StatusString(pw_Status status); +// Indicates the status code with the highest valid value. +#define PW_STATUS_LAST PW_STATUS_UNAUTHENTICATED + #ifdef __cplusplus } // extern "C" namespace pw { -// The Status class is a thin, zero-cost abstraction around the pw_Status enum. -// It initializes to OkStatus() by default and adds ok() and str() methods. -// Implicit conversions are permitted between pw_Status and pw::Status. +/// `Status` is a thin, zero-cost abstraction around the `pw_Status` enum. It +/// initializes to @pw_status{OK} by default and adds `ok()` and `str()` +/// methods. Implicit conversions are permitted between `pw_Status` and +/// `pw::Status`. +/// +/// An @pw_status{OK} `Status` is created by the @cpp_func{pw::OkStatus} +/// function or by the default `Status` constructor. Non-OK `Status` is created +/// with a static member function that corresponds with the status code. class _PW_STATUS_NO_DISCARD Status { public: using Code = pw_Status; // Functions that create a Status with the specified code. + // + // The status codes are described at + // https://pigweed.dev/pw_status#status-codes. Consult that guide when + // deciding which status code to use. // clang-format off [[nodiscard]] static constexpr Status Cancelled() { return PW_STATUS_CANCELLED; @@ -249,10 +147,12 @@ class _PW_STATUS_NO_DISCARD Status { constexpr Status(const Status&) = default; constexpr Status& operator=(const Status&) = default; - // Returns the Status::Code (pw_Status) for this Status. + /// Returns the `Status::Code` (`pw_Status`) for this `Status`. constexpr Code code() const { return code_; } - // True if the status is OK. + /// True if the status is @pw_status{OK}. + /// + /// This function is provided in place of an `IsOk()` function. [[nodiscard]] constexpr bool ok() const { return code_ == PW_STATUS_OK; } // Functions for checking which status this is. @@ -305,30 +205,31 @@ class _PW_STATUS_NO_DISCARD Status { return code_ == PW_STATUS_UNAUTHENTICATED; } - // Updates this Status to the provided Status IF this status is OK. This is - // useful for tracking the first encountered error, as calls to this helper - // will not change one error status to another error status. + /// Updates this `Status` to the provided `Status` IF this status is + /// @pw_status{OK}. This is useful for tracking the first encountered error, + /// as calls to this helper will not change one error status to another error + /// status. constexpr void Update(Status other) { if (ok()) { code_ = other.code(); } } - // 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. + /// 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. constexpr void IgnoreError() const {} - // Returns a null-terminated string representation of the Status. + /// Returns a null-terminated string representation of the `Status`. [[nodiscard]] const char* str() const { return pw_StatusString(code_); } private: Code code_; }; -// Returns an OK status. Equivalent to Status() or Status(PW_STATUS_OK). This -// function is used instead of a Status::Ok() function, which would be too -// similar to Status::ok(). +/// Returns an @pw_status{OK} status. Equivalent to `Status()` or +/// `Status(PW_STATUS_OK)`. This function is used instead of a `Status::Ok()` +/// function, which would be too similar to `Status::ok()`. [[nodiscard]] constexpr Status OkStatus() { return Status(); } constexpr bool operator==(const Status& lhs, const Status& rhs) { |