| .. _module-pw_perf_test: |
| |
| ============ |
| pw_perf_test |
| ============ |
| Pigweed's perf test module provides an easy way to measure performance on |
| any test setup. By using an API similar to GoogleTest, this module aims to bring |
| a robust and intuitive testing framework to our users. |
| |
| .. note:: |
| This module is still under construction. Some features may not be available |
| yet. |
| |
| --------- |
| Timer API |
| --------- |
| In order to provide meaningful performance timings for given functions, events, |
| etc a timing interface must be implemented from scratch to be able to provide |
| for the testing needs. The timing API meets these needs by implementing either |
| clock cycle record keeping or second based recordings. |
| |
| Time-Based Measurement |
| ====================== |
| In order to achieve time-based measurements, pw_perf_test depends on |
| :ref:`module-pw_chrono` its timing needs. At the moment, the interface will |
| only measure performance in terms of nanoseconds. To see more information about |
| how pw_chrono works, see the module documentation. |
| |
| ----- |
| State |
| ----- |
| Within the testing framework, the state object is responsible for calling the |
| timing interface and keeping track of testing iterations. It contains only two |
| publicly accessible functions, since the object is intended for internal use |
| only. ``The SetIterations()`` function ensures that the user can specify the |
| amount of iterations if the default behavior is not satisfactory, while the |
| ``KeepRunning()`` function collects timestamps for when parts of the code are |
| executed and ensures that only a certain number of iterations are run. |
| |
| .. code-block:: cpp |
| |
| void TestFunction(::pw::perf_test::State& state){ |
| state.SetIterations(10); |
| while(state_obj.KeepRunning()){ |
| // code to measure here |
| } |
| } |
| PW_PERF_TEST(VariableIterationTest, TestFunction); |
| |
| |