1.. _module-pw_status-reference: 2 3========= 4Reference 5========= 6.. pigweed-module-subpage:: 7 :name: pw_status 8 9.. _module-pw_status-codes: 10 11------------ 12Status codes 13------------ 14.. c:enumerator:: OK = 0 15 16 :c:enumerator:`OK` indicates that the operation completede successfully. It 17 is typical to check for this value before proceeding on any given call across 18 an API or RPC boundary. To check this value, use the ``ok()`` member function 19 rather than inspecting the raw code. 20 21 .. list-table:: 22 23 * - C++ 24 - ``pw::OkStatus()`` 25 * - C 26 - ``PW_STATUS_OK`` 27 * - Python / Java / TypeScript 28 - ``Status.OK`` 29 * - Rust 30 - ``Ok(val)`` 31 32.. c:enumerator:: CANCELLED = 1 33 34 :c:enumerator:`CANCELLED` indicates the operation was cancelled, typically by 35 the caller. 36 37 .. list-table:: 38 39 * - C++ 40 - ``pw::Status::Cancelled()`` 41 * - C 42 - ``PW_STATUS_CANCELLED`` 43 * - Python / Java / TypeScript 44 - ``Status.CANCELLED`` 45 * - Rust 46 - ``Error::Cancelled`` 47 48.. c:enumerator:: UNKNOWN = 2 49 50 :c:enumerator:`UNKNOWN` indicates an unknown error occurred. In general, more 51 specific errors should be raised, if possible. Errors raised by APIs that do 52 not return enough error information may be converted to this error. 53 54 .. list-table:: 55 56 * - C++ 57 - ``pw::Status::Unknown()`` 58 * - C 59 - ``PW_STATUS_UNKNOWN`` 60 * - Python / Java / TypeScript 61 - ``Status.UNKNOWN`` 62 * - Rust 63 - ``Error::Unknown`` 64 65.. c:enumerator:: INVALID_ARGUMENT = 3 66 67 :c:enumerator:`INVALID_ARGUMENT` indicates the caller specified an invalid 68 argument, such as a malformed filename. Note that use of such errors should 69 be narrowly limited to indicate the invalid nature of the arguments 70 themselves. Errors with validly formed arguments that may cause errors with 71 the state of the receiving system should be denoted with 72 :c:enumerator:`FAILED_PRECONDITION` instead. 73 74 .. list-table:: 75 76 * - C++ 77 - ``pw::Status::InvalidArgument()`` 78 * - C 79 - ``PW_STATUS_INVALID_ARGUMENT`` 80 * - Python / Java / TypeScript 81 - ``Status.INVALID_ARGUMENT`` 82 * - Rust 83 - ``Error::InvalidArgument`` 84 85.. c:enumerator:: DEADLINE_EXCEEDED = 4 86 87 :c:enumerator:`DEADLINE_EXCEEDED` indicates a deadline expired before the 88 operation could complete. For operations that may change state within a 89 system, this error may be returned even if the operation has completed 90 successfully. For example, a successful response from a server could have 91 been delayed long enough for the deadline to expire. 92 93 .. list-table:: 94 95 * - C++ 96 - ``pw::Status::DeadlineExceeded()`` 97 * - C 98 - ``PW_STATUS_DEADLINE_EXCEEDED`` 99 * - Python / Java / TypeScript 100 - ``Status.DEADLINE_EXCEEDED`` 101 * - Rust 102 - ``Error::DeadlineExceeded`` 103 104.. c:enumerator:: NOT_FOUND = 5 105 106 :c:enumerator:`NOT_FOUND` indicates some requested entity (such as a file or 107 directory) was not found. 108 109 :c:enumerator:`NOT_FOUND` is useful if a request should be denied for an 110 entire class of users, such as during a gradual feature rollout or 111 undocumented allowlist. If a request should be denied for specific sets of 112 users, such as through user-based access control, use 113 :c:enumerator:`PERMISSION_DENIED` instead. 114 115 .. list-table:: 116 117 * - C++ 118 - ``pw::Status::NotFound()`` 119 * - C 120 - ``PW_STATUS_NOT_FOUND`` 121 * - Python / Java / TypeScript 122 - ``Status.NOT_FOUND`` 123 * - Rust 124 - ``Error::NotFound`` 125 126.. c:enumerator:: ALREADY_EXISTS = 6 127 128 :c:enumerator:`ALREADY_EXISTS` indicates that the entity a caller attempted 129 to create (such as a file or directory) is already present. 130 131 .. list-table:: 132 133 * - C++ 134 - ``pw::Status::AlreadyExists()`` 135 * - C 136 - ``PW_STATUS_ALREADY_EXISTS`` 137 * - Python / Java / TypeScript 138 - ``Status.ALREADY_EXISTS`` 139 * - Rust 140 - ``Error::AlreadyExists`` 141 142.. c:enumerator:: PERMISSION_DENIED = 7 143 144 :c:enumerator:`PERMISSION_DENIED` indicates that the caller does not have 145 permission to execute the specified operation. Note that this error is 146 different than an error due to an unauthenticated user. This error code does 147 not imply the request is valid or the requested entity exists or satisfies 148 any other pre-conditions. 149 150 :c:enumerator:`PERMISSION_DENIED` must not be used for rejections caused by 151 exhausting some resource. Instead, use :c:enumerator:`RESOURCE_EXHAUSTED` for 152 those errors. :c:enumerator:`PERMISSION_DENIED` must not be used if the 153 caller cannot be identified. Instead, use :c:enumerator:`UNAUTHENTICATED` 154 for those errors. 155 156 .. list-table:: 157 158 * - C++ 159 - ``pw::Status::PermissionDenied()`` 160 * - C 161 - ``PW_STATUS_PERMISSION_DENIED`` 162 * - Python / Java / TypeScript 163 - ``Status.PERMISSION_DENIED`` 164 * - Rust 165 - ``Error::PermissionDenied`` 166 167.. c:enumerator:: RESOURCE_EXHAUSTED = 8 168 169 :c:enumerator:`RESOURCE_EXHAUSTED` indicates some resource has been 170 exhausted, perhaps a per-user quota, or perhaps the entire file system is out 171 of space. 172 173 .. list-table:: 174 175 * - C++ 176 - ``pw::Status::ResourceExhausted()`` 177 * - C 178 - ``PW_STATUS_RESOURCE_EXHAUSTED`` 179 * - Python / Java / TypeScript 180 - ``Status.RESOURCE_EXHAUSTED`` 181 * - Rust 182 - ``Error::ResourceExhausted`` 183 184.. c:enumerator:: FAILED_PRECONDITION = 9 185 186 :c:enumerator:`FAILED_PRECONDITION` indicates that the operation was rejected 187 because the system is not in a state required for the operation's execution. 188 For example, a directory to be deleted may be non-empty, an ``rmdir`` 189 operation is applied to a non-directory, etc. 190 191 .. _module-pw_status-guidelines: 192 193 Some guidelines that may help a service implementer in deciding between 194 :c:enumerator:`FAILED_PRECONDITION`, :c:enumerator:`ABORTED`, and 195 :c:enumerator:`UNAVAILABLE`: 196 197 a. Use :c:enumerator:`UNAVAILABLE` if the client can retry just the failing 198 call. 199 b. Use :c:enumerator:`ABORTED` if the client should retry at a higher 200 transaction level (such as when a client-specified test-and-set fails, 201 indicating the client should restart a read-modify-write sequence). 202 c. Use :c:enumerator:`FAILED_PRECONDITION` if the client should not retry 203 until the system state has been explicitly fixed. For example, if a 204 ``rmdir`` fails because the directory is non-empty, 205 :c:enumerator:`FAILED_PRECONDITION` should be returned since the client 206 should not retry unless the files are deleted from the directory. 207 208 .. list-table:: 209 210 * - C++ 211 - ``pw::Status::FailedPrecondition()`` 212 * - C 213 - ``PW_STATUS_FAILED_PRECONDITION`` 214 * - Python / Java / TypeScript 215 - ``Status.FAILED_PRECONDITION`` 216 * - Rust 217 - ``Error::FailedPrecondition`` 218 219.. c:enumerator:: ABORTED = 10 220 221 :c:enumerator:`ABORTED` indicates the operation was aborted, typically due to 222 a concurrency issue such as a sequencer check failure or a failed 223 transaction. 224 225 See the :ref:`guidelines <module-pw_status-guidelines>` above for deciding 226 between :c:enumerator:`FAILED_PRECONDITION`, :c:enumerator:`ABORTED`, and 227 :c:enumerator:`UNAVAILABLE`. 228 229 .. list-table:: 230 231 * - C++ 232 - ``pw::Status::Aborted()`` 233 * - C 234 - ``PW_STATUS_ABORTED`` 235 * - Python / Java / TypeScript 236 - ``Status.ABORTED`` 237 * - Rust 238 - ``Error::Aborted`` 239 240.. c:enumerator:: OUT_OF_RANGE = 11 241 242 :c:enumerator:`OUT_OF_RANGE` indicates the operation was attempted past the 243 valid range, such as seeking or reading past an end-of-file. 244 245 Unlike :c:enumerator:`INVALID_ARGUMENT`, this error indicates a problem that 246 may be fixed if the system state changes. For example, a 32-bit file system 247 will generate :c:enumerator:`INVALID_ARGUMENT` if asked to read at an offset 248 that is not in the range [0,2^32-1], but it will generate 249 :c:enumerator:`OUT_OF_RANGE` if asked to read from an offset past the current 250 file size. 251 252 There is a fair bit of overlap between :c:enumerator:`FAILED_PRECONDITION` 253 and :c:enumerator:`OUT_OF_RANGE`. Use :c:enumerator:`OUT_OF_RANGE` (the more 254 specific error) when it applies so that callers who are iterating through a 255 space can easily look for an :c:enumerator:`OUT_OF_RANGE` error to detect 256 when they are done. 257 258 .. list-table:: 259 260 * - C++ 261 - ``pw::Status::OutOfRange()`` 262 * - C 263 - ``PW_STATUS_OUT_OF_RANGE`` 264 * - Python / Java / TypeScript 265 - ``Status.OUT_OF_RANGE`` 266 * - Rust 267 - ``Error::OutOfRange`` 268 269.. c:enumerator:: UNIMPLEMENTED = 12 270 271 :c:enumerator:`UNIMPLEMENTED` indicates the operation is not implemented or 272 supported in this service. In this case, the operation should not be 273 re-attempted. 274 275 .. list-table:: 276 277 * - C++ 278 - ``pw::Status::Unimplemented()`` 279 * - C 280 - ``PW_STATUS_UNIMPLEMENTED`` 281 * - Python / Java / TypeScript 282 - ``Status.UNIMPLEMENTED`` 283 * - Rust 284 - ``Error::Unimplemented`` 285 286.. c:enumerator:: INTERNAL = 13 287 288 :c:enumerator:`INTERNAL` indicates an internal error has occurred and some 289 invariants expected by the underlying system have not been satisfied. This 290 error code is reserved for serious errors. 291 292 .. list-table:: 293 294 * - C++ 295 - ``pw::Status::Internal()`` 296 * - C 297 - ``PW_STATUS_INTERNAL`` 298 * - Python / Java / TypeScript 299 - ``Status.INTERNAL`` 300 * - Rust 301 - ``Error::Internal`` 302 303.. c:enumerator:: UNAVAILABLE = 14 304 305 :c:enumerator:`UNAVAILABLE` indicates the service is currently unavailable 306 and that this is most likely a transient condition. An error such as this can 307 be corrected by retrying with a backoff scheme. Note that it is not always 308 safe to retry non-idempotent operations. 309 310 See the :ref:`guidelines <module-pw_status-guidelines>` above for deciding 311 between :c:enumerator:`FAILED_PRECONDITION`, :c:enumerator:`ABORTED`, and 312 :c:enumerator:`UNAVAILABLE`. 313 314 .. list-table:: 315 316 * - C++ 317 - ``pw::Status::Unavailable()`` 318 * - C 319 - ``PW_STATUS_UNAVAILABLE`` 320 * - Python / Java / TypeScript 321 - ``Status.UNAVAILABLE`` 322 * - Rust 323 - ``Error::Unavailable`` 324 325.. c:enumerator:: DATA_LOSS = 15 326 327 :c:enumerator:`DATA_LOSS` indicates that unrecoverable data loss or 328 corruption has occurred. As this error is serious, proper alerting should be 329 attached to errors such as this. 330 331 .. list-table:: 332 333 * - C++ 334 - ``pw::Status::DataLoss()`` 335 * - C 336 - ``PW_STATUS_DATA_LOSS`` 337 * - Python / Java / TypeScript 338 - ``Status.DATA_LOSS`` 339 * - Rust 340 - ``Error::DataLoss`` 341 342.. c:enumerator:: UNAUTHENTICATED = 16 343 344 :c:enumerator:`UNAUTHENTICATED` indicates that the request does not have 345 valid authentication credentials for the operation. Correct the 346 authentication and try again. 347 348 .. list-table:: 349 350 * - C++ 351 - ``pw::Status::Unauthenticated()`` 352 * - C 353 - ``PW_STATUS_UNAUTHENTICATED`` 354 * - Python / Java / TypeScript 355 - ``Status.UNAUTHENTICATED`` 356 * - Rust 357 - ``Error::Unauthenticated`` 358 359------- 360C++ API 361------- 362.. doxygenclass:: pw::Status 363 :members: 364 365.. doxygenfunction:: pw::OkStatus 366 367.. c:enum:: pw_Status 368 369 Enum to use in place of :cpp:class:`pw::Status` in C code. Always use 370 :cpp:class:`pw::Status` in C++ code. 371 372 The values of the :c:enum:`pw_Status` enum are all-caps and prefixed with 373 ``PW_STATUS_``. For example, ``PW_STATUS_DATA_LOSS`` corresponds with 374 :c:enumerator:`DATA_LOSS`. 375 376.. doxygenclass:: pw::StatusWithSize 377 :members: 378 :undoc-members: 379 380.. doxygendefine:: PW_TRY 381.. doxygendefine:: PW_TRY_ASSIGN 382.. doxygendefine:: PW_TRY_WITH_SIZE 383.. doxygendefine:: PW_CO_TRY 384.. doxygendefine:: PW_CO_TRY_ASSIGN 385 386.. _module-pw_status-reference-unused: 387 388Unused result warnings 389---------------------- 390If the ``PW_STATUS_CFG_CHECK_IF_USED`` option is enabled, ``pw::Status`` objects 391returned from function calls must be used or it is a compilation error. To 392silence these warnings call ``IgnoreError()`` on the returned status object. 393 394``PW_STATUS_CFG_CHECK_IF_USED`` defaults to ``false`` in GN and CMake, but 395``true`` in Bazel. Pigweed compiles with this option enabled, but projects that 396use Pigweed will need to be updated to compile with this option. After all 397projects have migrated, unused result warnings will be enabled unconditionally. 398 399----- 400C API 401----- 402``pw_status`` provides the C-compatible :c:enum:`pw_Status` enum for the status 403codes. For ease of use, :cpp:class:`pw::Status` implicitly converts to and from 404:c:enum:`pw_Status`. However, the :c:enum:`pw_Status` enum should never be used 405in C++; instead use the :cpp:class:`pw::Status` class. 406 407-------- 408Rust API 409-------- 410``pw_status``'s Rust API is documented in our 411`rustdoc API docs </rustdoc/pw_status/>`_. 412