Inside Bitcoin

751
752    /**
753     * @brief Sets the operation unit.
754     *
755     * Defaults to "op". Could be e.g. "byte" for string processing. This is used for the table header, e.g. to show `ns/byte`. Use
756     * singular (*byte*, not *bytes*). A change clears the currently collected results.
757     *
758     * @param unit The unit name.
759     */
760    Bench& unit(char const* unit);
761    Bench& unit(std::string const& unit);
762    ANKERL_NANOBENCH(NODISCARD) std::string const& unit() const noexcept;
763
764    /**
765     * @brief Sets the time unit to be used for the default output.
766     *
767     * Nanobench defaults to using ns (nanoseconds) as output in the markdown. For some benchmarks this is too coarse, so it is
768     * possible to configure this. E.g. use `timeUnit(1ms, "ms")` to show `ms/op` instead of `ns/op`.
769     *
770     * @param tu Time unit to display the results in, default is 1ns.
771     * @param tuName Name for the time unit, default is "ns"
772     */
773    Bench& timeUnit(std::chrono::duration<double> const& tu, std::string const& tuName);
774    ANKERL_NANOBENCH(NODISCARD) std::string const& timeUnitName() const noexcept;
775    ANKERL_NANOBENCH(NODISCARD) std::chrono::duration<double> const& timeUnit() const noexcept;
776
777    /**
778     * @brief Set the output stream where the resulting markdown table will be printed to.
779     *
780     * The default is `&std::cout`. You can disable all output by setting `nullptr`.
781     *
782     * @param outstream Pointer to output stream, can be `nullptr`.
783     */
784    Bench& output(std::ostream* outstream) noexcept;
785    ANKERL_NANOBENCH(NODISCARD) std::ostream* output() const noexcept;
786
787    /**
788     * Modern processors have a very accurate clock, being able to measure as low as 20 nanoseconds. This is the main trick nanobech to
789     * be so fast: we find out how accurate the clock is, then run the benchmark only so often that the clock's accuracy is good enough
790     * for accurate measurements.
791     *
792     * The default is to run one epoch for 1000 times the clock resolution. So for 20ns resolution and 11 epochs, this gives a total
793     * runtime of
794     *
795     * @f[
796     * 20ns * 1000 * 11 \approx 0.2ms
797     * @f]
798     *
799     * To be precise, nanobench adds a 0-20% random noise to each evaluation. This is to prevent any aliasing effects, and further
800     * improves accuracy.
801     *
802     * Total runtime will be higher though: Some initial time is needed to find out the target number of iterations for each epoch, and
803     * there is some overhead involved to start & stop timers and calculate resulting statistics and writing the output.
804     *
805     * @param multiple Target number of times of clock resolution. Usually 1000 is a good compromise between runtime and accuracy.
806     */
807    Bench& clockResolutionMultiple(size_t multiple) noexcept;
808    ANKERL_NANOBENCH(NODISCARD) size_t clockResolutionMultiple() const noexcept;
809
810    /**
811     * @brief Controls number of epochs, the number of measurements to perform.
812     *
813     * The reported result will be the median of evaluation of each epoch. The higher you choose this, the more
814     * deterministic the result be and outliers will be more easily removed. Also the `err%` will be more accurate the higher this
815     * number is. Note that the `err%` will not necessarily decrease when number of epochs is increased. But it will be a more accurate
816     * representation of the benchmarked code's runtime stability.
817     *
818     * Choose the value wisely. In practice, 11 has been shown to be a reasonable choice between runtime performance and accuracy.
819     * This setting goes hand in hand with minEpochIterations() (or minEpochTime()). If you are more interested in *median* runtime,
820     * you might want to increase epochs(). If you are more interested in *mean* runtime, you might want to increase
821     * minEpochIterations() instead.
822     *
823     * @param numEpochs Number of epochs.
824     */
825    Bench& epochs(size_t numEpochs) noexcept;
826    ANKERL_NANOBENCH(NODISCARD) size_t epochs() const noexcept;
827
828    /**
829     * @brief Upper limit for the runtime of each epoch.
830     *
831     * As a safety precaution if the clock is not very accurate, we can set an upper limit for the maximum evaluation time per
832     * epoch. Default is 100ms. At least a single evaluation of the benchmark is performed.
833     *
834     * @see minEpochTime, minEpochIterations
835     *
836     * @param t Maximum target runtime for a single epoch.
837     */
838    Bench& maxEpochTime(std::chrono::nanoseconds t) noexcept;
839    ANKERL_NANOBENCH(NODISCARD) std::chrono::nanoseconds maxEpochTime() const noexcept;
840
841    /**
842     * @brief Minimum time each epoch should take.
843     *
844     * Default is 1ms, so we are mostly relying on clockResolutionMultiple(). In most cases this is exactly what you want. If you see
845     * that the evaluation is unreliable with a high `err%`, you can increase either minEpochTime() or minEpochIterations().
846     *
847     * @see maxEpochTime, minEpochIterations
848     *
849     * @param t Minimum time each epoch should take.
850     */
851    Bench& minEpochTime(std::chrono::nanoseconds t) noexcept;
852    ANKERL_NANOBENCH(NODISCARD) std::chrono::nanoseconds minEpochTime() const noexcept;
853
854    /**
855     * @brief Sets the minimum number of iterations each epoch should take.
856     *
857     * Default is 1, and we rely on clockResolutionMultiple(). If the `err%` is high and you want a more smooth result, you might want
858     * to increase the minimum number of iterations, or increase the minEpochTime().
859     *
860     * @see minEpochTime, maxEpochTime, minEpochIterations
861     *
862     * @param numIters Minimum number of iterations per epoch.
863     */
864    Bench& minEpochIterations(uint64_t numIters) noexcept;
865    ANKERL_NANOBENCH(NODISCARD) uint64_t minEpochIterations() const noexcept;
866
867    /**
868     * Sets exactly the number of iterations for each epoch. Ignores all other epoch limits. This forces nanobench to use exactly
869     * the given number of iterations for each epoch, not more and not less. Default is 0 (disabled).
870     *
871     * @param numIters Exact number of iterations to use. Set to 0 to disable.
872     */
873    Bench& epochIterations(uint64_t numIters) noexcept;
874    ANKERL_NANOBENCH(NODISCARD) uint64_t epochIterations() const noexcept;
875
876    /**
877     * @brief Sets a number of iterations that are initially performed without any measurements.
878     *
879     * Some benchmarks need a few evaluations to warm up caches / database / whatever access. Normally this should not be needed, since
880     * we show the median result so initial outliers will be filtered away automatically. If the warmup effect is large though, you
881     * might want to set it. Default is 0.
882     *
883     * @param numWarmupIters Number of warmup iterations.
884     */
885    Bench& warmup(uint64_t numWarmupIters) noexcept;
886    ANKERL_NANOBENCH(NODISCARD) uint64_t warmup() const noexcept;
887
888    /**
889     * @brief Marks the next run as the baseline.
890     *
891     * Call `relative(true)` to mark the run as the baseline. Successive runs will be compared to this run. It is calculated by
892     *
893     * @f[
894     * 100\% * \frac{baseline}{runtime}
895     * @f]
896     *
897     *  * 100% means it is exactly as fast as the baseline
898     *  * >100% means it is faster than the baseline. E.g. 200% means the current run is twice as fast as the baseline.
899     *  * <100% means it is slower than the baseline. E.g. 50% means it is twice as slow as the baseline.
900     *
901     * See the tutorial section "Comparing Results" for example usage.
902     *
903     * @param isRelativeEnabled True to enable processing
904     */
905    Bench& relative(bool isRelativeEnabled) noexcept;
906    ANKERL_NANOBENCH(NODISCARD) bool relative() const noexcept;
907
908    /**
909     * @brief Enables/disables performance counters.
910     *
911     * On Linux nanobench has a powerful feature to use performance counters. This enables counting of retired instructions, count
912     * number of branches, missed branches, etc. On default this is enabled, but you can disable it if you don't need that feature.
913     *
914     * @param showPerformanceCounters True to enable, false to disable.
915     */
916    Bench& performanceCounters(bool showPerformanceCounters) noexcept;
917    ANKERL_NANOBENCH(NODISCARD) bool performanceCounters() const noexcept;
918
919    /**
920     * @brief Retrieves all benchmark results collected by the bench object so far.
921     *
922     * Each call to run() generates a Result that is stored within the Bench instance. This is mostly for advanced users who want to
923     * see all the nitty gritty details.
924     *
925     * @return All results collected so far.
926     */
927    ANKERL_NANOBENCH(NODISCARD) std::vector<Result> const& results() const noexcept;
928
929    /*!
930      @verbatim embed:rst
931
932      Convenience shortcut to :cpp:func:`ankerl::nanobench::doNotOptimizeAway`.
933
934      @endverbatim
935     */
936    template <typename Arg>
937    Bench& doNotOptimizeAway(Arg&& arg);
938
939    /*!
940      @verbatim embed:rst
941
942      Sets N for asymptotic complexity calculation, so it becomes possible to calculate `Big O
943      <https://en.wikipedia.org/wiki/Big_O_notation>`_ from multiple benchmark evaluations.
944
945      Use :cpp:func:`ankerl::nanobench::Bench::complexityBigO` when the evaluation has finished. See the tutorial
946      :ref:`asymptotic-complexity` for details.
947
948      @endverbatim
949
950      @tparam T Any type is cast to `double`.
951      @param n Length of N for the next benchmark run, so it is possible to calculate `bigO`.
952     */
953    template <typename T>
954    Bench& complexityN(T n) noexcept;
955    ANKERL_NANOBENCH(NODISCARD) double complexityN() const noexcept;
956
957    /*!
958      Calculates [Big O](https://en.wikipedia.org/wiki/Big_O_notation>) of the results with all preconfigured complexity functions.
959      Currently these complexity functions are fitted into the benchmark results:
960
961       @f$ \mathcal{O}(1) @f$,
962       @f$ \mathcal{O}(n) @f$,
963       @f$ \mathcal{O}(\log{}n) @f$,
964       @f$ \mathcal{O}(n\log{}n) @f$,
965       @f$ \mathcal{O}(n^2) @f$,
966       @f$ \mathcal{O}(n^3) @f$.
967
968      If we e.g. evaluate the complexity of `std::sort`, this is the result of `std::cout << bench.complexityBigO()`:
969
970      ```
971      |   coefficient |   err% | complexity
972      |--------------:|-------:|------------
973      |   5.08935e-09 |   2.6% | O(n log n)
974      |   6.10608e-08 |   8.0% | O(n)
975      |   1.29307e-11 |  47.2% | O(n^2)
976      |   2.48677e-15 |  69.6% | O(n^3)
977      |   9.88133e-06 | 132.3% | O(log n)
978      |   5.98793e-05 | 162.5% | O(1)
979      ```
980
981      So in this case @f$ \mathcal{O}(n\log{}n) @f$ provides the best approximation.
982
983      @verbatim embed:rst
984      See the tutorial :ref:`asymptotic-complexity` for details.
985      @endverbatim
986      @return Evaluation results, which can be printed or otherwise inspected.
987     */
988    std::vector<BigO> complexityBigO() const;
989
990    /**
991     * @brief Calculates bigO for a custom function.
992     *
993     * E.g. to calculate the mean squared error for @f$ \mathcal{O}(\log{}\log{}n) @f$, which is not part of the default set of
994     * complexityBigO(), you can do this:
995     *
996     * ```
997     * auto logLogN = bench.complexityBigO("O(log log n)", [](double n) {
998     *     return std::log2(std::log2(n));
999     * });
1000     * ```