xref: /aosp_15_r20/external/pigweed/pw_status/docs.rst (revision 61c4878ac05f98d0ceed94b57d316916de578985) 
1.. _module-pw_status:
2
3=========
4pw_status
5=========
6.. pigweed-module::
7   :name: pw_status
8
9   - **Easy**: Simple to understand, includes convenient macro ``PW_TRY``
10   - **Efficient**: No memory allocation, no exceptions
11   - **Established**: Just like ``absl::Status``, deployed extensively at Google
12
13   :cpp:type:`pw::Status` is Pigweed's error propagation primitive, enabling
14   exception-free error handling. The primary feature of ``pw_status`` is the
15   :cpp:class:`pw::Status` class, a simple, zero-overhead status object that
16   wraps a status code, and the ``PW_TRY`` macro. For example:
17
18   .. code-block:: cpp
19
20      #include "pw_status/status.h"
21
22      pw::Status ImuEnable() {
23        if (!device_has_imu) {
24          return Status::FailedPrecondition();
25        }
26        PW_TRY(ImuSpiSendEnable());  // Propagates failure on non-OK status.
27        return pw::OkStatus();
28      }
29
30      void Initialize() {
31        if (auto status = ImuEnable(); status.ok()) {
32          PW_LOG_INFO("Imu initialized successfully")
33        } else {
34          if (status.IsFailedPrecondition()) {
35            PW_LOG_WARNING("No IMU present");
36          } else {
37            PW_LOG_ERROR("Unknown error initializing IMU: %d", status.code());
38          }
39        }
40      }
41
42``pw_status`` provides an implementation of status in every supported
43Pigweed language, including C, Rust, TypeScript, Java, and Python.
44
45Pigweed's status matches Google's standard status codes (see the `Google APIs
46repository
47<https://github.com/googleapis/googleapis/blob/HEAD/google/rpc/code.proto>`_).
48These codes are used extensively in Google projects including `Abseil
49<https://abseil.io>`_ (`status/status.h
50<https://cs.opensource.google/abseil/abseil-cpp/+/HEAD:absl/status/status.h>`_)
51and `gRPC <https://grpc.io>`_ (`doc/statuscodes.md
52<https://github.com/grpc/grpc/blob/HEAD/doc/statuscodes.md>`_).
53
54.. grid:: 2
55
56   .. grid-item-card:: :octicon:`rocket` Get Started & Guides
57      :link: module-pw_status-get-started
58      :link-type: ref
59      :class-item: sales-pitch-cta-primary
60
61      Integrate pw_status into your project, see common uses
62
63   .. grid-item-card:: :octicon:`code-square` API Reference
64      :link: module-pw_status-reference
65      :link-type: ref
66      :class-item: sales-pitch-cta-secondary
67
68      Detailed description of pw_status's methods.
69
70.. _module-pw_status-quickref:
71
72---------------
73Quick reference
74---------------
75See :ref:`module-pw_status-codes` for the precise semantics of each error, as
76well as how to spell the status in each of our supported languages.  Click on
77the status names below to jump directly to that error's reference.
78
79.. list-table::
80   :widths: 35 5 60
81   :header-rows: 1
82
83   * - Status
84     - Code
85     - Description
86   * - :c:enumerator:`OK`
87     - 0
88     - Operation succeeded
89   * - :c:enumerator:`CANCELLED`
90     - 1
91     - Operation was cancelled, typically by the caller
92   * - :c:enumerator:`UNKNOWN`
93     - 2
94     - Unknown error occurred. Avoid this code when possible.
95   * - :c:enumerator:`INVALID_ARGUMENT`
96     - 3
97     - Argument was malformed; e.g. invalid characters when parsing integer
98   * - :c:enumerator:`DEADLINE_EXCEEDED`
99     - 4
100     - Deadline passed before operation completed
101   * - :c:enumerator:`NOT_FOUND`
102     - 5
103     - The entity that the caller requested (e.g. file or directory) is not
104       found
105   * - :c:enumerator:`ALREADY_EXISTS`
106     - 6
107     - The entity that the caller requested to create is already present
108   * - :c:enumerator:`PERMISSION_DENIED`
109     - 7
110     - Caller lacks permission to execute action
111   * - :c:enumerator:`RESOURCE_EXHAUSTED`
112     - 8
113     - Insufficient resources to complete operation; e.g. supplied buffer is too
114       small
115   * - :c:enumerator:`FAILED_PRECONDITION`
116     - 9
117     - System isn't in the required state; e.g. deleting a non-empty directory
118   * - :c:enumerator:`ABORTED`
119     - 10
120     - Operation aborted due to e.g. concurrency issue or failed transaction
121   * - :c:enumerator:`OUT_OF_RANGE`
122     - 11
123     - Operation attempted out of range; e.g. seeking past end of file
124   * - :c:enumerator:`UNIMPLEMENTED`
125     - 12
126     - Operation isn't implemented or supported
127   * - :c:enumerator:`INTERNAL`
128     - 13
129     - Internal error occurred; e.g. system invariants were violated
130   * - :c:enumerator:`UNAVAILABLE`
131     - 14
132     - Requested operation can't finish now, but may at a later time
133   * - :c:enumerator:`DATA_LOSS`
134     - 15
135     - Unrecoverable data loss occurred while completing the requested operation
136   * - :c:enumerator:`UNAUTHENTICATED`
137     - 16
138     - Caller does not have valid authentication credentials for the operation
139
140.. toctree::
141   :hidden:
142   :maxdepth: 1
143
144   guide
145   reference
146