Reference#
pw_status: Exception-free error propagation for embedded
Status codes#
-
enumerator OK = 0#
OK
indicates that the operation completede successfully. It is typical to check for this value before proceeding on any given call across an API or RPC boundary. To check this value, use theok()
member function rather than inspecting the raw code.C++
pw::OkStatus()
C
PW_STATUS_OK
Python / Java / TypeScript
Status.OK
Rust
Ok(val)
-
enumerator CANCELLED = 1#
CANCELLED
indicates the operation was cancelled, typically by the caller.C++
pw::Status::Cancelled()
C
PW_STATUS_CANCELLED
Python / Java / TypeScript
Status.CANCELLED
Rust
Error::Cancelled
-
enumerator UNKNOWN = 2#
UNKNOWN
indicates an unknown error occurred. In general, more specific errors should be raised, if possible. Errors raised by APIs that do not return enough error information may be converted to this error.C++
pw::Status::Unknown()
C
PW_STATUS_UNKNOWN
Python / Java / TypeScript
Status.UNKNOWN
Rust
Error::Unknown
-
enumerator INVALID_ARGUMENT = 3#
INVALID_ARGUMENT
indicates the caller specified an invalid argument, such as a malformed filename. Note that use of such errors should be narrowly limited to indicate the invalid nature of the arguments themselves. Errors with validly formed arguments that may cause errors with the state of the receiving system should be denoted withFAILED_PRECONDITION
instead.C++
pw::Status::InvalidArgument()
C
PW_STATUS_INVALID_ARGUMENT
Python / Java / TypeScript
Status.INVALID_ARGUMENT
Rust
Error::InvalidArgument
-
enumerator DEADLINE_EXCEEDED = 4#
DEADLINE_EXCEEDED
indicates a deadline expired before the operation could complete. For operations that may change state within a system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.C++
pw::Status::DeadlineExceeded()
C
PW_STATUS_DEADLINE_EXCEEDED
Python / Java / TypeScript
Status.DEADLINE_EXCEEDED
Rust
Error::DeadlineExceeded
-
enumerator NOT_FOUND = 5#
NOT_FOUND
indicates some requested entity (such as a file or directory) was not found.NOT_FOUND
is useful if a request should be denied for an entire class of users, such as during a gradual feature rollout or undocumented allowlist. If a request should be denied for specific sets of users, such as through user-based access control, usePERMISSION_DENIED
instead.C++
pw::Status::NotFound()
C
PW_STATUS_NOT_FOUND
Python / Java / TypeScript
Status.NOT_FOUND
Rust
Error::NotFound
-
enumerator ALREADY_EXISTS = 6#
ALREADY_EXISTS
indicates that the entity a caller attempted to create (such as a file or directory) is already present.C++
pw::Status::AlreadyExists()
C
PW_STATUS_ALREADY_EXISTS
Python / Java / TypeScript
Status.ALREADY_EXISTS
Rust
Error::AlreadyExists
-
enumerator PERMISSION_DENIED = 7#
PERMISSION_DENIED
indicates that the caller does not have permission to execute the specified operation. Note that this error is different than an error due to an unauthenticated user. This error code does not imply the request is valid or the requested entity exists or satisfies any other pre-conditions.PERMISSION_DENIED
must not be used for rejections caused by exhausting some resource. Instead, useRESOURCE_EXHAUSTED
for those errors.PERMISSION_DENIED
must not be used if the caller cannot be identified. Instead, useUNAUTHENTICATED
for those errors.C++
pw::Status::PermissionDenied()
C
PW_STATUS_PERMISSION_DENIED
Python / Java / TypeScript
Status.PERMISSION_DENIED
Rust
Error::PermissionDenied
-
enumerator RESOURCE_EXHAUSTED = 8#
RESOURCE_EXHAUSTED
indicates some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.C++
pw::Status::ResourceExhausted()
C
PW_STATUS_RESOURCE_EXHAUSTED
Python / Java / TypeScript
Status.RESOURCE_EXHAUSTED
Rust
Error::ResourceExhausted
-
enumerator FAILED_PRECONDITION = 9#
FAILED_PRECONDITION
indicates that the operation was rejected because the system is not in a state required for the operation’s execution. For example, a directory to be deleted may be non-empty, anrmdir
operation is applied to a non-directory, etc.Some guidelines that may help a service implementer in deciding between
FAILED_PRECONDITION
,ABORTED
, andUNAVAILABLE
:Use
UNAVAILABLE
if the client can retry just the failing call.Use
ABORTED
if the client should retry at a higher transaction level (such as when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence).Use
FAILED_PRECONDITION
if the client should not retry until the system state has been explicitly fixed. For example, if armdir
fails because the directory is non-empty,FAILED_PRECONDITION
should be returned since the client should not retry unless the files are deleted from the directory.
C++
pw::Status::FailedPrecondition()
C
PW_STATUS_FAILED_PRECONDITION
Python / Java / TypeScript
Status.FAILED_PRECONDITION
Rust
Error::FailedPrecondition
-
enumerator ABORTED = 10#
ABORTED
indicates the operation was aborted, typically due to a concurrency issue such as a sequencer check failure or a failed transaction.See the guidelines above for deciding between
FAILED_PRECONDITION
,ABORTED
, andUNAVAILABLE
.C++
pw::Status::Aborted()
C
PW_STATUS_ABORTED
Python / Java / TypeScript
Status.ABORTED
Rust
Error::Aborted
-
enumerator OUT_OF_RANGE = 11#
OUT_OF_RANGE
indicates the operation was attempted past the valid range, such as seeking or reading past an end-of-file.Unlike
INVALID_ARGUMENT
, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generateINVALID_ARGUMENT
if asked to read at an offset that is not in the range [0,2^32-1], but it will generateOUT_OF_RANGE
if asked to read from an offset past the current file size.There is a fair bit of overlap between
FAILED_PRECONDITION
andOUT_OF_RANGE
. We recommend usingOUT_OF_RANGE
(the more specific error) when it applies so that callers who are iterating through a space can easily look for anOUT_OF_RANGE
error to detect when they are done.C++
pw::Status::OutOfRange()
C
PW_STATUS_OUT_OF_RANGE
Python / Java / TypeScript
Status.OUT_OF_RANGE
Rust
Error::OutOfRange
-
enumerator UNIMPLEMENTED = 12#
UNIMPLEMENTED
indicates the operation is not implemented or supported in this service. In this case, the operation should not be re-attempted.C++
pw::Status::Unimplemented()
C
PW_STATUS_UNIMPLEMENTED
Python / Java / TypeScript
Status.UNIMPLEMENTED
Rust
Error::Unimplemented
-
enumerator INTERNAL = 13#
INTERNAL
indicates an internal error has occurred and some invariants expected by the underlying system have not been satisfied. This error code is reserved for serious errors.C++
pw::Status::Internal()
C
PW_STATUS_INTERNAL
Python / Java / TypeScript
Status.INTERNAL
Rust
Error::Internal
-
enumerator UNAVAILABLE = 14#
UNAVAILABLE
indicates the service is currently unavailable and that this is most likely a transient condition. An error such as this can be corrected by retrying with a backoff scheme. Note that it is not always safe to retry non-idempotent operations.See the guidelines above for deciding between
FAILED_PRECONDITION
,ABORTED
, andUNAVAILABLE
.C++
pw::Status::Unavailable()
C
PW_STATUS_UNAVAILABLE
Python / Java / TypeScript
Status.UNAVAILABLE
Rust
Error::Unavailable
-
enumerator DATA_LOSS = 15#
DATA_LOSS
indicates that unrecoverable data loss or corruption has occurred. As this error is serious, proper alerting should be attached to errors such as this.C++
pw::Status::DataLoss()
C
PW_STATUS_DATA_LOSS
Python / Java / TypeScript
Status.DATA_LOSS
Rust
Error::DataLoss
-
enumerator UNAUTHENTICATED = 16#
UNAUTHENTICATED
indicates that the request does not have valid authentication credentials for the operation. Correct the authentication and try again.C++
pw::Status::Unauthenticated()
C
PW_STATUS_UNAUTHENTICATED
Python / Java / TypeScript
Status.UNAUTHENTICATED
Rust
Error::Unauthenticated
C++ API#
-
class Status#
Status
is a thin, zero-cost abstraction around thepw_Status
enum. It initializes toOK
by default and addsok()
andstr()
methods. Implicit conversions are permitted betweenpw_Status
andpw::Status
.An
OK
Status
is created by thepw::OkStatus()
function or by the defaultStatus
constructor. Non-OKStatus
is created with a static member function that corresponds with the status code.Public Functions
-
inline constexpr bool ok() const#
True if the status is
OK
.This function is provided in place of an
IsOk()
function.
-
inline constexpr void Update(Status other)#
Updates this
Status
to the providedStatus
IF this status isOK
. This is useful for tracking the first encountered error, as calls to this helper will not change one error status to another error status.
-
inline constexpr void IgnoreError() const#
Ignores any errors. This method does nothing except potentially suppress complaints from any tools that are checking that errors are not dropped on the floor.
-
inline constexpr bool ok() const#
-
constexpr Status pw::OkStatus()#
Returns an
OK
status. Equivalent toStatus()
orStatus(PW_STATUS_OK)
. This function is used instead of aStatus::Ok()
function, which would be too similar toStatus::ok()
.
-
enum pw_Status#
Enum to use in place of
pw::Status
in C code. Always usepw::Status
in C++ code.The values of the
pw_Status
enum are all-caps and prefixed withPW_STATUS_
. For example,PW_STATUS_DATA_LOSS
corresponds withDATA_LOSS
.
Unused result warnings#
If the PW_STATUS_CFG_CHECK_IF_USED
option is enabled, pw::Status
objects
returned from function calls must be used or it is a compilation error. To
silence these warnings call IgnoreError()
on the returned status object.
PW_STATUS_CFG_CHECK_IF_USED
defaults to false
. Pigweed compiles with
this option enabled, but projects that use Pigweed will need to be updated to
compile with this option. After all projects have migrated, unused result
warnings will be enabled unconditionally.
C API#
pw_status
provides the C-compatible pw_Status
enum for the status
codes. For ease of use, pw::Status
implicitly converts to and from
pw_Status
. However, the pw_Status
enum should never be used
in C++; instead use the pw::Status
class.
Rust API#
pw_status
’s Rust API is documented in our
rustdoc API docs.