From 9204b86bf5927e9ff420fd8b05e0a89ccd84102b Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 5 Jan 2022 15:22:12 +0100 Subject: [PATCH 01/11] doc: delete unsatisfied forward reference to anti-replay counter --- docs/introduction/howtouse.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index 243589aae322..5c96205e6d7b 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -441,8 +441,7 @@ In the rare case when an operation is lost, how can we be sure that it will not be included in any future block, and then we may re-emit it? After 60 blocks a transaction is considered invalid and can't be included anymore in a block. -Furthermore each operation has a counter (explained in more detail -later) that prevents replays so it is usually safe to re-emit an +Furthermore each operation has a counter that prevents replays so it is usually safe to re-emit an operation that seems lost. -- GitLab From b13eaded86346f86153077e5f2b9a5ed01bd8895 Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Wed, 5 Jan 2022 15:55:00 +0100 Subject: [PATCH 02/11] doc: typos in error_monad.rst --- docs/developer/error_monad.rst | 36 +++++++++++++++++----------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/developer/error_monad.rst b/docs/developer/error_monad.rst index 868b991c70c2..d45a77eb8d51 100644 --- a/docs/developer/error_monad.rst +++ b/docs/developer/error_monad.rst @@ -261,7 +261,7 @@ are the same (``'e``): val ( let* ) : ('a, 'e) result -> ('a -> ('b, 'e) result) -> ('b, 'e) result When you need to mix those function, you have to either handle the -errors of each idependently (see the section above about recovering from +errors of each independently (see the section above about recovering from errors) or you need to convert the errors so they have the same type. You should use ``Result.map_error`` to do that. @@ -768,7 +768,7 @@ dedicated to binding Result-only expressions. .. sidebar:: Mnemonic The ``let*?`` binding operator uses the question mark (``?``) to represent - the uncertainty of the ``result``. Is it a sucess? Is it a failure? + the uncertainty of the ``result``. Is it a success? Is it a failure? From Lwt-only into Lwt-``result`` @@ -786,10 +786,10 @@ dedicated to binding Lwt-only expressions. .. sidebar:: Mnemonic The ``let*!`` binding operator uses the exclamation mark (``!``) to represent - the impossibilty of errors: Thou shall not fail! + the impossibility of errors: Thou shall not fail! -Wait! there is too much! what module am I supposed to open locally and what operators should I use? +Wait! There is too much! What module am I supposed to open locally and what operators should I use? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you are feeling overwhelmed by the different syntax modules, here are @@ -993,10 +993,10 @@ the errors to a common type. You can also use the ``Result.map_error`` and ``lwt_map_error`` functions introduced in previous sections. -Wait! it was supposed to be “one single uniform way of dealing with errors”! what is this? +Wait! It was supposed to be “one single uniform way of dealing with errors”! What is this? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The error management in Octez is through a unified way (syntax modules +The error management in Octez is a unified way (syntax modules with regular, predictable interfaces) of handling different types of errors. @@ -1098,7 +1098,7 @@ They do not even require the syntax modules to be open. in retry original_limit f - You can use all the formating percent-escapes from the `Format + You can use all the formatting percent-escapes from the `Format module `__. However, you should generally keep the message on a single line so that it can be printed nicely in logs. @@ -1216,7 +1216,7 @@ in the shell, just use :literal:`\`Temporary`. - ``description``: a longer human readable string. - ``pp``: a pretty-printing function carrying enough information for a full error message for the user. Note that the function does not receive the error, - instead it receives the *projected payload of the error* (here a 3-uple + instead it receives the *projected payload of the error* (here a 3-tuple ``(expected, got, line)``. - encoding: an encoding for the projected payload of the error. - projection: a partial function that matches the specific error @@ -2144,9 +2144,9 @@ E.g., Haskell relies heavily on monads and has the dedicated let add x y = let ( let* ) = OptionMonad.bind in - let* x = int_of_strin_opt x in - let* y = int_of_strin_opt y in - Some (strin_of_int (x + y)) + let* x = int_of_string_opt x in + let* y = int_of_string_opt y in + Some (string_of_int (x + y)) - `infix operators `__ @@ -2155,9 +2155,9 @@ E.g., Haskell relies heavily on monads and has the dedicated let add x y = let ( >>= ) = OptionMonad.bind in - int_of_strin_opt x >>= fun x -> - int_of_strin_opt y >>= fun y -> - Some (strin_of_int (x + y)) + int_of_string_opt x >>= fun x -> + int_of_string_opt y >>= fun y -> + Some (string_of_int (x + y)) Note that mixing multiple infix operators is not always easy because of precedence and associativity. @@ -2167,9 +2167,9 @@ E.g., Haskell relies heavily on monads and has the dedicated :: let add x y = - OptionMonad.bind (int_of_strin_opt x) @@ fun x -> - OptionMonad.bind (int_of_strin_opt y) @@ fun y -> - Some (strin_of_int (x + y)) + OptionMonad.bind (int_of_string_opt x) @@ fun x -> + OptionMonad.bind (int_of_string_opt y) @@ fun y -> + Some (string_of_int (x + y)) This is useful for the occasional application: you do not need to declare a dedicated operator nor open a dedicated syntax module. @@ -2181,7 +2181,7 @@ In depth discussion: ``Error_monad``, ``src/lib_error_monad/``, ``Tezos_base__Tz ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The different parts of the error monad (syntax modules, extended stdlib, -tracing promitives, etc.) are defined in separate files. Yet, they are +tracing primitives, etc.) are defined in separate files. Yet, they are all available to you directly. This section explains where each part is defined and how it reaches the scope of your code. -- GitLab From 4577d197e23a7262191847f3f6e31d97f52a9e43 Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Wed, 5 Jan 2022 15:56:39 +0100 Subject: [PATCH 03/11] doc: typos in time_measurement_ppx.rst --- docs/developer/time_measurement_ppx.rst | 44 ++++++++++++------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/developer/time_measurement_ppx.rst b/docs/developer/time_measurement_ppx.rst index c5086f87ea4e..7690ec1fd4c4 100644 --- a/docs/developer/time_measurement_ppx.rst +++ b/docs/developer/time_measurement_ppx.rst @@ -1,17 +1,17 @@ Time measurement PPX ==================== -The time measurement PPX is an Ocaml preprocessing tool that intends to -embed generated benchmark tooling into specific pieces of Ocaml code. +The time measurement PPX is an OCaml preprocessing tool that intends to +embed generated benchmark tooling into specific pieces of OCaml code. -It is able to measure the time spent in the execution of annotated Ocaml +It is able to measure the time spent in the execution of annotated OCaml expressions and to log these measurements when desired. Since it uses ``Tezos_event_logging`` for the logging part, this PPX can easily be used together with ``Tezt`` framework to perform the benchmarking of specific parts of Tezos node. **This PPX is only intended to be used for tests. As the current runtime -implemetation performs memory allocation, an unwise usage could mess with +implementation performs memory allocation, an unwise usage could mess with the garbage collector or blow up your memory.** **PLEASE, MAKE SURE THAT IT IS NOT ACTIVATED WHEN COMPILING CODE FOR @@ -21,9 +21,9 @@ Getting started --------------- Suppose we want to measure the performance of some specific parts of -the following Ocaml function inside the module ``lib_my_module``: +the following OCaml function inside the module ``lib_my_module``: -.. code-block:: Ocaml +.. code-block:: OCaml let my_function () = let a = f () in @@ -40,10 +40,10 @@ Suppose also that module ``lib_my_module`` contains the following dune file: (libraries lwt) (flags (:standard -open Lwt))) -We can mesure the execution time of ``f ()`` and ``g ()`` and log them by -adding the following Ocaml attributes: +We can measure the execution time of ``f ()`` and ``g ()`` and log them by +adding the following OCaml attributes: -.. code-block:: Ocaml +.. code-block:: OCaml let my_function () = let a = f () [@time.duration f_time] in @@ -51,13 +51,13 @@ adding the following Ocaml attributes: h () >>= fun c -> foo a b c [@time.flush] -``[@time.duration]`` will be used to mesure the time of ``f ()`` and ``g ()`` +``[@time.duration]`` will be used to measure the time of ``f ()`` and ``g ()`` expressions execution and to name them respectively ``f_time`` and ``g_time``. ``[@time.flush]`` will then be used to log these measurements. -When the preprocessig will occur, the code will be transform as follows: +When the preprocessing will occur, the code will be transformed as follows: -.. code-block:: Ocaml +.. code-block:: OCaml let my_function () = let a = Tezos_time_measurement_runtime.Default.Time_measurement.duration @@ -81,7 +81,7 @@ The resulting thunk is passed to the function ``Time_measurement.duration`` from the module ``Tezos_time_measurement_runtime.Default`` along with the argument ``("f_time", [])``. -``Time_measurement.duration`` mesures the current time before and after executing +``Time_measurement.duration`` measures the current time before and after executing the given thunk in order to compute the span between the two timestamps. The resulting measurement is then bufferized in memory and, at last, the function evaluates in the result of the thunk so that we can respect the invariants of the initial program. @@ -110,11 +110,11 @@ and also removes them from memory. The flushing promise is then bounded again to return ``__flush__id__0`` value to preserve the program invariants as well. -That's great, but since Ocaml attributes are ignored by default, +That's great, but since OCaml attributes are ignored by default, we still need to update the dune stanza of ``lib_my_module`` so that it can take effect: -.. code-block:: Ocaml +.. code-block:: OCaml (library (name tezos_my_module) @@ -124,11 +124,11 @@ it can take effect: This update adds the ``tezos-time-measurement`` instrumentation backend, which, if set using ``--instrument-with tezos-time-measurement`` on ``dune build`` -command line, will preprocess our Ocaml code using the PPX. +command line, will preprocess our OCaml code using the PPX. This is useful to prevent our code from embedding benchmarking tooling in production by mistake: If no backend is specified for the compilation, added -attributes will just be ignored by the Ocaml compiler and that's it! +attributes will just be ignored by the OCaml compiler and that's it! We can now compile our ready-to-benchmark code::: @@ -146,18 +146,18 @@ is displayed on standard output. For example: Aug 23 17:52:58.593 - benchmarking: time measurements: Aug 23 17:52:58.593 - benchmarking: [(f_time, 0.000177); (g_time, 0.005658)] -Compatible Ocaml Attributes +Compatible OCaml Attributes --------------------------- The PPX provides the handling of three attributes: - ``[@time.duration