pw_status#

Exception-free error propagation for embedded

Stable C++17 C Python Java TypeScript Rust

  • Easy: Simple to understand, includes convenient macro PW_TRY

  • Efficient: No memory allocation, no exceptions

  • Established: Just like absl::Status, deployed extensively at Google

pw::Status is Pigweed’s error propagation primitive, enabling exception-free error handling. The primary feature of pw_status is the pw::Status class, a simple, zero-overhead status object that wraps a status code, and the PW_TRY macro. For example:

#include "pw_status/status.h"

pw::Status ImuEnable() {
  if (!device_has_imu) {
    return Status::FailedPrecondition();
  }
  PW_TRY(ImuSpiSendEnable());  // Propagates failure on non-OK status.
  return pw::OkStatus();
}

void Initialize() {
  if (auto status = ImuEnable(); status.ok()) {
    PW_LOG_INFO("Imu initialized successfully")
  } else {
    if (status.IsFailedPrecondition()) {
      PW_LOG_WARNING("No IMU present");
    } else {
      PW_LOG_ERROR("Unknown error initializing IMU: %d", status.code());
    }
  }
}

pw_status provides an implementation of status in every supported Pigweed language, including C, Rust, TypeScript, Java, and Python.

Pigweed’s status matches Google’s standard status codes (see the Google APIs repository). These codes are used extensively in Google projects including Abseil (status/status.h) and gRPC (doc/statuscodes.md).

Get Started & Guides

Integrate pw_status into your project, see common uses

API Reference

Detailed description of pw_status’s methods.

Quick reference#

See Status codes for the precise semantics of each error, as well as how to spell the status in each of our supported languages. Click on the status names below to jump directly to that error’s reference.

Status

Code

Description

OK

0

Operation succeeded

CANCELLED

1

Operation was cancelled, typically by the caller

UNKNOWN

2

Unknown error occurred. Avoid this code when possible.

INVALID_ARGUMENT

3

Argument was malformed; e.g. invalid characters when parsing integer

DEADLINE_EXCEEDED

4

Deadline passed before operation completed

NOT_FOUND

5

The entity that the caller requested (e.g. file or directory) is not found

ALREADY_EXISTS

6

The entity that the caller requested to create is already present

PERMISSION_DENIED

7

Caller lacks permission to execute action

RESOURCE_EXHAUSTED

8

Insufficient resources to complete operation; e.g. supplied buffer is too small

FAILED_PRECONDITION

9

System isn’t in the required state; e.g. deleting a non-empty directory

ABORTED

10

Operation aborted due to e.g. concurrency issue or failed transaction

OUT_OF_RANGE

11

Operation attempted out of range; e.g. seeking past end of file

UNIMPLEMENTED

12

Operation isn’t implemented or supported

INTERNAL

13

Internal error occurred; e.g. system invariants were violated

UNAVAILABLE

14

Requested operation can’t finish now, but may at a later time

DATA_LOSS

15

Unrecoverable data loss occurred while completing the requested operation

UNAUTHENTICATED

16

Caller does not have valid authentication credentials for the operation
On this page