Exception-free error propagation for embedded.
Classes | |
| class | pw::Status |
| class | pw::StatusBase< Derived, kOkCode, kMessages > |
| class | pw::StatusOf< kOkCode, kMessages > |
| class | pw::StatusWithSize |
Macros | |
| #define | PW_STATUS_CFG_CHECK_IF_USED 0 |
| #define | PW_STATUS_CFG_MESSAGES_NONE 0 |
| #define | PW_STATUS_CFG_MESSAGES_STRING 1 |
| #define | PW_STATUS_CFG_MESSAGES_TOKENIZED 2 |
| #define | PW_STATUS_CFG_MESSAGES PW_STATUS_CFG_MESSAGES_NONE |
| #define | PW_STATUS_MSG_DOMAIN(code_domain) code_domain "::Message" |
| #define | PW_STATUS_MSG(string_literal) _PW_STATUS_MSG(string_literal) |
| #define | PW_STATUS_LAST PW_STATUS_UNAUTHENTICATED |
| Indicates the status code with the highest valid value. | |
| #define | PW_TRY(expr) _PW_TRY(_PW_TRY_UNIQUE(__LINE__), expr, return) |
Returns early if expr is a non-OK Status or Result. | |
| #define | PW_TRY_ASSIGN(lhs, expression) _PW_TRY_ASSIGN(_PW_TRY_UNIQUE(__LINE__), lhs, expression, return) |
| #define | PW_TRY_WITH_SIZE(expr) _PW_TRY_WITH_SIZE(_PW_TRY_UNIQUE(__LINE__), expr) |
| #define | PW_CO_TRY(expr) _PW_TRY(_PW_TRY_UNIQUE(__LINE__), expr, co_return) |
| #define | PW_CO_TRY_ASSIGN(lhs, expression) _PW_TRY_ASSIGN(_PW_TRY_UNIQUE(__LINE__), lhs, expression, co_return) |
Typedefs | |
| typedef enum pw_Status | pw_Status |
| C API for status codes. In C++, use the pw::Status class instead. | |
Enumerations | |
| enum | pw_Status { PW_STATUS_OK = 0 , PW_STATUS_CANCELLED = 1 , PW_STATUS_UNKNOWN = 2 , PW_STATUS_INVALID_ARGUMENT = 3 , PW_STATUS_DEADLINE_EXCEEDED = 4 , PW_STATUS_NOT_FOUND = 5 , PW_STATUS_ALREADY_EXISTS = 6 , PW_STATUS_PERMISSION_DENIED = 7 , PW_STATUS_RESOURCE_EXHAUSTED = 8 , PW_STATUS_FAILED_PRECONDITION = 9 , PW_STATUS_ABORTED = 10 , PW_STATUS_OUT_OF_RANGE = 11 , PW_STATUS_UNIMPLEMENTED = 12 , PW_STATUS_INTERNAL = 13 , PW_STATUS_UNAVAILABLE = 14 , PW_STATUS_DATA_LOSS = 15 , PW_STATUS_UNAUTHENTICATED = 16 , PW_STATUS_DO_NOT_USE_RESERVED_FOR_FUTURE_EXPANSION_USE_DEFAULT_IN_SWITCH_INSTEAD_ } |
| C API for status codes. In C++, use the pw::Status class instead. More... | |
| enum class | pw::StatusMessages { pw::StatusMessages::kDefault , pw::StatusMessages::kDisabled } |
| Whether a status type may carry an optional error message. More... | |
Functions | |
| const char * | pw_StatusString (pw_Status status) |
| constexpr Status | pw::OkStatus () noexcept |
| template<typename T , typename = std::enable_if_t< (std::is_integral_v<T> && !std::is_same_v<std::remove_cv_t<T>, bool>) || std::is_same_v<std::remove_cv_t<T>, Status::Code>>> | |
| constexpr Status | pw::StatusFromCodeOrUnknown (T code) noexcept |
| const char * | pw_StatusString (pw::Status status) |
| #define PW_CO_TRY | ( | expr | ) | _PW_TRY(_PW_TRY_UNIQUE(__LINE__), expr, co_return) |
Like PW_TRY, but using co_return instead of early return.
This is necessary because only co_return can be used inside of a coroutine, and there is no way to detect whether particular code is running within a coroutine or not.
| #define PW_CO_TRY_ASSIGN | ( | lhs, | |
| expression | |||
| ) | _PW_TRY_ASSIGN(_PW_TRY_UNIQUE(__LINE__), lhs, expression, co_return) |
Like PW_TRY_ASSIGN, but using co_return instead of early return.
This is necessary because only co_return can be used inside of a coroutine, and there is no way to detect whether particular code is running within a coroutine or not.
| #define PW_STATUS_CFG_CHECK_IF_USED 0 |
Controls whether to check if pw::Status values are used. Unused status values cause compilation warnings or errors. Calling the nop pw::status::IgnoreError() function silences these warnings.
| #define PW_STATUS_CFG_MESSAGES PW_STATUS_CFG_MESSAGES_NONE |
Selects how pw::Status and other pw::StatusBase-derived statuses store optional error messages, which are created with PW_STATUS_MSG("...") and logged with PW_LOG_STATUS. Set to PW_STATUS_CFG_MESSAGES_NONE (the default), PW_STATUS_CFG_MESSAGES_STRING, or PW_STATUS_CFG_MESSAGES_TOKENIZED.
Messages are stored in the form the pw_log backend emits, so this option must match the backend. pw_log/status.h fails to compile if it does not.
In Bazel, set the @pigweed//pw_status:messages flag to none, string, or tokenized instead.
pw::StatusBase. | #define PW_STATUS_CFG_MESSAGES_NONE 0 |
PW_STATUS_CFG_MESSAGES value: statuses do not store messages. PW_STATUS_MSG arguments are discarded at compile time and statuses are exactly as large as their code.
| #define PW_STATUS_CFG_MESSAGES_STRING 1 |
PW_STATUS_CFG_MESSAGES value: statuses store a pointer to the message's string literal. Use with pw_log backends that do not tokenize logs.
| #define PW_STATUS_CFG_MESSAGES_TOKENIZED 2 |
PW_STATUS_CFG_MESSAGES value: statuses store the message's pw_tokenizer token. Use with pw_log backends that tokenize logs, such as pw_log_tokenized.
| #define PW_STATUS_MSG | ( | string_literal | ) | _PW_STATUS_MSG(string_literal) |
Creates an optional error message for pw::Status or another pw::StatusBase-derived status.
Pass the result to a status constructor or factory function:
The argument must be a string literal. What happens to it depends on the pw_status configuration (PW_STATUS_CFG_MESSAGES):
PW_STATUS_CFG_MESSAGES_NONE (the default): the string is discarded at compile time.PW_STATUS_CFG_MESSAGES_TOKENIZED: the string is tokenized in the status's PW_STATUS_MSG_DOMAIN and only its token is stored.PW_STATUS_CFG_MESSAGES_STRING: a pointer to the string literal is stored.A status with a message logs as CODE (message), so that it reads well after a description of what failed:
Messages are stored in the form they are logged in, " (message)", so logging a status does not have to format its message.
Status equality comparisons (== and !=) consider only the status code and ignore messages.
Creating a status with a message is constexpr in C++23 and later, and never constexpr in earlier standards. Each PW_STATUS_MSG has its own type, so two of them cannot be the operands of a conditional expression.
| #define PW_STATUS_MSG_DOMAIN | ( | code_domain | ) | code_domain "::Message" |
Expands to the pw_tokenizer domain for the messages of statuses whose code enum is tokenized in code_domain: the code's domain followed by "::Message". For example, the messages of pw::Status are in the "::pw::Status::Message" domain.
Each status code enum has its own message domain because message tokens are masked to fit the bits its code leaves free, so they are specific to it.
| [in] | code_domain | String literal with the tokenizer domain of the status's code enum (pw::EnumTraits<Code>::kTokenDomain). |
| #define PW_TRY_ASSIGN | ( | lhs, | |
| expression | |||
| ) | _PW_TRY_ASSIGN(_PW_TRY_UNIQUE(__LINE__), lhs, expression, return) |
Returns early if expression is a non-OK Result. If expression is okay, assigns the inner value to lhs.
| #define PW_TRY_WITH_SIZE | ( | expr | ) | _PW_TRY_WITH_SIZE(_PW_TRY_UNIQUE(__LINE__), expr) |
Returns early if expr is a non-OK Status or StatusWithSize.
This is designed for use in functions that return a StatusWithSize.
| enum pw_Status |
C API for status codes. In C++, use the pw::Status class instead.
| Enumerator | |
|---|---|
| PW_STATUS_OK |
|
| PW_STATUS_CANCELLED |
|
| PW_STATUS_UNKNOWN |
|
| PW_STATUS_INVALID_ARGUMENT |
|
| PW_STATUS_DEADLINE_EXCEEDED |
|
| PW_STATUS_NOT_FOUND |
|
| PW_STATUS_ALREADY_EXISTS |
|
| PW_STATUS_PERMISSION_DENIED |
|
| PW_STATUS_RESOURCE_EXHAUSTED |
|
| PW_STATUS_FAILED_PRECONDITION |
|
| PW_STATUS_ABORTED |
|
| PW_STATUS_OUT_OF_RANGE |
|
| PW_STATUS_UNIMPLEMENTED |
|
| PW_STATUS_INTERNAL |
|
| PW_STATUS_UNAVAILABLE |
|
| PW_STATUS_DATA_LOSS |
|
| PW_STATUS_UNAUTHENTICATED |
|
|
strong |
|
constexprnoexcept |
Operation succeeded.
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().
OK). The C++ API for this code is OkStatus() (or Status::ok()) and the C API is PW_STATUS_OK. See OK for details on interacting with this status code in other languages.
|
inline |
Creates a C++ overload of pw_StatusString so that it supports pw::Status in addition to pw_Status.
| const char * pw_StatusString | ( | pw_Status | status | ) |
|
constexprnoexcept |
Creates a Status from a raw status code, mapping unrecognized or out-of-range values to Status::Unknown().
Use this instead of casting to Status::Code when decoding status codes from external sources such as wire protocols, persistent storage, or C APIs. Casting an out-of-range integer directly to Status::Code (pw_Status) produces a Status with no corresponding enumerator and is undefined behavior if the value exceeds the enum's range.
Accepts any integer type (except bool) as well as Status::Code.