mirror of
https://fuchsia.googlesource.com/third_party/pigweed.googlesource.com/pigweed/pigweed
synced 2024-09-19 21:29:48 +00:00
07d564b6cd
- Remove blank lines from the end the reST files. - Ensure the file ends with a newline. - Apply updated format to the repo. Change-Id: I82418c6bced140995fbb1f1b6285357ac833b479 Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/207511 Reviewed-by: Armando Montanez <amontanez@google.com> Lint: Lint 🤖 <android-build-ayeaye@system.gserviceaccount.com> Reviewed-by: Anthony DiGirolamo <tonymd@google.com>
219 lines
6.2 KiB
ReStructuredText
219 lines
6.2 KiB
ReStructuredText
.. _module-pw_status-guide:
|
|
|
|
====================
|
|
Get started & guides
|
|
====================
|
|
.. pigweed-module-subpage::
|
|
:name: pw_status
|
|
|
|
.. _module-pw_status-get-started:
|
|
|
|
-----------
|
|
Get started
|
|
-----------
|
|
To deploy ``pw_status``, depend on the library:
|
|
|
|
.. tab-set::
|
|
|
|
.. tab-item:: Bazel
|
|
|
|
Add ``@pigweed//pw_status`` to the ``deps`` list in your Bazel target:
|
|
|
|
.. code-block::
|
|
|
|
cc_library("...") {
|
|
# ...
|
|
deps = [
|
|
# ...
|
|
"@pigweed//pw_status",
|
|
# ...
|
|
]
|
|
}
|
|
|
|
This assumes that your Bazel ``WORKSPACE`` has a `repository
|
|
<https://bazel.build/concepts/build-ref#repositories>`_ named ``@pigweed``
|
|
that points to the upstream Pigweed repository.
|
|
|
|
.. tab-item:: GN
|
|
|
|
Add ``$dir_pw_status`` to the ``deps`` list in your ``pw_executable()``
|
|
build target:
|
|
|
|
.. code-block::
|
|
|
|
pw_executable("...") {
|
|
# ...
|
|
deps = [
|
|
# ...
|
|
"$dir_pw_status",
|
|
# ...
|
|
]
|
|
}
|
|
|
|
.. tab-item:: CMake
|
|
|
|
Add ``pw_status`` to your ``pw_add_library`` or similar CMake target:
|
|
|
|
.. code-block::
|
|
|
|
pw_add_library(my_library STATIC
|
|
HEADERS
|
|
...
|
|
PRIVATE_DEPS
|
|
# ...
|
|
pw_status
|
|
# ...
|
|
)
|
|
|
|
.. tab-item:: Zephyr
|
|
|
|
There are two ways to use ``pw_status`` from a Zephyr project:
|
|
|
|
* Depend on ``pw_status`` in your CMake target (see CMake tab). This is
|
|
the Pigweed team's suggested approach since it enables precise CMake
|
|
dependency analysis.
|
|
|
|
* Add ``CONFIG_PIGWEED_STATUS=y`` to the Zephyr project's configuration,
|
|
which causes ``pw_status`` to become a global dependency and have the
|
|
includes exposed to all targets. The Pigweed team does not recommend
|
|
this approach, though it is the typical Zephyr solution.
|
|
|
|
Then use the status object or try macros:
|
|
|
|
.. code-block:: cpp
|
|
|
|
#include "pw_status/try.h"
|
|
#include "pw_status/status.h"
|
|
|
|
pw::Status MyOperation() {
|
|
PW_TRY(SubOp1());
|
|
PW_TRY(SubOp2());
|
|
// ...
|
|
return pw::OkStatus();
|
|
}
|
|
|
|
------
|
|
Guides
|
|
------
|
|
|
|
Tracking the first error encountered
|
|
------------------------------------
|
|
In some contexts it is useful to track the first error encountered while
|
|
allowing execution to continue. Manually writing out ``if`` statements to check
|
|
and then assign quickly becomes verbose, and doesn't explicitly highlight the
|
|
intended behavior of "latching" to the first error.
|
|
|
|
.. admonition:: **No**: Track status manually across calls
|
|
:class: error
|
|
|
|
.. code-block:: cpp
|
|
|
|
Status overall_status;
|
|
for (Sector& sector : sectors) {
|
|
Status erase_status = sector.Erase();
|
|
if (!overall_status.ok()) {
|
|
overall_status = erase_status;
|
|
}
|
|
|
|
if (erase_status.ok()) {
|
|
Status header_write_status = sector.WriteHeader();
|
|
if (!overall_status.ok()) {
|
|
overall_status = header_write_status;
|
|
}
|
|
}
|
|
}
|
|
return overall_status;
|
|
|
|
:cpp:class:`pw::Status` has a :cpp:func:`pw::Status::Update()` helper function
|
|
that does exactly this to reduce visual clutter and succinctly highlight the
|
|
intended behavior.
|
|
|
|
.. admonition:: **Yes**: Track status with :cpp:func:`pw::Status::Update()`
|
|
:class: checkmark
|
|
|
|
.. code-block:: cpp
|
|
|
|
Status overall_status;
|
|
for (Sector& sector : sectors) {
|
|
Status erase_status = sector.Erase();
|
|
overall_status.Update(erase_status);
|
|
|
|
if (erase_status.ok()) {
|
|
overall_status.Update(sector.WriteHeader());
|
|
}
|
|
}
|
|
return overall_status;
|
|
|
|
.. _module-pw_status-guide-status-with-size:
|
|
|
|
----------------------------------
|
|
Jointly reporting status with size
|
|
----------------------------------
|
|
``pw::StatusWithSize`` (``pw_status/status_with_size.h``) is a convenient,
|
|
efficient class for reporting a status along with an unsigned integer value.
|
|
It is similar to the ``pw::Result<T>`` class, but it stores both a size and a
|
|
status, regardless of the status value, and only supports a limited range (27
|
|
bits).
|
|
|
|
``pw::StatusWithSize`` values may be created with functions similar to
|
|
``pw::Status``. For example:
|
|
|
|
.. code-block:: cpp
|
|
|
|
#include "pw_status/status_with_size.h"
|
|
|
|
// An OK StatusWithSize with a size of 123.
|
|
StatusWithSize(123)
|
|
|
|
// A NOT_FOUND StatusWithSize with a size of 0.
|
|
StatusWithSize::NotFound()
|
|
|
|
// A RESOURCE_EXHAUSTED StatusWithSize with a size of 10.
|
|
StatusWithSize::ResourceExhausted(10)
|
|
|
|
``pw::StatusWithSize`` is useful for cases where an operation may partially
|
|
complete - for example read operations may read some number of bytes into an
|
|
output buffer, but not all.
|
|
|
|
-----------------------------------
|
|
Reducing error handling boilerplate
|
|
-----------------------------------
|
|
Manual error handling through return codes is easy to understand and
|
|
straightforward to write, but leads to verbose code. To reduce boilerplate,
|
|
Pigweed has the ``PW_TRY`` (``pw_status/try.h``) macro, easing development of
|
|
functions checking or returning ``pw::Status`` and ``pw::StatusWithSize``
|
|
objects. The ``PW_TRY`` and ``PW_TRY_WITH_SIZE`` macros call a function and do
|
|
an early return if the function's return status is not :c:enumerator:`OK`.
|
|
|
|
Example:
|
|
|
|
.. code-block:: cpp
|
|
|
|
Status PwTryExample() {
|
|
PW_TRY(FunctionThatReturnsStatus());
|
|
PW_TRY(FunctionThatReturnsStatusWithSize());
|
|
|
|
// Do something, only executed if both functions above return OK.
|
|
}
|
|
|
|
StatusWithSize PwTryWithSizeExample() {
|
|
PW_TRY_WITH_SIZE(FunctionThatReturnsStatus());
|
|
PW_TRY_WITH_SIZE(FunctionThatReturnsStatusWithSize());
|
|
|
|
// Do something, only executed if both functions above return OK.
|
|
}
|
|
|
|
``PW_TRY_ASSIGN`` is for working with ``pw::StatusWithSize`` objects in in
|
|
functions that return Status. It is similar to ``PW_TRY`` with the addition of
|
|
assigning the size from the ``pw::StatusWithSize`` on ok.
|
|
|
|
.. code-block:: cpp
|
|
|
|
Status PwTryAssignExample() {
|
|
size_t size_value
|
|
PW_TRY_ASSIGN(size_value, FunctionThatReturnsStatusWithSize());
|
|
|
|
// Do something that uses size_value. size_value is only assigned and this
|
|
// following code executed if the PW_TRY_ASSIGN function above returns OK.
|
|
}
|