Skip to main content
Pigweed's logo Pigweed
code_xml
  1. Home
  2. Reference
  3. C/C++
  4. Data structures & utilities
  5. pw_status

Overview

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)
 

Macro Definition Documentation

◆ PW_CO_TRY

#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.

◆ PW_CO_TRY_ASSIGN

#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.

◆ PW_STATUS_CFG_CHECK_IF_USED

#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.

◆ PW_STATUS_CFG_MESSAGES

#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.

Warning
When messages are stored as tokens, status codes must be valid enumerators. See pw::StatusBase.

◆ PW_STATUS_CFG_MESSAGES_NONE

#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.

◆ PW_STATUS_CFG_MESSAGES_STRING

#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.

◆ PW_STATUS_CFG_MESSAGES_TOKENIZED

#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.

◆ PW_STATUS_MSG

#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:

return pw::Status::NotFound(PW_STATUS_MSG("No such key"));
return MyStatus(MyCode::kFailed, PW_STATUS_MSG("Sector CRC error"));
static constexpr Status NotFound() noexcept
Definition: status.h:270
#define PW_STATUS_MSG(string_literal)
Definition: message.h:137

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:

// Logs "Read failed: NOT_FOUND (No such key)". If messages are disabled,
// logs "Read failed: NOT_FOUND".
PW_LOG_WARN("Read failed: " PW_STATUS_FMT, PW_LOG_STATUS(status));
#define PW_LOG_STATUS(...)
Definition: status.h:148
#define PW_STATUS_FMT
Definition: status.h:69

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.

◆ PW_STATUS_MSG_DOMAIN

#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.

Parameters
[in]code_domainString literal with the tokenizer domain of the status's code enum (pw::EnumTraits<Code>::kTokenDomain).

◆ PW_TRY_ASSIGN

#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.

◆ PW_TRY_WITH_SIZE

#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.

Enumeration Type Documentation

◆ pw_Status

enum pw_Status

C API for status codes. In C++, use the pw::Status class instead.

Enumerator
PW_STATUS_OK 
See also
OK
PW_STATUS_CANCELLED 
See also
CANCELLED
PW_STATUS_UNKNOWN 
See also
UNKNOWN
PW_STATUS_INVALID_ARGUMENT 
See also
INVALID_ARGUMENT
PW_STATUS_DEADLINE_EXCEEDED 
See also
DEADLINE_EXCEEDED
PW_STATUS_NOT_FOUND 
See also
NOT_FOUND
PW_STATUS_ALREADY_EXISTS 
See also
ALREADY_EXISTS
PW_STATUS_PERMISSION_DENIED 
See also
PERMISSION_DENIED
PW_STATUS_RESOURCE_EXHAUSTED 
See also
RESOURCE_EXHAUSTED
PW_STATUS_FAILED_PRECONDITION 
See also
FAILED_PRECONDITION
PW_STATUS_ABORTED 
See also
ABORTED
PW_STATUS_OUT_OF_RANGE 
See also
OUT_OF_RANGE
PW_STATUS_UNIMPLEMENTED 
See also
UNIMPLEMENTED
PW_STATUS_INTERNAL 
See also
INTERNAL
PW_STATUS_UNAVAILABLE 
See also
UNAVAILABLE
PW_STATUS_DATA_LOSS 
See also
DATA_LOSS
PW_STATUS_UNAUTHENTICATED 
See also
UNAUTHENTICATED

◆ StatusMessages

enum class pw::StatusMessages
strong

Whether a status type may carry an optional error message.

Enumerator
kDefault 

Messages are stored if PW_STATUS_CFG_MESSAGES enables them and the status code supports them.

kDisabled 

The status never carries a message, so it is always only its code.

Function Documentation

◆ OkStatus()

constexpr Status pw::OkStatus ( )
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().

Note
In the Pigweed docs we refer to this code by its generic, canonical name (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.

◆ pw_StatusString() [1/2]

const char * pw_StatusString ( pw::Status  status)
inline

Creates a C++ overload of pw_StatusString so that it supports pw::Status in addition to pw_Status.

◆ pw_StatusString() [2/2]

const char * pw_StatusString ( pw_Status  status)
Returns
A null-terminated string representation of the pw_Status.

◆ StatusFromCodeOrUnknown()

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)
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.