Overview

Exception-free error propagation for embedded.

Main docs: Home | Quickstart & guides | Reference

Classes
class	pw::Status

class	pw::StatusBase< Derived, kOkCode >

class	pw::StatusWithSize

Macros
#define	PW_STATUS_CFG_CHECK_IF_USED 0

#define	PW_STATUS_LAST PW_STATUS_UNAUTHENTICATED
	Indicates the status code with the highest valid value.

#define	PW_STATUS_TYPE(name, ok_code)

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

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

Functions
const char *	pw_StatusString (pw_Status status)

constexpr Status	pw::OkStatus ()

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_TYPE

#define PW_STATUS_TYPE	(	name,
		ok_code
	)

Value:

  class [[nodiscard]] name final : public ::pw::StatusBase<name, ok_code> { \
   public:                                                                  \
    static_assert(::std::is_enum_v<Code>,                                   \
                  "PW_STATUS_TYPE requires an enum status code");           \
    constexpr name() = default;                                             \
    explicit constexpr name(Code code)                                      \
        : ::pw::StatusBase<name, ok_code>(code) {}                          \
  }

Defines a status type wrapping an existing status code enum.

The status type is default constructible (OK) and explicitly constructible from the enum. Enumerators are accessed through the enum type or the Code alias (e.g. MyStatus::Code::kFailed).

◆ 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

Function Documentation

◆ OkStatus()

constexpr Status pw::OkStatus ( )

constexpr

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.