Overview

Exception-free error propagation for embedded.

Main docs: Home | Quickstart & guides | Reference

Classes
class	pw::Status

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_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 ()

constexpr bool	pw::operator== (const Status &lhs, const Status &rhs)

constexpr bool	pw::operator!= (const Status &lhs, const Status &rhs)

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