Oveview

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

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

Enumerator
PW_STATUS_OK
PW_STATUS_CANCELLED	Operation was cancelled, typically by the caller.
PW_STATUS_UNKNOWN	Unknown error occurred. Avoid this code when possible.
PW_STATUS_INVALID_ARGUMENT	Argument was malformed; e.g. invalid characters when parsing integer.
PW_STATUS_DEADLINE_EXCEEDED	Deadline passed before operation completed.
PW_STATUS_NOT_FOUND	The entity that the caller requested (e.g. file or directory) is not found.
PW_STATUS_ALREADY_EXISTS	The entity that the caller requested to create is already present.
PW_STATUS_PERMISSION_DENIED	Caller lacks permission to execute action.
PW_STATUS_RESOURCE_EXHAUSTED	Insufficient resources to complete operation; e.g. supplied buffer is too small
PW_STATUS_FAILED_PRECONDITION	System isn’t in the required state; e.g. deleting a non-empty directory.
PW_STATUS_ABORTED	Operation aborted due to e.g. concurrency issue or failed transaction.
PW_STATUS_OUT_OF_RANGE	Operation attempted out of range; e.g. seeking past end of file.
PW_STATUS_UNIMPLEMENTED	Operation isn’t implemented or supported.
PW_STATUS_INTERNAL	Internal error occurred; e.g. system invariants were violated.
PW_STATUS_UNAVAILABLE	Requested operation can’t finish now, but may at a later time.
PW_STATUS_DATA_LOSS	Unrecoverable data loss occurred while completing the requested operation.
PW_STATUS_UNAUTHENTICATED	Caller does not have valid authentication credentials for the operation.

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

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