diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3experimental/l3benchmark/l3benchmark.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3experimental/l3benchmark/l3benchmark.dtx | 583 |
1 files changed, 583 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/l3experimental/l3benchmark/l3benchmark.dtx b/Master/texmf-dist/source/latex/l3experimental/l3benchmark/l3benchmark.dtx new file mode 100644 index 00000000000..b8e976677da --- /dev/null +++ b/Master/texmf-dist/source/latex/l3experimental/l3benchmark/l3benchmark.dtx @@ -0,0 +1,583 @@ +% \iffalse meta-comment +% +%% File: l3benchmark.dtx Copyright (C) 2011,2012,2014-2018 The LaTeX3 Project +% +% It may be distributed and/or modified under the conditions of the +% LaTeX Project Public License (LPPL), either version 1.3c of this +% license or (at your option) any later version. The latest version +% of this license is in the file +% +% http://www.latex-project.org/lppl.txt +% +% This file is part of the "l3experimental bundle" (The Work in LPPL) +% and all files in that bundle must be distributed together. +% +% ----------------------------------------------------------------------- +% +% The development version of the bundle can be found at +% +% https://github.com/latex3/latex3 +% +% for those people who are interested. +% +%<*driver|package> +\RequirePackage{expl3} +%</driver|package> +%<*driver> +\documentclass[full]{l3doc} +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +%</driver> +% \fi +% +% \title{^^A +% The \pkg{l3benchmark} package\\ Experimental benchmarking^^A +% } +% +% \author{^^A +% The \LaTeX3 Project\thanks +% {^^A +% E-mail: +% \href{mailto:latex-team@latex-project.org} +% {latex-team@latex-project.org}^^A +% }^^A +% } +% +% \date{Released 2018-10-26} +% +% \maketitle +% +% \begin{documentation} +% +% \section{Additions to \pkg{l3sys}: elapsed time} +% +% \begin{function}{\sys_gzero_timer:} +% \begin{syntax} +% \cs{sys_gzero_timer:} +% \end{syntax} +% Resets the timer to zero. +% \end{function} +% +% \begin{function}[EXP]{\sys_timer:} +% \begin{syntax} +% \cs{sys_timer:} +% \end{syntax} +% Expands to the current value of the engine's timer clock, a +% non-negative integer. In engines without clock support this +% expands to $0$. +% \end{function} +% +% \section{Benchmark} +% +% \begin{variable}{\g_benchmark_duration_target_fp} +% This variable controls roughly for how long \cs{benchmark:n} will +% repeat code to more accurately benchmark it. The actual duration of +% one call to \cs{benchmark:n} typically lasts between half and twice +% \cs{g_benchmark_duration_target_fp} seconds, unless of course +% running the code only once already lasts longer than this. +% \end{variable} +% +% \begin{variable}{\g_benchmark_time_fp, \g_benchmark_ops_fp} +% Functions such as \cs{benchmark:n} store the measured time in +% \cs{g_benchmark_time_fp} (in seconds). Functions such as +% \cs{benchmark_normalized:n} store the estimated number of operations +% in \cs{g_benchmark_ops_fp}. +% \end{variable} +% +% \begin{function}{\benchmark_display:, \benchmark_display_in_ops:} +% \begin{syntax} +% \cs{benchmark_display:} +% \end{syntax} +% Prints the time \cs{g_benchmark_time_fp} (in seconds) or the +% estimated number of operations \cs{g_benchmark_ops_fp} to the +% terminal. These functions are called by functions such as +% \cs{benchmark:n} and can be redefined by the user. +% \end{function} +% +% \begin{function}{\benchmark_once:n, \benchmark_once_in_ops:n, \benchmark_once_silent:n} +% \begin{syntax} +% \cs{benchmark_once:n} \Arg{code} +% \end{syntax} +% Measures the time taken by \TeX{} to run the \meta{code} once, sets +% \cs{g_benchmark_time_fp} and \cs{g_benchmark_ops_fp}, and calls +% \cs{benchmark_display:}. The \meta{code} is run only once so the +% time may be quite inaccurate for fast code. The +% \cs{benchmark_once_silent:n} function omits the call to +% \cs{benchmark_display:}, while \cs{benchmark_once_in_ops:n} calls +% \cs{benchmark_display_in_ops:} instead. +% \end{function} +% +% \begin{function}{\benchmark:n, \benchmark_in_ops:n, \benchmark_silent:n} +% \begin{syntax} +% \cs{benchmark:n} \Arg{code} +% \end{syntax} +% Measures the time taken by \TeX{} to run the \meta{code}, sets +% \cs{g_benchmark_time_fp} and \cs{g_benchmark_ops_fp}, and calls +% \cs{benchmark_display:}. The \meta{code} may be run many times and +% not within a group, thus code with side-effects may cause problems. +% The \cs{benchmark_silent:n} function omits the call to +% \cs{benchmark_display:}, while \cs{benchmark_in_ops:n} calls +% \cs{benchmark_display_in_ops:} instead. +% \end{function} +% +% \begin{function}{\benchmark_tic:, \benchmark_toc:} +% \begin{syntax} +% \cs{benchmark_tic:} \meta{slow code} \cs{benchmark_toc:} +% \end{syntax} +% When it is not possible to run \cs{benchmark:n} (e.g., the code is +% part of the execution of a package which cannot be looped) the +% tic/toc commands can be used instead to time between two points in +% the code. When executed, \cs{benchmark_tic:} will print a line to the +% terminal, and \cs{benchmark_toc:} will print a matching line with a +% time to indicate the duration between them in seconds. Note that +% these commands can be nested. +% \end{function} +% +% \end{documentation} +% +% \begin{implementation} +% +% \section{\pkg{l3benchmark} implementation} +% +% Our working unit is the scaled second, namely $2^{-16}$ seconds. +% +% \begin{macrocode} +%<*initex|package> +% \end{macrocode} +% +% \begin{macrocode} +%<*package> +\ProvidesExplPackage{l3benchmark}{2018-10-26}{} + {L3 Experimental benchmarking} +%</package> +% \end{macrocode} +% +% \subsection{Additions to \pkg{l3sys}: elapsed time} +% +% \begin{macrocode} +%<@@=sys> +% \end{macrocode} +% +% \begin{macro}[EXP]{\sys_timer:} +% \begin{macro}[EXP,pTF]{\sys_if_timer_exist:} +% In \LuaTeX{}, use emulation (see \pkg{l3luatex}), +% otherwise try to locate the primitive. The +% elapsed time will be available if this succeeds or if unrestricted +% shell escape is available. +% \begin{macrocode} +\sys_if_engine_luatex:TF + { + \cs_new:Npn \sys_timer: + { \int_eval:w \lua_now:n { l3kernel.elapsedtime() } \scan_stop: } + } + { + \cs_if_exist:NT \tex_elapsedtime:D + { + \cs_new:Npn \sys_timer: + { \int_eval:w \tex_elapsedtime:D } + } + } +\@@_const:nn { sys_if_timer_exist } + { \cs_if_exist_p:N \sys_timer: } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\sys_gzero_timer:, \@@_timer_fp:} +% \begin{variable}{\g_@@_timer_base_fp} +% Three case, and in each case we define \cs{sys_gzero_timer:}. +% \begin{macrocode} +\cs_if_exist:NTF \sys_timer: + { + \sys_if_engine_luatex:TF + { + \cs_new_protected:Npn \sys_gzero_timer: + { \lua_now:n { l3kernel.resettimer() } } + } + { \cs_new_protected:Npn \sys_gzero_timer: { \tex_resettimer:D } } + } +% \end{macrocode} +% If the elapsed time cannot be accessed then we define user +% commands to produce errors. +% \begin{macrocode} + { + \__kernel_msg_new:nnnn { kernel } { no-elapsed-time } + { No~clock~detected~for~#1. } + { The~current~engine~provides~no~way~to~access~the~system~time. } + \cs_new_protected:Npn \sys_gzero_timer: + { + \__kernel_msg_error:nnn { kernel } { no-elapsed-time } + { \sys_gzero_timer: } + } + \cs_new:Npn \sys_timer: + { + \int_value:w + \__kernel_msg_expandable_error:nnn { kernel } { no-elapsed-time } + { \sys_timer: } + \c_zero_int + } + } +% \end{macrocode} +% \end{variable} +% \end{macro} +% +% \subsection{Benchmarking code} +% +% \begin{macrocode} +%<@@=benchmark> +% \end{macrocode} +% +% \begin{variable}{\g_benchmark_time_fp, \g_benchmark_ops_fp} +% Functions such as \cs{benchmark:n} store the measured time in +% \cs{g_benchmark_time_fp} (in seconds) and the estimated number of +% operations in \cs{g_benchmark_ops_fp}. +% \begin{macrocode} +\fp_new:N \g_benchmark_time_fp +\fp_new:N \g_benchmark_ops_fp +% \end{macrocode} +% \end{variable} +% +% \begin{macro}{\benchmark_display:, \benchmark_display_in_ops:} +% Function to display the time that was measured or the estimated +% number of operations. This can be redefined by the user. +% \begin{macrocode} +\cs_new_protected:Npn \benchmark_display: + { \iow_term:x { \fp_to_tl:N \g_benchmark_time_fp \c_space_tl seconds } } +\cs_new_protected:Npn \benchmark_display_in_ops: + { + \iow_term:x + { + \fp_compare:nTF { \g_benchmark_ops_fp > 1e9 } + { \fp_to_tl:n { \g_benchmark_ops_fp * 1e-9 } ~ G~ops } + { + \fp_compare:nTF { \g_benchmark_ops_fp > 1e6 } + { \fp_to_tl:n { \g_benchmark_ops_fp * 1e-6 } ~ M~ops } + { + \fp_compare:nTF { \g_benchmark_ops_fp > 1e3 } + { \fp_to_tl:n { \g_benchmark_ops_fp * 1e-3 } ~ K~ops } + { \fp_to_tl:n { \g_benchmark_ops_fp } ~ ops } + } + } + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +\sys_if_timer_exist:F + { + \msg_new:nnnn { benchmark } { no-time } + { The~l3benchmark~package~failed~to~access~a~clock. } + { The~current~engine~provides~no~way~to~access~the~system~time. } + \cs_new_protected:Npn \benchmark_once:n #1 + { \msg_error:nn { benchmark } { no-time } } + \cs_new_protected:Npn \benchmark_once_in_ops:n #1 + { \msg_error:nn { benchmark } { no-time } } + \cs_new_protected:Npn \benchmark_once_silent:n #1 + { \msg_error:nn { benchmark } { no-time } } + \cs_new_protected:Npn \benchmark:n #1 + { \msg_error:nn { benchmark } { no-time } } + \cs_new_protected:Npn \benchmark_in_ops:n #1 + { \msg_error:nn { benchmark } { no-time } } + \cs_new_protected:Npn \benchmark_silent:n #1 + { \msg_error:nn { benchmark } { no-time } } + \fp_gset:Nn \g_benchmark_time_fp { nan } + \fp_gset:Nn \g_benchmark_ops_fp { nan } + \msg_critical:nn { benchmark } { no-time } + } +% \end{macrocode} +% +% \begin{variable}{\g_benchmark_duration_target_fp, \g_@@_duration_int} +% The benchmark is constrained to take roughly (from half to twice) +% \cs{g_benchmark_duration_target_fp} seconds, more precisely +% \cs{g_@@_duration_int} scaled seconds, unless one iteration of the +% code takes longer. +% \begin{macrocode} +\fp_new:N \g_benchmark_duration_target_fp +\fp_gset:Nn \g_benchmark_duration_target_fp { 1 } +\int_new:N \g_@@_duration_int +% \end{macrocode} +% \end{variable} +% +% \begin{variable}{\g_@@_time_int, \g_@@_time_a_int, \g_@@_time_b_int, \g_@@_time_c_int, \g_@@_time_d_int} +% These variables hold the time for running a piece of code, as an +% integer in scaled seconds. +% \begin{macrocode} +\int_new:N \g_@@_time_int +\int_new:N \g_@@_time_a_int +\int_new:N \g_@@_time_b_int +\int_new:N \g_@@_time_c_int +\int_new:N \g_@@_time_d_int +% \end{macrocode} +% \end{variable} +% +% \begin{variable}{\g_@@_repeat_int} +% Holds the number of times that the piece of code was +% repeated when timing. +% \begin{macrocode} +\int_new:N \g_@@_repeat_int +% \end{macrocode} +% \end{variable} +% +% \begin{variable}{\g_@@_nesting_int} +% \begin{macro}{\@@_raw:nN, \@@_raw_aux:N, \@@_raw_end:N} +% Store in the given integer variable the time it took to perform a given +% piece of code, in scaled seconds. We call \cs{sys_timer:} as +% close before and after the code as possible. We store the +% intermediate result in a new integer when \cs{@@_raw:nN} is +% nested. +% \begin{macrocode} +\int_new:N \g_@@_nesting_int +\cs_new_protected:Npn \@@_raw:nN #1 + { + \int_gincr:N \g_@@_nesting_int + \exp_args:Nc \@@_raw_aux:N + { g_@@_ \int_use:N \g_@@_nesting_int _int } + \@@_raw_aux: + #1 + \@@_raw_end:N + } +\cs_new_protected:Npn \@@_raw_aux:N #1 + { + \int_gzero_new:N #1 + \cs_gset_protected:Npn \@@_raw_aux: { \int_gset:Nn #1 { \sys_timer: } } + } +\cs_new_protected:Npn \@@_raw_end:N #1 + { + \int_gset:Nn #1 + { + \sys_timer: - + \int_use:c { g_@@_ \int_use:N \g_@@_nesting_int _int } + } + \int_gdecr:N \g_@@_nesting_int + } +% \end{macrocode} +% \end{macro} +% \end{variable} +% +% \begin{macro}{\@@_raw_replicate:nnN, \@@_tmp:w} +% Here, we wish to measure the time it takes for the piece of code +% |#2| to be run |#1| times, and store the result in the +% integer~|#3|. +% +% If the number of copies required is large, defining \cs{@@_tmp:w} +% would exhaust \TeX{}'s main memory. In that case, we replicate +% $|#1|/5000$ times the given code before passing it to the main call +% to \cs{@@_tmp:w}. Of course the division rounds to an integer, so +% that step introduces a relative error of order at most +% $5000/500000$, less than many other sources of variability. +% +% We subtract the time for another call to \cs{@@_tmp:w}, with the +% same arguments (to capture the time it takes to read the argument) +% but empty expansion. +% \begin{macrocode} +\cs_new_eq:NN \@@_tmp:w ? +\cs_new_protected:Npn \@@_raw_replicate:nnN #1 + { + \int_compare:nNnTF {#1} > { 500000 } + { \@@_raw_replicate_large:nnN {#1} } + { \@@_raw_replicate_small:nnN {#1} } + } +\cs_new_protected:Npn \@@_raw_replicate_large:nnN #1#2 + { + \cs_set:Npx \@@_tmp:w ##1 { \prg_replicate:nn { 5000 } {##1} } + \exp_args:Nno \@@_raw_replicate:nnN { #1 / 5000 } + { \@@_tmp:w {#2} } + } +\cs_new_protected:Npn \@@_raw_replicate_small:nnN #1#2 + { + \cs_set:Npx \@@_tmp:w ##1##2 { \prg_replicate:nn {#1} {##1} } + \@@_raw:nN { \@@_tmp:w {#2} { } } \g_@@_time_int + \exp_args:No \@@_raw_replicate_aux:nnN + { \int_use:N \g_@@_time_int } {#2} + } +\cs_new_protected:Npn \@@_raw_replicate_aux:nnN #1#2#3 + { + \@@_raw:nN { \@@_tmp:w { } {#2} } \g_@@_time_int + \int_gset:Nn #3 { #1 - \g_@@_time_int } + \cs_set_eq:NN \@@_tmp:w \prg_do_nothing: + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\benchmark:n, \benchmark_silent:n} +% The main timing function. First time the user code once. If that +% took more than a third of a second we're done. If that took much +% less than a second, quadruple the number of copies until it takes a +% reasonable amount of time (this is to avoid division by a possibly +% zero time). Once we reach a reasonable time, compute a number of +% times that can fit in one quarter of a second and measure that four +% times. To save time we reuse the result of the first pass if +% \cs{g_@@_repeat_int} is one. Once we have four results, find the smallest, +% divided by $65536$ and by the number of repetitions, and display that. +% \begin{macrocode} +\fp_new:N \g_@@_one_op_fp +\tl_new:N \g_@@_code_tl +\cs_new_protected:Npn \benchmark:n #1 + { \benchmark_silent:n {#1} \benchmark_display: } +\cs_new_protected:Npn \benchmark_in_ops:n #1 + { \benchmark_silent:n {#1} \benchmark_display_in_ops: } +\cs_new_protected:Npn \@@_measure_op: + { + \int_gset:Nn \g_@@_duration_int { 256 } + \tl_gset:Nn \g_@@_code_tl + { \int_gset:Nn \g_@@_duration_int { 256 } } % arbitrary single operation + \@@_aux: + \fp_gset_eq:NN \g_@@_one_op_fp \g_benchmark_time_fp + \fp_compare:nNnT \g_@@_one_op_fp < { 1e-6 } + { \fp_gset:Nn \g_@@_one_op_fp { 1e-6 } } + } +\cs_new_protected:Npn \benchmark_silent:n #1 + { + \@@_measure_op: + \int_gset:Nn \g_@@_duration_int + { \fp_to_int:n { 65536 * \g_benchmark_duration_target_fp } } + \tl_gset:Nn \g_@@_code_tl {#1} + \@@_aux: + \fp_gset:Nn \g_benchmark_ops_fp + { \g_benchmark_time_fp / \g_@@_one_op_fp } + } +\cs_new_protected:Npn \@@_aux: + { + \int_gset:Nn \g_@@_repeat_int { 1 } + \@@_raw:nN { \g_@@_code_tl } \g_@@_time_int + \int_compare:nNnF \g_@@_time_int < { \g_@@_duration_int / 2 } + { + \int_gset_eq:NN \g_@@_time_a_int \g_@@_time_int + \int_gset_eq:NN \g_@@_time_b_int \g_@@_time_int + \int_gset_eq:NN \g_@@_time_c_int \g_@@_time_int + \int_gset_eq:NN \g_@@_time_d_int \g_@@_time_int + \prg_break: + } + \int_while_do:nNnn \g_@@_time_int < { \g_@@_duration_int / 100 } + { + \int_compare:nNnT \g_@@_repeat_int > { \c_max_int / 4 } + { + \int_gzero:N \g_@@_time_a_int + \int_gzero:N \g_@@_time_b_int + \int_gzero:N \g_@@_time_c_int + \int_gzero:N \g_@@_time_d_int + \prg_break: + } + \int_gset:Nn \g_@@_repeat_int { 4 * \g_@@_repeat_int } + \@@_run:N \g_@@_time_int + } + \int_gset:Nn \g_@@_repeat_int + { + \int_max:nn { 1 } + { + \g_@@_duration_int * \g_@@_repeat_int + / ( \g_@@_time_int * 4 ) + } + } + \int_compare:nNnTF \g_@@_repeat_int = 1 + { \int_gset_eq:NN \g_@@_time_a_int \g_@@_time_int } + { \@@_run:N \g_@@_time_a_int } + \@@_run:N \g_@@_time_b_int + \@@_run:N \g_@@_time_c_int + \@@_run:N \g_@@_time_d_int + \prg_break_point: + \fp_gset:Nn \g_benchmark_time_fp + { + \int_min:nn + { \int_min:nn \g_@@_time_a_int \g_@@_time_b_int } + { \int_min:nn \g_@@_time_c_int \g_@@_time_d_int } + / \g_@@_repeat_int / 65536 + } + } +\cs_new_protected:Npn \@@_run:N + { \exp_args:NNo \@@_raw_replicate:nnN \g_@@_repeat_int { \g_@@_code_tl } } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\benchmark_once:n, \benchmark_once_in_ops:n, \benchmark_once_silent:n} +% Convert from scaled seconds to seconds. +% \begin{macrocode} +\cs_new_protected:Npn \benchmark_once:n #1 + { \benchmark_once_silent:n {#1} \benchmark_display: } +\cs_new_protected:Npn \benchmark_once_in_ops:n #1 + { \benchmark_once_silent:n {#1} \benchmark_display_in_ops: } +\cs_new_protected:Npn \benchmark_once_silent:n #1 + { + \@@_measure_op: + \@@_raw:nN {#1} \g_@@_time_int + \fp_gset:Nn \g_benchmark_time_fp { \g_@@_time_int / 65536 } + \fp_gset:Nn \g_benchmark_ops_fp + { \g_benchmark_time_fp / \g_@@_one_op_fp } + } +% \end{macrocode} +% \end{macro} +% +% \subsection{Benchmark tic toc} +% +% \begin{variable}{\g_@@_tictoc_int, \g_@@_tictoc_seq} +% \begin{macrocode} +\int_new:N \g_@@_tictoc_int +\seq_new:N \g_@@_tictoc_seq +% \end{macrocode} +% \end{variable} +% +% \begin{macro}{\benchmark_tic:, \@@_tic:} +% \begin{macrocode} +\cs_new_protected:Npn \benchmark_tic: + { + \int_compare:nTF { \g_@@_tictoc_int == 0 } + { + \sys_gzero_timer: + \@@_tic:n { 0 } + } + { \@@_tic: } + } +\cs_new_protected:Npn \@@_tic: + { + \exp_args:NNf \seq_put_right:Nn \g_@@_tictoc_seq { \sys_timer: } + \int_gincr:N \g_@@_tictoc_int + \iow_term:x + { + \prg_replicate:nn {\g_@@_tictoc_int} {---+} \space + TIC + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\benchmark_toc:, \@@_toc:} +% \begin{macrocode} +\cs_new:Npn \benchmark_toc: + { + \int_compare:nT { \g_@@_tictoc_int == 0 } + { \msg_error:nn {benchmark} {toc-first} } + \seq_pop_right:NN \g_@@_tictoc_seq \l_@@_tictoc_pop_tl + \@@_toc: + } +\cs_new_protected:Npn \@@_toc: + { + \tl_set:Nx \l_@@_tictoc_tl + { + \fp_to_decimal:n + { round( ( \sys_timer: - \l_@@_tictoc_pop_tl) / 65536 , 3 ) } + } + \iow_term:x + { + \prg_replicate:nn {\g_@@_tictoc_int} {---+} \c_space_tl + TOC: \c_space_tl + \l_@@_tictoc_tl \c_space_tl s + } + \int_gdecr:N \g_@@_tictoc_int + } +\msg_new:nnn {benchmark} {toc-first} + { + \token_to_str:N \benchmark_toc: \space without~ + \token_to_str:N \benchmark_tic: \space ! + } +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +%</initex|package> +% \end{macrocode} +% +% \end{implementation} +% +% \PrintIndex |